A client-side ruby gem for communicating with message brokers that support
the STOMP 1.0 and 1.1 protocols. This gem was formerly known as stomper,
but that name has been dropped because a
python stomp library by the same name
already existed. Also, I think "OnStomp" better expresses the event-driven
nature of this gem.
The OnStomp gem can be installed as a standard ruby gem:
gem install onstomp
Alternatively, you can clone the source through github.
# A simple message producer
client = OnStomp.connect('stomp://user:passw0rd@broker.example.org')
client.send('/queue/onstomp-test', 'hello world')
client.disconnect
# A simple message consumer
client = OnStomp::Client.new('stomp+ssl://broker.example.org:10101')
client.connect
client.subscribe('/queue/onstomp-test', :ack => 'client') do |m|
client.ack m
puts "Got and ACK'd a message: #{m.body}"
end
while true
# Keep the subscription running until the sun burns out
end
There is a STOMP client gem named stomp, so why create another gem? OnStomp was designed around giving users more control over how STOMP frames are handled through an event-driven interface. All IO reading and writing is performed through the use of non-blocking methods in the hopes of increasing performance.
The stomp gem is a good gem that works well, I just desired a different
style API for working with message brokers.
Both Ruby 1.8.7 and JRuby (as of 1.6.1) do not provide non-blocking read
or write methods for OpenSSL connections. While a gem named
openssl-nonblock exists for
Ruby < 1.9.2, I have not personally used it and given that it's a C extension,
it may not be compatible with JRuby's openssl gem. When an OnStomp connection
is created, the socket (SSL or TCP) is checked to see whether or not the methods
write_nonblock and read_nonblock have been defined. If not, OnStomp will
fall back on write for writing and readpartial for reading. While both of
these methods will block, the use of IO::select should help mitigate their
effects. I initially missed this detail, so if you're using an older version
of OnStomp (pre 1.0.4) with Ruby 1.8.7 or JRuby, you either want to upgrade
your gem or avoid stomp+ssl:// URIs like the plague.
The final "gotcha" is more of an advanced warning. When JRuby's support
for the Ruby 1.9 API stabilizes (and read_nonblock and write_nonblock are
available for OpenSSL connections), I will be dropping support for Ruby 1.8.x
entirely. This is probably a ways off yet, but when the time comes, I'll
post obvious warnings and increment the gem's major version. OnStomp 1.x
will always be compatible with Ruby 1.8.7+, OnStomp 2.x will be Ruby 1.9.x
only.
- The OnStomp YARD Documentation
- The OnStomp Github Wiki
- Some Contrived Examples
- A {file:extra_doc/UserNarrative.md User's Narrative}
- The {file:extra_doc/API.md OnStomp API Promise} (sort of)
- A {file:extra_doc/CHANGELOG.md History of Changes}
OnStomp is covered by the Apache License 2.0. See the full {file:docs/LICENSE.md LICENSE} for details.
There are a few people/groups I'd like to thank for helping me with the creation of this gem.
- Lionel Cons for the good suggestions while I was implementing support for the STOMP 1.1 spec. Check out his Perl client Net::STOMP::Client
- Brian McCallister, Johan Sørensen, Guy M. Allard and Thiago Morello for
their work on the
stompgem which introduced me to the STOMP protocol. - Hiram Chino and everyone on the stomp-spec mailing list for keeping the STOMP 1.1 spec moving
- Aman Gupta and contributors to eventmachine for the insights into working with non-blocking IO in Ruby