com.sas.services.user
Interface ProfileInterface

All Superinterfaces:

java.rmi.Remote

All Known Subinterfaces:

GlobalProfileInterface

All Known Implementing Classes:

Profile

public interface ProfileInterface
extends java.rmi.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

static java.lang.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

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

Field Detail

NO_BACK_END_MSG_KEY

static final java.lang.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 Detail

getUserContext

UserContextInterface getUserContext()
                                    throws java.rmi.RemoteException

Get a handle to the UserContext that owns this profile.

Returns:

The owner UserContextInterface.

Throws:

java.rmi.RemoteException - In the event of remote object failure.

setRefreshCycle

void setRefreshCycle(long refreshInMillis)
                     throws java.rmi.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:

java.rmi.RemoteException - in the event of remote object failure.

isLoaded

boolean isLoaded()
                 throws java.rmi.RemoteException

Get a flag indicating if the profile has been successfully loaded.

Returns:

True if the profile is loaded, false otherwise.

Throws:

java.rmi.RemoteException - in the event of remote object failure.

getApplication

java.lang.String getApplication()
                                throws java.rmi.RemoteException

Get the application string for this profile.

Returns:

The application string.

Throws:

java.rmi.RemoteException - in the event of remote object failure.

getAllAttributes

java.util.Map getAllAttributes(java.lang.String application)
                               throws java.rmi.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.

java.rmi.RemoteException - in the event of remote object failure.

getAttribute

java.lang.String getAttribute(java.lang.String application,
                              java.lang.String key)
                              throws java.rmi.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.

java.rmi.RemoteException - if a networking exception is encountered.

getAttributes

java.util.List getAttributes(java.lang.String application,
                             java.lang.String key)
                             throws java.rmi.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.

java.rmi.RemoteException - in the event of a remote communication failure.

getProfile

ProfileInterface getProfile(java.lang.String application)
                            throws java.rmi.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.

java.rmi.RemoteException - in the event of a remote communication failure.

getProfile

ProfileInterface getProfile(java.lang.String application,
                            boolean create)
                            throws java.rmi.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.

java.rmi.RemoteException

setAttribute

void setAttribute(java.lang.String application,
                  java.lang.String key,
                  java.lang.String value)
                  throws java.rmi.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.

java.rmi.RemoteException - in the event of a remote communication failure.

addAttribute

void addAttribute(java.lang.String application,
                  java.lang.String key,
                  java.lang.String value)
                  throws java.rmi.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.

java.rmi.RemoteException - in the event of a remote communication failure.

removeAttribute

void removeAttribute(java.lang.String application,
                     java.lang.String key)
                     throws java.rmi.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.

java.rmi.RemoteException - in the event of a remote communication failure.

setParentProfile

void setParentProfile(ProfileInterface parent)
                      throws ServiceException,
                             java.rmi.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.

java.rmi.RemoteException - In the event of remote object failure.

getParentProfile

ProfileInterface getParentProfile()
                                  throws ServiceException,
                                         java.rmi.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.

java.rmi.RemoteException - in the event of remote object failure.

getRootProfile

ProfileInterface getRootProfile()
                                throws ServiceException,
                                       java.rmi.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.

java.rmi.RemoteException - In the event of remote object failure.

getPathFromRoot

java.lang.String getPathFromRoot()
                                 throws ServiceException,
                                        java.rmi.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.

java.rmi.RemoteException - In the event of remote object failure.

deleteProfile

void deleteProfile(java.lang.String application)
                   throws ServiceException,
                          java.rmi.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.

java.rmi.RemoteException - In the event of remote object failure.

createSubprofile

void createSubprofile(ProfileInterface profile)
                      throws ServiceException,
                             java.rmi.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.

java.rmi.RemoteException - in the event of network problems.

addProfile

void addProfile(java.lang.String application,
                ProfileInterface profile,
                boolean force)
                throws java.rmi.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.

java.rmi.RemoteException - in the event of a remote communication failure.

removeProfile

boolean removeProfile(java.lang.String application)
                      throws java.rmi.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).

java.rmi.RemoteException - in the event of a remote communication failure.

keySet

java.util.Set keySet()
                     throws java.rmi.RemoteException

Gets the set of attribute keys.

Returns:

Key set.

Throws:

java.rmi.RemoteException - if a networking exception is encountered.

values

java.util.Collection values()
                            throws java.rmi.RemoteException

Gets a collection of values.

Returns:

Collection of values.

Throws:

java.rmi.RemoteException - if a networking exception is encountered.

refresh

void refresh()
             throws ServiceException,
                    java.rmi.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.

java.rmi.RemoteException - In the event of remote object failure.

persist

void persist(java.lang.String application,
             boolean recursive)
             throws java.rmi.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".

java.rmi.RemoteException - in the event of a remote communication failure.

setLoadParameters

void setLoadParameters(MetadataInterface root,
                       UserContextInterface user,
                       RepositoryInterface repos,
                       ProfileDomain pd)
                       throws java.rmi.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.

java.rmi.RemoteException - if a networking issue is encountered.

load

void load(MetadataInterface root,
          UserContextInterface user,
          RepositoryInterface repos,
          ProfileDomain pd)
          throws java.rmi.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.

java.rmi.RemoteException - in the event of a remote communication failure.

create

void create(MetadataInterface root,
            UserContextInterface user,
            RepositoryInterface repos,
            ProfileDomain pd)
            throws java.rmi.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.

java.rmi.RemoteException - in the event of a remote communication failure.

setLocale

void setLocale(java.lang.String application,
               java.util.Locale locale)
               throws ServiceException,
                      java.rmi.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.

java.rmi.RemoteException - in the event of remote object failure.

getLocale

java.util.Locale getLocale(java.lang.String application)
                           throws ServiceException,
                                  java.rmi.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.

java.rmi.RemoteException - in the event of remote object failure.

destroy

void destroy()
             throws java.rmi.RemoteException

Destroy any resources held by this profile instance and its subordinates.

Throws:

java.rmi.RemoteException - In the event of remote object failure.