com.compoze.collab
Interface ISession

All Superinterfaces

Serializable

All Known Subinterfaces:

ICmSession, IGroupwareSession

public interface ISession
extends Serializable

Provides a session to a collaboration service provider and an entry point to the Personal Messaging API. Once opened, sessions can be in one of the states shown in the diagram below:

The distinction between the Open and Authenticated states allows one physical connection to be re-used across multiple sequential user logins for those providers that support this. Calling login() will automatically call open() for you. If you do not wish to use a Session again, call close() on it to be sure that you both log the user out and free any underlying resources.

Caching

Sessions can optionally support caching for all read queries. Any API call that results in an identical query may return cached results. A maximum number of cached results is stored before results are purged, starting with the least frequently used then proceeding to the least recently used. Providers either provide dependency check support or do not, and this affects the behavior of the cache control session properties as follows:

Property	Dep. checks supported	Dep. checks not supported	Default	Behavior
PROP_CACHE_ENABLED	Store cached results, performing dependency checks for each request at the maximum rate specified by PROP_CACHE_DEPENDENCY_CHECK_MILLIS.	Store cached results only if PROP_CACHE_UPDATE_MILLIS is a positive number.	true	Setting to true enables cache.
PROP_CACHE_UPDATE_MILLIS	The minimum amount of milliseconds to elapse before a dependency check will be performed on any particular request.	The minimum amount of milliseconds to elapse the server will be contacted for an update on the results of any particular request.	0	Setting to a positive millisecond value causes cached results to remain in memory and always be used until this time expires.
PROP_CACHE_DEPENDENCY_CHECK_MILLIS	The minimum amount of time in milliseconds to elapse between dependency checks.	Not used.	1000	Setting to a positive millisecond value causes the provider to wait the specified number of milliseconds between dependency checks. This prevents a flurry of dependency checks from occurring in the course of one web page, for example.
PROP_CACHE_USE_SOFT_REFERENCES	Controls the use of soft references for cached results.	Controls the use of soft references for cached results.	false	Setting to true causes all cache results to be stored using Java soft references. There will be no guarantee that cached results are available (and in fact in practical testing they get discarded rather quickly, depending on VM configuration and load).
PROP_CACHE_QUERY_MAX	Controls the maximum number of queries to keep in the cache.	Controls the maximum number of queries to keep in the cache.	20	Increasing or decreasing the number causes the cache to store the results of more, or less queries, respectively.

See Also

SessionFactory.createSession(Map)

Field Summary

static String	PROP_ADMIN_LOCALE Optional- The session property that specifies the administrator locale (this Locale object is used when obtaining all internationalizable resources for the user.
static String	PROP_AUTO_FETCH Optional- The session property that specifies whether or not properties should be retrieved from the server automatically if they are not already local.
static String	PROP_CACHE_DEPENDENCY_CHECK_MILLIS Optional- The minimum amount of time in milliseconds to elapse between dependency checks.
static String	PROP_CACHE_ENABLED Optional- The session property that enables or disables caching.
static String	PROP_CACHE_QUERY_MAX Optional- The maximum number of query results that may be stored when caching is enabled.
static String	PROP_CACHE_UPDATE_MILLIS Optional- The session property that sets the maximum amount of time before the server will be contacted again for an update on any particular request.
static String	PROP_CACHE_USE_SOFT_REFERENCES Optional- The session property that enables or disables the use of soft references in the caching mechanism.
static String	PROP_LOCALE Optional- The session property that specifies the user locale (this Locale object is used when obtaining all internationalizable resources for the user.
static String	PROP_LOG_LEVEL Optional- The session property that specifies the log level (the log level for messages generated for the session, an instance of LogLevel.
static String	PROP_PROGRAMMER_LOCALE Optional- The session property that specifies the programmer locale (this Locale object is used when obtaining all internationalizable resources for the user.
static String	PROP_PROVIDER Required- The session property that specifies the internal name of the provider.
static String	PROP_SCHEMA Optional- The session property that specifies the schema internal name (must be one of the provider's supported schemas).
static Object	PROPVALUE_REMOVE Optional- If this property is specified as a value in the replacementProps Map parameter to either the open(Map) or login(Map) methods, it means to remove the property from the session properties.
static int	STATE_AUTHENTICATED The state constant for the 'authenticated' session state, meaning that a connection has been opened to the provider's backend store or server and a user has been authenticated so all session operations are valid.
static int	STATE_INITIALIZED The state constant for the 'initialized' session state, meaning that the session is closed but its internal state is initialized and the session is ready for use.
static int	STATE_OPEN The state constant for the 'open' session state, meaning that a connection may have been opened to the provider's backend store or server, but no user has been authenticated so some session operations may not work.
static int	STATE_UNINITIALIZED The state constant for the 'uninitialized' session state, meaning that the session is closed and its internal state is uninitialized.

Method Summary

void	addLogListener(ILogListener listener) Adds a listener for both API and provider specific log messages that are related to this session.
void	close() Closes the session to the server.
String	endProfile() Ends profiling and returns a String containing the profile results.
long	endTimer() Ends the default timer.
long	endTimer(String sName) Ends a named timer.
Locale	getAdminLocale() Gets the locale used to translate admin messages.
Object	getAttribute(String sName) Gets a non-persistent attribute off of the session.
IRootContainer	getDefaultRootContainer() Gets the default root container.
IRootContainer	getDefaultRootContainer(FetchProfile fetchProfile) Get the default root container using a FetchProfile.
Locale	getLocale() Gets the locale used to translate user messages.
LogLevel	getLogLevel() Get the current session LogLevel
Object	getOption(String sKey) Gets a session option.
Object[]	getOptions(String[] sKeys) Gets an array of session options for each key supplied.
Locale	getProgrammerLocale() Gets the locale used to translate programmer messages.
Map	getProperties(boolean bAll) Gets all non-sensitive session properties.
Object	getProperty(String sProperty) Gets a session property (used by the context for providers and stubs).
IProvider	getProvider() Get this session's Provider
int	getState() Gets the current state of the session.
void	invalidateCache() Throws away any cached queries for the session.
boolean	isCapabilitySupported(String sCapability) Determine if the specified capability is supported by the provider for this session.
void	log(String sMessage) Logs a debug level message using the provider's logger.
void	login() Authenticates a user to this session.
void	login(Map replacementProps) Authenticates a user to this session.
void	logout() Logs a user out, revoking authentication on the session.
void	open() Opens a connection to the backend, if possible.
void	open(Map replacementProps) Opens a connection to the backend, if possible.
Object	removeAttribute(String sName) Removes an attribute from the session.
void	setAdminLocale(Locale locale) Sets the locale used to translate admin messages.
Object	setAttribute(String sName, Object value) Sets a non-persistent attribute on the session.
void	setLocale(Locale locale) Sets the locale used to translate user messages.
void	setLogLevel(LogLevel level) Sets the log level for both API and provider specific log messages that are related to this session.
void	setOption(String sKey, Object value) Sets a persistent, programmer defined session option useful for persisting an application preference.
void	setOptions(String[] sKeys, Object[] values) Sets persistent, programmer defined session options useful for persisting application preferences.
void	setProgrammerLocale(Locale locale) Sets the locale used to translate programmer messages.
void	startProfile() Starts profiling of all stub methods that are called in the current thread.
void	startProfile(boolean bCurrentThread) Starts profiling of all stub methods that are called.
void	startTimer() Starts the default timer.
void	startTimer(String sTimerName) Starts a named timer that can be used to measure the duration between events.

Field Detail

STATE_UNINITIALIZED

static final int STATE_UNINITIALIZED

The state constant for the 'uninitialized' session state, meaning that the session is closed and its internal state is uninitialized. This state will only be seen immediately after de-serialization and before any other methods have been called.

See Also

Constants Summary

STATE_INITIALIZED

static final int STATE_INITIALIZED

The state constant for the 'initialized' session state, meaning that the session is closed but its internal state is initialized and the session is ready for use.

See Also

Constants Summary

STATE_OPEN

static final int STATE_OPEN

The state constant for the 'open' session state, meaning that a connection may have been opened to the provider's backend store or server, but no user has been authenticated so some session operations may not work.

See Also

Constants Summary

STATE_AUTHENTICATED

static final int STATE_AUTHENTICATED

The state constant for the 'authenticated' session state, meaning that a connection has been opened to the provider's backend store or server and a user has been authenticated so all session operations are valid.

See Also

Constants Summary

PROP_PROVIDER

static final String PROP_PROVIDER

Required- The session property that specifies the internal name of the provider.

See Also

Constants Summary

PROP_AUTO_FETCH

static final String PROP_AUTO_FETCH

Optional- The session property that specifies whether or not properties should be retrieved from the server automatically if they are not already local.

See Also

Constants Summary

PROP_SCHEMA

static final String PROP_SCHEMA

Optional- The session property that specifies the schema internal name (must be one of the provider's supported schemas).

See Also

Constants Summary

PROP_LOCALE

static final String PROP_LOCALE

Optional- The session property that specifies the user locale (this Locale object is used when obtaining all internationalizable resources for the user. If this property is not specified then the value of Locale.getDefault() is used.

See Also

Constants Summary

PROP_PROGRAMMER_LOCALE

static final String PROP_PROGRAMMER_LOCALE

Optional- The session property that specifies the programmer locale (this Locale object is used when obtaining all internationalizable resources for the user. If this property is not specified then the value of Locale.getDefault() is used.

See Also

Constants Summary

PROP_ADMIN_LOCALE

static final String PROP_ADMIN_LOCALE

Optional- The session property that specifies the administrator locale (this Locale object is used when obtaining all internationalizable resources for the user. If this property is not specified then the value of Locale.getDefault() is used.

See Also

Constants Summary

PROP_LOG_LEVEL

static final String PROP_LOG_LEVEL

Optional- The session property that specifies the log level (the log level for messages generated for the session, an instance of LogLevel. If not specified, then the value of CollaborationManager.getDefaultLogLevel() is used).

See Also

Constants Summary

PROP_CACHE_ENABLED

static final String PROP_CACHE_ENABLED

Optional- The session property that enables or disables caching. Caching support is provider dependent, so this property is only a hint. Set to true to enable caching. The value may be a Boolean or a String. For more information see the cache property section in the description of this class.

See Also

Constants Summary

PROP_CACHE_UPDATE_MILLIS

static final String PROP_CACHE_UPDATE_MILLIS

Optional- The session property that sets the maximum amount of time before the server will be contacted again for an update on any particular request. A positive value allows caching even for providers which do not support cache dependency checking at the expense of query results not being up to date. The value may be a Long or a String. For more information see the cache property section in the description of this class.

See Also

Constants Summary

PROP_CACHE_DEPENDENCY_CHECK_MILLIS

static final String PROP_CACHE_DEPENDENCY_CHECK_MILLIS

Optional- The minimum amount of time in milliseconds to elapse between dependency checks. The value may be a Long or a String. For more information see the cache property section in the description of this class.

See Also

Constants Summary

PROP_CACHE_USE_SOFT_REFERENCES

static final String PROP_CACHE_USE_SOFT_REFERENCES

Optional- The session property that enables or disables the use of soft references in the caching mechanism. If soft references are not used, all requests are cached until the session is closed. The value may be a Boolean or a String. For more information see the cache property section in the description of this class.

See Also

Constants Summary

PROP_CACHE_QUERY_MAX

static final String PROP_CACHE_QUERY_MAX

Optional- The maximum number of query results that may be stored when caching is enabled. The value may be an Integer or a String. For more information see the cache property section in the description of this class.

See Also

Constants Summary

PROPVALUE_REMOVE

static final Object PROPVALUE_REMOVE

Optional- If this property is specified as a value in the replacementProps Map parameter to either the open(Map) or login(Map) methods, it means to remove the property from the session properties.

Method Detail

addLogListener

void addLogListener(ILogListener listener)
                    throws CollaborationException

Adds a listener for both API and provider specific log messages that are related to this session.

Parameters

listener - the log listener to add (not null)

Throws

CollaborationException - if the listener could not be added

close

void close()
           throws CollaborationException

Closes the session to the server.

Throws

CollaborationException - if the session is already closed, or there was a provider problem while closing the session

endTimer

long endTimer(String sName)
              throws CollaborationException

Ends a named timer.

Parameters

sName - the name of the timer (must have been started)

Returns

the time, in milliseconds, that the specified timer ran for.

Throws

CollaborationException - if the named timer does not exist

endTimer

long endTimer()
              throws CollaborationException

Ends the default timer.

Returns

the time, in milliseconds, that the specified timer ran for.

Throws

CollaborationException - if the default timer has not been started

getAdminLocale

Locale getAdminLocale()

Gets the locale used to translate admin messages.

Returns

the admin locale

getAttribute

Object getAttribute(String sName)

Gets a non-persistent attribute off of the session.

Parameters

sName - the attribute name

Returns

the attribute value

getDefaultRootContainer

IRootContainer getDefaultRootContainer()
                                       throws CollaborationException

Gets the default root container.

Returns

the default root container (never null)

Throws

CollaborationException

getDefaultRootContainer

IRootContainer getDefaultRootContainer(FetchProfile fetchProfile)
                                       throws CollaborationException

Get the default root container using a FetchProfile.

Parameters

fetchProfile - the FetchProfile to use

Returns

the default root container (never null)

Throws

CollaborationException

getLocale

Locale getLocale()

Gets the locale used to translate user messages.

Returns

the user locale

getLogLevel

LogLevel getLogLevel()

Get the current session LogLevel

Returns

the current LogLevel

getOption

Object getOption(String sKey)
                 throws CollaborationException

Gets a session option.

Parameters

sKey - the key for the option (not null)

Returns

the option value (array values will be returned as their wrapper types, for example Integer[] or Boolean[])

Throws

CollaborationException

See Also

(String)

getOptions

Object[] getOptions(String[] sKeys)
                    throws CollaborationException

Gets an array of session options for each key supplied.

Parameters

sKeys - the keys to retrieve values for (not null)

Returns

the option values (array values will be returned as their wrapper types, for example Integer[] or Boolean[])

Throws

CollaborationException

See Also

(String[])

getProgrammerLocale

Locale getProgrammerLocale()

Gets the locale used to translate programmer messages.

Returns

the programmer locale

getProperty

Object getProperty(String sProperty)
                   throws CollaborationException

Gets a session property (used by the context for providers and stubs).

Parameters

sProperty - the property name

Returns

the session property value, or null if it's not set

Throws

CollaborationException - if the property is not valid for the provider for the session or the property could not be obtained because it contains sensitive information

getProperties

Map getProperties(boolean bAll)
                  throws CollaborationException

Gets all non-sensitive session properties.

Parameters

bAll - if true, get all properties, otherwise get only get the provider specific session properties ( typically only those properties needed to identify important context for a session)

Returns

the session properties (not null)

Throws

CollaborationException - if the session could not be set to the initialized state

getProvider

IProvider getProvider()
                      throws CollaborationException

Get this session's Provider

Returns

the Provider

Throws

CollaborationException

isCapabilitySupported

boolean isCapabilitySupported(String sCapability)
                              throws CollaborationException

Determine if the specified capability is supported by the provider for this session.

Parameters

sCapability - the capability (not null)

Returns

true if the capability is supported, false otherwise

Throws

CollaborationException

log

void log(String sMessage)
         throws CollaborationException

Logs a debug level message using the provider's logger.

Parameters

sMessage - the message to log (not null)

Throws

CollaborationException - if the message could not be logged

login

void login()
           throws CollaborationException

Authenticates a user to this session. The session is opened if it has not already been opened.

Throws

CollaborationException - if the user could not be authenticated, or there was another problem with the provider

login

void login(Map replacementProps)
           throws CollaborationException

Authenticates a user to this session. The session is opened if it has not already been opened.

Parameters

replacementProps - properties to replace in the session properties specified in the constructor (null means don't replace any properties, and a value of PROPVALUE_REMOVE in the Map means to remove that property from the session properties)

Throws

CollaborationException - if the user could not be authenticated, or there was another problem with the provider

logout

void logout()
            throws CollaborationException

Logs a user out, revoking authentication on the session.

Throws

CollaborationException

open

void open()
          throws CollaborationException

Opens a connection to the backend, if possible. For some providers opening the connection to the backend can be costly. Use of a single Session that remains open for multiple invocations of login() and logout() may increase performance.

Throws

CollaborationException - if the session is already open, or there was a provider problem when opening the session

open

void open(Map replacementProps)
          throws CollaborationException

Opens a connection to the backend, if possible. For some providers opening the connection to the backend can be costly. Use of a single Session that remains open for multiple invocations of login() and logout() may increase performance.

Parameters

replacementProps - properties to replace in the session properties specified in the constructor (null means don't replace any properties, and a value of PROPVALUE_REMOVE in the Map means to remove that property from the session properties)

Throws

CollaborationException - if the session is already open, or there was a provider problem when opening the session

removeAttribute

Object removeAttribute(String sName)

Removes an attribute from the session.

Parameters

sName - the attribute name

Returns

the attribute value that was removed, or null if it was not set or was a non-serializable object and the session was serialized

setAdminLocale

void setAdminLocale(Locale locale)

Sets the locale used to translate admin messages.

Parameters

locale - the admin locale

setAttribute

Object setAttribute(String sName,
                    Object value)

Sets a non-persistent attribute on the session. Attributes are useful for non-persistent storage of frequently used but expensive to instantiate objects that are often repeatedly the same, such as Restriction objects. This can reduce memory consumption and increase performance.

Parameters

sName - the attribute name

value - the attribute value (attribute values may be either Serializable or not Serializable. If they are not, prepare for them to be null at any time after you have set them, which will occur when the session is serialized. Specifying a value of null will remove the attribute from the session.)

Returns

the previous value associated with the key, or null if there was no previous value

setLocale

void setLocale(Locale locale)

Sets the locale used to translate user messages.

Parameters

locale - the user locale

setLogLevel

void setLogLevel(LogLevel level)
                 throws CollaborationException

Sets the log level for both API and provider specific log messages that are related to this session.

Parameters

level - the log level to set (not null)

Throws

CollaborationException - if the log level could not be set

setOption

void setOption(String sKey,
               Object value)
               throws CollaborationException

Sets a persistent, programmer defined session option useful for persisting an application preference.

Parameters

sKey - the key for the option (any String but must not be null)

value - the value (must be one of the types String, int, Integer, boolean, Boolean or arrays of any of these)

Throws

CollaborationException

setOptions

void setOptions(String[] sKeys,
                Object[] values)
                throws CollaborationException

Sets persistent, programmer defined session options useful for persisting application preferences.

Parameters

sKeys - the keys for each option (keys are any String but must not be null)

values - the values (each value must be one of the types String, int, Integer, boolean, Boolean or arrays of any of these)

Throws

CollaborationException

setProgrammerLocale

void setProgrammerLocale(Locale locale)

Sets the locale used to translate programmer messages.

Parameters

locale - the programmer locale

startTimer

void startTimer(String sTimerName)
                throws CollaborationException

Starts a named timer that can be used to measure the duration between events.

Parameters

sTimerName - a name for the timer (must be unique to the session)

Throws

CollaborationException - if the named timer already exists

startTimer

void startTimer()
                throws CollaborationException

Starts the default timer.

Throws

CollaborationException - if the default timer has already been started

getState

int getState()

Gets the current state of the session.

Returns

the session state (one of the STATE_ constants in this class: STATE_UNINITIALIZED, STATE_INITIALIZED, STATE_OPEN or STATE_AUTHENTICATED)

startProfile

void startProfile()
                  throws CollaborationException

Starts profiling of all stub methods that are called in the current thread.

Throws

CollaborationException

See Also

startProfile(boolean), endProfile()

startProfile

void startProfile(boolean bCurrentThread)
                  throws CollaborationException

Starts profiling of all stub methods that are called. Take note of the following information regarding profiling results:

• If the session is serialized, profiling information is lost in sessions which are re-constituted from the serialization process.
• If you include profiling information from all threads, be prepared for the total time that the profiling is enabled to be less than the total time spent in stub calls, because time is accumulating separately for each thread.
• For stub methods which call other stub methods, the time listed is only that spent in the current stub method, not the time spent in called stub methods.

Parameters

bCurrentThread - if true, only include times for stub calls that occur in the current thread

Throws

CollaborationException

See Also

endProfile()

endProfile

String endProfile()
                  throws CollaborationException

Ends profiling and returns a String containing the profile results.

Returns

the profile results (or null if no profile is in progress)

Throws

CollaborationException

See Also

startProfile()

invalidateCache

void invalidateCache()
                     throws CollaborationException

Throws away any cached queries for the session.

Throws

CollaborationException