UserAdmin
Date: 2016-06-25

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

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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 and all groups it is a member of.

- - ### Method Detail

    - #### createRole

          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

          boolean removeRole(java.lang.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:
        `java.lang.SecurityException` - If a security manager exists and the caller does not have the `UserAdminPermission` with name `admin`.

    - #### getRole

          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

          Role[] getRoles(java.lang.String filter)
                          throws org.osgi.framework.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:
        `org.osgi.framework.InvalidSyntaxException` - If the filter is not well formed.

    - #### getUser

          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

          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.