OSGi 8.1.0 · org.osgi.service.useradmin.UserAdmin · APIdia, the JavaDoc alternative

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.

Method Summary

Modifier and Type	Method and Description
public Role	Returns: The newly created `Role` object, or `null` if a role with the given name already exists. createRole(String The `name` of the `Role` object to create. name, int The type of the `Role` object to create. Must be either a `Role#USER` type or `Role#GROUP` type. type) Creates a `Role` object with the given name and of the given type.
public Authorization	Returns: the `Authorization` object for the specified `User` object. getAuthorization(User The `User` object to create an `Authorization` object for, or `null` for the anonymous user. user) Creates an `Authorization` object that encapsulates the specified `User` object and the `Role` objects it possesses.
public Role	Returns: The requested `Role` object, or `null` if this User Admin service does not have a `Role` object with the given `name`. getRole(String The name of the `Role` object to get. name) Gets the `Role` object with the given `name` from this User Admin service.
public Role[]	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. getRoles(String The filter criteria to match. filter) Gets the `Role` objects managed by this User Admin service that have properties matching the specified LDAP filter criteria.
public User	Returns: A matching user, if exactly one is found. If zero or more than one matching users are found, `null` is returned. getUser(String The property key to look for. key, String The property value to compare with. value) Gets the user with the given property `key`-`value` pair from the User Admin service database.
public boolean	Returns: `true` If a `Role` object with the given name is present in this User Admin service and could be removed, otherwise `false`. removeRole(String The name of the `Role` object to remove. 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 back to summary

createRole	back to summary
public 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:String The `name` of the `Role` object to create. type:int The type of the `Role` object to create. Must be either a `Role#USER` type or `Role#GROUP` type. Returns:Role The newly created `Role` object, or `null` if a role with the given name already exists. Exceptions IllegalArgumentException: if `type` is invalid. SecurityException: If a security manager exists and the caller does not have the `UserAdminPermission` with name `admin`.

public 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:String: The name of the Role object to create.
type:int: The type of the Role object to create. Must be either a Role#USER type or Role#GROUP type.

Returns:Role

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

Exceptions

IllegalArgumentException:: if type is invalid.
SecurityException:: If a security manager exists and the caller does not have the UserAdminPermission with name admin.

getAuthorization back to summary

getAuthorization	back to summary
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:User The `User` object to create an `Authorization` object for, or `null` for the anonymous user. Returns:Authorization the `Authorization` object for the specified `User` object.

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:User: The User object to create an Authorization object for, or null for the anonymous user.

Returns:Authorization

the Authorization object for the specified User object.

getRole back to summary

getRole	back to summary
public Role getRole(String name) Gets the `Role` object with the given `name` from this User Admin service. Parameters name:String The name of the `Role` object to get. Returns:Role The requested `Role` object, or `null` if this User Admin service does not have a `Role` object with the given `name`.

public Role getRole(String name)

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

Parameters

name:String: The name of the Role object to get.

Returns:Role

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

getRoles back to summary

getRoles	back to summary
public 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:String The filter criteria to match. Returns:Role[] 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. Exceptions InvalidSyntaxException: If the filter is not well formed.

public 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:String: The filter criteria to match.

Returns:Role[]

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.

Exceptions

InvalidSyntaxException:: If the filter is not well formed.

getUser back to summary

getUser	back to summary
public 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:String The property key to look for. value:String The property value to compare with. Returns:User A matching user, if exactly one is found. If zero or more than one matching users are found, `null` is returned.

public 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:String: The property key to look for.
value:String: The property value to compare with.

Returns:User

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

removeRole back to summary

removeRole	back to summary
public 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:String The name of the `Role` object to remove. Returns:boolean `true` If a `Role` object with the given name is present in this User Admin service and could be removed, otherwise `false`. Exceptions SecurityException: If a security manager exists and the caller does not have the `UserAdminPermission` with name `admin`.

public 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:String: The name of the Role object to remove.

Returns:boolean

true If a Role object with the given name is present in this User Admin service and could be removed, otherwise false.

Exceptions

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

public Interface UserAdmin

Method Summary

Method Detail