Package com.adobe.granite.security.user

Interface UserProperties

@ProviderType
public interface UserProperties

UserProperties is a general interface used to represent user preferences and profiles. It provides convenience methods to retrieve properties in various formats.

The properties are either read from a single node or are composed from an list of nodes. Such a composite can be retrieved via UserPropertiesManager.getUserProperties(String, String, Comparator). The comparator will define the order in which a given property is read from the composite in case it is present in more than one of the enclosed UserProperties.

In addition this interface allows to access the underlying JCR Node used to write or modify this UserProperties, version or lock it as well as to register observation event listeners. In case of a singular UserProperties object this is the node the information is read from. In case of composite the it's the node representing the relative root path specified in UserPropertiesManager.getUserProperties(String, String, Comparator).

Field Summary

Fields

Modifier and Type	Field	Description
static String	ABOUT_ME	Constant for the property containing a description of an authorizable.
static String	DISPLAY_NAME	Constant for the display name (or nick name) property of a given user or group.
static String	EMAIL	Constant for the email property of an authorizable.
static String	FAMILY_NAME	Constant for the family name of a given user.
static String	GIVEN_NAME	Constant for the given name of a given user or group.
static String	MIDDLE_NAME	Constant for the middle name property of a user.
static String	PHOTOS	Constant for the user property storing images of a user.

Method Summary

Modifier and Type	Method	Description
List<UserProperties>	getAggregatedUserProperties()	Returns a list of UserProperties enclosed within this instance or an empty list if this instance doesn't represent an aggregation of UserProperties.
String	getAuthorizableID()	Returns the ID of the authorizable this user properties belong to.
String	getAuthorizablePath()	Returns the authorizables path
String	getDisplayName()	Calculate a display name from this UserProperties instance.
String	getDisplayName(String nameDisplayOrder)	Calculate a display name from this UserProperties instance.
Node	getNode()	Returns the JCR node associated with this user properties instance.
String	getPrincipalName()	Returns the principal name of the authorizable.
String	getProperty(String relativePath)	Returns the string value of the property identified by the specified relativePath.
<T> T	getProperty(String relativePath, T defaultValue, Class<T> type)	Same as getProperty(String).
String[]	getPropertyNames()	Retrieves all first-level property names found on the underlying Node or on all enclosed user properties in case this instance is the result of aggregation.
String[]	getPropertyNames(String relPath)	Retrieves all property names available at the specified relative path on the underlying Node or on the enclosed UserProperties in case this instance is the result of aggregation.
Resource	getResource(String relativePath)	Retrieve the resource at the specified path relative to this instance.
String	getResourcePath(String relativePath, String suffix, String defaultPath)	Calculates the resource path for the property located the specified relativePath using the given suffix.
Iterator<Resource>	getResources(String relativePath)	Retrieve the resources at the specified path relative to this instance.
boolean	isGroupProperties()	Checks if the authorizable of this properties is a group.

Field Detail

ABOUT_ME

static final String ABOUT_ME

Constant for the property containing a description of an authorizable.

See Also:

Constant Field Values

EMAIL

static final String EMAIL

Constant for the email property of an authorizable.

See Also:

Constant Field Values

FAMILY_NAME

static final String FAMILY_NAME

Constant for the family name of a given user.

See Also:

Constant Field Values

GIVEN_NAME

static final String GIVEN_NAME

Constant for the given name of a given user or group.

See Also:

Constant Field Values

MIDDLE_NAME

static final String MIDDLE_NAME

Constant for the middle name property of a user.

See Also:

Constant Field Values

DISPLAY_NAME

static final String DISPLAY_NAME

Constant for the display name (or nick name) property of a given user or group. See also getDisplayName() for a implementation specific calculation of a display name that may rely on or fallback to various name related properties.

See Also:

Constant Field Values

PHOTOS

static final String PHOTOS

Constant for the user property storing images of a user.

See Also:

Constant Field Values

Method Detail

getAuthorizableID

@Nonnull
String getAuthorizableID()

Returns the ID of the authorizable this user properties belong to.

Returns:

the ID of the authorizable this user properties belong to.

getAuthorizablePath

@Nonnull
String getAuthorizablePath()

Returns the authorizables path

Returns:

the path of the authorizable.

getPrincipalName

@Nonnull
String getPrincipalName()

Returns the principal name of the authorizable.

Returns:

The principal name.

getNode

@CheckForNull
Node getNode()

Returns the JCR node associated with this user properties instance. The node may then be used to write properties or execute other JCR specific operations on this user properties that are not covered by convenience methods defined by this interface. If this instance is composed of multiple enclosed UserProperties, this method will return the Node representing the relative root path as specified with UserPropertiesManager.getUserProperties(String, String, Comparator). If that node is not accessible to the editing session, this method will return null.

Returns:

the node associated with this user properties instance or null if the node is not accessible.

getPropertyNames

@Nonnull
String[] getPropertyNames()
                   throws RepositoryException

Retrieves all first-level property names found on the underlying Node or on all enclosed user properties in case this instance is the result of aggregation. This is the same as getPropertyNames(String) where the relative path is null.

Returns:

An array of property names.

Throws:

RepositoryException - If an error occurs.

getPropertyNames

@Nonnull
String[] getPropertyNames(@Nullable
                          String relPath)
                   throws RepositoryException

Retrieves all property names available at the specified relative path on the underlying Node or on the enclosed UserProperties in case this instance is the result of aggregation. If relPath is null, the names are obtained from the node directly (and not from a subtree).

Parameters:

relPath - A relative path to the sub tree where to retrieve the property names.

Returns:

An array of property names.

Throws:

RepositoryException - If an error occurs.

getProperty

@CheckForNull
String getProperty(@Nonnull
                   String relativePath)
            throws RepositoryException

Returns the string value of the property identified by the specified relativePath. This may be a simple property name in case of getPropertyNames() or the relative path to the property in case of getPropertyNames(String).

Note that this method is a simplified variant of getProperty(String, Object, Class) where the default value is null and the desired type String.

In case of aggregation the referenced property may be found on multiple enclosed UserProperties. In this case the order of the underlying UserProperties will determine, which property value will be exposed. The order of the user properties is governed by explicitly specifying the order in UserPropertiesManager.getUserProperties(String, String, Comparator).

Parameters:

relativePath - Relative path referring to the property to be retrieved.

Returns:

The string value of the specified property or null.

Throws:

RepositoryException - If an error occurs.

getProperty

@CheckForNull
<T> T getProperty(@Nonnull
                  String relativePath,
                  @Nullable
                  T defaultValue,
                  @Nonnull
                  Class<T> type)
           throws RepositoryException

Same as getProperty(String). Additionally the expected format of the property value is specified by the type parameter. If no property exists at relativePath the specified defaultValue is returned.

Type Parameters:

T - specifies the expected format of the property

Parameters:

relativePath - Relative path referring to the property to be retrieved.

defaultValue - The default value to be used if the property at relativePath does not exist.

type - The expected value type. The property value may need to be converted.

Returns:

The value of the specified property converted to the specified type or the defaultValue if the property does not exist or cannot be converted to the specified type.

Throws:

RepositoryException - If an error occurs.

getResource

@CheckForNull
Resource getResource(@Nonnull
                     String relativePath)
              throws RepositoryException

Retrieve the resource at the specified path relative to this instance.

Parameters:

relativePath - Relative path to the resource to be retrieved.

Returns:

The resource at the specified relative path or null if the the path cannot be resolved to a resource.

Throws:

RepositoryException - If an error occurs.

getResources

@CheckForNull
Iterator<Resource> getResources(@Nonnull
                                String relativePath)
                         throws RepositoryException

Retrieve the resources at the specified path relative to this instance.

Parameters:

relativePath - Relative path to the resources to be retrieved.

Returns:

The resources at the specified relative path or null if the the path cannot be resolved to resources.

Throws:

RepositoryException - If an error occurs.

getResourcePath

@Nonnull
String getResourcePath(@Nonnull
                       String relativePath,
                       @Nullable
                       String suffix,
                       @Nonnull
                       String defaultPath)
                throws RepositoryException

Calculates the resource path for the property located the specified relativePath using the given suffix. If the property does not exist the specified defaultPath is returned.

Parameters:

relativePath - Relative path to the property for which the resource path will be calculated.

suffix - An optional suffix to be appended to the resource path.

defaultPath - An optional default path in case the requested property does not exist (or is not accessible).

Returns:

The resource path for the requested property or the default path.

Throws:

RepositoryException - If an error occurs.

getDisplayName

@Nonnull
String getDisplayName()
               throws RepositoryException

Calculate a display name from this UserProperties instance.

Returns:

Implementation specific display name as stored in this user properties instance or some implementation specific default.

Throws:

RepositoryException - If an error occurs.

getDisplayName

@Nonnull
String getDisplayName(@Nullable
                      String nameDisplayOrder)
               throws RepositoryException

Calculate a display name from this UserProperties instance.

Parameters:

nameDisplayOrder - Order of given, middle and family names. Western name order should be "givenName middleName familyName", Eastern name order should be "familyName givenName middleName".

Returns:

Implementation specific display name as stored in this user properties instance or some implementation specific default.

Throws:

RepositoryException - If an error occurs.

isGroupProperties

boolean isGroupProperties()

Checks if the authorizable of this properties is a group.

Returns:

true if this properties belongs to a group.

getAggregatedUserProperties

@Nonnull
List<UserProperties> getAggregatedUserProperties()

Returns a list of UserProperties enclosed within this instance or an empty list if this instance doesn't represent an aggregation of UserProperties.

Returns:

The collection of aggregated user properties or an empty collection if there are no aggregated properties.