Package com.sas.services.user

# Class Profile

java.lang.Object
java.rmi.server.RemoteObject
java.rmi.server.RemoteServer
java.rmi.server.UnicastRemoteObject
com.sas.services.user.Profile

All Implemented Interfaces:
  `ProfileInterface`, `Serializable`, `Remote`

@SASScope("ALL") @NeedsAPIReview public class Profile extends UnicastRemoteObject implements ProfileInterface
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.

This class is intended as a parent for classes that will have specific methods for accessing profile information rather than having to use keys for everything. Subclasses will also be responsible for handling the persistence of any information that is changed in the profile.

Since:
  1.0
See Also:
  - Serialized Form

- ## Field Summary

  ### Fields inherited from class java.rmi.server.RemoteObject

  `ref`

  ### Fields inherited from interface com.sas.services.user.ProfileInterface

  `NO_BACK_END_MSG_KEY`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `Profile()`
  Constructs a default profile.
  `protected`
  `Profile(Class theClass)`
  Constructs a profile and exports it to the RMI system using RMI socket factories for the specified class.
  ``
  `Profile(String application)`
  Default constructor.
  `protected`
  `Profile(String application, Class subClass)`
  Default constructor.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected void`
  `addAttribute(String key, String value)`
  Add an attribute to the current set of attributes.
  `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.
  `protected Locale`
  `attribute2Locale(String localeString)`
  `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()`
  Gets the application.
  `protected List`
  `getAttribute(String key)`
  Get an attribute from 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()`
  Determines whether or not the profile is loaded.
  `Set`
  `keySet()`
  Gets the key set for the attributes.
  `void`
  `load(MetadataInterface root, UserContextInterface user, RepositoryInterface repos, ProfileDomain pd)`
  Load user profile information from a repository.
  `protected boolean`
  `needReload()`
  `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.
  `protected void`
  `reload()`
  `protected void`
  `removeAttribute(String key)`
  `void`
  `removeAttribute(String application, String key)`
  Remove an attribute from the profile.
  `boolean`
  `removeProfile(String application)`
  Remove an application profile from the profile tree.
  `protected void`
  `setAttribute(String key, String value)`
  Set an attribute value in the profile.
  `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 the values for the attributes.

  ### Methods inherited from class java.rmi.server.UnicastRemoteObject

  `clone, exportObject, exportObject, exportObject, exportObject, exportObject, unexportObject`

  ### Methods inherited from class java.rmi.server.RemoteServer

  `getClientHost, getLog, setLog`

  ### Methods inherited from class java.rmi.server.RemoteObject

  `equals, getRef, hashCode, toString, toStub`

  ### Methods inherited from class java.lang.Object

  `finalize, getClass, notify, notifyAll, wait, wait, wait`

- ## Constructor Details

  - ### Profile

    protected Profile() throws RemoteException
    Constructs a default profile.
    Throws:
      `RemoteException` - if a networking issue is encountered.

  - ### Profile

    public Profile(String application) throws RemoteException
    Default constructor. Initializes instance variables.

    Parameters:
      `application` - Application
    Throws:
      `RemoteException` - if a networking issue is encountered.

  - ### Profile

    protected Profile(String application, Class subClass) throws RemoteException
    Default constructor. Initializes instance variables.

    Parameters:
      `application` - Application
      `subClass` - The subclass's class which will be used to determine the appropriate RMI socket factories used to export this remote object.
    Throws:
      `RemoteException` - if a networking issue is encountered.

  - ### Profile

    protected Profile(Class theClass) throws RemoteException
    Constructs a profile and exports it to the RMI system using RMI socket factories for the specified class.
    Parameters:
      `theClass` - Class to be used to determine the appropriate RMI socket factory.
    Throws:
      `RemoteException` - if unable to export a remote object to the RMI system.

- ## Method Details

  - ### setRefreshCycle

    public void setRefreshCycle(long refreshInMillis) throws RemoteException
    Set the refresh cycle for this profile instance.
    Specified by:
      `setRefreshCycle` in interface `ProfileInterface`
    Parameters:
      `refreshInMillis` - Number of milliseconds that the profile information is considered valid.
    Throws:
      `RemoteException` - in the event of remote object failure.

  - ### isLoaded

    public boolean isLoaded() throws RemoteException
    Determines whether or not the profile is loaded.
    Specified by:
      `isLoaded` in interface `ProfileInterface`
    Returns:
      `true` if the profile is loaded.
    Throws:
      `RemoteException` - if a networking issue is encountered.

  - ### getApplication

    public String getApplication() throws RemoteException
    Gets the application.
    Specified by:
      `getApplication` in interface `ProfileInterface`
    Returns:
      Application
    Throws:
      `RemoteException` - if a networking issue is encountered.

  - ### getUserContext

    public UserContextInterface getUserContext() throws RemoteException
    Description copied from interface: `ProfileInterface`
    Get a handle to the UserContext that owns this profile.
    Specified by:
      `getUserContext` in interface `ProfileInterface`
    Returns:
      The owner UserContextInterface.
    Throws:
      `RemoteException` - In the event of remote object failure.

  - ### getAllAttributes

    public Map getAllAttributes(String application) throws RemoteException, ServiceException
    Description copied from interface: `ProfileInterface`
    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.
    Specified by:
      `getAllAttributes` in interface `ProfileInterface`
    Parameters:
      `application` - The application path for the profile to get the attribute map for.
    Returns:
      The attribute Map.
    Throws:
      `RemoteException` - in the event of remote object failure.
      `ServiceException` - if there is no profile matching the application string.

  - ### getAttribute

    public 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.

    Specified by:
      `getAttribute` in interface `ProfileInterface`
    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 issue is encountered.

  - ### getAttributes

    public 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.

    Specified by:
      `getAttributes` in interface `ProfileInterface`
    Parameters:
      `application` - The application string to search with. This is a slash-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`

  - ### getAttribute

    protected List getAttribute(String key) throws RemoteException
    Get an attribute from this profile. This method should be overridden by subclasses to handle retrieving attribute from the persistent store if necessary.

    Parameters:
      `key` - The key for which to return values.
    Returns:
      A List of values that match the key. This may be an empty List, but shouldn't be null.
    Throws:
      `RemoteException`

  - ### getProfile

    public 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.

    Specified by:
      `getProfile` in interface `ProfileInterface`
    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`

  - ### getProfile

    public 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.

    Specified by:
      `getProfile` in interface `ProfileInterface`
    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

    public 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.

    Specified by:
      `setAttribute` in interface `ProfileInterface`
    Parameters:
      `application` - A slash-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`

  - ### setAttribute

    protected void setAttribute(String key, String value) throws RemoteException
    Set an attribute value in the profile. This method should be overridden in subclasses to handle special processing for persisting changes back to the store.

    Parameters:
      `key` - The key of the attribute to set.
      `value` - The new value of the attribute
    Throws:
      `RemoteException`

  - ### removeAttribute

    public void removeAttribute(String application, String key) throws RemoteException, ServiceException
    Remove an attribute from the profile.
    Specified by:
      `removeAttribute` in interface `ProfileInterface`
    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.

  - ### removeAttribute

    protected void removeAttribute(String key) throws RemoteException
    Throws:
      `RemoteException`

  - ### addAttribute

    public 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.

    Specified by:
      `addAttribute` in interface `ProfileInterface`
    Parameters:
      `application` - A slash-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`

  - ### addAttribute

    protected void addAttribute(String key, String value) throws RemoteException
    Add an attribute to the current set of attributes. This method should be overridden by subclasses to perform special processing to allow changes to be persisted.

    Parameters:
      `key` - The key of the attribute to add a value to.
      `value` - The new value to add.
    Throws:
      `RemoteException`

  - ### setParentProfile

    public void setParentProfile(ProfileInterface parent) throws ServiceException, RemoteException
    Set the parent profile in the preference tree.
    Specified by:
      `setParentProfile` in interface `ProfileInterface`
    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

    public ProfileInterface getParentProfile() throws ServiceException, RemoteException
    Description copied from interface: `ProfileInterface`
    Get the profile that's the parent of this one. If this is the global profile, a null will be returned.
    Specified by:
      `getParentProfile` in interface `ProfileInterface`
    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

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

  - ### getPathFromRoot

    public String getPathFromRoot() throws ServiceException, RemoteException
    Description copied from interface: `ProfileInterface`
    Get the application path string from the root to this profile object.
    Specified by:
      `getPathFromRoot` in interface `ProfileInterface`
    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.

  - ### createSubprofile

    public void createSubprofile(ProfileInterface profile) throws ServiceException, RemoteException
    Create a new subprofile under this profile in the same repository. The new profile object will be a child of this object.

    Specified by:
      `createSubprofile` in interface `ProfileInterface`
    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

    public void addProfile(String application, ProfileInterface profile, boolean force) throws RemoteException, ServiceException
    Add a new application profile.

    Specified by:
      `addProfile` in interface `ProfileInterface`
    Parameters:
      `application` - A slash-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`

  - ### deleteProfile

    public void deleteProfile(String application) throws ServiceException, RemoteException
    Description copied from interface: `ProfileInterface`
    Delete a Profile from the metadata and the profile hierarchy.
    Specified by:
      `deleteProfile` in interface `ProfileInterface`
    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.

  - ### removeProfile

    public boolean removeProfile(String application) throws RemoteException, ServiceException
    Remove an application profile from the profile tree.

    Specified by:
      `removeProfile` in interface `ProfileInterface`
    Parameters:
      `application` - The application string that identifies the profile to remove. This is a slash-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`

  - ### keySet

    public Set keySet() throws RemoteException
    Gets the key set for the attributes.
    Specified by:
      `keySet` in interface `ProfileInterface`
    Returns:
      Attribute's key set.
    Throws:
      `RemoteException` - if a networking issue is encountered.

  - ### values

    public Collection values() throws RemoteException
    Gets the values for the attributes.
    Specified by:
      `values` in interface `ProfileInterface`
    Returns:
      Attribute's values.
    Throws:
      `RemoteException` - if a networking issue is encountered.

  - ### persist

    public void persist(String application, boolean recursive) throws RemoteException, ServiceException
    Write any changes to the profile back to the persistent store.

    Specified by:
      `persist` in interface `ProfileInterface`
    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`

  - ### refresh

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

  - ### needReload

    protected boolean needReload() throws ServiceException, RemoteException
    Throws:
      `ServiceException`
      `RemoteException`

  - ### reload

    protected void reload() throws ServiceException, RemoteException
    Throws:
      `ServiceException`
      `RemoteException`

  - ### setLoadParameters

    public 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.
    Specified by:
      `setLoadParameters` in interface `ProfileInterface`
    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

    public 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.

    Specified by:
      `load` in interface `ProfileInterface`
    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` - if a networking issue is encountered.

  - ### create

    public 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.

    Specified by:
      `create` in interface `ProfileInterface`
    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

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

    Specified by:
      `setLocale` in interface `ProfileInterface`
    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

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

    Specified by:
      `getLocale` in interface `ProfileInterface`
    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.

  - ### attribute2Locale

    protected Locale attribute2Locale(String localeString) throws RemoteException
    Throws:
      `RemoteException`

  - ### destroy

    public void destroy() throws RemoteException
    Description copied from interface: `ProfileInterface`
    Destroy any resources held by this profile instance and its subordinates.
    Specified by:
      `destroy` in interface `ProfileInterface`
    Throws:
      `RemoteException` - In the event of remote object failure.