Packages
Package	Description
asia.stampy.client.listener.connected	Provides the abstract listener to intercept incoming CONNECTED messages
asia.stampy.client.listener.disconnect	Provides the abstract listener to intercept incoming DISCONNECT messages
asia.stampy.client.listener.validate	Provides a listener to ensure only server messages are accepted on the client
asia.stampy.client.message	Provides the abstract client header classes
asia.stampy.client.message.abort	Provides the STOMP 1.2 ABORT header and message classes
asia.stampy.client.message.ack	Provides the STOMP 1.2 ACK header and message classes
asia.stampy.client.message.begin	Provides the STOMP 1.2 BEGIN header and message classes
asia.stampy.client.message.commit	Provides the STOMP 1.2 COMMIT header and message classes
asia.stampy.client.message.connect	Provides the STOMP 1.2 COMMIT header and message classes
asia.stampy.client.message.disconnect	Provides the STOMP 1.2 DISCONNECT header and message classes
asia.stampy.client.message.nack	Provides the STOMP 1.2 NACK header and message classes
asia.stampy.client.message.send	Provides the STOMP 1.2 SEND header and message classes
asia.stampy.client.message.stomp	Provides the STOMP 1.2 STOMP header and message classes
asia.stampy.client.message.subscribe	Provides the STOMP 1.2 SUBSCRIBE header and message classes
asia.stampy.client.message.unsubscribe	Provides the STOMP 1.2 UNSUBSCRIBE header and message classes
asia.stampy.client.mina	Provides the gateway and handler(s) to run a Stampy MINA client
asia.stampy.client.mina.connected	Provides the MINA implementation of a CONNECTED message listener
asia.stampy.client.mina.disconnect	Provides the MINA implementation of a DISCONNECT message listener
asia.stampy.client.netty	Provides the gateway and handler to run a Stampy NETTY client
asia.stampy.client.netty.connected	Provides the NETTY implementation of a CONNECTED message listener
asia.stampy.client.netty.disconnect	Provides the NETTY implementation of a DISCONNECT message listener
asia.stampy.common	Provides common classes
asia.stampy.common.gateway	Provides interfaces and super classes for the implementation of STOMP 1.2 clients and servers
asia.stampy.common.heartbeat	Provides heartbeat management classes
asia.stampy.common.message	Provides the STOMP 1.2 common interfaces and super classes for messages
asia.stampy.common.message.interceptor	Provides interceptor classes to capture outgoing message state, trigger events etc.
asia.stampy.common.mina	Provides abstract MINA implementations for clients and servers
asia.stampy.common.mina.raw	Provides a raw string MINA handler implementation (spec compliant)
asia.stampy.common.netty	Provides abstract NETTY implementations for clients and servers
asia.stampy.common.parsing	Provides message parsing tools
asia.stampy.common.serialization	Provides serialization tools
asia.stampy.examples.client.mina	Provides a MINA client gateway which terminates the Java process on disconnection
asia.stampy.examples.client.netty	Provides a NETTY client gateway which terminates the Java process on disconnection
asia.stampy.examples.common	Provides a blank implementation of a SecurityMessageListener
asia.stampy.examples.loadtest.client	Provides the load test client
asia.stampy.examples.loadtest.client.mina	Provides the MINA client gateway initializer for the load test client
asia.stampy.examples.loadtest.client.netty	Provides the NETTY client gateway initializer for the load test client
asia.stampy.examples.loadtest.server	Provides the load test server
asia.stampy.examples.loadtest.server.mina	Provides the MINA initializer for the load test server
asia.stampy.examples.loadtest.server.netty	Provides the NETTY initializer for the load test server
asia.stampy.examples.remote.exe.common	Provides client/server classes which can execute a binary object sent from a client or server
asia.stampy.examples.remote.exe.log4j.client	Provides the log4j level changer client
asia.stampy.examples.remote.exe.log4j.client.mina	Provides the MINA client gateway initializer for the log4j level changer client
asia.stampy.examples.remote.exe.log4j.client.netty	Provides the NETTY client gateway initializer for the log4j level changer client
asia.stampy.examples.remote.exe.log4j.common	Provides the log4j level changer implementation
asia.stampy.examples.remote.exe.log4j.server	Provides the log4j level changer server
asia.stampy.examples.remote.exe.log4j.server.mina	Provides the MINA server gateway initializer for the log4j level changer server
asia.stampy.examples.remote.exe.log4j.server.netty	Provides the NETTY server gateway initializer for the log4j level changer server
asia.stampy.examples.system.client	Provides the system client
asia.stampy.examples.system.client.mina	Provides the MINA client gateway initializer for the system test client
asia.stampy.examples.system.client.netty	Provides the NETTY client gateway initializer for the system client
asia.stampy.examples.system.server	Provides the system server
asia.stampy.examples.system.server.mina	Provides the MINA server gateway initializer for the system test server
asia.stampy.examples.system.server.netty	Provides the NETTY server gateway initializer for the system server
asia.stampy.server.listener.connect	Provides the abstract listener to intercept incoming CONNECT messages
asia.stampy.server.listener.heartbeat	Provides the abstract listener to intercept incoming CONNECT messages requesting heartbeats
asia.stampy.server.listener.login	Provides the abstract listener to intercept incoming CONNECT messages with login credentials
asia.stampy.server.listener.receipt	Provides the abstract listener to generate RECEIPT messages for incoming messages requesting such
asia.stampy.server.listener.subscription	Provides the abstract listener to expect an ACK from a sent MESSAGE
asia.stampy.server.listener.transaction	Provides the abstract listener to manage transactional boundaries
asia.stampy.server.listener.validate	Provides a listener to ensure only client messages are accepted on the server
asia.stampy.server.listener.version	Provides the listener to check version information
asia.stampy.server.message.connected	Provides the STOMP 1.2 CONNECTED header and message classes
asia.stampy.server.message.error	Provides the STOMP 1.2 ERROR header and message classes
asia.stampy.server.message.message	Provides the STOMP 1.2 MESSAGE header and message classes
asia.stampy.server.message.receipt	Provides the STOMP 1.2 RECEIPT header and message classes
asia.stampy.server.mina	Provides the gateway and handler(s) to run a Stampy MINA server
asia.stampy.server.mina.connect	Provides the MINA implementation of a CONNECT message listener
asia.stampy.server.mina.heartbeat	Provides the MINA implementation of a CONNECT message requesting heartbeats
asia.stampy.server.mina.login	Provides the MINA implementation of a CONNECT message with login credentials
asia.stampy.server.mina.receipt	Provides the MINA implementation to generate RECEIPT messages for those incoming requesting such
asia.stampy.server.mina.subscription	Provides the MINA implementation to expect an ACK for a sent MESSAGE
asia.stampy.server.mina.transaction	Provides the MINA implementation to manage transactional boundaries
asia.stampy.server.netty	Provides the gateway and handler to run a Stampy NETTY server
asia.stampy.server.netty.connect	Provides the NETTY implementation of a CONNECT message listener
asia.stampy.server.netty.heartbeat	Provides the NETTY implementation of a CONNECT message requesting heartbeats
asia.stampy.server.netty.login	Provides the NETTY implementation of a CONNECT message with login credentials
asia.stampy.server.netty.receipt	Provides the NETTY implementation to generate RECEIPT messages for those incoming requesting such
asia.stampy.server.netty.subscription	Provides the NETTY implementation to expect an ACK for a sent MESSAGE
asia.stampy.server.netty.transaction	Provides the NETTY implementation to manage transactional boundaries

Stampy, a Java implementation of the STOMP 1.2 specification

Release 1.0-RELEASE, 18-02-2013

stampy-examples-1.0-RELEASE

The Stampy example code demonstrates how to configure Stampy clients and servers to perform customized tasks.

Dependencies

<dependency org="asia.stampy" name="stampy-core" rev="1.0-RELEASE"/>

<dependency org="commons-codec" name="commons-codec" rev="1.7"/>

Load Test

The load test attempts to send a configurable one million ACK messages from the client to the server and requests one million receipts from the server.

Log4j Level Changer

This example shows how to send a serializable Java object for execution on a server.

System

This example shows how to configure a STOMP 1.2 compliant client and server and tests for compliancy.

stampy-NETTY-client-server-RI-1.0-RELEASE

This library provides a Netty implementation of the stampy-client-server-1.0-RELEASE STOMP 1.2 architecture.

Design considerations

Compiled for Java 5 compatibility
Ease of configuration and use
DI framework-friendly
Minimal dependencies
Massively multithreaded, many clients can communicate with a server simultaneously
Fast (6 microseconds per message during testing)
Reliable
Extensible
Security focused

Dependencies

<dependency org="asia.stampy" name="stampy-core" rev="1.0-RELEASE"/>

<dependency org="commons-codec" name="commons-codec" rev="1.7"/>

Client Configuration (from examples)

While easy to programmatically configure a Netty client gateway, it is expected that a DI framework such as Spring or Guice will be used to perform this task.

The following code demonstrates all that is necessary to configure a STOMP 1.2 compliant client:

  public static AbstractStampyMessageGateway initialize() {
    HeartbeatContainer heartbeatContainer = new HeartbeatContainer();

    ClientNettyMessageGateway gateway = new ClientNettyMessageGateway();
    gateway.setPort(1234);
    gateway.setHost("localhost");
    gateway.setHeartbeat(1000);

    ClientNettyChannelHandler channelHandler = new ClientNettyChannelHandler();
    channelHandler.setGateway(gateway);
    channelHandler.setHeartbeatContainer(heartbeatContainer);

    gateway.addMessageListener(new IDontNeedSecurity()); // DON'T DO THIS!!!
    
    gateway.addMessageListener(new ClientMessageValidationListener());

    NettyConnectedMessageListener cml = new NettyConnectedMessageListener();
    cml.setHeartbeatContainer(heartbeatContainer);
    cml.setGateway(gateway);
    gateway.addMessageListener(cml);

    NettyDisconnectListenerAndInterceptor disconnect = new NettyDisconnectListenerAndInterceptor();
    disconnect.setCloseOnDisconnectMessage(false);
    gateway.addMessageListener(disconnect);
    gateway.addOutgoingMessageInterceptor(disconnect);
    disconnect.setGateway(gateway);

    gateway.setHandler(channelHandler);

    return gateway;
  }

Server Configuration (from examples)

While easy to programmatically configure a Netty server gateway, it is expected that a DI framework such as Spring or Guice will be used to perform this task.

The following code demonstrates all that is necessary to configure a STOMP 1.2 compliant server:

  public static AbstractStampyMessageGateway initialize() {
    HeartbeatContainer heartbeatContainer = new HeartbeatContainer();

    ServerNettyMessageGateway gateway = new ServerNettyMessageGateway();
    gateway.setPort(1234);
    gateway.setHeartbeat(1000);
    gateway.setAutoShutdown(true);

    ServerNettyChannelHandler channelHandler = new ServerNettyChannelHandler();
    channelHandler.setGateway(gateway);
    channelHandler.setHeartbeatContainer(heartbeatContainer);

    gateway.addMessageListener(new IDontNeedSecurity()); // DON'T DO THIS!!!
    
    gateway.addMessageListener(new ServerMessageValidationListener());

    gateway.addMessageListener(new VersionListener());

    NettyLoginMessageListener login = new NettyLoginMessageListener();
    login.setGateway(gateway);
    login.setLoginHandler(new SystemLoginHandler());
    gateway.addMessageListener(login);

    NettyConnectStateListener connect = new NettyConnectStateListener();
    connect.setGateway(gateway);
    gateway.addMessageListener(connect);

    NettyHeartbeatListener heartbeat = new NettyHeartbeatListener();
    heartbeat.setHeartbeatContainer(heartbeatContainer);
    heartbeat.setGateway(gateway);
    gateway.addMessageListener(heartbeat);

    NettyTransactionListener transaction = new NettyTransactionListener();
    transaction.setGateway(gateway);
    gateway.addMessageListener(transaction);

    SystemAcknowledgementHandler sys = new SystemAcknowledgementHandler();

    NettyAcknowledgementListenerAndInterceptor acknowledgement = new NettyAcknowledgementListenerAndInterceptor();
    acknowledgement.setHandler(sys);
    acknowledgement.setGateway(gateway);
    acknowledgement.setAckTimeoutMillis(200);
    gateway.addMessageListener(acknowledgement);
    gateway.addOutgoingMessageInterceptor(acknowledgement);

    NettyReceiptListener receipt = new NettyReceiptListener();
    receipt.setGateway(gateway);
    gateway.addMessageListener(receipt);

    NettyConnectResponseListener connectResponse = new NettyConnectResponseListener();
    connectResponse.setGateway(gateway);
    gateway.addMessageListener(connectResponse);

    gateway.setHandler(channelHandler);

    return gateway;
  }

stampy-MINA-client-server-RI-1.0-RELEASE

This library provides a Mina implementation of the stampy-client-server-1.0-RELEASE STOMP 1.2 architecture.

Design considerations

Compiled for Java 5 compatibility
Ease of configuration and use
DI framework-friendly
Minimal dependencies
Massively multithreaded, many clients can communicate with a server simultaneously
Fast (11 microseconds per message during testing)
Reliable
Extensible
Security focused

Dependencies

<dependency org="asia.stampy" name="stampy-core" rev="1.0-RELEASE"/>

<dependency org="commons-codec" name="commons-codec" rev="1.7"/>

Client Configuration (from examples)

While easy to programmatically configure a Mina client gateway, it is expected that a DI framework such as Spring or Guice will be used to perform this task.

The following code demonstrates all that is necessary to configure a STOMP 1.2 compliant client:

  public static AbstractStampyMessageGateway initialize() {
    HeartbeatContainer heartbeatContainer = new HeartbeatContainer();

    ClientMinaMessageGateway gateway = new ClientMinaMessageGateway();
    gateway.setPort(1234);
    gateway.setHost("localhost");
    gateway.setHeartbeat(1000);

    RawClientMinaHandler handler = new RawClientMinaHandler();
    handler.setGateway(gateway);
    handler.setHeartbeatContainer(heartbeatContainer);

    gateway.addMessageListener(new IDontNeedSecurity()); // DON'T DO THIS!!!
    
    gateway.addMessageListener(new ClientMessageValidationListener());

    MinaConnectedMessageListener cml = new MinaConnectedMessageListener();
    cml.setHeartbeatContainer(heartbeatContainer);
    cml.setGateway(gateway);
    gateway.addMessageListener(cml);

    MinaDisconnectListenerAndInterceptor disconnect = new MinaDisconnectListenerAndInterceptor();
    disconnect.setCloseOnDisconnectMessage(false);
    gateway.addMessageListener(disconnect);
    gateway.addOutgoingMessageInterceptor(disconnect);
    disconnect.setGateway(gateway);

    gateway.setHandler(handler);

    return gateway;
  }

Server Configuration (from examples)

While easy to programmatically configure a Mina server gateway, it is expected that a DI framework such as Spring or Guice will be used to perform this task.

The following code demonstrates all that is necessary to configure a STOMP 1.2 compliant server:

  public static AbstractStampyMessageGateway initialize() {
    HeartbeatContainer heartbeatContainer = new HeartbeatContainer();

    ServerMinaMessageGateway gateway = new ServerMinaMessageGateway();
    gateway.setPort(1234);
    gateway.setHeartbeat(1000);
    gateway.setAutoShutdown(true);

    RawServerMinaHandler handler = new RawServerMinaHandler();
    handler.setGateway(gateway);
    handler.setHeartbeatContainer(heartbeatContainer);

    gateway.addMessageListener(new IDontNeedSecurity()); // DON'T DO THIS!!!
    
    gateway.addMessageListener(new ServerMessageValidationListener());

    gateway.addMessageListener(new VersionListener());

    MinaLoginMessageListener login = new MinaLoginMessageListener();
    login.setGateway(gateway);
    login.setLoginHandler(new SystemLoginHandler());
    gateway.addMessageListener(login);

    MinaConnectStateListener connect = new MinaConnectStateListener();
    connect.setGateway(gateway);
    gateway.addMessageListener(connect);

    MinaHeartbeatListener heartbeat = new MinaHeartbeatListener();
    heartbeat.setHeartbeatContainer(heartbeatContainer);
    heartbeat.setGateway(gateway);
    gateway.addMessageListener(heartbeat);

    MinaTransactionListener transaction = new MinaTransactionListener();
    transaction.setGateway(gateway);
    gateway.addMessageListener(transaction);

    SystemAcknowledgementHandler sys = new SystemAcknowledgementHandler();

    MinaAcknowledgementListenerAndInterceptor acknowledgement = new MinaAcknowledgementListenerAndInterceptor();
    acknowledgement.setHandler(sys);
    acknowledgement.setGateway(gateway);
    acknowledgement.setAckTimeoutMillis(200);
    gateway.addMessageListener(acknowledgement);
    gateway.addOutgoingMessageInterceptor(acknowledgement);

    MinaReceiptListener receipt = new MinaReceiptListener();
    receipt.setGateway(gateway);
    gateway.addMessageListener(receipt);

    MinaConnectResponseListener connectResponse = new MinaConnectResponseListener();
    connectResponse.setGateway(gateway);
    gateway.addMessageListener(connectResponse);

    gateway.setHandler(handler);

    return gateway;
  }

stampy-client-server-1.0-RELEASE

This library provides the structure to implement STOMP 1.2 clients and servers using the stampy-core library.

Design considerations

Compiled for Java 5 compatibility
Ease of configuration and use
DI framework-friendly
Minimal dependencies
Reliable
Extensible
Security focused

Dependencies

<dependency org="asia.stampy" name="stampy-core" rev="1.0-RELEASE"/>

<dependency org="commons-codec" name="commons-codec" rev="1.7"/>

Gateways

A Stampy gateway is the interface between an application and the technology used to create/accept connections from STOMP 1.2 compliant clients and servers. All gateways extend from AbstractStampyMessageGateway. This class contains common methods for all Stampy gateways and defines abstract methods which must be implemented in an implementation.

StampyMessageListener

All gateways allow the addition of any number of StampyMessageListeners which are invoked when a STOMP 1.2 message has been received. By themselves the gateway implementations are not STOMP 1.2 compliant. Compliancy is obtained by adding implementations of this listener. The stampy-client-server library contains implementations which enforce compliance. Any additional custom functionality is obtained by creating a new implementation & adding it to the gateway ie: intercepting a specific message type and notifying the application to perform some bit of functionality. Note: the order of addition of these listeners is important.

SecurityMessageListener

At least one implementation of this interface must be included in the list of message listeners, and one must be first in the list else a security exception is thrown. This is to ensure that any custom implementations implement any necessary security for their platform.

Additional security pre-Stampy can be added to the gateway implementations.

Interceptors

All gateways allow the addition of interceptors which are invoked for outgoing messages. There are two types; a message interceptor and a text interceptor. Message interceptors can be tailored to intercept specific types & messages while text interceptors inspect all strings prior to sending them down the pipe. They can be used for outgoing security but are more useful for capturing the state of messages prior to the send. This state can be used to then evaluate any subsequent messages received.

The AbstractDisconnectListenerAndInterceptor and AbstractAcknowledgementListenerAndInterceptor are two classes which make effective use of this functionality.

Heartbeats

A heartbeat container instance is used by the gateway to automatically send heartbeats at the agreed upon rate. Heartbeats are started by the client and server using the AbstractConnectedMessageListener and AbstractHeartbeatListener StampyMessageListeners.

stampy-core-1.0-RELEASE

This library provides class representations of STOMP 1.2 messages and the ability to convert to and from the classes. It can be used with the additional Stampy libraries or it can be used with existing STOMP client or server implementations.

Design considerations

Compiled for Java 5 compatibility
Ease of configuration and use
DI framework-friendly
Minimal dependencies
Reliable
Extensible

Dependencies

<dependency org="org.slf4j" name="slf4j-api" rev="1.7.2"/>

<dependency org="commons-lang" name="commons-lang" rev="2.6"/>

<dependency org="commons-codec" name="commons-codec" rev="1.7"/>

Messages

All STOMP message classes implement the StampyMessage interface. Message classes typically have at least two constructors, one blank & the other with parameters - the parameterized constructors are all the mandatory header values that must be set for a valid STOMP message. Should any mandatory header information be missing an exception will be thrown when the message's

validate()

method is called.

Each StampyMessage class has an associated header class which can be obtained by calling the

getHeader()

method. The header classes are wrappers around a map which manages the key value pairs. Known key names have their own getter and setter methods; any key value pair can be added to a Stampy message header.

Note: should a header key already exist in the map any subsequent adds for that key will be ignored. This is to enforce the specification: If a client or a server receives repeated frame header entries, only the first header entry SHOULD be used as the value of header entry. Subsequent values are only used to maintain a history of state changes of the header and MAY be ignored. To replace an existing key the header's

removeHeader(existingKey)

method must be called first.

Parsing

A message parser is included for converting the raw string messages to their associated StampyMessage objects.

Message Bodies

Any STOMP message that has a body can accept a string as the body as well as any Java serializable object. The mime type used by Stampy to represent such serialized objects is

java/base64

Encoding to and from Base64 is handled by the message superclasses & the parser, respectively.