DEPRECATED: Java Client Classic API
The client Classic API provides the ability to connect to a Diffusion™ server as an external client from within any Java™ application.
For full API documentation, see Java Classic API documentation
How to use the Java client API
There is a single class called ExternalClientConnection which can be instantiated with the required connection details and used to make an actual connection.
The connection class is of the generic type ServerConnection and as such, once a connection is made, any notifications or messages from the server are passed through the ServerConnectionListener interface.
The topic or topics to subscribe to can be specified when connecting or at any time after connection.
The ServerConnectionListener specified will receive all messages for all topics. However, any number of additional topic listeners can be specified and messages for different topics routed to different listeners as required.
The API permits the following types of connection to be specified by using the ServerDetails (see connection package) specified when configuring the connection object:
TCP | For a standard connection over TCP/IP. This must connect to a standard client connector. |
Secure Sockets Layer (SSL) | For a secure TCP/IP connection over SSL. This must connect to a client connector with SSL enabled |
HTTP | For a connection using HTTP |
HTTP/SSL | For a connection using HTTP over SSL. |
By specifying more than one ServerDetails, fallback connections can be specified. If the first connection does not succeed, the second is tried, and so on.
For a detailed description of the API see the issued API documentation (in docs directory).
Authorization credentials
If authorization credentials are required by the Diffusion server, these are set at the ConnectionDetails level and used for all ServerDetails. Credentials can be set in a ServerDetails by creating a Credentials object and using setCredentials before connecting.
Credentials can also be sent to the server after connection using the method sendCredentials in ExternalClientConnection. In this case the credentials can be rejected by the server, in which case this is notified on the serverRejectedCredentials method of each ServerConnectionListener.
Certificates
Diffusion Java clients use certificates to validate the security of their connection to the Diffusion server. The client validates the certificate sent by the Diffusion server against the set of certificates trusted by the Java Development Kit (JDK).
If the certificate sent by the Diffusion server cannot be validated against any certificates in the set trusted by the JDK, you must set up a trust store for the client and add the appropriate certificates to that trust store.
Diffusion is authenticated using the certificates provided by your certificate authority for the domain you host the Diffusion server on.
- Obtain the appropriate intermediate certificate from the certificate authority.
- Use keytool to create a trust store for your client that includes this
certificate.
For more information, see https://docs.oracle.com/cd/E19509-01/820-3503/ggfka/index.html
- Use system properties to add the trust store to your client. For example:
System.setProperty("javax.net.ssl.trustStore", "truststore_name");
Or at the command line:-Djavax.net.ssl.keyStore=path_to_truststore
Reconnection
If a client unexpectedly loses connection, it can try to reconnect using the reconnect method. If the server has specified reconnection timeout (keep-alive) for the connector, the client can pick up the same session as before and receive all messages that were queued for it whilst disconnected. The topic state (that is, which topics the client is subscribed to) is also re-established on reconnection. If unable to reconnect, a new connection is established with the same topic set as used on the original connection. Successful reconnection or connection is notified on the normal serverConnected method and you can determine which has occurred using the ServerConnection.isReconnected() method.
There is no guarantee that messages in transit at the time of the disconnection will be redelivered. However, all messages marked as requiring acknowledgment by the server are delivered.
Failover
The Java client supports autofailover. For more information, see Client failover.
Special features
- Paged topic data handling
- Where paged topic data is in use at the server there are features within the client API which simplify the handling of messages to and from such a topic.
- Service topic data handling
- Where service topic data is in use at the server there are features within the client API which simplify the handling of messages to and from such a topic.
Example: Simple client class
The following example shows a simple client class which sends a message containing "Hello" to the server and logs all messages it receives, until it receives a message from the server (Publisher) asking it to stop. It tries to connect through TCP first but if that fails it tries HTTP.
public class ClientApplication implements ServerConnectionListener { private static final Logger LOG = LoggerFactory.getLogger(ClientApplication.class); private ExternalClientConnection theConnection; public ClientApplication() throws APIException { // Create Connection theConnection= new ExternalClientConnection( this, "ws://diffusion.example.com:80", "http://diffusion.example.com:80"); // Connect, subscribing to a single topic theConnection.connect("MyTopic"); // Send a message TopicMessage message = theConnection.createDeltaMessage("MyTopic"); message.put("Hello"); theConnection.send(message); } public void messageFromServer( ServerConnection serverConnection, TopicMessage message) { LOG.info("Message Received : {}",message); try { if (message.asString().equals("STOP")) { theConnection.close(); } } catch(Exception ex) { ex.printStackTrace(); } } public void serverConnected(ServerConnection serverConnection){ LOG.info("Connected to Server : {}",serverConnection); } public void serverTopicStatusChanged( ServerConnection serverConnection, String topicName, TopicStatus status) { LOG.info( "Topic {} at {} status changed to {}", topicName,serverConnection,status); } public void serverRejectedCredentials( ServerConnection serverConnection, Credentials credentials) { LOG.info("Server Rejected Credentials : {}",serverConnection); } public void serverDisconnected(ServerConnection serverConnection) { LOG.info("Disconnected from Server : {}",serverConnection); } }