public interface Session extends AutoCloseable
To open a new Session connection to a server use
SessionFactory.open(String)
specifying the server URL. There is also
a non blocking version (
SessionFactory.open(String, SessionFactory.OpenCallback)
) which calls
back when the session has been connected.
The factory allows a number of other attributes of the session to be specified.
The functionality of a session is exposed to the application by getting the
required feature(s) using the feature(Class)
method.
For each session there is a single instance of each feature which may be obtained and used at any time.
Properties are essentially key/value pairs. A property is identified by its key. All property keys must be alphanumeric, starting with an alphabetic and are case sensitive. Embedded whitespace is not allowed.
All fixed properties are identified by a '$' prefix. The currently available fixed session properties are:
Fixed Property Key | Property Description |
$SessionId | The session identifier. Equivalent to SessionId.toString() . |
$Principal | The session principal. Equivalent to ClientSummary.getPrincipal()
. |
$ClientType | The client type of the session. Equivalent to
ClientSummary.getClientType() . |
$Transport | The session transport type. Equivalent to
ClientSummary.getTransportType() . |
$Connector | The name of the connector on which the client connected. See
SessionDetails.getConnectorName() . |
$Country | The session's country code. See ClientLocation.CountryDetails.getCountry() . |
$Language | The session's language code. See ClientLocation.CountryDetails.getLanguage() . |
$ServerName | The name of the session's server. See
SessionDetails.getServerName() . |
When registering to receive session properties special key values of
ALL_FIXED_PROPERTIES
and ALL_USER_PROPERTIES
may be used.
A session filter query consists of either a single search clause (example 1) or multiple search clauses connected by boolean operators (example 2):
1. Department is "Accounts"
2. Department is "Payroll" and Status is "Closed"
Search clauses may be linked by the boolean operators and or or. 'and' takes precedence over 'or' but parentheses may be used to override the precedence as follows:
(Department is "Accounts" or Department is "Payroll") and Status is "Closed"
The boolean not operator may be used to negate the following clause or
an expression within parentheses:
1. not Department is "Payroll"
2. not (Department is "Payroll" or Department is "Accounts")
A search clause takes the form:
key operator value
Where key is the name of a session property and value is the property value. Only string values are currently supported and must be enclosed within either single or double quotes.
Supported operators are as follows:
Operator | Description |
is or eq | equals |
ne | not equals |
All operators are case insensitive.
The following are examples of valid expressions:
$Principal is "Alice"
Department is "Accounts" and $Country ne "US"
$Language EQ "en" and $Country NE "US"
not (Department is "Accounts" or
"Department is "Payroll") and $Country is "FR"
Modifier and Type | Interface and Description |
---|---|
static interface |
Session.ErrorHandler
The error notification interface for a session.
|
static interface |
Session.Listener
The optional listener interface for a session which may be used to
receive state notifications.
|
static interface |
Session.SessionError
Encapsulates the detail of a reported error.
|
static class |
Session.State
Session state.
|
Modifier and Type | Field and Description |
---|---|
static String |
ALL_FIXED_PROPERTIES
This constant can be used instead of a property key in requests for
session property values to indicate that all fixed session
properties are required.
|
static String |
ALL_USER_PROPERTIES
This constant can be used instead of a property key in requests for
session property values to indicate that all user defined session
properties are required.
|
static String |
ANONYMOUS
Value returned by
getPrincipal() if no principal name is
associated with the session. |
Modifier and Type | Method and Description |
---|---|
void |
addListener(Session.Listener listener)
Add a session listener.
|
void |
close()
Close the session.
|
<T extends Feature> |
feature(Class<T> featureInterface)
Obtain a feature.
|
SessionAttributes |
getAttributes()
Returns the session attributes.
|
String |
getPrincipal()
Returns the name of the security principal associated with the session.
|
SessionId |
getSessionId()
Returns the unique identifier for the session as assigned by the (first)
server it connects to.
|
Session.State |
getState()
Returns the current state of the session.
|
void |
removeListener(Session.Listener listener)
Remove a session listener.
|
void |
start()
Deprecated.
since 5.3 this method has no effect and will be removed at a
future release
|
static final String ANONYMOUS
getPrincipal()
if no principal name is
associated with the session.static final String ALL_FIXED_PROPERTIES
static final String ALL_USER_PROPERTIES
SessionId getSessionId()
String getPrincipal()
ANONYMOUS
) will be returnedSessionAttributes getAttributes()
Session.State getState()
@Deprecated void start()
void close()
Has no effect if the session is already closed
close
in interface AutoCloseable
<T extends Feature> T feature(Class<T> featureInterface) throws SessionClosedException, IllegalArgumentException, UnsupportedOperationException
This may be used to get any feature,. It will automatically instantiate the feature the first time it is called.
T
- feature typefeatureInterface
- the feature interfaceSessionClosedException
- if the session is closedIllegalArgumentException
- if featureInterface
is null or
not an interfaceUnsupportedOperationException
- if no implementation of the feature
is supported or foundvoid addListener(Session.Listener listener)
listener
- the listenerIllegalArgumentException
- if listener
is nullvoid removeListener(Session.Listener listener)
equal
to listener
will be removed.listener
- the listenerIllegalArgumentException
- if listener
is nullCopyright © 2016 Push Technology Ltd. All Rights Reserved.