onstomp 1.0.0pre1

data/.autotest

@@ -0,0 +1,2 @@
+require 'autotest/bundler'
+

data/.gitignore

@@ -0,0 +1,6 @@
+.DS_Store
+pkg/*
+*.gem
+.bundle
+.yardoc
+nbproject

data/.rspec

@@ -0,0 +1,2 @@
+--colour
+--format d

data/.yardopts

@@ -0,0 +1,5 @@
+--no-private
+--title "OnStomp Documentation"
+--readme README.md
+--files LICENSE.md,CHANGELOG.md,DeveloperNarrative.md,UserNarrative.md
+lib/**/*.rb

data/CHANGELOG.md

@@ -0,0 +1,4 @@
+# Changes
+
+## 1.0pre - 2011-03-30
+* initial pre-release

data/DeveloperNarrative.md

@@ -0,0 +1,15 @@
+# A Narrative for Developers
+
+This document explores the `OnStomp` library through a narrative aimed at end
+developers who wish to extend or modify the library.  It will start with the
+basics and work through the important code through exposition and examples.
+
+## Clients
+
+## Event Management
+
+## URI Based Configuration
+
+## Connections
+
+## Processors

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in onstomp.gemspec
+gemspec

data/LICENSE.md

@@ -0,0 +1,221 @@
+# Apache License
+
+Version 2.0, January 2004
+
+[http://www.apache.org/licenses/](http://www.apache.org/licenses/)
+
+## TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+### 1. Definitions
+
+"License" shall mean the terms and conditions for use, reproduction,
+and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity. For the purposes of this definition,
+"control" means (i) the power, direct or indirect, to cause the
+direction or management of such entity, whether by contract or
+otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity
+exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation
+source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical
+transformation or translation of a Source form, including but
+not limited to compiled object code, generated documentation,
+and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or
+Object form, made available under the License, as indicated by a
+copyright notice that is included in or attached to the work
+(an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object
+form, that is based on (or derived from) the Work and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship. For the purposes
+of this License, Derivative Works shall not include works that remain
+separable from, or merely link (or bind by name) to the interfaces of,
+the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including
+the original version of the Work and any modifications or additions
+to that Work or Derivative Works thereof, that is intentionally
+submitted to Licensor for inclusion in the Work by the copyright owner
+or by an individual or Legal Entity authorized to submit on behalf of
+the copyright owner. For the purposes of this definition, "submitted"
+means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems,
+and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity
+on behalf of whom a Contribution has been received by Licensor and
+subsequently incorporated within the Work.
+
+### 2. Grant of Copyright License
+
+Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the
+Work and such Derivative Works in Source or Object form.
+
+### 3. Grant of Patent License
+Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+(except as stated in this section) patent license to make, have made,
+use, offer to sell, sell, import, and otherwise transfer the Work,
+where such license applies only to those patent claims licensable
+by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s)
+with the Work to which such Contribution(s) was submitted. If You
+institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work
+or a Contribution incorporated within the Work constitutes direct
+or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate
+as of the date such litigation is filed.
+
+### 4. Redistribution
+
+You may reproduce and distribute copies of the
+Work or Derivative Works thereof in any medium, with or without
+modifications, and in Source or Object form, provided that You
+meet the following conditions:
+
+<ol style="list-style-type: lower-alpha;">
+  <li>
+    You must give any other recipients of the Work or
+    Derivative Works a copy of this License; and
+  </li>
+  <li>
+    You must cause any modified files to carry prominent notices
+    stating that You changed the files; and
+  </li>
+  <li>
+    You must retain, in the Source form of any Derivative Works
+    that You distribute, all copyright, patent, trademark, and
+    attribution notices from the Source form of the Work,
+    excluding those notices that do not pertain to any part of
+    the Derivative Works; and
+  </li>
+  <li>
+    If the Work includes a "NOTICE" text file as part of its
+    distribution, then any Derivative Works that You distribute must
+    include a readable copy of the attribution notices contained
+    within such NOTICE file, excluding those notices that do not
+    pertain to any part of the Derivative Works, in at least one
+    of the following places: within a NOTICE text file distributed
+    as part of the Derivative Works; within the Source form or
+    documentation, if provided along with the Derivative Works; or,
+    within a display generated by the Derivative Works, if and
+    wherever such third-party notices normally appear. The contents
+    of the NOTICE file are for informational purposes only and
+    do not modify the License. You may add Your own attribution
+    notices within Derivative Works that You distribute, alongside
+    or as an addendum to the NOTICE text from the Work, provided
+    that such additional attribution notices cannot be construed
+    as modifying the License.
+  </li>
+</ol>
+
+You may add Your own copyright statement to Your modifications and
+may provide additional or different license terms and conditions
+for use, reproduction, or distribution of Your modifications, or
+for any such Derivative Works as a whole, provided Your use,
+reproduction, and distribution of the Work otherwise complies with
+the conditions stated in this License.
+
+### 5. Submission of Contributions
+Unless You explicitly state otherwise,
+any Contribution intentionally submitted for inclusion in the Work
+by You to the Licensor shall be under the terms and conditions of
+this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify
+the terms of any separate license agreement you may have executed
+with Licensor regarding such Contributions.
+
+### 6. Trademarks
+This License does not grant permission to use the trade
+names, trademarks, service marks, or product names of the Licensor,
+except as required for reasonable and customary use in describing the
+origin of the Work and reproducing the content of the NOTICE file.
+
+### 7. Disclaimer of Warranty
+Unless required by applicable law or
+agreed to in writing, Licensor provides the Work (and each
+Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied, including, without limitation, any warranties or conditions
+of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any
+risks associated with Your exercise of permissions under this License.
+
+### 8. Limitation of Liability
+In no event and under no legal theory,
+whether in tort (including negligence), contract, or otherwise,
+unless required by applicable law (such as deliberate and grossly
+negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special,
+incidental, or consequential damages of any character arising as a
+result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill,
+work stoppage, computer failure or malfunction, or any and all
+other commercial damages or losses), even if such Contributor
+has been advised of the possibility of such damages.
+
+### 9. Accepting Warranty or Additional Liability
+While redistributing
+the Work or Derivative Works thereof, You may choose to offer,
+and charge a fee for, acceptance of support, warranty, indemnity,
+or other liability obligations and/or rights consistent with this
+License. However, in accepting such obligations, You may act only
+on Your own behalf and on Your sole responsibility, not on behalf
+of any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason
+of your accepting any such warranty or additional liability.
+
+## END OF TERMS AND CONDITIONS
+
+## APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following
+boilerplate notice, with the fields enclosed by brackets "[]"
+replaced with your own identifying information. (Don't include
+the brackets!)  The text should be enclosed in the appropriate
+comment syntax for the file format. We also recommend that a
+file or class name and description of purpose be included on the
+same "printed page" as the copyright notice for easier
+identification within third-party archives.
+
+    Copyright [yyyy] [name of copyright owner]
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+

data/README.md

@@ -0,0 +1,73 @@
+# 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](http://code.google.com/p/stomper/) 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](https://github.com/meadvillerb/onstomp) 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](http://gitorious.org/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.
+
+## Further Reading
+
+* A {file:docs/UserNarrative.md User's Narrative}
+* A {file:docs/DeveloperNarrative.md Developers's Narrative}
+* A {file:docs/CHANGELOG.md History of Changes}
+
+## 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 the good suggestions while I was implementing support for the
+  STOMP 1.1 spec. Check out his Perl client [Net::STOMP::Client](http://search.cpan.org/~lcons/Net-STOMP-Client-0.9.5/lib/Net/STOMP/Client.pm)
+* 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](https://github.com/eventmachine/eventmachine) for the insights
+  into working with non-blocking IO in Ruby

data/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'yard'
+require File.expand_path("../yard_extensions", __FILE__)
+YARD::Rake::YardocTask.new

data/UserNarrative.md

@@ -0,0 +1,8 @@
+# A Narrative for Users
+
+This document explores the `OnStomp` API through a narrative aimed at end
+users of the library.  It will start with the basics and work through the
+available features through exposition and examples.
+
+## Creating a STOMP Client
+

data/examples/basic.rb

@@ -0,0 +1,40 @@
+# -*- encoding: utf-8 -*-
+$:.unshift(File.expand_path('../../lib', __FILE__))
+require 'onstomp'
+
+puts "Starting demo"
+puts "----------------------------"
+
+running = true
+client = OnStomp::Client.new("stomp://localhost")
+client.connect
+
+puts "Connected to broker using protocol #{client.connection.version}"
+
+client.subscribe("/queue/onstomp/test") do |message|
+  puts "Received: '#{message.body}'"
+  if message.body == 'finished'
+    running = false
+  end
+end
+
+client.send("/queue/onstomp/test", "hello world")
+client.send("/queue/onstomp/test", "this is a simple demo of onstomp")
+client.send("/queue/onstomp/test", "finished")
+
+Thread.pass while running
+client.disconnect
+puts "----------------------------"
+puts "End of demo"
+
+# Example output:
+#
+#
+# Starting demo
+# ----------------------------
+# Connected to broker using protocol 1.0
+# Received: hello world
+# Received: this is a simple demo of onstomp
+# Received: finished
+# ----------------------------
+# End of demo

data/examples/events.rb

@@ -0,0 +1,72 @@
+# -*- encoding: utf-8 -*-
+$:.unshift(File.expand_path('../../lib', __FILE__))
+require 'onstomp'
+
+puts "Starting demo"
+puts "----------------------------"
+
+client = OnStomp::Client.new("stomp://localhost")
+
+client.before_transmitting do |frame, _|
+  puts "Frame headers [#{frame.command}] before modification: #{frame.headers.to_a.inspect}"
+  frame[:'x-alt-header'] = 'another value'
+end
+
+client.before_send do |frame, _|
+  puts "SEND headers before modification: #{frame.headers.to_a.inspect}"
+  frame[:'x-misc-header'] = 'this is a test'
+end
+
+client.after_transmitting do |frame, _|
+  puts "Final frame headers [#{frame.command}]: #{frame.headers.to_a.inspect}"
+end
+
+client.before_disconnect do |frame, _|
+  puts "Disconnecting from broker"
+end
+
+client.on_connection_established do |client, con|
+  puts "=== Connected to broker using protocol #{con.version} ==="
+end
+
+client.on_connection_closed do |client, con|
+  puts "=== Connection has been closed ==="
+end
+
+client.on_connection_terminated do |client, con|
+  puts "=== Connection closed unexpectedly ==="
+end
+
+receipt_count = 0
+client.connect
+client.send("/queue/onstomp/test", "hello world") do |r|
+  puts "---- Got receipt #{r[:'receipt-id']} ----"
+  raise ArgumentError, 'blam!'
+  receipt_count += 1
+end
+
+while receipt_count < 1 && client.connected?
+end
+
+client.disconnect rescue nil
+
+puts "----------------------------"
+puts "End of demo"
+
+# Example output:
+#
+#
+# Starting demo
+# ----------------------------
+# Final frame headers [CONNECT]: [["accept-version", "1.0,1.1"], ["host", "localhost"], ["heart-beat", "0,0"], ["login", ""], ["passcode", ""]]
+# === Connected to broker using protocol 1.0 ===
+# Frame headers [SEND] before modification: [["destination", "/queue/onstomp/test"], ["receipt", "1"]]
+# SEND headers before modification: [["destination", "/queue/onstomp/test"], ["receipt", "1"], ["x-alt-header", "another value"]]
+# Final frame headers [SEND]: [["destination", "/queue/onstomp/test"], ["receipt", "1"], ["x-alt-header", "another value"], ["x-misc-header", "this is a test"], ["content-length", "11"]]
+# ---- Got receipt 1 ----
+# === Connection closed unexpectedly ===
+# Frame headers [DISCONNECT] before modification: []
+# Disconnecting from broker
+# === Connection has been closed ===
+# ----------------------------
+# End of demo

data/lib/onstomp/client.rb

@@ -0,0 +1,152 @@
+# -*- encoding: utf-8 -*-
+
+# This class encapsulates a client connection to a message broker through the
+# Stomp protocol.
+class OnStomp::Client
+  include OnStomp::Interfaces::ClientConfigurable
+  include OnStomp::Interfaces::FrameMethods
+  include OnStomp::Interfaces::ClientEvents
+  include OnStomp::Interfaces::ReceiptManager
+  include OnStomp::Interfaces::SubscriptionManager
+  include OnStomp::Components::Scopes
+  
+  # The +URI+ reference to the STOMP broker
+  # @return [String]
+  attr_reader :uri
+  # SSL options for the connection
+  # @return {Symbol => Object}
+  attr_reader :ssl
+  # Connection object specific to the established STOMP protocol version
+  # @return [OnStomp::Connections::Base]
+  attr_reader :connection
+  
+  # The protocol versions to allow for this connection
+  # @return [Array<String>]
+  attr_configurable_protocols :versions
+  
+  # The client-side heartbeat settings to allow for this connection
+  # @return [Array<Fixnum>]
+  attr_configurable_client_beats :heartbeats
+  
+  # The host header value to send to the broker when connecting. This allows
+  # the client to inform the server which host it wishes to connect with
+  # when multiple brokers may share an IP address through virtual hosting.
+  # @return [String]
+  attr_configurable_str :host, :default => 'localhost', :uri_attr => :host
+  
+  # The login header value to send to the broker when connecting.
+  # @return [String]
+  attr_configurable_str :login, :default => '', :uri_attr => :user
+  
+  # The passcode header value to send to the broker when connecting.
+  # @return [String]
+  attr_configurable_str :passcode, :default => '', :uri_attr => :password
+  
+  # The class to use when instantiating a new IO processor for the connection.
+  # Defaults to {OnStomp::Components::ThreadedProcessor}
+  # @return [Class]
+  attr_configurable_processor :processor
+  
+  # Creates a new client for the specified uri and optional hash of options.
+  # @param [String,URI] uri
+  # @param [{Symbol => Object}] options
+  def initialize(uri, options={})
+    @uri = uri.is_a?(::URI) ? uri : ::URI.parse(uri)
+    @ssl = options.delete(:ssl)
+    configure_configurable options
+    configure_subscription_management
+    configure_receipt_management
+    on_disconnect do |f, con|
+      close unless f[:receipt]
+    end
+  end
+  
+  # Connects to the STOMP broker referenced by {#uri}. Includes optional
+  # headers in the CONNECT frame, if specified.
+  # @param [{#to_sym => #to_s}] headers
+  # @return [self]
+  def connect(headers={})
+    @connection = OnStomp::Connections.connect self, headers,
+      { :'accept-version' => @versions.join(','), :host => @host,
+        :'heart-beat' => @heartbeats.join(','), :login => @login,
+        :passcode => @passcode }, pending_connection_events
+    processor_inst.start
+    self
+  end
+  alias :open :connect
+  
+  # Sends a DISCONNECT frame to the broker and blocks until the connection
+  # has been closed. This method ensures that all frames not yet sent to
+  # the broker will get processed barring any IO exceptions.
+  # @param [{#to_sym => #to_s}] headers
+  # @return [OnStomp::Components::Frame] transmitted DISCONNECT frame
+  def disconnect_with_flush(headers={})
+    disconnect_without_flush(headers).tap do
+      processor_inst.join
+    end
+  end
+  alias :disconnect_without_flush :disconnect
+  alias :disconnect :disconnect_with_flush
+  
+  # Returns true if a connection to the broker exists and itself is connected.
+  # @return [true,false]
+  def connected?
+    connection && connection.connected?
+  end
+  
+  # Forces the connection between broker and client closed.
+  # @note Use of this method may result in frames never being sent to the
+  #   broker. This method should only be used if {#disconnect} is not an
+  #   option and the connection needs to be terminated immediately.
+  # @return [self]
+  def close!
+    close
+    processor_inst.stop
+    self
+  end
+  
+  # @group Methods you ought not use directly.
+  
+  # Ultimately sends a {OnStomp::Components::Frame frame} to the STOMP broker.
+  # This method should not be invoked directly. Use the frame methods provided
+  # by the {OnStomp::Interfaces:FrameMethod} interface.
+  # @return [OnStomp::Components::Frame]
+  def transmit(frame, cbs={})
+    frame.tap do
+      register_callbacks frame, cbs
+      trigger_before_transmitting frame
+      connection.write_frame_nonblock frame
+    end
+  end
+  
+  # Called by {#connection} when a frame has been read from the socket
+  # connection to the STOMP broker.
+  def dispatch_received frame
+    trigger_before_receiving frame
+    trigger_after_receiving frame
+  end
+  
+  # Called by {#connection} when a frame has been written to the socket
+  # connection to the STOMP broker.
+  def dispatch_transmitted frame
+    trigger_after_transmitting frame
+  end
+  
+  # @endgroup
+  
+  private
+  def register_callbacks f, cbs
+    cbs[:subscribe] && add_subscription(f, cbs[:subscribe])
+    cbs[:receipt] && add_receipt(f, cbs[:receipt])
+  end
+  
+  def processor_inst
+    @processor_inst ||= processor.new(self)
+  end
+  
+  def close
+    connection && connection.close
+    clear_subscriptions
+    clear_receipts
+  end
+end