Package org.apache.jackrabbit.api.security.user

Interface UserManager

All Known Implementing Classes:
AutoSaveEnabledManager, UserManagerDelegator, UserManagerImpl
@ProviderType public interface UserManager
The UserManager provides access to and means to maintain authorizable objects i.e. users and groups. The UserManager is bound to a particular Session.

Note that all create calls will modify the session associated with the UserManager (whether this is the current session or not depends on the repository configuration). If the user manager is not in auto-save mode (see isAutoSave()), problems like overlapping creation of intermediate nodes may only surface upon a subsequent Session.save() operation; callers should be prepared to repeat them in case this happens.

  • Field Details

    • SEARCH_TYPE_USER

      static final int SEARCH_TYPE_USER
      Filter flag indicating that only Users should be searched and returned.
      See Also:

    • SEARCH_TYPE_GROUP

      static final int SEARCH_TYPE_GROUP
      Filter flag indicating that only Groups should be searched and returned.
      See Also:

    • SEARCH_TYPE_AUTHORIZABLE

      static final int SEARCH_TYPE_AUTHORIZABLE
      Filter flag indicating that all Authorizables should be searched.
      See Also:

  • Method Details

    • getAuthorizable

      @Nullable @Nullable Authorizable getAuthorizable(@NotNull @NotNull String id) throws RepositoryException
      Get the Authorizable by its id.
      Parameters:
      id - The user or group id.
      Returns:
      Authorizable or null, if not present.
      Throws:
      RepositoryException - If an error occurs.
      See Also:

    • getAuthorizable

      @Nullable <T extends Authorizable> T getAuthorizable(@NotNull @NotNull String id, @NotNull @NotNull Class<T> authorizableClass) throws AuthorizableTypeException, RepositoryException
      Get the Authorizable of a specific type by its id.
      Type Parameters:
      T - the required Authorizable type.
      Parameters:
      id - the user or group id.
      authorizableClass - the class of the type of Authorizable required; must not be null.
      Returns:
      Authorizable or null, if not present.
      Throws:
      AuthorizableTypeException - If an authorizable exists but is not of the requested type.
      RepositoryException - If an error occurs

    • getAuthorizable

      @Nullable @Nullable Authorizable getAuthorizable(@NotNull @NotNull Principal principal) throws RepositoryException
      Get the Authorizable by its Principal.
      Parameters:
      principal - The principal of the authorizable to retrieve.
      Returns:
      Authorizable or null, if not present.
      Throws:
      RepositoryException - If an error occurs.

    • getAuthorizableByPath

      @Nullable @Nullable Authorizable getAuthorizableByPath(@NotNull @NotNull String path) throws UnsupportedRepositoryOperationException, RepositoryException
      In accordance to Authorizable.getPath() this method allows to retrieve an given authorizable by it's path.
      Parameters:
      path - The path to an authorizable.
      Returns:
      Authorizable or null, if not present.
      Throws:
      UnsupportedRepositoryOperationException - If this implementation does not support to retrieve authorizables by path.
      RepositoryException - If another error occurs.
      See Also:

    • findAuthorizables

      @NotNull @NotNull Iterator<Authorizable> findAuthorizables(@NotNull @NotNull String relPath, @Nullable @Nullable String value) throws RepositoryException
      Returns all Authorizables that have a property with the given relative path (or name) that matches the specified value.

      If a relative path with more than one segment is specified only properties exactly matching that patch will be returned. If, however, a name is specified all properties that may be retrieved using Authorizable.getProperty(String) will be searched for a match.

      Parameters:
      relPath - A relative property path or name.
      value - A string value to match.
      Returns:
      All Authorizables that have a property with the given name exactly matching the given value.
      Throws:
      RepositoryException - If an error occurs.
      See Also:

    • findAuthorizables

      @NotNull @NotNull Iterator<Authorizable> findAuthorizables(@NotNull @NotNull String relPath, @Nullable @Nullable String value, int searchType) throws RepositoryException
      Returns all Authorizables that have a property with the given relative path (or name) that matches the specified value. In contrast to findAuthorizables(String, String) the type of authorizable is respected while executing the search.

      If a relative path with more than one segment is specified only properties exactly matching that path will be returned. If, however, a name is specified all properties that may be retrieved using Authorizable.getProperty(String) will be searched for a match.

      Parameters:
      relPath - A relative property path or name.
      value - A string value to match.
      searchType - Any of the following constants:
      Returns:
      An iterator of Authorizable.
      Throws:
      RepositoryException - If an error occurs.

    • findAuthorizables

      @NotNull @NotNull Iterator<Authorizable> findAuthorizables(@NotNull @NotNull Query query) throws RepositoryException
      Return Authorizables that match a specific Query.
      Parameters:
      query - A query
      Returns:
      Iterator of authorizables witch match the query.
      Throws:
      RepositoryException - If an error occurs.

    • createUser

      @NotNull @NotNull User createUser(@NotNull @NotNull String userID, @Nullable @Nullable String password) throws AuthorizableExistsException, RepositoryException
      Creates a user for the given userID / password pair.
      Same as createUser(String,String,Principal,String) where the specified userID is equal to the principal name and the intermediate path is null.
      Parameters:
      userID - The ID of the new user.
      password - The initial password of this user.
      Returns:
      The new User.
      Throws:
      AuthorizableExistsException - in case the given userID is already in use or another Authorizable with the same principal name exists.
      RepositoryException - If another error occurs.

    • createUser

      @NotNull @NotNull User createUser(@NotNull @NotNull String userID, @Nullable @Nullable String password, @NotNull @NotNull Principal principal, @Nullable @Nullable String intermediatePath) throws AuthorizableExistsException, RepositoryException
      Creates a user for the given parameters. If the implementation is not able to deal with the intermediatePath that parameter should be ignored. Except for the intermediatePath and password, neither of the specified parameters can be null.

      The given password may be null however the behavior of such users depend on the implementation (usually those users cannot be used for authentication but only for impersonation). Consider using createSystemUser(String, String) rather than creating a user with a null password with this method.

      Parameters:
      userID - The ID of the new user.
      password - The initial password of the new user.
      principal - The principal of the new user.
      intermediatePath - An optional intermediate path used to create the new user. If the intermediate path is null an internal, implementation specific structure will be used.
      Returns:
      The new User.
      Throws:
      AuthorizableExistsException - in case the given userID is already in use or another Authorizable with the same principal name exists.
      RepositoryException - If the current Session is not allowed to create users or some another error occurs.
      See Also:

    • createSystemUser

      @NotNull @NotNull User createSystemUser(@NotNull @NotNull String userID, @Nullable @Nullable String intermediatePath) throws AuthorizableExistsException, RepositoryException
      Create a new system user for the specified userID. The new authorizable is required to have the following characteristics:
      • User.isSystemUser() returns true.
      • The system user doesn't have a password set and doesn't allow change the password.
      • The principal name is generated by the system; it may be the same as userID.
      • A given implementation may choose to keep system users in a dedicated location and thus may impose restrictions on the intermediatePath.
      Parameters:
      userID - A valid userID.
      intermediatePath - An optional intermediate path to create the new system user. The implemenation may decide to reject intermediate paths if they violate an implementation specific requirement with respect to the location where systems users are being held. If the intermediate path is null an internal implementation specific structure will be used.
      Returns:
      The new system user.
      Throws:
      AuthorizableExistsException - if an Authorizable with this id already exists.
      RepositoryException - If another error occurs.

    • createGroup

      @NotNull @NotNull Group createGroup(@NotNull @NotNull String groupID) throws AuthorizableExistsException, RepositoryException
      Creates a Group for the given groupID, which must not be null.
      Same as createGroup(String, Principal,String) where the specified groupID is the name of the Principal the intermediate path is null.
      Parameters:
      groupID - The ID of the new group; must not be null.
      Returns:
      The new Group.
      Throws:
      AuthorizableExistsException - in case the given groupID is already in use or another Authorizable with the same ID or principal name already exists.
      RepositoryException - If another error occurs.

    • createGroup

      @NotNull @NotNull Group createGroup(@NotNull @NotNull Principal principal) throws AuthorizableExistsException, RepositoryException
      Creates a new Group that is based on the given principal. Note that the group's ID is implementation specific. The implementation may take the principal name as ID hint but must in any case assert that it is unique among the IDs known to this manager.
      Parameters:
      principal - A non-null Principal
      Returns:
      The new Group.
      Throws:
      AuthorizableExistsException - in case the given principal is already in use with another Authorizable.
      RepositoryException - If another error occurs.

    • createGroup

      @NotNull @NotNull Group createGroup(@NotNull @NotNull Principal principal, @Nullable @Nullable String intermediatePath) throws AuthorizableExistsException, RepositoryException
      Same as createGroup(String, Principal, String) where the name of the specified principal is used to create the group's ID.
      Parameters:
      principal - The principal associated with the new group.
      intermediatePath - An optional intermediate path used to create the new group. If the intermediate path is null an internal, implementation specific structure will be used.
      Returns:
      The new Group.
      Throws:
      AuthorizableExistsException - in case the given principal is already in use with another Authorizable.
      RepositoryException - If another error occurs.

    • createGroup

      @NotNull @NotNull Group createGroup(@NotNull @NotNull String groupID, @NotNull @NotNull Principal principal, @Nullable @Nullable String intermediatePath) throws AuthorizableExistsException, RepositoryException
      Creates a new Group that is based on the given id, principal and the specified intermediatePath hint. If the implementation is not able to deal with the intermediatePath this parameter should be ignored.
      Parameters:
      groupID - The ID of the new group.
      principal - The principal of the new group.
      intermediatePath - An optional intermediate path used to create the new group. If the intermediate path is null an internal, implementation specific structure will be used.
      Returns:
      The new Group.
      Throws:
      AuthorizableExistsException - in case the given principal is already in use with another Authorizable.
      RepositoryException - If another error occurs.

    • isAutoSave

      boolean isAutoSave()
      If any write operations executed through the User API are automatically persisted this method returns true. In this case there are no pending transient changes left and there is no need to explicitly call Session.save(). If this method returns false any changes must be completed by an extra save call on the Session associated with this UserManager.
      Returns:
      true if changes are automatically persisted; false if changes made through this API (including method calls on Authorizable and subclasses are only transient and must be persisted using Session.save().
      See Also:

    • autoSave

      void autoSave(boolean enable) throws UnsupportedRepositoryOperationException, RepositoryException
      Changes the auto save behavior of this UserManager.

      Note, that this shouldn't be allowed in cases where the associated session is different from the original session accessing the user manager.

      Parameters:
      enable - If true changes made through this API will be automatically saved; otherwise an explicit call to Session.save() is required in order to persist changes.
      Throws:
      UnsupportedRepositoryOperationException - If the implementation does not allow to change the auto save behavior.
      RepositoryException - If some other error occurs.