com.compoze.collab
Interface ISession

All Superinterfaces:

java.io.Serializable

All Known Subinterfaces:

IExchangeSession, IGroupwareSession, IImSession, ILcsSession, IMapiSession, IWebdavSession, IYahooSession

public interface ISession

extends java.io.Serializable

Provides a session to a collaboration service provider and an entry point to the Collaboration Framework. 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.

See Also:

SessionFactory.createSession(Map)

Field Summary

static java.lang.String	PROP_ADMIN_LOCALE The session property that specifies the administrator locale (see the SessionFactory constructor for more details).
static java.lang.String	PROP_AUTO_FETCH The session property that specifies whether or not properties should be retrieved from the server automatically if they are not already local.
static java.lang.String	PROP_LOCALE The session property that specifies the user locale (see the SessionFactory constructor for more details).
static java.lang.String	PROP_LOG_LEVEL The session property that specifies the log level (see the SessionFactory constructor for more details).
static java.lang.String	PROP_PROGRAMMER_LOCALE The session property that specifies the programmer locale (see the SessionFactory constructor for more details).
static java.lang.String	PROP_PROVIDER The session property that specifies the provider (see the SessionFactory constructor for more details).
static java.lang.String	PROP_SCHEMA The session property that specifies the schema (see the SessionFactory constructor for more details).
static java.lang.Object	PROPVALUE_REMOVE 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.
java.lang.String	endProfile() Ends profiling and returns a String containing the profile results.
long	endTimer() Ends the default timer.
long	endTimer(java.lang.String sName) Ends a named timer.
java.util.Locale	getAdminLocale() Gets the locale used to translate admin messages.
java.lang.Object	getAttribute(java.lang.String sName) Gets a non-persistent attribute off of the session.
IRootContainer	getDefaultRootContainer() Gets the default root container.
java.util.Locale	getLocale() Gets the locale used to translate user messages.
LogLevel	getLogLevel() Get the current session LogLevel
java.lang.Object	getOption(java.lang.String sKey) Gets a session option.
java.lang.Object[]	getOptions(java.lang.String[] sKeys) Gets an array of session options for each key supplied.
java.util.Locale	getProgrammerLocale() Gets the locale used to translate programmer messages.
java.lang.Object	getProperty(java.lang.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.
boolean	isCapabilitySupported(java.lang.String sCapability) Determine if the specified capability is supported by the provider for this session.
void	log(java.lang.String sMessage) Logs a debug level message using the provider's logger.
void	login() Authenticates a user to this session.
void	login(java.util.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(java.util.Map replacementProps) Opens a connection to the backend, if possible.
java.lang.Object	removeAttribute(java.lang.String sName) Removes an attribute from the session.
void	setAdminLocale(java.util.Locale locale) Sets the locale used to translate admin messages.
java.lang.Object	setAttribute(java.lang.String sName, java.lang.Object value) Sets a non-persistent attribute on the session.
void	setLocale(java.util.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(java.lang.String sKey, java.lang.Object value) Sets a persistent, programmer defined session option useful for persisting an application preference.
void	setOptions(java.lang.String[] sKeys, java.lang.Object[] values) Sets persistent, programmer defined session options useful for persisting application preferences.
void	setProgrammerLocale(java.util.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(java.lang.String sTimerName) Starts a named timer that can be used to measure the duration between events.

Field Detail

STATE_UNINITIALIZED

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

STATE_INITIALIZED

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

STATE_OPEN

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

STATE_AUTHENTICATED

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

PROP_AUTO_FETCH

public static final java.lang.String PROP_AUTO_FETCH

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

PROP_PROVIDER

public static final java.lang.String PROP_PROVIDER

The session property that specifies the provider (see the SessionFactory constructor for more details).

PROP_SCHEMA

public static final java.lang.String PROP_SCHEMA

The session property that specifies the schema (see the SessionFactory constructor for more details).

PROP_LOCALE

public static final java.lang.String PROP_LOCALE

The session property that specifies the user locale (see the SessionFactory constructor for more details).

PROP_PROGRAMMER_LOCALE

public static final java.lang.String PROP_PROGRAMMER_LOCALE

The session property that specifies the programmer locale (see the SessionFactory constructor for more details).

PROP_ADMIN_LOCALE

public static final java.lang.String PROP_ADMIN_LOCALE

The session property that specifies the administrator locale (see the SessionFactory constructor for more details).

PROP_LOG_LEVEL

public static final java.lang.String PROP_LOG_LEVEL

The session property that specifies the log level (see the SessionFactory constructor for more details).

PROPVALUE_REMOVE

public static final java.lang.Object PROPVALUE_REMOVE

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

public 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

public 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

public long endTimer(java.lang.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

public 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

public java.util.Locale getAdminLocale()

Gets the locale used to translate admin messages.

Returns:

the admin locale

getAttribute

public java.lang.Object getAttribute(java.lang.String sName)

Gets a non-persistent attribute off of the session.

Parameters:

sName - the attribute name

Returns:

the attribute value

getDefaultRootContainer

public IRootContainer getDefaultRootContainer()
                                       throws CollaborationException

Gets the default root container.

Returns:

the default root container (never null)

getLocale

public java.util.Locale getLocale()

Gets the locale used to translate user messages.

Returns:

the user locale

getLogLevel

public LogLevel getLogLevel()

Get the current session LogLevel

Returns:

the current LogLevel

getOption

public java.lang.Object getOption(java.lang.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[])

See Also:

(String)

getOptions

public java.lang.Object[] getOptions(java.lang.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[])

See Also:

(String[])

getProgrammerLocale

public java.util.Locale getProgrammerLocale()

Gets the locale used to translate programmer messages.

Returns:

the programmer locale

getProperty

public java.lang.Object getProperty(java.lang.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

getProvider

public IProvider getProvider()
                      throws CollaborationException

Get this session's Provider

Returns:

the Provider

isCapabilitySupported

public boolean isCapabilitySupported(java.lang.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

log

public void log(java.lang.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

public 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

public void login(java.util.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

public void logout()
            throws CollaborationException

Logs a user out, revoking authentication on the session.

open

public 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

public void open(java.util.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

public java.lang.Object removeAttribute(java.lang.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

public void setAdminLocale(java.util.Locale locale)

Sets the locale used to translate admin messages.

Parameters:

locale - the admin locale

setAttribute

public java.lang.Object setAttribute(java.lang.String sName,
                                     java.lang.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

public void setLocale(java.util.Locale locale)

Sets the locale used to translate user messages.

Parameters:

locale - the user locale

setLogLevel

public 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

public void setOption(java.lang.String sKey,
                      java.lang.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)

setOptions

public void setOptions(java.lang.String[] sKeys,
                       java.lang.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)

setProgrammerLocale

public void setProgrammerLocale(java.util.Locale locale)

Sets the locale used to translate programmer messages.

Parameters:

locale - the programmer locale

startTimer

public void startTimer(java.lang.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

public void startTimer()
                throws CollaborationException

Starts the default timer.

Throws:

CollaborationException - if the default timer has already been started

getState

public 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

public void startProfile()
                  throws CollaborationException

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

See Also:

startProfile(boolean), endProfile()

startProfile

public 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

See Also:

endProfile()

endProfile

public java.lang.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)

See Also:

startProfile()