README.rdoc in stomper-0.4 vs README.rdoc in stomper-1.0.0

@@ -1,16 +1,65 @@
 =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:
+Stomper is a library for connecting to and interacting with a message broker
+service that supports the Stomp 1.0 Protocol
 
-* 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)
+@see http://stomp.github.com/stomp-specification-1-0.html Stomp 1.0 Specification
 
+
+== OpenURI Example Usage
+
+    # A contrived example: Send two messages, receive them back
+    open("stomp://localhost/queue/testing") do |s|
+      s.puts "Hello World"
+      s.write "You may disagree, but I find this useful!"
+      messages = s.first(2) # => [ Message("Hello World"), Message("You may disagree...") ]
+    end
+
+    # Another example: connect, send a message to a destination and disconnect
+    open("stomp://localhost/topic/whatever") do |s|
+      s.put "PING!"
+    end
+
+    # Another example: connect, subscribe and process indefinitely
+    open("stomp://localhost/queue/worker") do |s|
+      s.each do |m|
+        logger.info "Received a message: #{m.body}"
+        # Do important work based on message
+      end
+    end
+
+    # Final example: connect, get a single message, and disconnect
+    open("stomp+ssl://localhost/queue/odd_jobs") do |s|
+      # you can use get, gets, read or first, they're all the same at
+      # this time and for the foreseeable future.
+      incoming_message = s.get
+      # Do some work on incoming_message
+    end
+
+This interface has been a goal of mine for this library for some time now.  I
+understand the value in a more typical socket object approach, and to that end
+the client interface still exists (albeit there's been quite a lot of refractoring.)
+However,
+
+    stomp = Stomper::Connection.new("stomp://localhost/")
+    stomp.subscribe("/queue/blather") do |m|
+      # ...
+    end
+    stomp.send("/topic/other", "Hello")
+
+just doesn't feel very Ruby-esque to me.  While the two methods for interacting with
+Stomper connections appear very different, +s+ in the OpenURI examples above
+really is a Stomper::Connection, but with some added extensions for handling
++put+, +get+, +each+, and so forth.  One note: +read+, +get+ and +gets+ are
+all aliases for +first+.  Similarly, +puts+ is an alias for +put+.  However,
++write+ is slightly different.  The message broker I most often use the
+STOMP protocol with is Apache ActiveMQ which, at the time of this writing, uses
+the absence or presence of a `content-length` header to discriminate between a
+JMS TextMessage and a BytesMessage.  The +put+ and +puts+ methods will force
+Stomper to omit that header, while +write+ will force its presence.
+
 == Example Usage
 
     client = Stomper::Client.new("stomp://my_username:s3cr3tz@localhost:61613")
     # Clients must be explicitly started to automatically receive incoming
     # messages.
@@ -44,25 +93,28 @@
     # Later ...
     client.stop
     client.close
 
 == To-Do
+* Provide other methods for handling the receiver.
 * 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
+Stomper began its life as a mere fork of the 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.
 
+@see http://github.com/js/stomp Stomp
+
 == Other Stuff
 
 Primary Author:: Ian D. Eccles
 Source Repository:: http://github.com/iande/stomper
-Current Version:: 0.3.2
-Last Updated:: 2010-03-05
+Current Version:: 1.0.0
+Last Updated:: 2010-09-25
\ No newline at end of file