=README

Stomper is a library for connecting to and interacting with a message queue
service that supports the {Stomp protocol}[http://stomp.codehaus.org/Protocol].
Characteristics that distinguish it from other libraries, such the
{stomp gem}[http://github.com/js/stomp], are:

* Transaction blocks with {transaction blocks}[link:classes/Stomper/Client.html#M000066]
* Playing nice with Apache ActiveMQ by being able to {disable automatic content-length generation}[link:classes/Stomper/Frames/ClientFrame.html#M000014]
* A receiver thread that can be bypassed by something else! (whatever that means)

== Example Usage

    client = Stomper::Client.new("stomp://my_username:s3cr3tz@localhost:61613")
    # Clients must be explicitly started to automatically receive incoming
    # messages.
    client.start

    client.subscribe("/queue/hello") do |msg|
      puts msg.body
    end

    # Send a simple message
    client.send("/queue/hello", "hello world!")

    # Send a message within a transaction.  This usage is new to stomper
    # however, one can manually manage transactions as well.
    client.transaction do |t|
      t.send("/queue/hello", "a transactioned message")
    end

    # If the block provided to #transaction accepts a single parameter,
    # the client yields the Transaction object to the block, otherwise
    # the block is instance_eval'd within the Transaction object.
    client.transaction do
      send("/queue/hello", "a message you will never receive")
      # Nested transactions, failures percolate up to parent transactions.
      transaction do
        send("/queue/hello", "because I am about to fail!")
        raise "by forcing an error in a nested transaction"
      end
    end

    # Later ...
    client.stop
    client.close

== To-Do
* Provide the `pipe` method on Stomper::Client
* Allow SSL verification if requested (option :verify_ssl?)
* Re-evaluate how to handle a 'reliable' connection.

== License

Stomper is released under the Apache License 2.0

== Pointless Backstory

Stomper began its life as a mere fork of the {Stomp}[http://github.com/js/stomp]
gem.  However, as changes were made and desires grew, the fork began breaking
API compatibility with the original gem, and thus Stomper was conceived.

== Other Stuff

Primary Author:: Ian D. Eccles
Source Repository:: http://github.com/iande/stomper
Current Version:: 0.3.1
Last Updated:: 2010-03-04