@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 "autosave" 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.
static int
SEARCH_TYPE_AUTHORIZABLE
Filter flag indicating that all
Authorizable
s should be
searched.
static int
SEARCH_TYPE_GROUP
Filter flag indicating that only
Group
s should be searched
and returned.
static int
SEARCH_TYPE_USER
Filter flag indicating that only
User
s should be searched
and returned.
@NotNull
Group
createGroup
(@NotNull java.security.Principal principal,
@Nullable java.lang.String intermediatePath)
@NotNull
Group
createGroup
(@NotNull java.lang.String groupID)
Creates a Group for the given groupID, which must not be
null
.
@NotNull
Group
createGroup
(@NotNull java.lang.String groupID,
@NotNull java.security.Principal principal,
@Nullable java.lang.String intermediatePath)
Creates a new
Group
that is based on the given id, principal
and the specified
intermediatePath
hint.
@NotNull
User
createSystemUser
(@NotNull java.lang.String userID,
@Nullable java.lang.String intermediatePath)
Create a new system user for the specified
userID
.
@NotNull
User
createUser
(@NotNull java.lang.String userID,
@Nullable java.lang.String password)
Creates an User for the given userID / password pair; neither of the
specified parameters can be
null
.
Same as
createUser(String,String,Principal,String)
where
the specified userID is equal to the principal name and the intermediate
path is
null
.
@NotNull
User
createUser
(@NotNull java.lang.String userID,
@Nullable java.lang.String password,
@NotNull java.security.Principal principal,
@Nullable java.lang.String intermediatePath)
Creates an User for the given parameters.
@NotNull java.util.Iterator<
Authorizable
>
findAuthorizables
(@NotNull
Query
query)
@NotNull java.util.Iterator<
Authorizable
>
findAuthorizables
(@NotNull java.lang.String relPath,
@Nullable java.lang.String value)
Returns all
Authorizable
s that have a
property
with the given relative
path (or name) that matches the specified value.
@NotNull java.util.Iterator<
Authorizable
>
findAuthorizables
(@NotNull java.lang.String relPath,
@Nullable java.lang.String value,
int searchType)
Returns all
Authorizable
s that have a
property
with the given relative
path (or name) that matches the specified value.
@Nullable
Authorizable
getAuthorizable
(@NotNull java.security.Principal principal)
Get the Authorizable by its Principal.
@Nullable
Authorizable
getAuthorizable
(@NotNull java.lang.String id)
Get the Authorizable by its id.
<T extends
Authorizable
>
T
getAuthorizable
(@NotNull java.lang.String id,
@NotNull java.lang.Class<T> authorizableClass)
Get the Authorizable of a specific type by its id.
@Nullable
Authorizable
getAuthorizableByPath
(@NotNull java.lang.String path)
boolean
isAutoSave
()
If any write operations executed through the User API are automatically
persisted this method returns
true
.
SEARCH_TYPE_USER
static final int SEARCH_TYPE_USER
Filter flag indicating that only
User
s should be searched
and returned.
See Also:
Constant Field Values
SEARCH_TYPE_GROUP
static final int SEARCH_TYPE_GROUP
Filter flag indicating that only
Group
s should be searched
and returned.
See Also:
Constant Field Values
SEARCH_TYPE_AUTHORIZABLE
static final int SEARCH_TYPE_AUTHORIZABLE
Filter flag indicating that all
Authorizable
s should be
searched.
See Also:
Constant Field Values
@Nullable
Authorizable
getAuthorizable(@NotNull
@NotNull java.lang.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:
Authorizable.getID()
@NotNull java.lang.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
@Nullable
@Nullable Authorizable getAuthorizable(@NotNull
@NotNull java.security.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.
@Nullable
@Nullable Authorizable getAuthorizableByPath(@NotNull
@NotNull java.lang.String path)
throws UnsupportedRepositoryOperationException,
RepositoryException
Parameters:
path
- The path to an authorizable.
Returns:
Authorizable or
null
, if not present.
Throws:
UnsupportedRepositoryOperationException
- If this implementation does
support to retrieve authorizables by path.
RepositoryException
- If another error occurs.
See Also:
Authorizable.getPath()
findAuthorizables
@NotNull
@NotNull java.util.Iterator<Authorizable> findAuthorizables(@NotNull
@NotNull java.lang.String relPath,
@Nullable
@Nullable java.lang.String value)
throws RepositoryException
Returns all
Authorizable
s 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
Authorizable
s that have a property with the given
name exactly matching the given value.
Throws:
RepositoryException
- If an error occurs.
See Also:
Authorizable.getProperty(String)
findAuthorizables
@NotNull
@NotNull java.util.Iterator<Authorizable> findAuthorizables(@NotNull
@NotNull java.lang.String relPath,
@Nullable
@Nullable java.lang.String value,
int searchType)
throws RepositoryException
Returns all
Authorizable
s 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:
SEARCH_TYPE_AUTHORIZABLE
SEARCH_TYPE_GROUP
SEARCH_TYPE_USER
Returns:
An iterator of
Authorizable
.
Throws:
RepositoryException
- If an error occurs.
findAuthorizables
@NotNull
@NotNull java.util.Iterator<Authorizable> findAuthorizables(@NotNull
@NotNull Query query)
throws RepositoryException
Parameters:
query
- A query
Returns:
Iterator of authorizables witch match the
query
.
Throws:
RepositoryException
- If an error occurs.
@Nullable java.lang.String password)
throws
AuthorizableExistsException
,
RepositoryException
Creates an User for the given userID / password pair; neither of the
specified parameters can be
null
.
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.
@NotNull java.security.Principal principal,
@Nullable
@Nullable java.lang.String intermediatePath)
throws
AuthorizableExistsException
,
RepositoryException
Creates an 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
, neither of the specified
parameters can be
null
.
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.
@Nullable
@Nullable java.lang.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.
@NotNull
Group
createGroup(@NotNull
@NotNull java.lang.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.
@NotNull
Group
createGroup(@NotNull
@NotNull java.security.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.
@NotNull java.security.Principal principal,
@Nullable
@Nullable java.lang.String intermediatePath)
throws
AuthorizableExistsException
,
RepositoryException
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.
@NotNull java.security.Principal principal,
@Nullable
@Nullable java.lang.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(boolean)
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.