Project

onstomp

0.03
No release in over 3 years
Low commit activity in last 3 years
There's a lot of open issues
Client library for message passing with brokers that support the Stomp protocol.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
 Dependencies

Development

< 11.0
~> 2.4.0
>= 0.3.0
>= 0.6.0
 Project Readme

OnStomp

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.

Installing

The OnStomp gem can be installed as a standard ruby gem:

gem install onstomp

Alternatively, you can clone the source through github.

Example Usage

# 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

Motivation

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.

Gotchas

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.

Further Reading

License

OnStomp is covered by the Apache License 2.0. See the full {file:docs/LICENSE.md LICENSE} for details.

Thanks

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 stomp gem 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