Overview | Package | Class | Tree | Deprecated | Index | Help
| Copyright © 2006 BEA Systems, Inc. All Rights Reserved
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2006 BEA Systems, Inc. All Rights Reserved