org.apache.jackrabbit.api.security.user.UserManager Maven / Gradle / Ivy
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.jackrabbit.api.security.user;
import java.security.Principal;
import java.util.Iterator;
import javax.jcr.RepositoryException;
import javax.jcr.Session;
import javax.jcr.UnsupportedRepositoryOperationException;
import org.osgi.annotation.versioning.ProviderType;
/**
* The UserManager
provides access to and means to maintain
* {@link Authorizable authorizable objects} i.e. {@link User users} and
* {@link Group groups}. The UserManager
is bound to a particular
* Session
.
*
* Note that all create
calls will modify the session associated
* with the {@linkplain UserManager} (whether this is the current session or not
* depends on the repository configuration). If the user manager is not
* in "autosave" mode (see {@link UserManager#isAutoSave()}), problems like
* overlapping creation of intermediate nodes may only surface upon a subsequent
* {@link Session#save()} operation; callers should be prepared to repeat them
* in case this happens.
*/
@ProviderType
public interface UserManager {
/**
* Filter flag indicating that only User
s should be searched
* and returned.
*/
int SEARCH_TYPE_USER = 1;
/**
* Filter flag indicating that only Group
s should be searched
* and returned.
*/
int SEARCH_TYPE_GROUP = 2;
/**
* Filter flag indicating that all Authorizable
s should be
* searched.
*/
int SEARCH_TYPE_AUTHORIZABLE = 3;
/**
* Get the Authorizable by its id.
*
* @param id The user or group id.
* @return Authorizable or null
, if not present.
* @throws RepositoryException If an error occurs.
* @see Authorizable#getID()
*/
Authorizable getAuthorizable(String id) throws RepositoryException;
/**
* Get the Authorizable of a specific type by its id.
*
* @param id the user or group id.
* @param authorizableClass the class of the type of Authorizable required; must not be null
.
* @param the required Authorizable type.
* @return Authorizable or null
, if not present.
* @throws AuthorizableTypeException If an authorizable exists but is not of the requested type.
* @throws RepositoryException If an error occurs
*/
T getAuthorizable(String id, Class authorizableClass) throws AuthorizableTypeException, RepositoryException;
/**
* Get the Authorizable by its Principal.
*
* @param principal The principal of the authorizable to retrieve.
* @return Authorizable or null
, if not present.
* @throws RepositoryException If an error occurs.
*/
Authorizable getAuthorizable(Principal principal) throws RepositoryException;
/**
* In accordance to {@link org.apache.jackrabbit.api.security.user.Authorizable#getPath()}
* this method allows to retrieve an given authorizable by it's path.
*
* @param path The path to an authorizable.
* @return Authorizable or null
, if not present.
* @throws UnsupportedRepositoryOperationException If this implementation does
* support to retrieve authorizables by path.
* @throws RepositoryException If another error occurs.
* @see org.apache.jackrabbit.api.security.user.Authorizable#getPath()
*/
Authorizable getAuthorizableByPath(String path) throws UnsupportedRepositoryOperationException, RepositoryException;
/**
* Returns all Authorizable
s that have a
* {@link Authorizable#getProperty(String) 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
* {@link Authorizable#getProperty(String)} will be searched for a match.
*
* @param relPath A relative property path or name.
* @param value A string value to match.
* @return All Authorizable
s that have a property with the given
* name exactly matching the given value.
* @throws RepositoryException If an error occurs.
* @see Authorizable#getProperty(String)
*/
Iterator findAuthorizables(String relPath, String value) throws RepositoryException;
/**
* Returns all Authorizable
s that have a
* {@link Authorizable#getProperty(String) property} with the given relative
* path (or name) that matches the specified value. In contrast to
* {@link #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
* {@link Authorizable#getProperty(String)} will be searched for a match.
*
* @param relPath A relative property path or name.
* @param value A string value to match.
* @param searchType Any of the following constants:
*
* - {@link #SEARCH_TYPE_AUTHORIZABLE}
* - {@link #SEARCH_TYPE_GROUP}
* - {@link #SEARCH_TYPE_USER}
*
* @return An iterator of Authorizable
.
* @throws RepositoryException If an error occurs.
*/
Iterator findAuthorizables(String relPath, String value, int searchType) throws RepositoryException;
/**
* Return {@link Authorizable}s that match a specific {@link Query}.
*
* @param query A query
* @return Iterator of authorizables witch match the query
.
* @throws RepositoryException If an error occurs.
*/
Iterator findAuthorizables(Query query) throws RepositoryException;
/**
* Creates an User for the given userID / password pair; neither of the
* specified parameters can be null
.
* Same as {@link #createUser(String,String,Principal,String)} where
* the specified userID is equal to the principal name and the intermediate
* path is null
.
*
* @param userID The ID of the new user.
* @param password The initial password of this user.
* @return The new User
.
* @throws AuthorizableExistsException in case the given userID is already
* in use or another Authorizable with the same principal name exists.
* @throws RepositoryException If another error occurs.
*/
User createUser(String userID, String password) 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
.
*
* @param userID The ID of the new user.
* @param password The initial password of the new user.
* @param principal The principal of the new user.
* @param 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.
* @return The new User
.
* @throws AuthorizableExistsException in case the given userID is already
* in use or another Authorizable with the same principal name exists.
* @throws RepositoryException If the current Session is
* not allowed to create users or some another error occurs.
*/
User createUser(String userID, String password, Principal principal,
String intermediatePath) throws AuthorizableExistsException, RepositoryException;
/**
* Create a new system user for the specified {@code userID}. The new authorizable
* is required to have the following characteristics:
*
*
* - {@link org.apache.jackrabbit.api.security.user.User#isSystemUser()} returns {@code 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 {@code userID}.
* - A given implementation may choose to keep system users in a dedicated
* location and thus may impose restrictions on the {@code intermediatePath}.
*
*
* @param userID A valid userID.
* @param 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 {@code null} an internal implementation specific structure will be used.
* @return The new system user.
* @throws AuthorizableExistsException if an Authorizable with this id already exists.
* @throws RepositoryException If another error occurs.
*/
User createSystemUser(String userID, String intermediatePath) throws AuthorizableExistsException, RepositoryException;
/**
* Creates a Group for the given groupID, which must not be null
.
*
* Same as {@link #createGroup(String, Principal,String)} where the specified
* groupID is the name of the Principal
the intermediate path
* is null
.
*
* @param groupID The ID of the new group; must not be null
.
* @return The new Group
.
* @throws AuthorizableExistsException in case the given groupID is already
* in use or another {@link Authorizable} with the same
* {@link Authorizable#getID() ID} or principal name already exists.
* @throws RepositoryException If another error occurs.
*/
Group createGroup(String groupID) 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.
*
* @param principal A non-null Principal
* @return The new Group
.
* @throws AuthorizableExistsException in case the given principal is
* already in use with another Authorizable.
* @throws RepositoryException If another error occurs.
*/
Group createGroup(Principal principal) throws AuthorizableExistsException, RepositoryException;
/**
* Same as {@link #createGroup(String, Principal, String)} where the
* name of the specified principal is used to create the group's ID.
*
* @param principal The principal associated with the new group.
* @param 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.
* @return The new Group
.
* @throws AuthorizableExistsException in case the given principal is
* already in use with another Authorizable.
* @throws RepositoryException If another error occurs.
*/
Group createGroup(Principal principal, 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.
*
* @param groupID The ID of the new group.
* @param principal The principal of the new group.
* @param 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.
* @return The new Group
.
* @throws AuthorizableExistsException in case the given principal is already
* in use with another Authorizable.
* @throws RepositoryException If another error occurs.
*/
Group createGroup(String groupID, Principal principal, String intermediatePath) throws AuthorizableExistsException, RepositoryException;
/**
* 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
* {@link javax.jcr.Session#save()}. If this method returns false
* any changes must be completed by an extra save call on the
* Session
associated with this UserManager
.
*
* @return true
if changes are automatically persisted;
* false
if changes made through this API (including method
* calls on {@link Authorizable} and subclasses are only transient and
* must be persisted using {@link javax.jcr.Session#save()}.
* @see #autoSave(boolean)
*/
boolean isAutoSave();
/**
* 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.
*
* @param enable If true
changes made through this API will
* be automatically saved; otherwise an explicit call to
* {@link javax.jcr.Session#save()} is required in order to persist changes.
* @throws UnsupportedRepositoryOperationException If the implementation
* does not allow to change the auto save behavior.
* @throws RepositoryException If some other error occurs.
*/
void autoSave(boolean enable) throws UnsupportedRepositoryOperationException, RepositoryException;
}