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 User object can be configured with credentials (e.g., a password) and properties (e.g., a street address, phone number, etc.).

A Group object represents an aggregation of User and Group objects. 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.

"Consumers of this API must not implement this interface"

Method Summary

Modifier and Type	Method and Description
Role	createRole(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(String name) Gets the Role object with the given name from this User Admin service.
Role[]	getRoles(String filter) Gets the Role objects managed by this User Admin service that have properties matching the specified LDAP filter criteria.
User	getUser(String key, String value) Gets the user with the given property key-value pair from the User Admin service database.
boolean	removeRole(String name) Removes the Role object with the given name from this User Admin service and all groups it is a member of.

Method Detail

createRole

Role createRole(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_CREATED is 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.USER type or Role.GROUP type.

Returns:

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

Throws:

IllegalArgumentException - if type is invalid.

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

removeRole

boolean removeRole(String name)

Removes the Role object with the given name from this User Admin service and all groups it is a member of.

If the Role object was removed, a UserAdminEvent object of type UserAdminEvent.ROLE_REMOVED is 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:

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

getRole

Role getRole(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

Role[] getRoles(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 - If the filter is not well formed.

getUser

User getUser(String key,
             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

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.