com.adobe.granite.security.user

Interface UserPropertiesManager

public interface UserPropertiesManager

The UserPropertiesManager interface provides access to UserProperties associated with a given authorizable.

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_RANKING Constant for the ranking property.
static java.util.Comparator<Node>	DESCENDING_RANKING_COMPARATOR Comparator used to sort UserProperties by descending ranking.
static java.lang.String	GRANITE_RANKING Constant for the ranking property name.
static java.lang.String	JCR_TITLE Constant for the UserProperties name.

Method Summary

Modifier and Type	Method and Description
boolean	addReaders(UserProperties userProperties, java.security.Principal... principals) Grant read permission on the UserProperties to the given Principal.
UserPropertiesQueryParams	createQueryParams() Creates a new instance of UserPropertiesQueryParams that can be used during a call to query(UserPropertiesQueryParams, String).
UserProperties	createUserProperties(java.lang.String authorizableId, java.lang.String relPath) Create a new instance of UserProperties.
java.util.Iterator<UserProperties>	getMemberOfUserProperties(java.lang.String authorizableId, java.lang.String relPath, boolean declaredOnly) Returns an iterator over the properties of all groups that the authorizable with authorizableId is a member of.
java.util.Iterator<UserProperties>	getMemberUserProperties(Group group, java.lang.String relPath, boolean declaredOnly) Returns an iterator over the user properties of all members of the given group.
UserProperties	getUserProperties(Authorizable authorizable, java.lang.String relPath) Retrieve the user properties identified by the given relative path and the specified authorizable.
UserProperties	getUserProperties(Node userPropertiesNode) Retrieve the user properties identified by the given node.
UserProperties	getUserProperties(java.lang.String authorizableId, java.lang.String relPath) Retrieve the user properties identified by the given relative path and the specified authorizable ID.
UserProperties	getUserProperties(java.lang.String authorizableId, java.lang.String relRootPath, java.util.Comparator<Node> comparator) Retrieves with the given session a composite (aggregation) of UserProperties associated with the authorizable identified by the given authorizableId.
UserPropertiesComposite	getUserPropertiesComposite(java.lang.String authorizableId, java.lang.String relRootPath) Deprecated. Use getUserProperties(String, String, Comparator) instead.
UserPropertiesComposite	getUserPropertiesComposite(java.lang.String authorizableId, java.lang.String[] relPaths) Deprecated. Use getUserProperties(String, String, Comparator) instead.
UserPropertiesComposite	getUserPropertiesComposite(java.lang.String authorizableId, java.lang.String relRootPath, java.util.Comparator<Node> comparator) Deprecated. Use getUserProperties(String, String, Comparator) instead.
UserPropertiesComposite	getUserPropertiesComposite(java.lang.String authorizableId, UserPropertiesFilter filter) Deprecated. Use getUserProperties(String, String, Comparator) instead.
java.util.Iterator<UserProperties>	query(UserPropertiesQueryParams params, java.lang.String relPath) Searches the user properties matching the given query parameters.
boolean	removeReaders(UserProperties userProperties, java.security.Principal... principals) Remove read permission granted on the UserProperties to the given Principal.

Field Detail

JCR_TITLE

static final java.lang.String JCR_TITLE

Constant for the UserProperties name.

GRANITE_RANKING

static final java.lang.String GRANITE_RANKING

Constant for the ranking property name.

See Also:

Constant Field Values

DEFAULT_RANKING

static final int DEFAULT_RANKING

Constant for the ranking property.

See Also:

Constant Field Values

DESCENDING_RANKING_COMPARATOR

static final java.util.Comparator<Node> DESCENDING_RANKING_COMPARATOR

Comparator used to sort UserProperties by descending ranking.

Method Detail

createUserProperties

UserProperties createUserProperties(java.lang.String authorizableId,
                                    java.lang.String relPath)
                             throws RepositoryException

Create a new instance of UserProperties. Please note that javax.jcr.Session#save() must be called by the editing JCR session in order to persist the new user properties.

Parameters:

authorizableId - The ID of the associated authorizable.

relPath - A name or relative path identifying the new user properties.

Returns:

A new UserProperties instance. Note that the associated JCR node will be NEW until Session.save is called to persist the changes.

Throws:

javax.jcr.RepositoryException - If an error occurs or the specified relative path is invalid.

RepositoryException

getUserProperties

UserProperties getUserProperties(java.lang.String authorizableId,
                                 java.lang.String relPath)
                          throws RepositoryException

Retrieve the user properties identified by the given relative path and the specified authorizable ID.

Parameters:

authorizableId - Identifier of the target authorizable.

relPath - A name or relative path identifying the user properties.

Returns:

An instance of UserProperties or null if the authorizable does not exist or it has no user properties at the specified relative path.

Throws:

RepositoryException - If an error occurs or the specified relative path is invalid.

getUserProperties

UserProperties getUserProperties(Authorizable authorizable,
                                 java.lang.String relPath)
                          throws RepositoryException

Retrieve the user properties identified by the given relative path and the specified authorizable.

Parameters:

authorizable - The target authorizable.

relPath - A name or relative path identifying the user properties.

Returns:

An instance of UserProperties or null if the authorizable has no user properties at the specified relative path.

Throws:

RepositoryException - If an error occurs or the specified relative path is invalid.

getUserProperties

UserProperties getUserProperties(Node userPropertiesNode)
                          throws RepositoryException

Retrieve the user properties identified by the given node.

Parameters:

userPropertiesNode - The node representing the user properties.

Returns:

The user properties identified by the given node.

Throws:

RepositoryException - If an exception occurs or if the given node does not represent valid user properties (e.g. not associated with an authorizable).

getUserProperties

UserProperties getUserProperties(java.lang.String authorizableId,
                                 java.lang.String relRootPath,
                                 java.util.Comparator<Node> comparator)
                          throws RepositoryException

Retrieves with the given session a composite (aggregation) of UserProperties associated with the authorizable identified by the given authorizableId. The UserProperties are ordered using the given Comparator prior to be aggregated. See example in getUserPropertiesComposite(String, String).

Parameters:

authorizableId - The ID of the Authorizable for which to retrieve the user properties composite.

relRootPath - relative root path for the properties to be obtained; if null UserPropertiesService.PROFILES_ROOT will be used as default.

comparator - The comparator used to sort candidates in a specific order

Returns:

A UserProperties aggregating the properties contained below relRootPath ordered using the given comparator.

Throws:

RepositoryException - If an error occurs during repository access or no authorizable was found with the given authorizableId.

getUserPropertiesComposite

UserPropertiesComposite getUserPropertiesComposite(java.lang.String authorizableId,
                                                   java.lang.String[] relPaths)
                                            throws RepositoryException

Deprecated. Use getUserProperties(String, String, Comparator) instead.

Retrieves a composite (aggregation) of UserProperties associated with the authorizable identified by the given authorizableId and corresponding to and in the order of the given relPaths. The ordering is relevant for e.g. accessing a property found on multiple user property nodes, in which case it is inherited according to the order (last has precedence).

Parameters:

authorizableId - The ID of the Authorizable for which to retrieve the user properties composite.

relPaths - An array of strings denoting the desired relative paths of the user property nodes and their order in which to be included in the composite.

Returns:

A composite of UserProperties.

Throws:

RepositoryException - If an error occurs during repository access or no authorizable was found with the given authorizableId.

getUserPropertiesComposite

UserPropertiesComposite getUserPropertiesComposite(java.lang.String authorizableId,
                                                   UserPropertiesFilter filter)
                                            throws RepositoryException

Deprecated. Use getUserProperties(String, String, Comparator) instead.

Retrieves a composite (aggregation) of UserProperties associated with the authorizable identified by the given authorizableId and included by the given filter.

Parameters:

authorizableId - The ID of the Authorizable for which to retrieve the user properties composite.

filter - A UserPropertiesFilter by which user properties are included or excluded.

Returns:

A UserPropertiesComposite containing the UserProperties included by the filter.

Throws:

RepositoryException - If an error occurs during repository access or no authorizable was found with the given authorizableId.

getUserPropertiesComposite

UserPropertiesComposite getUserPropertiesComposite(java.lang.String authorizableId,
                                                   java.lang.String relRootPath)
                                            throws RepositoryException

Deprecated. Use getUserProperties(String, String, Comparator) instead.

Retrieves a composite (aggregation) of UserProperties associated with the authorizable identified by the given authorizableId. The UserProperties are retrieved with the javax.jcr.Session passed to the @{link UserPropertiesManager}, then are ordered by descending ranking using DESCENDING_RANKING_COMPARATOR prior to being aggregated. The table below illustrates this behavior.

	Profile 1 value	Profile 2 value	Profile 3 value	Value returns by UserPropertiesComposite
Is Readable by user session	No	Yes	Yes	-
Ranking	700	500	100	-
Name	Robert Jnr	Robert	Bob	Robert
Age	(undefined)	(undefined)	25	25
email	robert.private@example.com	(undefined)	(undefined)	(undefined)

Parameters:

authorizableId - The ID of the Authorizable for which to retrieve the user properties composite.

relRootPath - relative root path of the UserProperties to be aggregated

Returns:

A UserPropertiesComposite containing the UserProperties

Throws:

RepositoryException - If an error occurs during repository access or no authorizable was found with the given authorizableId.

getUserPropertiesComposite

UserPropertiesComposite getUserPropertiesComposite(java.lang.String authorizableId,
                                                   java.lang.String relRootPath,
                                                   java.util.Comparator<Node> comparator)
                                            throws RepositoryException

Deprecated. Use getUserProperties(String, String, Comparator) instead.

Retrieves with the given session a composite (aggregation) of UserProperties associated with the authorizable identified by the given authorizableId. The UserProperties are ordered using the given Comparator prior to be aggregated. The UserPropertiesComposite will contain the most private properties accessible by the user session. See example in getUserPropertiesComposite(String, String).

Parameters:

authorizableId - The ID of the Authorizable for which to retrieve the user properties composite.

relRootPath - relative root path

comparator - The comparator used to sort candidates in a specific order

Returns:

A UserPropertiesComposite containing the UserProperties.

Throws:

RepositoryException - If an error occurs during repository access or no authorizable was found with the given authorizableId.

getMemberOfUserProperties

java.util.Iterator<UserProperties> getMemberOfUserProperties(java.lang.String authorizableId,
                                                             java.lang.String relPath,
                                                             boolean declaredOnly)
                                                      throws RepositoryException

Returns an iterator over the properties of all groups that the authorizable with authorizableId is a member of. please note that only groups are included of which the underlying session has read access to.

Parameters:

authorizableId - the id of the authorizable

relPath - the relative path to build the user properties from

declaredOnly - if true only declared groups are included

Returns:

an iterator of user properties

Throws:

RepositoryException - if an error occurs

See Also:

Authorizable.memberOf(), Authorizable.declaredMemberOf()

getMemberUserProperties

java.util.Iterator<UserProperties> getMemberUserProperties(Group group,
                                                           java.lang.String relPath,
                                                           boolean declaredOnly)
                                                    throws RepositoryException

Returns an iterator over the user properties of all members of the given group.

Parameters:

group - the group to retrieve the members from

relPath - the relative path to build the user properties from

declaredOnly - if true only declared members are included

Returns:

an iterator of user properties

Throws:

RepositoryException - if an error occurs

See Also:

Group.getMembers(), Group.getDeclaredMembers()

addReaders

boolean addReaders(UserProperties userProperties,
                   java.security.Principal... principals)
            throws RepositoryException

Grant read permission on the UserProperties to the given Principal. The permissions are set using the session provided while obtaining the UserPropertiesManager instance. Principal can be retrieved with PrincipalManager.getPrincipal(String). Similarly Everyone Principal can be retrieved with PrincipalManager.getEveryone().

Parameters:

userProperties - user properties to which readers should be added

principals - Principal to which read access must be granted

Returns:

true if permissions have been modified

Throws:

RepositoryException - if an error occurs or the editing session is not allowed to modify access control

removeReaders

boolean removeReaders(UserProperties userProperties,
                      java.security.Principal... principals)
               throws RepositoryException

Remove read permission granted on the UserProperties to the given Principal. The permissions are updated using the session provided while obtaining the UserPropertiesManager instance. Note that the Authorizable may keep having read access to the UserProperties if inherited from group membership or glob permissions.

Parameters:

userProperties - user properties to which readers should be removed

principals - Principal to which read access must be revoked

Returns:

true if permissions have been modified

Throws:

RepositoryException - if an error occurs or the editing session is not allowed to modify access control

createQueryParams

UserPropertiesQueryParams createQueryParams()

Creates a new instance of UserPropertiesQueryParams that can be used during a call to query(UserPropertiesQueryParams, String).

Returns:

a new instance of UserPropertiesQueryParams.

query

java.util.Iterator<UserProperties> query(UserPropertiesQueryParams params,
                                         java.lang.String relPath)
                                  throws RepositoryException

Searches the user properties matching the given query parameters.

Performance

The client of this method is responsible to review the underlying query performance related to the given relPath. Typically this is about creating an appropriate Oak index.

For example, inspect the authorizable index. See /oak:index/authorizables/ in your crx/de instance.

Also the user has to have jcr:read access to the node denoted by relPath.

Parameters:

params - the parameters of the query. If the AuthorizableTypes criterion from the parameters is not specified, all the authorizable types will be included in the query result.

relPath - the name or relative path identifying the user properties, such as profile.

Returns:

the iterator of UserProperties as the result of the query.

Throws:

RepositoryException - when there is an exception when accessing the repository.