17.8. Handling Replacing events

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

public void subscribeToREvent(String eventName, RemoteEventListener listener)

The method has 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. Note that the endpoint receives the next event only after the current call to the handler has completed. The method has two parameters:

  • clientEndpoint is an endpoint that called the handler;
  • remoteEvent of type RemoteEvent is the event itself. The type is described below.

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.

Let’s consider the RemoteEvent type. Note that it is used to represent events from all three categories. It has the following read-only fields:

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 Replacing events, it is set to Replacing;
  • isNull is true for Replacing null-events, false otherwise;
  • 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 Replacing event defined in the example of the previous section:

softnetClient.subscribeToREvent("WaterTemperature", new RemoteEventListener() {			
    public void accept(ClientEndpoint clientEndpoint, RemoteEvent remoteEvent) {
        try {
            if(!remoteEvent.isNull) {
                System.out.println(String.format(
                    "The event '%s' is received.",
                    remoteEvent.name));					
                System.out.println(String.format(
                    "Water temperature changed to '%d' degrees Celsius.", 
                    remoteEvent.arguments.Int32()));
            }
            else {
                System.out.println(String.format(
                    "The null-event '%s' is received.", 
                    remoteEvent.name));
                System.out.println("Water temperature is normal.");
            }
        }
        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