17.10. Handling Queueing events

Handling Queueing events is almost identical to handling Replacing events. In this description, most things are repeated, and the differences are noted.

A client application subscribes to a Queueing event by calling the following method of the ClientEndpoint class:

public void subscribeToQEvent(String eventName, RemoteEventListener listener)

The difference from the subscription method of Replacing events is only in the name of the method. It has the same two parameters:

  • eventName is the event name described in the previous section;
  • listener is an event listener of type RemoteEventListener.

An application provides the event name and implementation of the RemoteEventListener interface to the method call. The interface declares two methods to implement:

public interface RemoteEventListener {
    void accept(ClientEndpoint clientEndpoint, RemoteEvent remoteEvent);
    void acceptError(ClientEndpoint clientEndpoint, SoftnetException exception);
}

The first method, accept, is an event handler. It is called by the endpoint when it receives an event. As with Replacing events, the endpoint receives the next event only after the current call to the handler has completed. The method has two parameters:

  • clientEndpoint is the endpoint that called the handler;
  • remoteEvent of type RemoteEvent is the received event.

The second method, acceptError, is called in case of an error. Currently, the only possible error can be caused by subscribing to a non-existent event. The next is a description of the RemoteEvent fields. In contrast to Replacing events, here the category field is set to Queueing and the isNull field is not used:

public class RemoteEvent {
    public final String name;
    public final EventCategory category;
    public final boolean isNull;
    public final long serviceId;
    public final long age;
    public final java.util.Date createdDate;
    public final SequenceDecoder arguments;
}
  • name is the event name specified in the event subscription;
  • category is of type EventCategory enumeration. For Queueing events, it is set to Queueing;
  • isNull is not used;
  • serviceId is an ID of the remote service raised the event. To get the appropriate object of type RemoteService, call the client endpoint’s findService method that expects the service ID as an argument;
  • age specifies the time in seconds elapsed since the event has been received by the broker. This value is zero if the event is sent to the client without delay as soon as it is received by the broker;
  • createdDate specifies the date and time when the event has been received by the broker;
  • arguments is of type SequenceDecoder provided by Softnet ASN.1 Codec. It contains data attached to the event by the service.

This section concludes with an example of subscribing to the Queueing event defined in the example of the previous section:

softnetClient.subscribeToQEvent("CriticalWaterTemperature", new RemoteEventListener() {
    public void accept(ClientEndpoint clientEndpoint, RemoteEvent remoteEvent) {
        try {			
            System.out.println(String.format(
                "The event '%s' is received.",
                remoteEvent.name));
            System.out.println(String.format(
                "The water temperature reached a critical '%d' degrees Celsius.",
                remoteEvent.arguments.Int32()));
        }
        catch(Exception ex) {
            System.out.println(String.format(
                "Event data format error: %s",
                ex.getMessage()));
        }
    }
				
    public void acceptError(ClientEndpoint clientEndpoint, SoftnetException exception) {
        System.out.println(String.format(
            "Subscription error: %s",
            exception.getMessage()));					
    }
});

TABLE OF CONTENTS