                                    SERStomp
                                    0.1 (r6)

Home page: http://www.germane-software.com/software/Stomp

SERStomp is a lightweight implementation of the Stomp specification[1].  As
of the first release it includes both client and server implementations for
Java.

BUILDING

Requires Jakarta Ant.  You build one of: all-jar, server-only-jar, or
client-only-jar depending on what you're using it for.

  * client-only-jar Produces a 8kb stomp-client.jar.  Useful for applications
    that only want to be able to connect via a network to a Stomp server.
  * server-only-jar Produces a 12.5kb stomp-server.jar.  Useful for
    applications that want to run a server, but don't need the client
    class.  Right now, this doesn't gain you much over the all-jar, but
    I'll refactor with factories and it'll get a bit smaller in future
    versions.
  * all-jar Produces a 13.5kb stomp.jar.  Contains both the client and server
    codes.

USEAGE

The entry points are the Client and Server classes.  For intra-VM 
communications, only the Server class is needed, and is used to return
a Stomp client.  The Client class is used to connect to servers over
the network.  The other class you may use is the Listener interface, which
is how clients get Stomp messages delivered.  You shouldn't need to directly
access any of the other classes in the package.

I've purposely kept the API minimal.  

To run a server, 

  Server s = new Server( 61626 );   // To start it.
  s.stop();                         // To stop it.  That's it.

To deliver messages on the server, get an internal client:

  Stomp local_client = s.getClient();
  // Deliver some messages:
  local_client.send( "/log/foo", "Message number one" );
  // Listen for commands from clients
  local_client.subscribe( "/command/info", new Listener() {
    public void message( Map header, String body ) {
      if (body.equals( "get-info" )) {
        // Send some message to the clients with info about the server
      }
      // ...
    }
    public void receipt( Map header ) {}
  } );

To connect to a network server from a client:

  Client c = new Client( "localhost", 61626, "ser", "ser" );
  c.subscribe( "foo-channel", my-listener );
  c.unsubscribe( "foo-channel" );
  c.disconnect();

There's not much more to it, which is the beauty of Stomp. Oh, there are
transactions, but they're not difficult.

See the API docs and unit tests for usage information and examples.


0.1 (Alpha) Notes:

  * This is the first release.  As such, it contains a number of failings,
    limitations, bugs, and missing features.
  * Only Java is provided.
  * CONNECTED is not implemented.  That is, the server sends it, but the
    client can't receive it.  Furthermore, there is no assurance that
    the client must receive a CONNECTED message before it can start sending
    messages to the server.
  * RECEIPT is not implemented, either in the client or server.
  * You'll notice a complete lack of unit tests for transactions.  That's
    because I haven't tested it, at all.  The code is there; whether or not
    it works is another matter.
  * Intra-VM and Inter-network communications should all work.
  * The Receiver uses a busy loop (sleeping 100ms).  This sucks, but it
    works.  Java NIO sucks even more and *still* requires a busy loop.
  * The source documentation is really poor. The code quality is probably poor, 
    too. The first version was written, documented, and debugged within about 
    eight hours[2].  sloccount says that this should have taken about 2.4 
    person-months and cost $19,400.  And you get it for free!  What a bargain!


[1] http://docs.codehaus.org/display/STOMP/Home
[2] And I wasted several of those hours dicking around with NIO
