Package com.sas.services.user

# Interface ProfileInterface

All Superinterfaces:
  `Remote`

All Known Subinterfaces:
  `GlobalProfileInterface`

All Known Implementing Classes:
  `Profile`

public interface ProfileInterface extends Remote
The Profile class maintains information about a user that generally pertains to a specific application. Each profile can store subprofiles so they can be searched hierarchically. The root of the profile "tree" is the global profile. It contains information that doesn't really apply to a single application (like the user's name). An example of an application string is:
Solutions.SalesVision.Reports
Each level of the hierarchy can contain information about the user. For instance, the Solutions application may contain information whose scope spans all of the applications under it. The SalesVision application can have profile information specific to it, and the Reports profile can have SalesVision report preferences and customizations stored under it.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `NO_BACK_END_MSG_KEY`
  The key into the local resource bundle for the exception message that indicates that a profile cannot be loaded because it is not associated with a profile repository.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addAttribute(String application, String key, String value)`
  Add a value to an attribute.
  `void`
  `addProfile(String application, ProfileInterface profile, boolean force)`
  Add a new application profile as a subprofile to this one.
  `void`
  `create(MetadataInterface root, UserContextInterface user, RepositoryInterface repos, ProfileDomain pd)`
  Create a new profile object in the metadata store.
  `void`
  `createSubprofile(ProfileInterface profile)`
  Create a new subprofile under this profile in the same repository.
  `void`
  `deleteProfile(String application)`
  Delete a Profile from the metadata and the profile hierarchy.
  `void`
  `destroy()`
  Destroy any resources held by this profile instance and its subordinates.
  `Map`
  `getAllAttributes(String application)`
  Get all of the attributes in this Profile.
  `String`
  `getApplication()`
  Get the application string for this profile.
  `String`
  `getAttribute(String application, String key)`
  Get an attribute from a profile.
  `List`
  `getAttributes(String application, String key)`
  Get all the attributes for a key.
  `Locale`
  `getLocale(String application)`
  Get the profile locale.
  `ProfileInterface`
  `getParentProfile()`
  Get the profile that's the parent of this one.
  `String`
  `getPathFromRoot()`
  Get the application path string from the root to this profile object.
  `ProfileInterface`
  `getProfile(String application)`
  Get a Profile object associated with a given application string.
  `ProfileInterface`
  `getProfile(String application, boolean create)`
  Get a Profile object associated with a given application string.
  `ProfileInterface`
  `getRootProfile()`
  Follow the parent chain up to the root of the preference tree.
  `UserContextInterface`
  `getUserContext()`
  Get a handle to the UserContext that owns this profile.
  `boolean`
  `isLoaded()`
  Get a flag indicating if the profile has been successfully loaded.
  `Set`
  `keySet()`
  Gets the set of attribute keys.
  `void`
  `load(MetadataInterface root, UserContextInterface user, RepositoryInterface repos, ProfileDomain pd)`
  Load user profile information from a repository.
  `void`
  `persist(String application, boolean recursive)`
  Write any changes to the profile back to the persistent store.
  `void`
  `refresh()`
  Causes a re-fetch of data from the back-end store.
  `void`
  `removeAttribute(String application, String key)`
  Remove an attribute from the profile.
  `boolean`
  `removeProfile(String application)`
  Remove an application profile from the profile tree.
  `void`
  `setAttribute(String application, String key, String value)`
  Set the value of an attribute in an application profile.
  `void`
  `setLoadParameters(MetadataInterface root, UserContextInterface user, RepositoryInterface repos, ProfileDomain pd)`
  Set the parameters necessary to load the profile from a backing store.
  `void`
  `setLocale(String application, Locale locale)`
  Set the profile locale.
  `void`
  `setParentProfile(ProfileInterface parent)`
  Set the parent profile in the preference tree.
  `void`
  `setRefreshCycle(long refreshInMillis)`
  Set the refresh cycle for this profile instance.
  `Collection`
  `values()`
  Gets a collection of values.

- ## Field Details

  - ### NO_BACK_END_MSG_KEY

    static final String NO_BACK_END_MSG_KEY
    The key into the local resource bundle for the exception message that indicates that a profile cannot be loaded because it is not associated with a profile repository. An exception with this message would be thrown when trying to access the profile of a PUBLIC user or when trying to access the profile of a user whose context is not yet fully initialized.
    See Also:
      - Constant Field Values

- ## Method Details

  - ### getUserContext

    UserContextInterface getUserContext() throws RemoteException
    Get a handle to the UserContext that owns this profile.
    Returns:
      The owner UserContextInterface.
    Throws:
      `RemoteException` - In the event of remote object failure.

  - ### setRefreshCycle

    void setRefreshCycle(long refreshInMillis) throws RemoteException
    Set the refresh cycle for this profile instance. After the specified number of milliseconds, the data is considered stale and any attributes that have not been updated will be retrieved from the backing store. The default is -1, which means that no automatic refresh will be done.
    Parameters:
      `refreshInMillis` - Number of milliseconds that the profile information is considered valid.
    Throws:
      `RemoteException` - in the event of remote object failure.

  - ### isLoaded

    boolean isLoaded() throws RemoteException
    Get a flag indicating if the profile has been successfully loaded.

    Returns:
      True if the profile is loaded, false otherwise.
    Throws:
      `RemoteException` - in the event of remote object failure.

  - ### getApplication

    String getApplication() throws RemoteException
    Get the application string for this profile.

    Returns:
      The application string.
    Throws:
      `RemoteException` - in the event of remote object failure.

  - ### getAllAttributes

    Map getAllAttributes(String application) throws RemoteException, ServiceException
    Get all of the attributes in this Profile. Each value in the Map will be a List containing the values for the attribute. The List will contain Strings unless the Profile instance is a custom subclass.
    Parameters:
      `application` - The application path for the profile to get the attribute map for.
    Returns:
      The attribute Map.
    Throws:
      `ServiceException` - if there is no profile matching the application string.
      `RemoteException` - in the event of remote object failure.

  - ### getAttribute

    String getAttribute(String application, String key) throws RemoteException, ServiceException
    Get an attribute from a profile. This gets a single value, even though there may be multiple values in the profile. This method takes a full path for the application string, and searches up the profile tree to find a value for the key. This method should return the most specific value for a profile item that's available.

    Parameters:
      `application` - The application string to search with. This is a dot-separated list of application names, which should specify the most specific location to start looking for the key.
      `key` - The key of the attribute to return.
    Returns:
      The object stored at that key, or null if none is found.
    Throws:
      `ServiceException` - If there is no profile that matches the application string.
      `RemoteException` - if a networking exception is encountered.

  - ### getAttributes

    List getAttributes(String application, String key) throws RemoteException, ServiceException
    Get all the attributes for a key. This will return all matching values in a List. The profile tree is searched from the root for any application that matches the application string which has a value for the key requested. All the values that are found are returned.

    Parameters:
      `application` - The application string to search with. This is a dot-separated list of application names, which can include "*" as a wildcard.
      `key` - The key of the attribute to return.
    Returns:
      A List of Objects stored under the given key.
    Throws:
      `ServiceException` - If there is no profile that matches the application string.
      `RemoteException` - in the event of a remote communication failure.

  - ### getProfile

    ProfileInterface getProfile(String application) throws RemoteException, ServiceException
    Get a Profile object associated with a given application string. The string is a slash-separated list of names. Wildcards are not supported for this operation. The path is relative from the current profile. That is a given application profile may be at "SAS/Solutions/FM" from the global profile, but from the Solutions profile, it would be just "FM".

    Parameters:
      `application` - The application to return the profile for.
    Returns:
      The Profile that matches the application string.
    Throws:
      `ServiceException` - if no Profile matching the application string is found.
      `RemoteException` - in the event of a remote communication failure.

  - ### getProfile

    ProfileInterface getProfile(String application, boolean create) throws RemoteException, ServiceException
    Get a Profile object associated with a given application string. The string is a slash-separated list of names. Wildcards are not supported for this operation.

    Parameters:
      `application` - The application to return the profile for.
      `create` - If true, the profile will be created if it doesn't already exist.
    Returns:
      The Profile that matches the application string.
    Throws:
      `ServiceException` - if no Profile matching the application string is found.
      `RemoteException`

  - ### setAttribute

    void setAttribute(String application, String key, String value) throws RemoteException, ServiceException
    Set the value of an attribute in an application profile. Any existing value(s) will be cleared in favor of the new value.

    Parameters:
      `application` - A dot-separated list of application names. Wildcards are not accepted for this operation.
      `key` - The attribute key to set.
      `value` - The new value for the key. If this value is null, any existing value(s) are removed for the application.
    Throws:
      `ServiceException` - If there is no profile for the application string.
      `RemoteException` - in the event of a remote communication failure.

  - ### addAttribute

    void addAttribute(String application, String key, String value) throws RemoteException, ServiceException
    Add a value to an attribute. This value is added to the set of any existing values for the key in the application.

    Parameters:
      `application` - A dot-separated list of application strings. Wildcard operations are not allowed here.
      `key` - The attribute key to add a value for.
      `value` - The new value to add.
    Throws:
      `ServiceException` - If there is no profile for the given application string.
      `RemoteException` - in the event of a remote communication failure.

  - ### removeAttribute

    void removeAttribute(String application, String key) throws RemoteException, ServiceException
    Remove an attribute from the profile.
    Parameters:
      `application` - A dot-separated list of application strings. Wildcard operations are not allowed here.
      `key` - The attribute key to add a value for.
    Throws:
      `ServiceException` - If there is no profile for the given application string.
      `RemoteException` - in the event of a remote communication failure.

  - ### setParentProfile

    void setParentProfile(ProfileInterface parent) throws ServiceException, RemoteException
    Set the parent profile in the preference tree. This should ordinarily be done only by the UserService code when loading the profile hierarchy, unless a custom profile is being used.
    Parameters:
      `parent` - The parent profile for this one.
    Throws:
      `ServiceException` - In the event of service failure.
      `RemoteException` - In the event of remote object failure.

  - ### getParentProfile

    ProfileInterface getParentProfile() throws ServiceException, RemoteException
    Get the profile that's the parent of this one. If this is the global profile, a null will be returned.
    Returns:
      The ProfileInterface that's immediately above this one in the preference tree.
    Throws:
      `ServiceException` - In the event of service failure.
      `RemoteException` - in the event of remote object failure.

  - ### getRootProfile

    ProfileInterface getRootProfile() throws ServiceException, RemoteException
    Follow the parent chain up to the root of the preference tree.
    Returns:
      The root of the profile tree.
    Throws:
      `ServiceException` - If a service error occurs.
      `RemoteException` - In the event of remote object failure.

  - ### getPathFromRoot

    String getPathFromRoot() throws ServiceException, RemoteException
    Get the application path string from the root to this profile object.
    Returns:
      A String with the application path from the root profile to this one.
    Throws:
      `ServiceException` - If a service error occurs.
      `RemoteException` - In the event of remote object failure.

  - ### deleteProfile

    void deleteProfile(String application) throws ServiceException, RemoteException
    Delete a Profile from the metadata and the profile hierarchy.
    Parameters:
      `application` - The application string
    Throws:
      `ServiceException` - If the profile for the application doesn't exist, or if a back end error occurs.
      `RemoteException` - In the event of remote object failure.

  - ### createSubprofile

    void createSubprofile(ProfileInterface profile) throws ServiceException, RemoteException
    Create a new subprofile under this profile in the same repository. This method creates the profile object(s) in the backend, but does not change the in-memory profile hierarchy. This method is normally followed by a call to addProfile.

    Parameters:
      `profile` - The profile to create as a subprofile of this one.
    Throws:
      `ServiceException` - In the case of repository failure, or parameter errors.
      `RemoteException` - in the event of network problems.

  - ### addProfile

    void addProfile(String application, ProfileInterface profile, boolean force) throws RemoteException, ServiceException
    Add a new application profile as a subprofile to this one. Unless a custom profile is being used which is not in the backing store in a place that will be loaded automatically, this will usually only be called for a newly created profile. This call only adds a loaded or created profile to the in-memory profile hierarchy.

    Parameters:
      `application` - A dot-separated list of application names forming a "tree".
      `profile` - The new profile to add.
      `force` - A flag to indicate if the tree structure represented by the application string should be created if it doesn't already exist. If this is false, if the tree doesn't exist, a ServiceException will be thrown.
    Throws:
      `ServiceException` - If the force flag is false, and an application level is missing.
      `RemoteException` - in the event of a remote communication failure.

  - ### removeProfile

    boolean removeProfile(String application) throws RemoteException, ServiceException
    Remove an application profile from the profile tree. This does not delete the data from the backing store.

    Parameters:
      `application` - The application string that identifies the profile to remove. This is a dot-separated application list.
    Returns:
      A flag that indicates if the remove was successful.
    Throws:
      `ServiceException` - If the application string is invalid (null or zero length).
      `RemoteException` - in the event of a remote communication failure.

  - ### keySet

    Set keySet() throws RemoteException
    Gets the set of attribute keys.
    Returns:
      Key set.
    Throws:
      `RemoteException` - if a networking exception is encountered.

  - ### values

    Collection values() throws RemoteException
    Gets a collection of values.
    Returns:
      Collection of values.
    Throws:
      `RemoteException` - if a networking exception is encountered.

  - ### refresh

    void refresh() throws ServiceException, RemoteException
    Causes a re-fetch of data from the back-end store. This will be recursive down the profile hierarchy.
    Throws:
      `ServiceException` - If a data repository exception occurs.
      `RemoteException` - In the event of remote object failure.

  - ### persist

    void persist(String application, boolean recursive) throws RemoteException, ServiceException
    Write any changes to the profile back to the persistent store. This call is required after any attribute changes to commit those changes to the backing store.

    Parameters:
      `application` - The appliation string that identitfies the profile to persist.
      `recursive` - If this flag is true, all profiles below the one specified in the application string will be persisted.
    Throws:
      `ServiceException` - If the application string is invalid or isn't found in the profile "tree".
      `RemoteException` - in the event of a remote communication failure.

  - ### setLoadParameters

    void setLoadParameters(MetadataInterface root, UserContextInterface user, RepositoryInterface repos, ProfileDomain pd) throws RemoteException, ServiceException
    Set the parameters necessary to load the profile from a backing store.
    Parameters:
      `root` - The object off which the profile information is anchored.
      `user` - The UserContextInterface to which the profile belongs.
      `repos` - The RepositoryInterface in which the profile is stored.
      `pd` - The configuration information for the Profile.
    Throws:
      `ServiceException` - In the event of repository failure.
      `RemoteException` - if a networking issue is encountered.

  - ### load

    void load(MetadataInterface root, UserContextInterface user, RepositoryInterface repos, ProfileDomain pd) throws RemoteException, ServiceException
    Load user profile information from a repository. Store the new profile information as subprofile(s) of the profile supplied.

    Parameters:
      `root` - The object that the profile is "rooted" to. This will be a Person object for the first-level profile, but may be another property set, or other entity for lower level profiles.
      `user` - User context.
      `repos` - The repository to load from.
      `pd` - The profile to add the new information to.
    Throws:
      `ServiceException` - In the event of repository failure.
      `RemoteException` - in the event of a remote communication failure.

  - ### create

    void create(MetadataInterface root, UserContextInterface user, RepositoryInterface repos, ProfileDomain pd) throws RemoteException, ServiceException
    Create a new profile object in the metadata store. This will normally be called by the Profile.addProfile() method when a new profile is added.

    Parameters:
      `root` - The object that the profile is "rooted" to. This will be a Person object for the first-level profile, but may be another property set, or other entity for lower level profiles.
      `user` - User context.
      `repos` - The repository to load from.
      `pd` - The profile to add the new information to.
    Throws:
      `ServiceException` - In the event of repository failure.
      `RemoteException` - in the event of a remote communication failure.

  - ### setLocale

    void setLocale(String application, Locale locale) throws ServiceException, RemoteException
    Set the profile locale.

    Parameters:
      `application` - The application to set the locale for.
      `locale` - A Locale object to use for this application.
    Throws:
      `ServiceException` - in the event of errors.
      `RemoteException` - in the event of remote object failure.

  - ### getLocale

    Locale getLocale(String application) throws ServiceException, RemoteException
    Get the profile locale.

    Parameters:
      `application` - The application to get the locale for.
    Returns:
      The profile locale for this application.
    Throws:
      `ServiceException` - If the application string is invalid.
      `RemoteException` - in the event of remote object failure.

  - ### destroy

    void destroy() throws RemoteException
    Destroy any resources held by this profile instance and its subordinates.
    Throws:
      `RemoteException` - In the event of remote object failure.