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.
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.
stomp
gem which introduced me to the STOMP protocol.