Client API

The first step to opening a connection is providing the necessary configuration information. The AmqpSettings object contains connection settings for the broker, and the UserSettings object contains username/password information for client login.

Both can be loaded from configuration files:

// Load broker settings from config file
AmqpSettings amqp = new AmqpSettings("file path");

// Load user settings (login credentials) from config file
UserSettings user = new UserSettings("file path");
                

To establish a connection, first a ConnectionFactory must be instantiated (the ReefConnectionFactory class is the default implementation). It's configured with a AmqpSettings configuration and an instance of ServicesList, which provides bindings for actual services.

Using the ConnectionFactory interface, the connect method is used to acquire a connection to the server.

// Create a ConnectionFactory by passing the broker settings. The ConnectionFactory is
// used to create a Connection to the Reef server
ConnectionFactory connectionFactory = new ReefConnectionFactory(amqp, new ReefServices());

// Prepare a Connection reference so it can be cleaned up in case of an error
Connection connection = connectionFactory.connect();
                

Once the connection has been established, the next step is to log-in using user authorization credentials contained in the UserSettings class. The login method returns a Client object which can be used to acquire service interfaces.

The logout method is used to drop the authorization when the Client is no longer being used.

// Login with the user credentials
Client client = connection.login(user);

// Work with client...

// Log out, removing auth token from client and expiring it on the server
client.logout();
                

Service interfaces are acquired by calling the getService method on the Client interface and providing the class for the desired service. A full listing of service interfaces can be found in the service client API Javadoc.

// Get service interface for points
PointService service = client.getService(PointService.class);
                

Each service interface contains methods that represent the available service requests. A listing of available methods for each service can be found in the Javadoc for the service client API.

// Retrieve list of all points
List pointList = service.getPoints();
                

The Service APIs have been written with as clear names and typing as possible, but there are some conventions that are used across the APIs that are difficult to describe in the java type system. Most of the function names in the APIs follow a similar pattern:

{result} {verb}{ServiceType}{s}[ByX]({arguments})

API functions will also include what type of resource they are modifying, sometimes referred to as ServiceType. Normally we use the name of the Protobuf type that will be returned to the application. In cases where the Protobuf class name does not exactly match the behavior of the function we will use a more descriptive name. For example when searching Alarms we are usually only concerned with "active" alarms, so the function name is getActiveAlarms(int limit).

Generally the return type of the function will be indicated by the plurality of ServiceType name. Functions that return a list of objects will have ServiceTypes ending with "s" such as getActiveAlarms or getCommands . Functions returning a single type will have the singular getAlarmById(id) or getCommandByUuid(uuid) .

When there are a number of ways to search for, or specify, an object, we differentiate between them by adding a qualifier to the function name. Example qualifiers are "ByName", "UsedByEntity" "OnCommand". Functions without any qualifier that take an argument generally are going to be keying off the id of the object.

Most requests are prefixed with a verb indicating the type of operation being performed. Common verbs and their semantics and conventions:

// service API naming pattern
// {result} {verb}{ServiceType}{s}[ByX]({arguments})

// a "get" operation with pluralized type returning a list
List getCommands();

// a "get" operation with a "ByName" qualifier to select by name
Command getCommandByName("CommandName");

// a "create" operation that will create a new lock or fail
CommandLock createCommandExecutionLock(command);

// a "delete" operation
CommandLock deleteCommandLock(access);

Receiving subscription events involves first creating a class to accept call-backs for the events. This is done using the SubscriptionEventAcceptor interface, which contains the method onEvent. The onEvent method is called with a SubscriptionEvent, which contains two properties: the event type (whether the resource was added, modified or removed) and the resource value itself.

public static class MeasurementSubscriber implements SubscriptionEventAcceptor {

    @Override
    public void onEvent(SubscriptionEvent measurementSubscriptionEvent) {

        // Type of the Event (ADDED, MODIFIED, REMOVED)
        Envelope.SubscriptionEventType eventType = measurementSubscriptionEvent.getEventType();

        // Measurement associated with the event
        Measurement measurement = measurementSubscriptionEvent.getValue();
    }
}
                

Making the subscription request itself is as simple as calling the right method on the service interface. Instead of returning service objects themselves, subscription methods return SubscriptionResult objects. The result objects contain both the immediate results for the request--the state of the system at the time the request was filled--and the means to begin asynchronously receiving subscription events.

List pointList = services.getPoints();

SubscriptionResult, Measurement> result = services.subscribeToMeasurementsByPoints(pointList);
                

The immediate results of the request can be obtained using the getResult method:

List currentMeasurements = result.getResult();
                

Receiving subscription events involves first instantiating the callback object (SubscriptionEventAcceptor). The getSubscription method on SubscriptionResult provides a Subscription object, which manages the lifecycle of the subscription. Passing the callback object into the start method will cause it to begin receiving events.

// Build a MeasurementSubscriber callback to accept subscription events
MeasurementSubscriber subscriber = new MeasurementSubscriber();

// Get the Subscription object from the SubscriptionResult
Subscription subscription = result.getSubscription();

// Start the subscription, providing the MeasurementSubscriber as a callback
subscription.start(subscriber);
                

Since the Subscription will only be notified of changes, it is important that the initial results returned by a subscription request should be processed before starting the subscription. All subscription events that are received are guaranteed to have occurred after the immediate results were returned. Events begin queueing on the broker immediately, the call to start() simply signals the client code's willingness to being accepting them.

Each Subscription object is tied to a queue on the message broker. The queue is a "limited" resource and clients should take care to manage subscriptions as they would a file handle or network connection. When a SubscriptionResult is returned from a service function call, the Subscription has been configured and is consuming resources on the broker regardless of whether start() is ever called on the Subscription. If we do not want to start the Subscription (if, for example, the initial state wasn't valid) we need to call cancel() on the subscription object before returning a failure. It is also very important to cancel() the Subscription when it is no longer needed. Subscription will automatically be cleaned up when the client disconnects. However in a long running application subscriptions that are not canceled will accumulate and slow down the message broker as it enqueues messages that will never be delivered.

// Cancel the Subscription, cleaning up the resource
subscription.cancel();
                

Manually managing the Subscriptions and making sure they get canceled can be difficult, especially when handling exceptions. Client applications can implement SubscriptionCreationListener which will be notified when each subscription is created which makes them easier to cancel on shutdown.