org.osgi.service.useradmin
Interface UserAdmin

public interface UserAdmin

This interface is used to manage a database of named Role objects, which can be used for authentication and authorization purposes.

This version of the User Admin service defines two types of Role objects: "User" and "Group". Each type of role is represented by an int constant and an interface. The range of positive integers is reserved for new types of roles that may be added in the future. When defining proprietary role types, negative constant values must be used.

Every role has a name and a type.

A Userobject can be configured with credentials (e.g., a password) and properties (e.g., a street address, phone number, etc.).

A Groupobject represents an aggregation of User and Groupobjects. In other words, the members of a Group object are roles themselves.

Every User Admin service manages and maintains its own namespace of Role objects, in which each Role object has a unique name.

Method Summary

Role	createRole(java.lang.String name, int type) Creates a Role object with the given name and of the given type.
Authorization	getAuthorization(User user) Creates an Authorization object that encapsulates the specified User object and the Role objects it possesses.
Role	getRole(java.lang.String name) Gets the Role object with the given name from this User Admin service.
Role[]	getRoles(java.lang.String filter) Gets the Role objects managed by this User Admin service that have properties matching the specified LDAP filter criteria.
User	getUser(java.lang.String key, java.lang.String value) Gets the user with the given property key-value pair from the User Admin service database.
boolean	removeRole(java.lang.String name) Removes the Role object with the given name from this User Admin service.

Method Detail

createRole

public Role createRole(java.lang.String name,
                       int type)

Creates a Role object with the given name and of the given type.

If a Role object was created, a UserAdminEvent object of type UserAdminEvent.ROLE_CREATEDis broadcast to any UserAdminListener object.

Parameters:

name - The name of the Role object to create.

type - The type of the Role object to create. Must be either a Role.USERtype or Role.GROUPtype.

Returns:

The newly created Role object, or null if a role with the given name already exists.

Throws:

java.lang.IllegalArgumentException - if type is invalid.

java.lang.SecurityException - If a security manager exists and the caller does not have the UserAdminPermission with name admin.

removeRole

public boolean removeRole(java.lang.String name)

Removes the Role object with the given name from this User Admin service.

If the Role object was removed, a UserAdminEvent object of type UserAdminEvent.ROLE_REMOVEDis broadcast to any UserAdminListener object.

Parameters:

name - The name of the Role object to remove.

Returns:

true If a Role object with the given name is present in this User Admin service and 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.

getRole

public Role getRole(java.lang.String name)

Gets the Role object with the given name from this User Admin service.

Parameters:

name - The name of the Role object to get.

Returns:

The requested Role object, or null if this User Admin service does not have a Role object with the given name.

getRoles

public Role[] getRoles(java.lang.String filter)
                throws InvalidSyntaxException

Gets the Role objects managed by this User Admin service that have properties matching the specified LDAP filter criteria. See org.osgi.framework.Filter for a description of the filter syntax. If a null filter is specified, all Role objects managed by this User Admin service are returned.

Parameters:

filter - The filter criteria to match.

Returns:

The Role objects managed by this User Admin service whose properties match the specified filter criteria, or all Role objects if a null filter is specified. If no roles match the filter, null will be returned.

Throws:

InvalidSyntaxException

getUser

public User getUser(java.lang.String key,
                    java.lang.String value)

Gets the user with the given property key-value pair from the User Admin service database. This is a convenience method for retrieving a User object based on a property for which every User object is supposed to have a unique value (within the scope of this User Admin service), such as for example a X.500 distinguished name.

Parameters:

key - The property key to look for.

value - The property value to compare with.

Returns:

A matching user, if exactly one is found. If zero or more than one matching users are found, null is returned.

getAuthorization

public Authorization getAuthorization(User user)

Creates an Authorization object that encapsulates the specified User object and the Role objects it possesses. The null user is interpreted as the anonymous user. The anonymous user represents a user that has not been authenticated. An Authorization object for an anonymous user will be unnamed, and will only imply groups that user.anyone implies.

Parameters:

user - The User object to create an Authorization object for, or null for the anonymous user.

Returns:

the Authorization object for the specified User object.