Overview | Package | Class | Tree | Serialized | Deprecated | Index | Help
| OSGi Service Platform Release 3
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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.

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_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:
    `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_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:
    `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.

### 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.

Overview | Package | Class | Tree | Serialized | Deprecated | Index | Help
| OSGi Service Platform Release 3
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright (c) OSGi Alliance (2000, 2003). All Rights Reserved.