Package com.pushtechnology.diffusion.client.features

package com.pushtechnology.diffusion.client.features
Client API : Standard Features.

This package contains the standard client features.

A feature represents a unit of functionality that is available to use within a client session.

Standard client features include:

Topics
This feature allows a client to subscribe to topics in order to receive streaming updates. It also allows a client to fetch the state of topics without having to subscribe to them.

Messaging
This feature allows a client to send messages on a topic (to be delivered to the controller of that topic) or receive messages on topics (send by topic controllers).

Pings
This feature allows a client to ping the server to ensure connectivity and to obtain round trip timings.

Security
This feature allows a client to change it's principal.

A feature may be obtained from a session using the feature method specifying the feature class. For example: 


 Topics topics = session.feature(Topics.class);

CompletableFuture

Since version 6.0, the API has been extended to support Java 8's CompletableFuture. All methods that have a callback that produces a single outcome now have an alternative that returns the outcome using a CompletableFuture rather than a callback.

CompletableFuture<?>

Some methods have a return type of CompletableFuture<?>. The result type is a wildcard rather than Void to provide forward compatibility with future iterations of this API that may provide a non-null result with a more specific result type. If such a method is called and the task completes successfully, the CompletableFuture result will be null.

Blocking methods are unsupported when chaining CompletableFutures

Calling a blocking CompletableFuture method, such as get or join, from a Diffusion thread is disallowed since doing so can cause the client to deadlock because the same thread is used to deliver responses from the server to the session.

This situation typically happens when chaining CompletableFutures. To protect against deadlock, Diffusion detects the use of a blocking method from a Diffusion thread, and completes the CompletableFuture exceptionally with a UnsupportedOperationException. For example: 

 messaging.sendMessage("x", "m1", String.class, String.class)
     .thenAccept(r1 -> {
         // This will run in the Diffusion input thread, when the
         // result of the first call is received.
         CompletableFuture<String> cf =
             messaging.sendMessage("y", r1, String.class, String.class);

         // This will immediately throw an ExecutionException with an
         // UnsupportedOperationException cause.
         String r2 = cf.get();

         // Not reached.
         LOG.info("Result {}", r2);
     });

To avoid the problem, when calling a second Diffusion method from a handler attached to a Diffusion-supplied CompletableFuture, only use non-blocking methods such as thenAccept on the result returned by the second method. For example: 

 messaging.sendMessage("x", "m1", String.class, String.class)
     .thenAccept(r1 -> {
         // This will run in the Diffusion input thread, when the
         // result of the first call is received.
         CompletableFuture<String> cf =
             messaging.sendMessage("y", r1, String.class, String.class);

         cf.thenAccept(r2 -> {
             LOG.info("Result {}", r2);
         });
     });

The blocking call protection is effective against the use of get and join, but does not work if a CompletableFuture is exposed indirectly as a stage of a plain, unprotected CompletableFuture via allOf(), anyOf, thenCombine, acceptEither, etc.

Since:
5.0
Author:
DiffusionData Limited