|
Compoze Software, Inc. | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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.
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. |
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 |
public static final int STATE_UNINITIALIZED
public static final int STATE_INITIALIZED
public static final int STATE_OPEN
public static final int STATE_AUTHENTICATED
public static final java.lang.String PROP_PROVIDER
public static final java.lang.String PROP_AUTO_FETCH
public static final java.lang.String PROP_SCHEMA
public static final java.lang.String PROP_LOCALE
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.public static final java.lang.String PROP_PROGRAMMER_LOCALE
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.public static final java.lang.String PROP_ADMIN_LOCALE
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.public static final java.lang.String PROP_LOG_LEVEL
LogLevel
. If not specified, then the value
of CollaborationManager.getDefaultLogLevel()
is used).public static final java.lang.String PROP_CACHE_ENABLED
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.public static final java.lang.String PROP_CACHE_UPDATE_MILLIS
Long
or a String
. For more information
see the cache property section in the description of this class.public static final java.lang.String PROP_CACHE_DEPENDENCY_CHECK_MILLIS
Long
or a String
.
For more information see the cache property section in
the description of this class.public static final java.lang.String PROP_CACHE_USE_SOFT_REFERENCES
Boolean
or a
String
. For more information see the cache property section in
the description of this class.public static final java.lang.String PROP_CACHE_QUERY_MAX
Integer
or a
String
. For more information see the cache property section in
the description of this class.public static final java.lang.Object PROPVALUE_REMOVE
replacementProps
Map
parameter to either the open(Map)
or login(Map)
methods, it means to remove the property from the session properties.Method Detail |
public void addLogListener(ILogListener listener) throws CollaborationException
listener
- the log listener to add (not null
)CollaborationException
- if the listener could not be addedpublic void close() throws CollaborationException
CollaborationException
- if the session is already closed,
or there was a provider problem while closing the sessionpublic long endTimer(java.lang.String sName) throws CollaborationException
sName
- the name of the timer (must have been started)CollaborationException
- if the named timer does not existpublic long endTimer() throws CollaborationException
CollaborationException
- if the default timer has not been
startedpublic java.util.Locale getAdminLocale()
public java.lang.Object getAttribute(java.lang.String sName)
sName
- the attribute namepublic IRootContainer getDefaultRootContainer() throws CollaborationException
null
)public IRootContainer getDefaultRootContainer(FetchProfile fetchProfile) throws CollaborationException
FetchProfile
.fetchProfile
- the FetchProfile to usenull
)CollaborationException
- public java.util.Locale getLocale()
public LogLevel getLogLevel()
public java.lang.Object getOption(java.lang.String sKey) throws CollaborationException
sKey
- the key for the option (not null
)Integer[]
or
Boolean[]
)(String)
public java.lang.Object[] getOptions(java.lang.String[] sKeys) throws CollaborationException
sKeys
- the keys to retrieve values for (not null
)Integer[]
or
Boolean[]
)(String[])
public java.util.Locale getProgrammerLocale()
public java.lang.Object getProperty(java.lang.String sProperty) throws CollaborationException
sProperty
- the property namenull
if it's not setCollaborationException
- if the property is not valid for
the provider for the session or the property could not be
obtained because it contains sensitive informationpublic IProvider getProvider() throws CollaborationException
public boolean isCapabilitySupported(java.lang.String sCapability) throws CollaborationException
sCapability
- the capability (not null
)true
if the capability is supported, false
otherwisepublic void log(java.lang.String sMessage) throws CollaborationException
sMessage
- the message to log (not null
)CollaborationException
- if the message could not be loggedpublic void login() throws CollaborationException
CollaborationException
- if the user could not be authenticated,
or there was another problem with the providerpublic void login(java.util.Map replacementProps) throws CollaborationException
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)CollaborationException
- if the user could not be authenticated,
or there was another problem with the providerpublic void logout() throws CollaborationException
public void open() throws CollaborationException
Session
that remains open for multiple invocations of
login()
and logout()
may increase performance.CollaborationException
- if the session is already open,
or there was a provider problem when opening the sessionpublic void open(java.util.Map replacementProps) throws CollaborationException
Session
that remains open for multiple invocations of
login()
and logout()
may increase performance.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)CollaborationException
- if the session is already open,
or there was a provider problem when opening the sessionpublic java.lang.Object removeAttribute(java.lang.String sName)
sName
- the attribute namenull
if
it was not set or was a non-serializable object and the session
was serializedpublic void setAdminLocale(java.util.Locale locale)
locale
- the admin localepublic java.lang.Object setAttribute(java.lang.String sName, java.lang.Object value)
Restriction
objects. This
can reduce memory consumption and increase performance.sName
- the attribute namevalue
- 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.)null
if there was no previous valuepublic void setLocale(java.util.Locale locale)
locale
- the user localepublic void setLogLevel(LogLevel level) throws CollaborationException
level
- the log level to set (not null
)CollaborationException
- if the log level could not be setpublic void setOption(java.lang.String sKey, java.lang.Object value) throws CollaborationException
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)public void setOptions(java.lang.String[] sKeys, java.lang.Object[] values) throws CollaborationException
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)public void setProgrammerLocale(java.util.Locale locale)
locale
- the programmer localepublic void startTimer(java.lang.String sTimerName) throws CollaborationException
sTimerName
- a name for the timer (must be unique to the
session)CollaborationException
- if the named timer already existspublic void startTimer() throws CollaborationException
CollaborationException
- if the default timer has already been
startedpublic int getState()
STATE_
constants
in this class: STATE_UNINITIALIZED
,
STATE_INITIALIZED
, STATE_OPEN
or
STATE_AUTHENTICATED
)public void startProfile() throws CollaborationException
startProfile(boolean)
,
endProfile()
public void startProfile(boolean bCurrentThread) throws CollaborationException
bCurrentThread
- if true
, only include times for
stub calls that occur in the current threadendProfile()
public java.lang.String endProfile() throws CollaborationException
String
containing the profile
results.null
if no profile is
in progress)startProfile()
public void invalidateCache() throws CollaborationException
|
Compoze Software, Inc. | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |