The classic client API will be removed in a future release.
@Deprecated public final class ExternalClientConnection extends Object implements ServerConnection
This allows a Java application to connect as a Client to a Diffusion server.
Each instance of this class provides a single connection to a Diffusion server and allows subscription to a number of topics.
ConnectionDetails
must be provided before connection which specify
the server (or servers if cascade connecting, load balancing or failover is
required) to connect to and other connection properties.
Connection to the server does not actually occur until connect()
is
invoked.
Any Topics to initially subscribe to on connection may be supplied in the
ConnectionDetails
or may be explicitly specified using
connect(TopicSet)
.
A listener
must be specified which will
receive notifications regarding the connection.
Additional topic listeners
may be added to receive
messages on a per topic basis.
It is possible to subscribe
to further topics at
any time (before or after connection) and also to
unsubscribe
from topics.
Note that this is a non blocking interface which will begin to receive messages on its own thread as soon as connection is successful.
After connection all messages published on subscribed topics will be routed to the listener (and any topic listeners if specified).
Messages may also be sent to the server using the
ServerConnection.send(TopicMessage)
method.
Listeners will be informed of disconnection if the connection with the server is lost. It may then be possible to (@link #reconnect() reconnect}.
Most methods that require a list of topics have forms that take a
TopicSet
or a list of topics. In either case the topics specified can
either be topic names or topic selector patterns which can be used to select
multiple topics. See TopicSet
for full details of how to specify
topic selectors.
The close()
method should be used to close the connection when no
longer required.
Constructor and Description |
---|
ExternalClientConnection()
Deprecated.
Constructs a Client Connection without connection details or a listener.
|
ExternalClientConnection(ServerConnectionListener listener,
ConnectionDetails connectionDetails)
Deprecated.
Construct a Client connection object.
|
ExternalClientConnection(ServerConnectionListener listener,
ServerDetails serverDetails)
Deprecated.
Constructs a Client Connection.
|
ExternalClientConnection(ServerConnectionListener listener,
String... urls)
Deprecated.
Convenience constructor which allows
ConnectionDetails to be
automatically created from one or more URLs. |
Modifier and Type | Method and Description |
---|---|
boolean |
acknowledge(TopicMessage message)
Deprecated.
Acknowledges a message that is
'Pending Acknowledgement' . |
void |
addTopicListener(TopicListener topicListener,
String... topics)
Deprecated.
Adds a
TopicListener . |
void |
addTopicListener(TopicListener topicListener,
TopicSet topics)
Deprecated.
Adds a
TopicListener . |
boolean |
close()
Deprecated.
Close client connection.
|
String |
connect()
Deprecated.
Connects to the server without subscribing to any topics.
|
String |
connect(String... topics)
Deprecated.
Connects to the server.
|
String |
connect(TopicSet topics)
Deprecated.
Connects to the server.
|
TopicMessage |
createDeltaMessage(String topicName)
Deprecated.
Creates an empty delta message.
|
TopicMessage |
createDeltaMessage(String topicName,
int capacity)
Deprecated.
Creates an empty delta message.
|
TopicMessage |
createLoadMessage(String topicName)
Deprecated.
Creates an empty load message.
|
TopicMessage |
createLoadMessage(String topicName,
int capacity)
Deprecated.
Creates an empty load message.
|
PagedTopicHandler |
createPagedTopicHandler(TopicMessage message,
PagedTopicListener listener)
Deprecated.
Creates a handler object for a 'paged' topic.
|
ServiceTopicHandler |
createServiceTopicHandler(TopicMessage message,
ServiceTopicListener listener)
Deprecated.
Creates a handler object for a service topic.
|
TopicNotifyTopicHandler |
createTopicNotifyTopicHandler(TopicMessage message,
TopicNotifyTopicHandler.NotificationLevel level,
TopicNotifyTopicListener listener)
Deprecated.
Creates a handler object for a 'Topic Notify' topic.
|
TopicNotifyTopicHandler |
createTopicNotifyTopicHandler(TopicMessage message,
TopicNotifyTopicListener listener)
Deprecated.
Creates a handler object for a 'Topic Notify' topic.
|
void |
fetch(String topic,
String... headers)
Deprecated.
Fetch the current state of a set of topics.
|
void |
fetch(TopicSet topics,
String... headers)
Deprecated.
Fetch the current state of a set of topics.
|
long |
getAckTimeout()
Deprecated.
Returns the default Server ACK timeout value for the connection.
|
String |
getClientID()
Deprecated.
Returns the client identifier for the connection.
|
ConnectionDetails |
getConnectionDetails()
Deprecated.
Returns the Connection Details.
|
long |
getLastInteraction()
Deprecated.
Returns time of last interaction with the server.
|
MessageSourceType |
getMessageSourceType()
Deprecated.
Returns the message source type.
|
String |
getName()
Deprecated.
Returns a name which uniquely identifies the server within the context
that the connection is being made.
|
ServerDetails |
getServerDetails()
Deprecated.
Returns the server details.
|
int |
getServerProtocolVersion()
Deprecated.
Returns the Diffusion protocol version used for this connection.
|
ServerConnectionState |
getState()
Deprecated.
Returns the current state of the connection.
|
boolean |
isConnected()
Deprecated.
Is the connection connected?
|
boolean |
isReconnected()
Deprecated.
This indicates whether the current connection represents a reconnection
of a previous connection.
|
void |
ping()
Deprecated.
Sends a ping message to the server.
|
void |
reconnect()
Deprecated.
Re-establish the last connection.
|
void |
removeAllListeners()
Deprecated.
Removes all listeners.
|
boolean |
removeTopicListener(TopicListener topicListener)
Deprecated.
Removes a
TopicListener . |
boolean |
send(TopicMessage message)
Deprecated.
Send a message to the server.
|
void |
sendCredentials(Credentials credentials)
Deprecated.
Send credentials to the server.
|
void |
setAckListener(ServerAckListener listener)
Deprecated.
Sets a listener to receive notification of non acknowledgement of
messages sent to the server.
|
void |
setAckTimeout(long timeout)
Deprecated.
Sets the (default) Server ACK timeout value for messages sent to the
Server that require acknowledgement.
|
void |
setConnectionDetails(ConnectionDetails connectionDetails)
Deprecated.
Allows Connection Details to be set if not specified on construction.
|
void |
setListener(ServerConnectionListener listener)
Deprecated.
This may be used to set the listener if it has not been set on
construction.
|
void |
setPingResponseListener(ServerPingResponseListener listener)
Deprecated.
Sets a listener to receive
'ping' responses. |
void |
subscribe(String... topics)
Deprecated.
Subscribes to a set of topics.
|
void |
subscribe(TopicSet topics)
Deprecated.
Subscribes to a set of topics.
|
String |
toString()
Deprecated.
Returns a String representation of the connection detail.
|
void |
unsubscribe(String... topics)
Deprecated.
Unsubscribes from a set of topics.
|
void |
unsubscribe(TopicSet topics)
Deprecated.
Unsubscribes from a set of topics.
|
public ExternalClientConnection(ServerConnectionListener listener, ConnectionDetails connectionDetails)
listener
- the listener for client connection events.connectionDetails
- the connection details specifying the details of
the connection to a server.public ExternalClientConnection()
Connection information must be specified before connecting using
setConnectionDetails(ConnectionDetails)
and a listener must be
added using setListener
.
public ExternalClientConnection(ServerConnectionListener listener, ServerDetails serverDetails)
This is a convenience constructor that automatically creates the
ConnectionDetails
from the specified list of
ServerDetails
.
The connection object is created but not connected until the
connect
method is invoked.
The specified listener
will receive all
notifications.
Initial topics to subscribe to may be specified on the server details or on connection.
listener
- the listener to receive all notifications.serverDetails
- specifies the details of the server to connect to.public ExternalClientConnection(ServerConnectionListener listener, String... urls) throws APIException
ConnectionDetails
to be
automatically created from one or more URLs.listener
- the listener for all notifications.urls
- one or more URLs that will be converted into
ServerDetails
.APIException
- if one or more URLs are invalid.public void setConnectionDetails(ConnectionDetails connectionDetails)
connectionDetails
- the connection detailspublic ConnectionDetails getConnectionDetails()
The details returned may be adjusted before connection if required.
public ServerDetails getServerDetails()
ServerConnection
If connected then this will return the details actually used for the connection.
getServerDetails
in interface ServerConnection
public void sendCredentials(Credentials credentials) throws APIException
ServerConnection
sendCredentials
in interface ServerConnection
credentials
- the credentialsAPIException
- if not connected or unable to send a credentials
messagepublic boolean close()
ServerConnection
After calling this method connect may be called again to re-establish the connection.
close
in interface ServerConnection
public String connect() throws AuthorisationException, APIException
ServerConnection
connect
in interface ServerConnection
AuthorisationException
- if the connection has been rejected by the
serverAPIException
- if unable to connect to the serverpublic String connect(String... topics) throws AuthorisationException, APIException, TopicInvalidException
ServerConnection
This is effectively the same as calling ServerConnection.connect(TopicSet)
specifying a topic set constructed from the topic list.
connect
in interface ServerConnection
topics
- a set of topics/topic selectors specifying the topics to
initially subscribe to on connection. If no topics are specified
then no topics will be subscribed to on connection.AuthorisationException
- if the connection has been rejected by the
serverTopicInvalidException
- if one or more topics in the set are
invalidly specifiedAPIException
- if unable to connect to the server on its specified
host name and port numberpublic String connect(TopicSet topics) throws APIException, AuthorisationException, TopicInvalidException
ServerConnection
This blocks until successfully connected after which time incoming messages will be passed to all listeners declared for the topics subscribed to.
If this is called when already connected then the supplied topics will simply be subscribed.
connect
in interface ServerConnection
topics
- a set of topics/topic selectors specifying the topics to
initially subscribe to on connection. If this is null or empty
then no topics will be subscribed to on connection.TopicInvalidException
- if one or more topics in the set are
invalidly specifiedAuthorisationException
- if the connection has been rejected by the
serverAPIException
- if unable to connect to the server on its specified
host name and port numberpublic void reconnect() throws APIException
This can be used when a client has been disconnected to reconnect, assuming the server is using the keep alive facility to keep client state.
If reconnection is possible at the server then the connection will be
re-established as before with the same Topic subscriptions and any
messages queued for the Client whilst disconnected will be received.
Reconnection will be notified via the normal
ServerConnectionListener.serverConnected(ServerConnection)
.
On reconnection messages that were in transit at the time of the disconnection can be lost. Only messages that are set requiring acknowledgement are guaranteed to be redelivered on reconnect.
If a reconnection is not possible at the server, possibly because it is not supported or the Client session at the server has timed out, then a new connection will be established using the same Topic set that was used for the initial connection.
It is possible to tell whether a successful connection refers to a
reconnect or a new connection using the
ServerConnection.isReconnected()
method.
APIException
- if unable to reconnect or connect.public String getClientID()
ServerConnection
getClientID
in interface MessageSource
getClientID
in interface ServerConnection
public String getName()
ServerConnection
getName
in interface ServerConnection
public ServerConnectionState getState()
ServerConnection
getState
in interface ServerConnection
public boolean isConnected()
ServerConnection
isConnected
in interface ServerConnection
public boolean isReconnected()
ServerConnection
isReconnected
in interface ServerConnection
connected)
and the connection is a
reconnection of a previous connection, false if the connection is
a new connection.public void ping() throws APIException
ServerConnection
The response will be returned via the listener set using
ServerConnection.setPingResponseListener(ServerPingResponseListener)
.
ping
in interface ServerConnection
APIException
- if unable to send ping messagepublic boolean send(TopicMessage message) throws APIException
ServerConnection
send
in interface ServerConnection
message
- - the message to sendAPIException
- if unable to send the messagepublic boolean acknowledge(TopicMessage message) throws APIException
ServerConnection
'Pending Acknowledgement'
.
Assuming the message is pending acknowledgement then a message of acknowledgement is sent to the server.
acknowledge
in interface ServerConnection
message
- the message to acknowledgeAPIException
- if unable to acknowledge the given messagepublic void setListener(ServerConnectionListener listener)
A listener must be set before connecting.
setListener
in interface ServerConnection
listener
- the listener.public void setPingResponseListener(ServerPingResponseListener listener)
ServerConnection
'ping'
responses.
'ping' requests are sent using ServerConnection.ping()
.
If no listener is specified then any 'ping' responses will be ignored.
setPingResponseListener
in interface ServerConnection
listener
- the listener for 'ping' responses. Specifying null has
the effect of removing any current listener.public void setAckListener(ServerAckListener listener)
ServerConnection
This is only required if message acknowledgement is in use. i.e. messages
have setAckRequired
called before
sending them to the Server. When message acknowledgement is used then
such a listener must be set otherwise an attempt to send such a message
to the Server will fail.
setAckListener
in interface ServerConnection
listener
- the listener. Setting to null removes any current
listener.public void removeAllListeners()
This may only be called when not connected
.
This clears the listener, the ping response listener, the ack listener and any topic listeners that have been set.
public long getAckTimeout()
ServerConnection
getAckTimeout
in interface ServerConnection
public void setAckTimeout(long timeout)
ServerConnection
The ACK timeout is the number of milliseconds allowed between sending a
message with acknowledgement required (see
TopicMessage.setAckRequired()
) and acknowledgement being received
from the Server. If acknowledgement is not received within this time then
notification will occur via the ServerAckListener
interface (see
ServerConnection.setAckListener(ServerAckListener)
).
This value is used if the timeout value is not explicitly set for the
message using TopicMessage.setAckTimeout(long)
.
If no value is explicitly specified for the connection then a default value is assumed.
setAckTimeout
in interface ServerConnection
timeout
- the default ACK timeout value in millisecondspublic void subscribe(String... topics) throws TopicInvalidException, APIException
ServerConnection
This is the same as calling ServerConnection.subscribe(TopicSet)
with a
TopicSet
constructed from the specified topics list.
subscribe
in interface ServerConnection
topics
- a list of topic names and/or topic selector patterns
indicating topics to subscribe to. See the user manual for full
details of how to use topic selector patterns.TopicInvalidException
- if one or more topics are invalidly
specifiedAPIException
- if unable to subscribepublic void subscribe(TopicSet topics) throws TopicInvalidException, APIException
ServerConnection
This may be used at any time after connection to add to the topics subscribed to on connection.
subscribe
in interface ServerConnection
topics
- a set of topic names and/or topic selector patterns
indicating topics to subscribe toTopicInvalidException
- if one or more topics are invalidly
specifiedAPIException
- if unable to subscribepublic void fetch(TopicSet topics, String... headers) throws TopicInvalidException, APIException
ServerConnection
The state of a topic may be retrieved without the need to subscribe to the topic in question.
The state of each topic will be returned on the
ServerConnectionListener.messageFromServer(ServerConnection, TopicMessage)
method as a topic load message
which will return
true from the TopicMessage.isFetchReply()
method.
fetch
in interface ServerConnection
topics
- a set of topic names and/or topic selector patterns
indicating topics to fetch the state ofheaders
- a set of headers may optionally be supplied and if they
are then they will be reflected back with the fetched message
(appended to user headers on the message if there are any). These
headers may be used to supply correlation data so that the reply
can be associated with the request.TopicInvalidException
- if one or more topics are invalidly
specifiedAPIException
- if unable to fetchpublic void fetch(String topic, String... headers) throws TopicInvalidException, APIException
ServerConnection
This is the same as calling ServerConnection.fetch(TopicSet, String...)
with a
TopicSet
constructed from the specified topics list.
fetch
in interface ServerConnection
topic
- topic name and/or topic selector pattern indicating topic(s)
to fetch the state of. A list of such patterns separated by ','
may be supplied if required.headers
- a set of headers may optionally be supplied and if they
are then they will be reflected back with the fetched message
(appended to user headers on the message if there are any). These
headers may be used to supply correlation data so that the reply
can be associated with the request.TopicInvalidException
- if one or more topics are invalidly
specifiedAPIException
- if unable to fetchpublic void unsubscribe(String... topics) throws TopicInvalidException, APIException
ServerConnection
This is the same as calling ServerConnection.unsubscribe(TopicSet)
with a
TopicSet
constructed from the specified list.
unsubscribe
in interface ServerConnection
topics
- a list of topic names and/or topic selector patterns
specifying topics to unsubscribe fromTopicInvalidException
- if one or more of the specified topic
names/selector patterns is invalidAPIException
- if unable to unsubscribe topicspublic void unsubscribe(TopicSet topics) throws TopicInvalidException, APIException
ServerConnection
This may be used at any time whilst connected to reduce the set of topics that the client subscribes to.
unsubscribe
in interface ServerConnection
topics
- a set of topic names and/or topic selector patterns
specifying topics to unsubscribe fromTopicInvalidException
- if one or more of the specified topic
names/selector patterns is invalidAPIException
- if unable to unsubscribe topicspublic TopicMessage createDeltaMessage(String topicName) throws MessageException
ServerConnection
The message will have its capacity set to the value returned by
RootConfig.getDefaultDeltaMessageCapacity()
.
Note that when topic aliasing is in use then this may create a message that contains the alias rather than the full topic name and therefore such a message could only be sent on this connection.
createDeltaMessage
in interface ServerConnection
topicName
- the topic nameMessageException
- if unable to create a new messagepublic TopicMessage createDeltaMessage(String topicName, int capacity) throws MessageException
ServerConnection
Note that when topic aliasing is in use then this may create a message that contains the alias rather than the full Topic name and therefore such a message could only be sent on this connection.
createDeltaMessage
in interface ServerConnection
topicName
- the topic namecapacity
- the initial capacity of the message which should be
sufficient to hold the data and any user headers. If more is
written to the message than this then it will automatically be
extended, however there is an overhead to such extensions so for
maximum efficiency a suitable capacity should be chosen.MessageException
- if unable to create a new messagepublic TopicMessage createLoadMessage(String topicName) throws MessageException
ServerConnection
The message will have its capacity set to the value returned by
RootConfig.getDefaultLoadMessageCapacity()
.
createLoadMessage
in interface ServerConnection
topicName
- the topic nameMessageException
- if unable to create a new messagepublic TopicMessage createLoadMessage(String topicName, int capacity) throws MessageException
ServerConnection
createLoadMessage
in interface ServerConnection
topicName
- the topic namecapacity
- the initial capacity of the message which should be
sufficient to hold the data and any user headers. If more is
written to the message than this then it will automatically be
extended, however there is an overhead to such extensions so for
maximum efficiency a suitable capacity should be chosen.MessageException
- if unable to create a new messagepublic int getServerProtocolVersion()
ServerConnection
getServerProtocolVersion
in interface ServerConnection
public void addTopicListener(TopicListener topicListener, String... topics) throws APIException
ServerConnection
TopicListener
.
addTopicListener
in interface ServerConnection
topicListener
- the topic listener.topics
- a set of full topic names and/or topic selector patterns.APIException
- if unable to add the topic listenerServerConnection.addTopicListener(TopicListener, String...)
public void addTopicListener(TopicListener topicListener, TopicSet topics) throws APIException
ServerConnection
TopicListener
.
This allows inbound messages to be routed to one or more recipient
objects according to the message topic. Messages are routed to listeners
in the order that they were declared and before routing to
ServerConnectionListener.messageFromServer(ServerConnection, TopicMessage)
. Each listener will receive a different copy of the message.
A topic listener can be declared for each topic or can apply to more than
one topic by using topic selector patterns, see TopicSet
for full
details of how to use topic selector patterns. Also, any number of
listeners may be specified for any one topic or selector pattern.
Any listener can choose to consume the Message in which case it would not be passed to any other listeners.
addTopicListener
in interface ServerConnection
topicListener
- the topic listenertopics
- a list of full topic names and/or topic selector patternsAPIException
- if unable to add the topic listenerpublic boolean removeTopicListener(TopicListener topicListener)
ServerConnection
TopicListener
.
All uses of the given listener are removed.
removeTopicListener
in interface ServerConnection
topicListener
- the topic listenerpublic MessageSourceType getMessageSourceType()
MessageSource
getMessageSourceType
in interface MessageSource
public long getLastInteraction()
ServerConnection
This returns the time (in milliseconds since the epoch) of the last interaction (whether send or receive) with the server.
getLastInteraction
in interface ServerConnection
public ServiceTopicHandler createServiceTopicHandler(TopicMessage message, ServiceTopicListener listener) throws APIException
ServerConnection
See
ServiceTopicData
for details of service topics.
This would be called in response to receiving a
load
message from a service topic as
a result of subscribing to it. Note that no other messages would be
received from a service topic other than via the specified
ServiceTopicListener
.
createServiceTopicHandler
in interface ServerConnection
message
- the load message received from the topiclistener
- an object that is to receive all service replies and
notificationsAPIException
- if unable to create the handlerpublic PagedTopicHandler createPagedTopicHandler(TopicMessage message, PagedTopicListener listener) throws APIException
ServerConnection
See PagedTopicData
for details of paged topics.
This would be called in response to receiving a
load
message from a paged topic as a
result of subscribing to it. Note that no other messages would be
received from a paged topic until the returned handler is used to
open
the topic.
createPagedTopicHandler
in interface ServerConnection
message
- the load message received from the topic.listener
- an object that is to receive all notifications from the
topicAPIException
- if unable to create the handlerpublic TopicNotifyTopicHandler createTopicNotifyTopicHandler(TopicMessage message, TopicNotifyTopicHandler.NotificationLevel level, TopicNotifyTopicListener listener) throws APIException
ServerConnection
See TopicNotifyTopicData
for details of topic notify topics.
This would be called in response to receiving a
load
message from a topic notify
topic as a result of subscribing to it. Note that no other messages would
be received from a topic notify topic until the returned handler is used
to select notifications required.
createTopicNotifyTopicHandler
in interface ServerConnection
message
- the load message received from the topiclevel
- specifies the add notification level requiredlistener
- an object that is to receive all notifications from the
topicAPIException
- if unable to create the handler.public TopicNotifyTopicHandler createTopicNotifyTopicHandler(TopicMessage message, TopicNotifyTopicListener listener) throws APIException
ServerConnection
See
TopicNotifyTopicData
for details of topic notify topics.
This would be called in response to receiving a
load
message from a topic notify
topic as a result of subscribing to it. Note that no other messages would
be received from a topic notify topic until the returned handler is used
to select notifications required. The level of notification required may
also need to be set before any selections are made.
createTopicNotifyTopicHandler
in interface ServerConnection
message
- the load message received from the topiclistener
- an object that is to receive all notifications from the
topicAPIException
- if unable to create the handlerpublic String toString()
This will comprise the server name suffixed by the client identifier in parentheses when connected.
Copyright © 2016 Push Technology Ltd. All Rights Reserved.