OSGi™ Service Platform
Release 2

org.osgi.service.useradmin
Interface Group

All Superinterfaces:
Role, User

public interface Group
extends User

A named grouping of roles (Role objects).

Whether or not a given Authorization context implies a Group object depends on the members of that Group object.

A Group object can have two kinds of members: basic and required. A Group object is implied by an Authorization context if all of its required members are implied and at least one of its basic members is implied.

A Group object must contain at least one basic member in order to be implied. In other words, a Group object without any basic member roles is never implied by any Authorization context.

A User object always implies itself.

No loop detection is performed when adding members to Group objects, which means that it is possible to create circular implications. Loop detection is instead done when roles are checked. The semantics is that if a role depends on itself (i.e., there is an implication loop), the role is not implied.

The rule that a Group object must have at least one basic member to be implied is motivated by the following example:

 group foo
   required members: marketing
   basic members: alice, bob
 
Privileged operations that require membership in "foo" can be performed only by "alice" and "bob", who are in marketing.

If "alice" and "bob" ever transfer to a different department, anybody in marketing will be able to assume the "foo" role, which certainly must be prevented. Requiring that "foo" (or any Group object for that matter) must have at least one basic member accomplishes that.

However, this would make it impossible for a Group object to be implied by just its required members. An example where this implication might be useful is the following declaration: "Any citizen who is an adult is allowed to vote." An intuitive configuration of "voter" would be:

 group voter
   required members: citizen, adult
      basic members:
 
However, according to the above rule, the "voter" role could never be assumed by anybody, since it lacks any basic members. In order to address this issue a predefined role named "user.anyone" can be specified, which is always implied. The desired implication of the "voter" group can then be achieved by specifying "user.anyone" as its basic member, as follows:
 group voter
   required members: citizen, adult
      basic members: user.anyone
 


Field Summary
 
Fields inherited from interface org.osgi.service.useradmin.Role
GROUP, ROLE, USER
 
Method Summary
 boolean addMember(Role role)
          Adds the specified Role object as a basic member to this Group object.
 boolean addRequiredMember(Role role)
          Adds the specified Role object as a required member to this Group object.
 Role[] getMembers()
          Gets the basic members of this Group object.
 Role[] getRequiredMembers()
          Gets the required members of this Group object.
 boolean removeMember(Role role)
          Removes the specified Role object from this Group object.
 
Methods inherited from interface org.osgi.service.useradmin.User
getCredentials, hasCredential
 
Methods inherited from interface org.osgi.service.useradmin.Role
getName, getProperties, getType
 

Method Detail

addMember

public boolean addMember(Role role)
Adds the specified Role object as a basic member to this Group object.

Parameters:
role - The role to add as a basic member.
Returns:
true if the given role could be added as a basic member, and false if this Group object already contains a Role object whose name matches that of the specified role.
Throws:
java.lang.SecurityException - If a security manager exists and the caller does not have the UserAdminPermission with name admin.

addRequiredMember

public boolean addRequiredMember(Role role)
Adds the specified Role object as a required member to this Group object.

Parameters:
role - The Role object to add as a required member.
Returns:
true if the given Role object could be added as a required member, and false if this Group object already contains a Role object whose name matches that of the specified role.
Throws:
java.lang.SecurityException - If a security manager exists and the caller does not have the UserAdminPermission with name admin.

removeMember

public boolean removeMember(Role role)
Removes the specified Role object from this Group object.

Parameters:
role - The Role object to remove from this Group object.
Returns:
true if the Role object could be removed, otherwise false.
Throws:
java.lang.SecurityException - If a security manager exists and the caller does not have the UserAdminPermission with name admin.

getMembers

public Role[] getMembers()
Gets the basic members of this Group object.

Returns:
The basic members of this Group object, or null if this Group object does not contain any basic members.

getRequiredMembers

public Role[] getRequiredMembers()
Gets the required members of this Group object.

Returns:
The required members of this Group object, or null if this Group object does not contain any required members.

OSGi™ Service Platform
Release 2

Copyright © OSGi Alliance (2000, 2002). All Rights Reserved. Licensed under the OSGi Specification License, Version 1.0