Package com.adobe.granite.security.user

Interface UserPropertiesManager

@ProviderType
public interface UserPropertiesManager

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

Field Summary

Fields

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

Method Summary

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

Field Detail

JCR_TITLE

static final String JCR_TITLE

Constant for the UserProperties name.

See Also:

Constant Field Values

GRANITE_RANKING

static final 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 Comparator<Node> DESCENDING_RANKING_COMPARATOR

Comparator used to sort UserProperties by descending ranking.

Method Detail

createUserProperties

@CheckForNull
UserProperties createUserProperties(@Nonnull
                                    String authorizableId,
                                    @Nonnull
                                    String relPath)
                             throws RepositoryException

Create a new instance of UserProperties. Please note that 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:

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

getUserProperties

@CheckForNull
UserProperties getUserProperties(@Nonnull
                                 String authorizableId,
                                 @Nullable
                                 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

@CheckForNull
UserProperties getUserProperties(@Nonnull
                                 Authorizable authorizable,
                                 @Nullable
                                 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

@Nonnull
UserProperties getUserProperties(@Nonnull
                                 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

@Nonnull
UserProperties getUserProperties(@Nonnull
                                 String authorizableId,
                                 @Nullable
                                 String relRootPath,
                                 @Nonnull
                                 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(String authorizableId,
                                                   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(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

@Nonnull
UserPropertiesComposite getUserPropertiesComposite(@Nonnull
                                                   String authorizableId,
                                                   @Nullable
                                                   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 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	[email protected]	(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

@Nonnull
UserPropertiesComposite getUserPropertiesComposite(@Nonnull
                                                   String authorizableId,
                                                   @Nullable
                                                   String relRootPath,
                                                   @Nonnull
                                                   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

@Nonnull
Iterator<UserProperties> getMemberOfUserProperties(@Nonnull
                                                   String authorizableId,
                                                   @Nonnull
                                                   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

@Nonnull
Iterator<UserProperties> getMemberUserProperties(@Nonnull
                                                 Group group,
                                                 @Nonnull
                                                 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(@Nonnull
                   UserProperties userProperties,
                   @Nonnull
                   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(@Nonnull
                      UserProperties userProperties,
                      @Nonnull
                      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

@Nonnull
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

@Nonnull
Iterator<UserProperties> query(@Nonnull
                               UserPropertiesQueryParams params,
                               @Nonnull
                               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.