jruby-jms 0.10.2 → 0.11.0

data/examples/performance/consumer.rb

@@ -1,5 +1,5 @@
 #
-# Sample Consumer: 
+# Sample Consumer:
 #   Retrieve all messages from a queue
 #
 
@@ -10,18 +10,16 @@ require 'rubygems'
 require 'yaml'
 require 'jms'
 
-jms_provider = ARGV[1] || 'actvemq'
+jms_provider = ARGV[0] || 'activemq'
 
 # Load Connection parameters from configuration file
 config = YAML.load_file(File.join(File.dirname(__FILE__), '..', 'jms.yml'))[jms_provider]
 raise "JMS Provider option:#{jms_provider} not found in jms.yml file" unless config
 
 JMS::Connection.session(config) do |session|
-  session.consumer(:queue_name => 'ExampleQueue') do |consumer|
-    stats = consumer.each(:statistics => true) do |message|
-      puts "=================================="
-      p message
-    end
-    puts "STATISTICS :" + stats.inspect
+  stats = session.consume(:queue_name => 'ExampleQueue', :statistics => true) do |message|
+      # Do nothing in this example with each message
   end
+
+  JMS::logger.info "Consumed #{stats[:messages]} messages. Average #{stats[:ms_per_msg]}ms per message"
 end

data/examples/performance/producer.rb

@@ -1,6 +1,6 @@
 #
 # Sample Producer:
-#   Write messages to the queue
+#   Write multiple messages to the queue
 #
 
 # Allow examples to be run in-place without requiring a gem install
@@ -9,23 +9,23 @@ $LOAD_PATH.unshift File.dirname(__FILE__) + '/../../lib'
 require 'rubygems'
 require 'yaml'
 require 'jms'
- 
+require 'benchmark'
+
 jms_provider = ARGV[0] || 'activemq'
-count = (ARGV[1] || 5).to_i
+count = (ARGV[1] || 10).to_i
 
 # Load Connection parameters from configuration file
 config = YAML.load_file(File.join(File.dirname(__FILE__), '..', 'jms.yml'))[jms_provider]
 raise "JMS Provider option:#{jms_provider} not found in jms.yml file" unless config
 
 JMS::Connection.session(config) do |session|
-  start_time = Time.now
-  
-  session.producer(:queue_name => 'ExampleQueue') do |producer|
-    count.times do |i| 
-      producer.send(session.message("Hello Producer #{i}"))
+  duration = Benchmark.realtime do
+    session.producer(:queue_name => 'ExampleQueue') do |producer|
+      count.times do |i|
+        producer.send(session.message("Hello Producer #{i}"))
+      end
     end
   end
 
-  duration = Time.now - start_time
-  puts "Delivered #{count} messages in #{duration} seconds at #{count/duration} messages per second"
+  JMS::logger.info "Produced #{count} messages. Average #{duration*1000/count}ms per message"
 end

data/examples/producer-consumer/browser.rb

@@ -0,0 +1,24 @@
+#
+# Sample Browsing Consumer:
+#   Browse all messages on a queue without removing them
+#
+
+# Allow examples to be run in-place without requiring a gem install
+$LOAD_PATH.unshift File.dirname(__FILE__) + '/../../lib'
+
+require 'rubygems'
+require 'jms'
+require 'yaml'
+
+jms_provider = ARGV[0] || 'activemq'
+
+# Load Connection parameters from configuration file
+config = YAML.load_file(File.join(File.dirname(__FILE__), '..', 'jms.yml'))[jms_provider]
+raise "JMS Provider option:#{jms_provider} not found in jms.yml file" unless config
+
+# Consume all available messages on the queue
+JMS::Connection.session(config) do |session|
+  session.browse(:queue_name => 'ExampleQueue', :timeout=>1000) do |message|
+    JMS::logger.info message.inspect
+  end
+end

data/examples/{consumer.rb → producer-consumer/consumer.rb}

@@ -1,10 +1,10 @@
 #
-# Sample Consumer: 
+# Sample Consumer:
 #   Retrieve all messages from a queue
 #
 
 # Allow examples to be run in-place without requiring a gem install
-$LOAD_PATH.unshift File.dirname(__FILE__) + '/../lib'
+$LOAD_PATH.unshift File.dirname(__FILE__) + '/../../lib'
 
 require 'rubygems'
 require 'jms'
@@ -13,11 +13,12 @@ require 'yaml'
 jms_provider = ARGV[0] || 'activemq'
 
 # Load Connection parameters from configuration file
-config = YAML.load_file(File.join(File.dirname(__FILE__), 'jms.yml'))[jms_provider]
+config = YAML.load_file(File.join(File.dirname(__FILE__), '..', 'jms.yml'))[jms_provider]
 raise "JMS Provider option:#{jms_provider} not found in jms.yml file" unless config
 
+# Consume all available messages on the queue
 JMS::Connection.session(config) do |session|
   session.consume(:queue_name => 'ExampleQueue', :timeout=>1000) do |message|
-    p message
+    JMS::logger.info message.inspect
   end
 end

data/examples/producer-consumer/consumer_async.rb

@@ -0,0 +1,30 @@
+#
+# Sample Asynchronous Consumer:
+#   Retrieve all messages from the queue in a separate thread
+#
+
+# Allow examples to be run in-place without requiring a gem install
+$LOAD_PATH.unshift File.dirname(__FILE__) + '/../../lib'
+
+require 'rubygems'
+require 'jms'
+require 'yaml'
+
+jms_provider = ARGV[0] || 'activemq'
+
+# Load Connection parameters from configuration file
+config = YAML.load_file(File.join(File.dirname(__FILE__), '..', 'jms.yml'))[jms_provider]
+raise "JMS Provider option:#{jms_provider} not found in jms.yml file" unless config
+
+# Consume all available messages on the queue
+JMS::Connection.start(config) do |connection|
+  
+  # Define Asynchronous code block to be called every time a message is receive
+  connection.on_message(:queue_name => 'ExampleQueue') do |message|
+    JMS::logger.info message.inspect
+  end
+
+  # Since the on_message handler above is in a separate thread the thread needs
+  # to do some other work. For this example it will just sleep for 10 seconds
+  sleep 10
+end

data/examples/{producer.rb → producer-consumer/producer.rb}

@@ -4,7 +4,7 @@
 #
 
 # Allow examples to be run in-place without requiring a gem install
-$LOAD_PATH.unshift File.dirname(__FILE__) + '/../lib'
+$LOAD_PATH.unshift File.dirname(__FILE__) + '/../../lib'
 
 require 'rubygems'
 require 'yaml'
@@ -13,11 +13,13 @@ require 'jms'
 jms_provider = ARGV[0] || 'activemq'
 
 # Load Connection parameters from configuration file
-config = YAML.load_file(File.join(File.dirname(__FILE__), 'jms.yml'))[jms_provider]
+config = YAML.load_file(File.join(File.dirname(__FILE__), '..', 'jms.yml'))[jms_provider]
 raise "JMS Provider option:#{jms_provider} not found in jms.yml file" unless config
 
 JMS::Connection.session(config) do |session|
   session.producer(:queue_name => 'ExampleQueue') do |producer|
-    producer.send(session.message("Hello World"))
+    producer.delivery_mode = JMS::DeliveryMode::NON_PERSISTENT
+    producer.send(session.message("Hello World: #{Time.now}"))
+    JMS::logger.info "Successfully sent one message to queue ExampleQueue"
   end
 end

data/examples/publish-subscribe/publish.rb

@@ -0,0 +1,24 @@
+#
+# Sample Publisher:
+#   Write messages to a topic
+#
+
+# Allow examples to be run in-place without requiring a gem install
+$LOAD_PATH.unshift File.dirname(__FILE__) + '/../../lib'
+
+require 'rubygems'
+require 'yaml'
+require 'jms'
+
+jms_provider = ARGV[0] || 'activemq'
+
+# Load Connection parameters from configuration file
+config = YAML.load_file(File.join(File.dirname(__FILE__), '..', 'jms.yml'))[jms_provider]
+raise "JMS Provider option:#{jms_provider} not found in jms.yml file" unless config
+
+JMS::Connection.session(config) do |session|
+  session.producer(:topic_name => 'SampleTopic') do |producer|
+    producer.send(session.message("Hello World: #{Time.now}"))
+    JMS::logger.info "Successfully published one message to topic SampleTopic"
+  end
+end

data/examples/publish-subscribe/subscribe.rb

@@ -0,0 +1,31 @@
+#
+# Sample Topic Subscriber:
+#   Retrieve all messages from a topic using a non-durable subscription
+#
+# Try starting multiple copies of this Consumer. All active instances should
+# receive the same messages
+#
+# Since the topic subscription is non-durable, it will only receive new messages.
+# Any messages sent prior to the instance starting will not be received.
+# Also, any messages sent after the instance has stopped will not be received
+# when the instance is re-started, only new messages sent after it started will
+# be received.
+
+# Allow examples to be run in-place without requiring a gem install
+$LOAD_PATH.unshift File.dirname(__FILE__) + '/../../lib'
+
+require 'rubygems'
+require 'jms'
+require 'yaml'
+
+jms_provider = ARGV[0] || 'activemq'
+
+# Load Connection parameters from configuration file
+config = YAML.load_file(File.join(File.dirname(__FILE__), '..', 'jms.yml'))[jms_provider]
+raise "JMS Provider option:#{jms_provider} not found in jms.yml file" unless config
+
+JMS::Connection.session(config) do |session|
+  session.consume(:topic_name => 'SampleTopic', :timeout=>30000) do |message|
+    JMS::logger.info message.inspect
+  end
+end

data/lib/jms/bytes_message.rb

@@ -0,0 +1,52 @@
+################################################################################
+#  Copyright 2008, 2009, 2010, 2011  J. Reid Morrison
+#
+#  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.
+################################################################################
+
+#Interface javax.jms.BytesMessage
+module JMS::BytesMessage
+  def data
+    # Puts the message body in read-only mode and repositions the stream of
+    # bytes to the beginning
+    self.reset
+
+    available = self.body_length
+
+    return nil if available == 0
+
+    result = ""
+    bytes_size = 1024
+    bytes = Java::byte[bytes_size].new
+
+    while (n = available < bytes_size ? available : bytes_size) > 0
+      self.read_bytes(bytes, n)
+      if n == bytes_size
+        result << String.from_java_bytes(bytes)
+      else
+        result << String.from_java_bytes(bytes)[0..n-1]
+      end
+      available -= n
+    end
+    result
+  end
+
+  def data=(val)
+    self.write_bytes(val.respond_to?(:to_java_bytes) ? val.to_java_bytes : val)
+  end
+
+  def to_s
+    data
+  end
+
+end

data/lib/jms/connection.rb

@@ -32,15 +32,15 @@ module JMS
   #  require 'jms'
   #
   #  JMS::Connection.create_session(
-  #    :queue_manager=>'REID',   # Should be :q_mgr_name
-  #    :host_name=>'localhost',
-  #    :channel=>'MY.CLIENT.CHL',
-  #    :port=>1414,
-  #    :factory => com.ibm.mq.jms.MQQueueConnectionFactory,
-  #    :transport_type => com.ibm.mq.jms.JMSC::MQJMS_TP_CLIENT_MQ_TCPIP,
-  #    :username => 'mqm'
+  #    :factory => 'org.apache.activemq.ActiveMQConnectionFactory',
+  #    :broker_url => 'tcp://localhost:61616',
+  #    :require_jars => [
+  #      '~/Applications/apache-activemq-5.5.0/activemq-all-5.5.0.jar',
+  #      '~/Applications/apache-activemq-5.5.0/lib/optional/slf4j-log4j12-1.5.11.jar',
+  #      '~/Applications/apache-activemq-5.5.0/lib/optional/log4j-1.2.14.jar',
+  #    ]
   #  ) do |session|
-  #    session.consumer(:queue_name=>'TEST', :mode=>:input) do |consumer|
+  #    session.consumer(:queue_name=>'TEST') do |consumer|
   #      if message = consumer.receive_no_wait
   #        puts "Data Received: #{message.data}"
   #      else
@@ -70,13 +70,16 @@ module JMS
       end
     end
 
-    # Connect to a JMS Broker, create a session and call the code block passing in the session
+    # Connect to a JMS Broker, create and start the session,
+    # then call the code block passing in the session.
     # Both the Session and Connection are closed on termination of the block
     #
     # Shortcut convenience method to both connect to the broker and create a session
     # Useful when only a single session is required in the current thread
     #
     # Note: It is important that each thread have its own session to support transactions
+    #       This method will also start the session immediately so that any
+    #       consumers using this session will start immediately
     def self.session(params = {}, &proc)
       self.start(params) do |connection|
         connection.session(params, &proc)
@@ -101,22 +104,25 @@ module JMS
     # TODO make this a class method
     def fetch_dependencies(jar_list)
       jar_list.each do |jar|
-        JMS::logger.info "Loading Jar File:#{jar}"
+        JMS::logger.debug "Loading Jar File:#{jar}"
         begin
           require jar
         rescue Exception => exc
           JMS::logger.error "Failed to Load Jar File:#{jar}. #{exc.to_s}"
         end
       end if jar_list
-      
-      require 'jms/message_listener'
-      require 'jms/javax_jms_message'
-      require 'jms/javax_jms_text_message'
-      require 'jms/javax_jms_map_message'
-      require 'jms/javax_jms_object_message'
-      require 'jms/javax_jms_session'
-      require 'jms/javax_jms_message_consumer'
-      require 'jms/javax_jms_queue_browser'
+
+      require 'jms/imports'
+      require 'jms/message_listener_impl'
+      require 'jms/message'
+      require 'jms/text_message'
+      require 'jms/map_message'
+      require 'jms/bytes_message'
+      require 'jms/object_message'
+      require 'jms/session'
+      require 'jms/message_consumer'
+      require 'jms/queue_browser'
+      require 'jms/oracle_a_q_connection_factory'
     end
 
     # Create a connection to the JMS provider
@@ -139,101 +145,42 @@ module JMS
     #   :jndi_context => Mandatory if jndi lookup is being used, contains details
     #                    on how to connect to JNDI server etc.
     #
+    #   :require_jars => An optional array of Jar file names to load for the specified
+    #                    JMS provider. By using this option it is not necessary
+    #                    to put all the JMS Provider specific jar files into the
+    #                    environment variable CLASSPATH prior to starting JRuby
+    #
+    #   :username  => Username to connect to JMS provider with
+    #   :password  => Password to use when to connecting to the JMS provider
+    #                 Note: :password is ignored if :username is not supplied
+    #
     # :factory and :jndi_name are mutually exclusive, both cannot be supplied at the
     # same time. :factory takes precedence over :jndi_name
     #
     # JMS Provider specific properties can be set if the JMS Factory itself
-    # has setters for those properties. Some known examples:
-    #
-    #   For HornetQ
-    #    :factory => 'org.hornetq.jms.client.HornetQConnectionFactory',
-    #    :discovery_address => '127.0.0.1',
-    #    :discovery_port => '5445',
-    #    :username => 'guest',
-    #    :password => 'guest'
-    #
-    #   For HornetQ using JNDI lookup technique
-    #    :jndi_name => '/ConnectionFactory',
-    #    :jndi_context => {
-    #      'java.naming.factory.initial' => 'org.jnp.interfaces.NamingContextFactory',
-    #      'java.naming.provider.url' => 'jnp://localhost:1099',
-    #      'java.naming.factory.url.pkgs' => 'org.jboss.naming:org.jnp.interfaces',
-    #      'java.naming.security.principal' => 'guest',
-    #      'java.naming.security.credentials' => 'guest'
-    #    }
-    #
-    #   On Java 6, HornetQ needs the following jar files on your CLASSPATH:
-    #     hornetq-core-client.jar
-    #     netty.jar
-    #     hornetq-jms-client.jar
-    #     jboss-jms-api.jar
-    #     jnp-client.jar
-    #
-    #   On Java 5, HornetQ needs the following jar files on your CLASSPATH:
-    #     hornetq-core-client-java5.jar
-    #     netty.jar
-    #     hornetq-jms-client-java5.jar
-    #     jboss-jms-api.jar
-    #     jnp-client.jar
-    #
-    #   For: WebSphere MQ
-    #    :factory => 'com.ibm.mq.jms.MQQueueConnectionFactory',
-    #    :queue_manager=>'REID',
-    #    :host_name=>'localhost',
-    #    :channel=>'MY.CLIENT.CHL',
-    #    :port=>1414,
-    #    :transport_type => com.ibm.mq.jms.JMSC::MQJMS_TP_CLIENT_MQ_TCPIP,
-    #    :username => 'mqm'
-    #
-    #   For: Active MQ
-    #    :factory => 'org.apache.activemq.ActiveMQConnectionFactory',
-    #    :broker_url => 'tcp://localhost:61616'
-    #
-    #   ActiveMQ requires the following jar files on your CLASSPATH
-    #
-    #   For Oracle AQ 9 Server
-    #    :factory => 'JMS::OracleAQConnectionFactory',
-    #    :url => 'jdbc:oracle:thin:@hostname:1521:instanceid',
-    #    :username => 'aquser',
-    #    :password => 'mypassword'
-    #
-    #   For JBoss, which uses JNDI lookup technique
-    #    :jndi_name => 'ConnectionFactory',
-    #    :jndi_context => {
-    #      'java.naming.factory.initial' => 'org.jnp.interfaces.NamingContextFactory',
-    #      'java.naming.provider.url' => 'jnp://localhost:1099'
-    #      'java.naming.security.principal' => 'user',
-    #      'java.naming.security.credentials' => 'pwd'
-    #    }
-    #
-    #   For Apache Qpid / Redhat Messaging, using Factory class directly
-    #    :factory:  org.apache.qpid.client.AMQConnectionFactory
-    #    :broker_url: tcp://localhost:5672
-    #
-    #   For Apache Qpid / Redhat Messaging, via JNDI lookup
-    #    :jndi_name => 'local',
-    #    :jndi_context => {
-    #      'java.naming.factory.initial' => 'org.apache.qpid.jndi.PropertiesFileInitialContextFactory',
-    #      'connectionfactory.local' => "amqp://guest:guest@clientid/testpath?brokerlist='tcp://localhost:5672'"
-    #    }
+    # has setters for those properties.
+    #
+    # For some known examples, see: [Example jms.yml](https://github.com/reidmorrison/jruby-jms/blob/master/examples/jms.yml)
     #
     def initialize(params = {})
       # Used by ::on_message
       @sessions = []
       @consumers = []
 
+      options = params.dup
+
       # Load Jar files on demand so that they do not need to be in the CLASSPATH
       # of JRuby lib directory
-      fetch_dependencies(params[:require_jars])
+      fetch_dependencies(options.delete(:require_jars))
 
       connection_factory = nil
-      factory = params[:factory]
+      factory = options.delete(:factory)
       if factory
         # If factory is a string, then it is the name of a class, not the class itself
         factory = eval(factory) if factory.respond_to? :to_str
         connection_factory = factory.new
-      elsif jndi_name = params[:jndi_name]
-        raise "Missing mandatory parameter :jndi_context missing in call to Connection::connect" unless jndi_context = params[:jndi_context]
+      elsif jndi_name = options[:jndi_name]
+        raise "Missing mandatory parameter :jndi_context missing in call to Connection::connect" unless jndi_context = options[:jndi_context]
         jndi = javax.naming.InitialContext.new(java.util.Hashtable.new(jndi_context))
         begin
           connection_factory = jndi.lookup jndi_name
@@ -243,17 +190,25 @@ module JMS
       else
         raise "Missing mandatory parameter :factory or :jndi_name missing in call to Connection::connect"
       end
+      options.delete(:jndi_name)
+      options.delete(:jndi_context)
 
       JMS::logger.debug "Using Factory: #{connection_factory.java_class}" if connection_factory.respond_to? :java_class
-      params.each_pair do |key, val|
+      options.each_pair do |key, val|
+        next if [:username, :password].include?(key)
+
         method = key.to_s+'='
         if connection_factory.respond_to? method
           connection_factory.send method, val
-          JMS::logger.debug "   #{key} = #{connection_factory.send key}" if connection_factory.respond_to? key.to_sym
+          JMS::logger.debug "   #{key} = #{connection_factory.send key.to_sym}" if connection_factory.respond_to? key.to_sym
+        else
+          JMS::logger.warn "#{connection_factory.java_class} does not understand option: :#{key}=#{val}, ignoring :#{key}" if connection_factory.respond_to? :java_class
         end
       end
-      if params[:username]
-        @jms_connection = connection_factory.create_connection(params[:username], params[:password])
+
+      # Check for username and password
+      if options[:username]
+        @jms_connection = connection_factory.create_connection(options[:username], options[:password])
       else
         @jms_connection = connection_factory.create_connection
       end
@@ -266,7 +221,7 @@ module JMS
     def start
       @jms_connection.start
     end
-      
+
     # Temporarily stop delivery of incoming messages on this connection
     # Useful during a hot code update or other changes that need to be completed
     # without any new messages being processed
@@ -285,8 +240,25 @@ module JMS
     #      Determines whether transactions are supported within this session.
     #      I.e. Whether commit or rollback can be called
     #      Default: false
-    #  :options => any of the javax.jms.Session constants
-    #      Default: javax.jms.Session::AUTO_ACKNOWLEDGE
+    #      Note: :options below are ignored if this value is set to :true
+    #
+    #  :options => any of the JMS::Session constants:
+    #     Note: :options are ignored if :transacted => true
+    #     JMS::Session::AUTO_ACKNOWLEDGE
+    #        With this acknowledgment mode, the session automatically acknowledges
+    #        a client's receipt of a message either when the session has successfully
+    #        returned from a call to receive or when the message listener the session has
+    #        called to process the message successfully returns.
+    #     JMS::Session::CLIENT_ACKNOWLEDGE
+    #        With this acknowledgment mode, the client acknowledges a consumed
+    #        message by calling the message's acknowledge method.
+    #     JMS::Session::DUPS_OK_ACKNOWLEDGE
+    #        This acknowledgment mode instructs the session to lazily acknowledge
+    #        the delivery of messages.
+    #     JMS::Session::SESSION_TRANSACTED
+    #        This value is returned from the method getAcknowledgeMode if the
+    #        session is transacted.
+    #     Default: JMS::Session::AUTO_ACKNOWLEDGE
     #
     def session(params={}, &proc)
       raise "Missing mandatory Block when calling JMS::Connection#session" unless proc
@@ -310,28 +282,29 @@ module JMS
     #      Determines whether transactions are supported within this session.
     #      I.e. Whether commit or rollback can be called
     #      Default: false
-    #      Note: :options below is ignored if this value is set to :true
-    #  :options => any of the javax.jms.Session constants:
-    #     Note: :options is ignored of :transacted => true
-    #     javax.jms.Session::AUTO_ACKNOWLEDGE
+    #      Note: :options below are ignored if this value is set to :true
+    #
+    #  :options => any of the JMS::Session constants:
+    #     Note: :options are ignored if :transacted => true
+    #     JMS::Session::AUTO_ACKNOWLEDGE
     #        With this acknowledgment mode, the session automatically acknowledges
     #        a client's receipt of a message either when the session has successfully
     #        returned from a call to receive or when the message listener the session has
     #        called to process the message successfully returns.
-    #     javax.jms.Session::CLIENT_ACKNOWLEDGE
+    #     JMS::Session::CLIENT_ACKNOWLEDGE
     #        With this acknowledgment mode, the client acknowledges a consumed
     #        message by calling the message's acknowledge method.
-    #     javax.jms.Session::DUPS_OK_ACKNOWLEDGE
+    #     JMS::Session::DUPS_OK_ACKNOWLEDGE
     #        This acknowledgment mode instructs the session to lazily acknowledge
     #        the delivery of messages.
-    #     javax.jms.Session::SESSION_TRANSACTED
+    #     JMS::Session::SESSION_TRANSACTED
     #        This value is returned from the method getAcknowledgeMode if the
     #        session is transacted.
-    #     Default: javax.jms.Session::AUTO_ACKNOWLEDGE
+    #     Default: JMS::Session::AUTO_ACKNOWLEDGE
     #
     def create_session(params={})
       transacted = params[:transacted] || false
-      options = params[:options] || javax.jms.Session::AUTO_ACKNOWLEDGE
+      options = params[:options] || JMS::Session::AUTO_ACKNOWLEDGE
       @jms_connection.create_session(transacted, options)
     end
 
@@ -346,65 +319,62 @@ module JMS
 
       @jms_connection.close if @jms_connection
     end
-    
+
     # Gets the client identifier for this connection.
     def client_id
       @jms_connection.getClientID
     end
-          
+
     # Sets the client identifier for this connection.
     def client_id=(client_id)
       @jms_connection.setClientID(client_id)
     end
-    
+
     # Returns the ExceptionListener object for this connection
-    # Returned class implements interface javax.jms.ExceptionListener
+    # Returned class implements interface JMS::ExceptionListener
     def exception_listener
       @jms_connection.getExceptionListener
     end
- 
+
     # Sets an exception listener for this connection
     # See ::on_exception to set a Ruby Listener
     # Returns: nil
     def exception_listener=(listener)
-      setExceptionListener(listener)
+      @jms_connection.setExceptionListener(listener)
     end
-    
+
     # Whenever an exception occurs the supplied block is called
     # This is important when Connection::on_message has been used, since
     # failures to the connection would be lost otherwise
-    # 
-    # For details on the supplied parameter when the block is called, 
+    #
+    # For details on the supplied parameter when the block is called,
     # see: http://download.oracle.com/javaee/6/api/javax/jms/JMSException.html
-    # 
+    #
     # Example:
-    #   connection.on_message do |jms_exception|
+    #   connection.on_exception do |jms_exception|
     #     puts "JMS Exception has occurred: #{jms_exception}"
     #   end
     #
     # Returns: nil
     def on_exception(&block)
-      setExceptionListener(block)
+      @jms_connection.setExceptionListener(block)
     end
-    
+
     # Gets the metadata for this connection
     # see: http://download.oracle.com/javaee/6/api/javax/jms/ConnectionMetaData.html
     def meta_data
       @jms_connection.getMetaData
     end
-    
+
     # Return a string describing the JMS provider and version
     def to_s
       md = @jms_connection.getMetaData
       "JMS::Connection provider: #{md.getJMSProviderName} v#{md.getProviderVersion}, JMS v#{md.getJMSVersion}"
     end
 
-    # TODO: Return a pretty print version of the current JMS Connection
-    #    def to_s
-    #    end
-
     # Receive messages in a separate thread when they arrive
-    # Allows messages to be recieved in a separate thread. I.e. Asynchronously
+    #
+    # Allows messages to be received Asynchronously in a separate thread.
     # This method will return to the caller before messages are processed.
     # It is then the callers responsibility to keep the program active so that messages
     # can then be processed.
@@ -414,19 +384,36 @@ module JMS
     #      Determines whether transactions are supported within this session.
     #      I.e. Whether commit or rollback can be called
     #      Default: false
-    #  :options => any of the javax.jms.Session constants
-    #      Default: javax.jms.Session::AUTO_ACKNOWLEDGE
+    #      Note: :options below are ignored if this value is set to :true
+    #
+    #  :options => any of the JMS::Session constants:
+    #     Note: :options are ignored if :transacted => true
+    #     JMS::Session::AUTO_ACKNOWLEDGE
+    #        With this acknowledgment mode, the session automatically acknowledges
+    #        a client's receipt of a message either when the session has successfully
+    #        returned from a call to receive or when the message listener the session has
+    #        called to process the message successfully returns.
+    #     JMS::Session::CLIENT_ACKNOWLEDGE
+    #        With this acknowledgment mode, the client acknowledges a consumed
+    #        message by calling the message's acknowledge method.
+    #     JMS::Session::DUPS_OK_ACKNOWLEDGE
+    #        This acknowledgment mode instructs the session to lazily acknowledge
+    #        the delivery of messages.
+    #     JMS::Session::SESSION_TRANSACTED
+    #        This value is returned from the method getAcknowledgeMode if the
+    #        session is transacted.
+    #     Default: JMS::Session::AUTO_ACKNOWLEDGE
     #
     #   :session_count : Number of sessions to create, each with their own consumer which
-    #                    in turn will call the supplied Proc.
-    #                    Note: The supplied Proc must be thread safe since it will be called
+    #                    in turn will call the supplied code block.
+    #                    Note: The supplied block must be thread safe since it will be called
     #                          by several threads at the same time.
     #                          I.e. Don't change instance variables etc. without the
     #                          necessary semaphores etc.
     #                    Default: 1
     #
     # Consumer Parameters:
-    #   :queue_name     => String: Name of the Queue to return
+    #   :queue_name => String: Name of the Queue to return
     #                  Symbol: :temporary => Create temporary queue
     #                  Mandatory unless :topic_name is supplied
     #     Or,
@@ -438,8 +425,9 @@ module JMS
     #
     #   :selector   => Filter which messages should be returned from the queue
     #                  Default: All messages
+    #
     #   :no_local   => Determine whether messages published by its own connection
-    #                  should be delivered to it
+    #                  should be delivered to the supplied block
     #                  Default: false
     #
     #   :statistics Capture statistics on how many messages have been read
@@ -451,18 +439,15 @@ module JMS
     #              Also, the start time and message count is not reset until MessageConsumer::each
     #              is called again with :statistics => true
     #
-    #              The statistics gathered are returned when :statistics => true and :async => false
-    #
-    # Usage: For transacted sessions (the default) the Proc supplied must return
-    #        either true or false:
+    # Usage: For transacted sessions the block supplied must return either true or false:
     #          true => The session is committed
     #          false => The session is rolled back
     #          Any Exception => The session is rolled back
     #
-    # Note: Also supply connection::on_exception so that connection failures can be handled
+    # Note: Separately invoke Connection#on_exception so that connection failures can be handled
+    #       since on_message will Not be called if the connection is lost
     #
-    #
-    def on_message(params, &proc)
+    def on_message(params, &block)
       raise "JMS::Connection must be connected prior to calling JMS::Connection::on_message" unless @sessions && @consumers
 
       consumer_count = params[:session_count] || 1
@@ -472,40 +457,63 @@ module JMS
         if session.transacted?
           consumer.on_message(params) do |message|
             begin
-              proc.call(message) ? session.commit : session.rollback
+              block.call(message) ? session.commit : session.rollback
             rescue => exc
               session.rollback
               throw exc
             end
           end
         else
-          consumer.on_message(params, &proc)
+          consumer.on_message(params, &block)
         end
         @consumers << consumer
         @sessions << session
       end
     end
 
+    # Return the statistics for every active Connection#on_message consumer
+    # in an Array
+    #
+    # For details on the contents of each element in the array, see: Consumer#on_message_statistics
     def on_message_statistics
-      @consumers.collect{|consumer| consumer.on_message_statistics}
+      @consumers.collect { |consumer| consumer.on_message_statistics }
     end
 
-  end
-
-  # Wrapper to support Oracle AQ
-  class OracleAQConnectionFactory
-    attr_accessor :username, :url
-    attr_writer :password
-
-    # Creates a connection per standard JMS 1.1 techniques from the Oracle AQ JMS Interface
-    def create_connection
-      cf = oracle.jms.AQjmsFactory.getConnectionFactory(@url, java.util.Properties.new)
-      if username
-        cf.createConnection(@username, @password)
-      else
-        cf.createConnection()
-      end
+    # Since a Session can only be used by one thread at a time, we could create
+    # a Session for every thread. That could result in excessive unused Sessions.
+    # An alternative is to create a pool of sessions that can be shared by
+    # multiple threads.
+    #
+    # Each thread can request a session and then return it once it is no longer
+    # needed by that thread. The only way to get a session is to pass a block so that
+    # the Session is automatically returned to the pool upon completion of the block.
+    #
+    # Parameters:
+    #   see regular session parameters from: JMS::Connection#initialize
+    #
+    # Additional parameters for controlling the session pool itself
+    #   :pool_name         Name of the pool as it shows up in the logger.
+    #                      Default: 'JMS::SessionPool'
+    #   :pool_size         Maximum Pool Size. Default: 10
+    #                      The pool only grows as needed and will never exceed
+    #                      :pool_size
+    #   :pool_warn_timeout Number of seconds to wait before logging a warning when a
+    #                      session in the pool is not available. Measured in seconds
+    #                      Default: 5.0
+    #   :pool_logger       Supply a logger that responds to #debug, #info, #warn and #debug?
+    #                      For example: Rails.logger
+    #                      Default: None
+    # Example:
+    #   session_pool = connection.create_session_pool(config)
+    #
+    #   session_pool.session do |session|
+    #      producer.send(session.message("Hello World"))
+    #   end
+    def create_session_pool(params={})
+      require 'jms/session_pool' unless defined? JMS::SessionPool
+      JMS::SessionPool.new(self, params)
     end
+
   end
 
 end