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

## com.compoze.collab
Interface ISession

All Superinterfaces:
  java.io.Serializable

All Known Subinterfaces:
  IExchangeSession, IGroupwareSession, IWebdavSession

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.

### 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 java.lang.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 java.lang.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 java.lang.String` | `PROP_CACHE_DEPENDENCY_CHECK_MILLIS` Optional- The minimum amount of time in milliseconds to elapse between dependency checks.
`static java.lang.String` | `PROP_CACHE_ENABLED` Optional- The session property that enables or disables caching.
`static java.lang.String` | `PROP_CACHE_QUERY_MAX` Optional- The maximum number of query results that may be stored when caching is enabled.
`static java.lang.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 java.lang.String` | `PROP_CACHE_USE_SOFT_REFERENCES` Optional- The session property that enables or disables the use of soft references in the caching mechanism.
`static java.lang.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 java.lang.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 java.lang.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 java.lang.String` | `PROP_PROVIDER` Required- The session property that specifies the internal name of the provider.
`static java.lang.String` | `PROP_SCHEMA` Optional- The session property that specifies the schema internal name (must be one of the provider's supported schemas).
`static java.lang.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.
`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.
`IRootContainer` | `getDefaultRootContainer(FetchProfile fetchProfile)` Get the default root container using a `FetchProfile`.
`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.
`void` | `invalidateCache()` Throws away any cached queries for 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.

  See Also:
    Constant Field Values

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

  See Also:
    Constant Field Values

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

  See Also:
    Constant Field Values

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

  See Also:
    Constant Field Values

### PROP_PROVIDER

    public static final java.lang.String PROP_PROVIDER

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

  See Also:
    Constant Field Values

### PROP_AUTO_FETCH

    public static final java.lang.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:
    Constant Field Values

### PROP_SCHEMA

    public static final java.lang.String PROP_SCHEMA

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

  See Also:
    Constant Field Values

### PROP_LOCALE

    public static final java.lang.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:
    Constant Field Values

### PROP_PROGRAMMER_LOCALE

    public static final java.lang.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:
    Constant Field Values

### PROP_ADMIN_LOCALE

    public static final java.lang.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:
    Constant Field Values

### PROP_LOG_LEVEL

    public static final java.lang.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:
    Constant Field Values

### PROP_CACHE_ENABLED

    public static final java.lang.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:
    Constant Field Values

### PROP_CACHE_UPDATE_MILLIS

    public static final java.lang.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:
    Constant Field Values

### PROP_CACHE_DEPENDENCY_CHECK_MILLIS

    public static final java.lang.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:
    Constant Field Values

### PROP_CACHE_USE_SOFT_REFERENCES

    public static final java.lang.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:
    Constant Field Values

### PROP_CACHE_QUERY_MAX

    public static final java.lang.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:
    Constant Field Values

### PROPVALUE_REMOVE

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

    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`)
  Throws:
    `CollaborationException`

### getDefaultRootContainer

    public 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

    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[]`)
  Throws:
    `CollaborationException`
  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[]`)
  Throws:
    `CollaborationException`
  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
  Throws:
    `CollaborationException`

### 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
  Throws:
    `CollaborationException`

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

  Throws:
    `CollaborationException`

### 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)
  Throws:
    `CollaborationException`

### 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)
  Throws:
    `CollaborationException`

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

  Throws:
    `CollaborationException`
  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
  Throws:
    `CollaborationException`
  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)
  Throws:
    `CollaborationException`
  See Also:
    `startProfile()`

### invalidateCache

    public void invalidateCache()
                         throws CollaborationException

  Throws away any cached queries for the session.

  Throws:
    `CollaborationException`

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

Copyright ©1999-2003 Compoze Software, Inc. All rights reserved.