The first time a command causes an instance of the Client or HAClient to connect to AMPS (typically, the logon() command), the client creates a thread that runs in the background. This background thread is responsible for processing incoming messages from AMPS, which includes both messages that contain data and acknowledgments from the server.

When you call a command on the AMPS client, the command typically waits for an acknowledgment from the server and then returns. (The exception to this is publish. For performance, the publish command does not wait for an acknowledgment from the server before returning.)

In the simple case, using synchronous message processing, the client provides an internal handler function that populates the MessageStream. The client receive thread calls the internal handler function, which makes a deep copy of the incoming message and adds it to the MessageStream. The MessageStream is used on the calling thread, so operations on the MessageStream do not block the client receive thread.

When using asynchronous message processing, AMPS calls the handler function from the client receive thread. Message handlers provided for asynchronous message processing must be aware of the following considerations:

• The client creates one client receive thread at a time, and the lifetime of the thread lasts for the lifetime of the connection to the AMPS server. A message handler that is only provided to a single client will only be called from a single thread at a time. If your message handler will be used by multiple clients, then multiple threads will call your message handler. In this case, you should take care to protect any state that will be shared between threads. Notice that if the client connection fails (or is closed), and the client reconnects, the client will create a different thread for the new connection.

• For maximum performance, do as little work in the message handler as possible. For example, if you use the contents of the message to update an external database, a message handler that adds the relevant data to an update queue, that is processed by a different thread, will typically perform better than a message handler that does this update during the message handling.

• While your message handler is running, the thread that calls your message handler is no longer receiving messages. This makes it easier to write a message handler because you know that no other messages are arriving from the same subscription. However, this also means that you cannot use the same client that called the message handler to send commands to AMPS. Acknowledgments from AMPS cannot be processed and your application will deadlock waiting for the acknowledgment. Instead, enqueue the command in a work queue to be processed by a separate thread or use a different client object to submit the commands.

• The AMPS client resets and reuses the Message provided to this function between calls. This improves performance in the client, but means that if your handler function needs to preserve information contained within the message, you must copy the information (either by making a copy of the entire message or copying the required fields) rather than just saving the message object. Otherwise, the AMPS client cannot guarantee the state of the object or the contents of the object when your program goes to use it. Likewise, a message handler should not modify the Message -- this will result in modifying the message provided to other handlers (including handlers internal to the AMPS client).

The AMPS Java client also supports an interface designed for asynchronous message processing. In this case, you add a message handler to the call to subscribe. The client object returns the command ID of the subscribe command once the server has acknowledged that the command has been processed. As messages arrive, the client calls your message handler directly on the background thread. This can be an advantage for some applications. For example, if your application is highly multithreaded and copies message data to a work queue processed by multiple threads, there may be a performance benefit to enqueuing work directly from the background thread. See Understanding Threading for a discussion of threading considerations, including considerations for message handlers.

As with the simple interface, the AMPS client provides both convenience interfaces and interfaces that use a Command object. The following example shows how to use the asynchronous interface.

class MyApp {
    public static void main(String[] args) {

        /* We create a Client here, then call connect() and logon() to connect to
         * AMPS.
         */
        Client client = new Client("subscribe");

        try {
            client.connect("tcp://127.0.0.1:9007/amps/json");
            client.logon();

            /* Here, we create a new MessagePrinter object. The MessagePrinter
             * class implements MessageHandler, as described below. The subscription
             * uses this object to handle all messages returned from the subscription.
             */
            MessagePrinter mp = new MessagePrinter();
            Command command = new Command("subscribe").setTopic("messages");

            /* Here, we call the overload of Client.execute() that specifies the
             * command and the message handler to invoke with messages received
             * in response to the command.
             */
            CommandId subscriptionId = client.executeAsync(command, mp);
        }
        catch(AMPSException e){;}
        finally {
            client.close();
        }
    }
}

A sample message handler implementation is shown below:

/* An implementation of MessageHandler provides an invoke() method that receives
 * a com.crankuptheamps.client.Message object. Notice that the same instance of
 * this class is called for all messages on a given subscription, and that the
 * instance is called asynchronously from the background thread created by the
 * client. Design your message handlers so they have access to any program state
 * that they need to do their work.
 */
public class MessagePrinter implements MessageHandler {
    public void invoke(Message m) {
        System.out.println(m.getData());
    }
}