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 Detail

      • JCR_TITLE

        static final java.lang.String JCR_TITLE
        Constant for the UserProperties name.
        See Also:
        Constant Field Values

      • 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

        @CheckForNull
UserProperties createUserProperties​(@Nonnull
                                    java.lang.String authorizableId,
                                    @Nonnull
                                    java.lang.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
                                 java.lang.String authorizableId,
                                 @Nullable
                                 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

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

        @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
                                 java.lang.String authorizableId,
                                 @Nullable
                                 java.lang.String relRootPath,
                                 @Nonnull
                                 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

        @Nonnull
UserPropertiesComposite getUserPropertiesComposite​(@Nonnull
                                                   java.lang.String authorizableId,
                                                   @Nullable
                                                   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 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.

      • getMemberOfUserProperties

        @Nonnull
java.util.Iterator<UserProperties> getMemberOfUserProperties​(@Nonnull
                                                             java.lang.String authorizableId,
                                                             @Nonnull
                                                             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

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

      • query

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