public interface SessionFactory
sessions
.
An initial instance of this factory with all session attributes set as
default may be obtained from Diffusion.sessions()
. Every time an
attribute is changed a new immutable instance of the factory is returned with
all values as before other than the new changed value.
A new session may be created using open(String, OpenCallback)
specifying the URL that identifies the server. Since the URL can only be used
to configure a single transport it cannot be used to configure cascading. If
a connection was accepted by the server, the
onOpened
callback method will be
invoked passing a reference to the session otherwise the
onError
callback method will be
invoked.
There is also a blocking version of open(String)
which only returns
normally if a connection was accepted by the server.
A new session may be opened using open(OpenCallback)
without
specifying a URL. Instead the server is identified by using the
serverHost(String)
and serverPort(int)
methods. These
methods can be used with transports(SessionAttributes.Transport...)
,
requestPath(String)
and secureTransport(boolean)
to
configure additional information about how to connect to a server. This
allows the configuration of multiple transports for cascading. When these
values and a URL is specified to open the session, the URL takes precedence
and overrides the configured values.
URLs should take the form scheme://host:port, where scheme is chosen from the following table and determines the transport protocol used to send Diffusion messages.
Scheme | Transport Protocol |
---|---|
ws |
WebSocket. See RFC 6455 . |
wss |
WebSocket over TLS. |
dpt |
Deprecated. "DPT" or Diffusion Protocol. A proprietary TCP protocol. |
dpts |
Deprecated. Diffusion Protocol over TLS. |
http |
Deprecated. HTTP Duplex. A proprietary TCP protocol that is sufficiently like HTTP to be acceptable to some third-party network intermediaries. |
https |
Deprecated. HTTP Duplex over TLS. |
We recommend using the WebSocket protocol options ( ws
or wss
). There is no measurable performance difference between the DPT and
WebSocket protocols.
TLS is Transport Layer Security, commonly known as SSL. TLS-based protocols use cryptography to provide transport-level privacy, authentication, and integrity, and protects against network-sniffing and man-in-the-middle attacks. We recommend using the TLS variants for all communication. For a typical application, you should only consider not using TLS for unauthenticated ("anonymous") client sessions.
The HTTP Duplex protocol was deprecated in version 5.7 and will be removed in a future release of the product.
Modifier and Type | Interface and Description |
---|---|
static interface |
SessionFactory.OpenCallback
Callback interface for non-blocking opening of sessions.
|
static interface |
SessionFactory.OpenContextCallback<C>
Contextual version of
SessionFactory.OpenCallback for use with
open(String, Object, OpenContextCallback) |
Modifier and Type | Method and Description |
---|---|
SessionFactory |
connectionTimeout(int timeout)
Sets the connection timeout.
|
SessionFactory |
credentials(Credentials credentials)
Set credentials.
|
SessionFactory |
customCredentials(byte[] bytes)
Set credentials of type
Credentials.Type.CUSTOM . |
SessionFactory |
errorHandler(Session.ErrorHandler errorHandler)
Nominates an error handler for a session.
|
SessionFactory |
httpProxy(String host,
int port)
Set the address of the HTTP Proxy that should be used to make connections
to the server.
|
SessionFactory |
httpProxy(String host,
int port,
HTTPProxyAuthentication authentication)
A variant of
httpProxy(String, int) that provides authentication
details to the HTTP proxy. |
SessionFactory |
inputBufferSize(int size)
Sets the input buffer size for socket connection buffers and message
receiving buffers.
|
SessionFactory |
listener(Session.Listener listener)
Nominates a listener for session events from a session.
|
SessionFactory |
localSocketAddress(SocketAddress address)
Set the optional local socket address, used prior to connection.
|
SessionFactory |
maximumMessageSize(int size)
Set the maximum message size.
|
SessionFactory |
maximumQueueSize(int size)
Sets the maximum size of the outbound message queue for the connection.
|
SessionFactory |
noCredentials()
Set credentials to
Credentials.Type.NONE . |
SessionFactory |
noReconnection()
Disable reconnection.
|
Session |
open()
Open a new client session connected to a server using the configuration
of the factory.
|
<C> void |
open(C context,
SessionFactory.OpenContextCallback<C> callback)
Opens a new client session that will connect to a server using the
configuration of the factory and using a contextual callback.
|
void |
open(SessionFactory.OpenCallback callback)
Opens a new client session that will connect to a server using the
configuration of the factory.
|
Session |
open(String url)
Open a new client session connected to a server via a given URL.
|
<C> void |
open(String url,
C context,
SessionFactory.OpenContextCallback<C> callback)
Opens a new client session that will connect to a server via a given URL
and using a contextual callback.
|
void |
open(String url,
SessionFactory.OpenCallback callback)
Opens a new client session that will connect to a server via a given URL.
|
SessionFactory |
outputBufferSize(int size)
Sets the output buffer size for socket connection buffers and message
sending buffers.
|
SessionFactory |
password(String password)
Set credentials of type
Credentials.Type.PLAIN_PASSWORD . |
SessionFactory |
principal(String principal)
Sets the security principal.
|
SessionFactory |
reconnectionStrategy(ReconnectionStrategy strategy)
Sets the reconnection strategy.
|
SessionFactory |
reconnectionTimeout(int timeout)
Sets the reconnection timeout.
|
SessionFactory |
recoveryBufferSize(int size)
Set the recovery buffer size.
|
SessionFactory |
requestPath(String requestPath)
Set the path used for HTTP requests.
|
SessionFactory |
secureTransport(boolean secureTransport)
Set if a secure transport should be used.
|
SessionFactory |
serverHost(String host)
Set the host name of the server to connect the session to.
|
SessionFactory |
serverPort(int port)
Set the port of the server to connect the session to.
|
SessionFactory |
sslContext(SSLContext context)
Sets the SSL Context if a secure connection is required.
|
SessionFactory |
transports(SessionAttributes.Transport... transports)
Set the transports to use to connect the session to the server.
|
SessionFactory |
writeTimeout(int timeout)
Sets the write timeout value for blocking writes.
|
SessionFactory listener(Session.Listener listener)
If not specified, there will be no session listener.
listener
- specifies a listener to be used for subsequent sessions
that are created. Null may be specified to remove any previously
specified listenerSessionFactory errorHandler(Session.ErrorHandler errorHandler)
If not specified, an instance of Session.ErrorHandler.Default
will be used.
errorHandler
- specifies the error handler to use for subsequent
sessions that are created. Null may be specified to remove any
previously specified handler and effectively revert to using the
default handlerSessionFactory principal(String principal) throws IllegalArgumentException
By default this will be Session.ANONYMOUS
.
principal
- the principalIllegalArgumentException
- if principal
is nullSessionFactory noCredentials()
Credentials.Type.NONE
.
This is the default.
SessionFactory credentials(Credentials credentials) throws IllegalArgumentException
The default is Credentials.Type.NONE
.
credentials
- the credentialsIllegalArgumentException
- if credentials
is nullSessionFactory password(String password) throws IllegalArgumentException
Credentials.Type.PLAIN_PASSWORD
.
The default is Credentials.Type.NONE
.
password
- the passwordIllegalArgumentException
- is password
is nullSessionFactory customCredentials(byte[] bytes) throws IllegalArgumentException
Credentials.Type.CUSTOM
.
The default is Credentials.Type.NONE
.
bytes
- the credentialsIllegalArgumentException
- if bytes
is nullSessionFactory connectionTimeout(int timeout) throws IllegalArgumentException
This constrains the time taken to establish an initial connection to the
server. The write timeout
constrains the time
to send the connection request. The server is responsible for limiting
the overall time taken to complete a connection once it has received the
request.
The default is SessionAttributes.DEFAULT_CONNECTION_TIMEOUT
.
timeout
- the default connection timeout in milliseconds. If this
exceeds one hour (3600000ms) a warning will be logged and the
time-out will be set to one hour.IllegalArgumentException
- if an illegal timeout value is suppliedSessionFactory noReconnection()
This is equivalent to calling reconnectionTimeout(int)
with a timeout of 0
.
SessionFactory reconnectionTimeout(int timeout) throws IllegalArgumentException
The default is SessionAttributes.DEFAULT_RECONNECTION_TIMEOUT
.
A timeout value of 0
or less is equivalent to to calling
noReconnection()
.
timeout
- the timeout duration to use when attempting to reconnect,
in millisecondsIllegalArgumentException
- if an illegal timeout value is suppliedSessionFactory reconnectionStrategy(ReconnectionStrategy strategy) throws IllegalArgumentException
If the reconnection timeout has been set, but not a strategy, sessions will use a default strategy that attempts to reconnect on a regular basis of 5 seconds until the reconnection timeout is exceeded.
strategy
- the reconnection strategy to useIllegalArgumentException
- if an illegal strategy is suppliedSessionFactory inputBufferSize(int size) throws IllegalArgumentException
This controls both how much pending data the socket can accommodate and
how much available data will be read by the input tasks. In general
setting both this and outputBufferSize(int)
to the same
reasonable size will result in higher network throughput. The cost of the
receiving buffer is only incurred when actually reading data for
processing. The cost of the socket buffer is always incurred and may be
modified by the operating system.
The default is SessionAttributes.DEFAULT_INPUT_BUFFER_SIZE
.
size
- input buffer size in bytes. This may not be less than
SessionAttributes.MAXIMUM_MESSAGE_SIZE_MIN
.IllegalArgumentException
- if the input buffer size is invalidSessionFactory outputBufferSize(int size) throws IllegalArgumentException
This controls both how much pending data the socket can accommodate and
how much data will be batched by sending messages. In general setting
both this and inputBufferSize(int)
to the same reasonable size
will result in higher network throughput. The cost of the sending buffer
is only incurred when actually queuing data for output. The cost of the
socket buffer is always incurred and may be modified by the operating
system.
The default is SessionAttributes.DEFAULT_OUTPUT_BUFFER_SIZE
.
size
- output buffer size in bytes.IllegalArgumentException
- if the output buffer size is invalidSessionFactory localSocketAddress(SocketAddress address)
By default no local socket address is used.
address
- the local socket address. Setting this to null effectively
removes any previous settingSessionFactory sslContext(SSLContext context) throws IllegalArgumentException
If not explicitly supplied, the default
context
will be used.
Setting the SSL Context will not enable transport layer security. It must
also be specified by the URL or secureTransport(boolean)
.
context
- the SSL Context to use when making the connectionIllegalArgumentException
- if context
is null
SessionFactory writeTimeout(int timeout) throws IllegalArgumentException
Blocking writes are only used for the initial connection request. If it is not possible to complete the write within this time, the connection is closed.
The default is SessionAttributes.DEFAULT_WRITE_TIMEOUT
.
timeout
- the write timeout in milliseconds. If this exceeds one
hour (3600000ms) a warning will be logged and the time-out will be
set to one hour.IllegalArgumentException
- if timeout
is invalidSessionFactory maximumMessageSize(int size) throws IllegalArgumentException
This constrains the size of messages that may be received from the server and thus the size of any content that can be received. The limit is simply to protect against unexpectedly large messages.
The default is SessionAttributes.DEFAULT_MAXIMUM_MESSAGE_SIZE
.
size
- the maximum message size in bytes. This must not be less than
SessionAttributes.MAXIMUM_MESSAGE_SIZE_MIN
IllegalArgumentException
- if the specified size
is invalidSessionFactory httpProxy(String host, int port) throws IllegalArgumentException
This allows connection to a server using HTTP CONNECT tunnelling through the specified proxy.
host
- the host name of the HTTP proxyport
- the port of the HTTP proxyIllegalArgumentException
- if the specified host
or
port
are invalidhttpProxy(String, int, HTTPProxyAuthentication)
SessionFactory httpProxy(String host, int port, HTTPProxyAuthentication authentication) throws IllegalArgumentException
httpProxy(String, int)
that provides authentication
details to the HTTP proxy.
This allows connection to a server using HTTP CONNECT tunnelling through the specified proxy, with authentication.
The authentication
parameter only affects communication with the
proxy, it is not passed on to the server.
Diffusion.proxyAuthentication()
and
ProxyAuthenticationFactory
can be used to create a suitable
instance. For example, to specify HTTP BASIC authentication with a user
name joe and password s3cret:
HTTPProxyAuthentication authentication = Diffusion.proxyAuthentication().basic("joe", "s3cret")
The principal(String)
and credentials(Credentials)
methods control authentication with the server and do not affect proxy
authentication.
host
- the host name of the HTTP proxyport
- the port of the HTTP proxyauthentication
- the authentication detailsIllegalArgumentException
- if the specified host
or
port
are invalidSessionFactory serverHost(String host) throws IllegalArgumentException
This value is only used if a URL is not provided when opening a session.
host
- the host name of the serverIllegalArgumentException
- if the specified host
is invalidSessionFactory serverPort(int port) throws IllegalArgumentException
This value is only used if a URL is not provided when opening a session. If the port is not set using this method or a URL, the port will be inferred based on the transport and security configuration. No port is inferred for DPT or DPTS and must be explicitly provided.
The provided value must be within the range used for port numbers.
port
- the port of the serverIllegalArgumentException
- if the specified port
is invalidSessionFactory transports(SessionAttributes.Transport... transports) throws IllegalArgumentException
When a session is opened, it will try to establish a connection with each transport in the list until successful. If a connection cannot be established using any of the transports, the session will be closed.
This value is only used if a URL is not provided when opening a session.
The WebSocket transport will be used by default.
transports
- the transports to use to connect the session to the
server. The provided transports may not be null, contain null or
be an empty array.IllegalArgumentException
- if the specified transports
are
invalidSessionFactory secureTransport(boolean secureTransport)
This value is only used if a URL is not provided when opening a session.
Enables or disables the use of transport layer security. TLS is disabled
by default because in most cases to correctly enable TLS an
SSLContext
must also be provided using
sslContext(SSLContext)
.
secureTransport
- If transport layer security is enabledSessionFactory requestPath(String requestPath) throws IllegalArgumentException
This value is only used if a URL is not provided when opening a session. The path must start with a '/' and end with '/diffusion'. The path used defaults to '/diffusion'. It has no effect upon DPT or DPTS connections.
requestPath
- the path used for HTTP requestsIllegalArgumentException
- if the specified requestPath
is
invalidSessionFactory recoveryBufferSize(int size) throws IllegalArgumentException
If the server is configured to support reconnection, a session
established with a non-zero
reconnection
time
retains a buffer of sent messages. If the session disconnects and
reconnects, this buffer is used to re-send messages that the server has
not received.
The default is SessionAttributes.DEFAULT_RECOVERY_BUFFER_SIZE
.
Higher values increase the chance of successful reconnection, but
increase the per-session memory footprint.
size
- the recovery buffer size in messages; can be 0IllegalArgumentException
- if the specified size
is
negativeSessionFactory maximumQueueSize(int size) throws IllegalArgumentException
The outbound message queue should be large enough to accommodate all the
messages sent to the server. This would include topic updates, messages
sent using Messaging
, MessagingControl
and service
requests such as registering a handler.
It may be necessary to increase this value for applications that send messages in bursts, or continue to send messages when a session is disconnected and reconnecting. Larger values allow more messages to be queued, and increase the memory footprint of the session.
If the outbound message queue fills, sending a message will cause the session to close with an error.
The default is SessionAttributes.DEFAULT_MAXIMUM_QUEUE_SIZE
.
size
- a positive integer indicating the maximum number of messages
that may be queuedIllegalArgumentException
- if the specified size is not a positive
integerSession open(String url) throws IllegalArgumentException, IllegalStateException, SessionClosedException, SessionSecurityException
This is a convenience version of open(String, OpenCallback)
which blocks until the connection with the server has been established.
url
- the server URL, see the class javadoc
IllegalArgumentException
- if url
is null or invalidIllegalStateException
- if any of the session attributes are found
to be inconsistent. For example, if the default SSL context could
not be loaded.SessionClosedException
- if an initial connection could not be
establishedSessionSecurityException
- if the client is insufficiently
authorized to start the session, based on the supplied client
credentialsvoid open(String url, SessionFactory.OpenCallback callback) throws IllegalArgumentException, IllegalStateException
This is a non-blocking methods which will return immediately and the
result of the attempt to open the session will be notified to the
specified callback
.
url
- the server URL, see the class javadoc
callback
- which will be notified of the result of attempting to
open the sessionIllegalArgumentException
- if either parameter is nullIllegalStateException
- if any of the session attributes are found
to be inconsistent. For example, if the default SSL context could
not be loaded.<C> void open(String url, C context, SessionFactory.OpenContextCallback<C> callback) throws IllegalArgumentException, IllegalStateException
This is the same as open(String, OpenCallback)
but with the
addition of an arbitrary context object.
C
- the context typeurl
- the server URL, see the class javadoc
context
- the context to pass to the callback, may be nullcallback
- which will be notified of the result of attempting to
open the sessionIllegalArgumentException
- if url
or callback
is
nullIllegalStateException
- if any of the session attributes are found
to be inconsistent. For example, if the default SSL context could
not be loaded.Session open() throws IllegalStateException, SessionClosedException, SessionSecurityException
serverHost(String)
, serverPort(int)
,
transports(SessionAttributes.Transport...)
,
secureTransport(boolean)
and requestPath(String)
methods.
This is a convenience version of open(OpenCallback)
which blocks
until the connection with the server has been established.
IllegalStateException
- if any of the session attributes are found
to be inconsistent. For example, if the default SSL context could
not be loaded.SessionClosedException
- if an initial connection could not be
establishedSessionSecurityException
- if the client is insufficiently
authorized to start the session, based on the supplied client
credentialsvoid open(SessionFactory.OpenCallback callback) throws IllegalArgumentException, IllegalStateException
serverHost(String)
, serverPort(int)
,
transports(SessionAttributes.Transport...)
,
secureTransport(boolean)
and requestPath(String)
methods.
This is a non-blocking methods which will return immediately and the
result of the attempt to open the session will be notified to the
specified callback
.
callback
- which will be notified of the result of attempting to
open the sessionIllegalArgumentException
- if the callback
is nullIllegalStateException
- if any of the session attributes are found
to be inconsistent. For example, if the default SSL context
could not be loaded.<C> void open(C context, SessionFactory.OpenContextCallback<C> callback) throws IllegalArgumentException, IllegalStateException
serverHost(String)
,
serverPort(int)
,
transports(SessionAttributes.Transport...)
,
secureTransport(boolean)
and requestPath(String)
methods.
This is the same as open(OpenCallback)
but with the addition of
an arbitrary context object.
C
- the context typecontext
- the context to pass to the callback, may be nullcallback
- which will be notified of the result of attempting to
open the sessionIllegalArgumentException
- if the callback
is nullIllegalStateException
- if any of the session attributes are found
to be inconsistent. For example, if the default SSL context could
not be loaded.Copyright © 2016 Push Technology Ltd. All Rights Reserved.