jruby-jms 1.1.0-java

data/lib/jms/message_consumer.rb

@@ -0,0 +1,117 @@
+################################################################################
+#  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.MessageConsumer
+module JMS::MessageConsumer
+  # Obtain a message from the Destination or Topic
+  # In JMS terms, the message is received from the Destination
+  # :timeout follows the rules for MQSeries:
+  #   -1 : Wait forever
+  #    0 : Return immediately if no message is available
+  #    x : Wait for x milli-seconds for a message to be received from the broker
+  #         Note: Messages may still be on the queue, but the broker has not supplied any messages
+  #                   in the time interval specified
+  #    Default: 0
+  def get(params={})
+    timeout = params[:timeout] || 0
+    if timeout == -1
+      self.receive
+    elsif timeout == 0
+      self.receiveNoWait
+    else
+      self.receive(timeout)
+    end
+  end
+
+  # For each message available to be consumed call the Proc supplied
+  # Returns the statistics gathered when :statistics => true, otherwise nil
+  #
+  # Parameters:
+  #   :timeout How to timeout waiting for messages on the Queue or Topic
+  #     -1 : Wait forever
+  #      0 : Return immediately if no message is available
+  #      x : Wait for x milli-seconds for a message to be received from the broker
+  #           Note: Messages may still be on the queue, but the broker has not supplied any messages
+  #                     in the time interval specified
+  #      Default: 0
+  #
+  #   :statistics Capture statistics on how many messages have been read
+  #      true  : This method will capture statistics on the number of messages received
+  #              and the time it took to process them.
+  #              The statistics can be reset by calling MessageConsumer::each again
+  #              with :statistics => true
+  #
+  #              The statistics gathered are returned when :statistics => true and :async => false
+  def each(params={}, &proc)
+    raise "Destination::each requires a code block to be executed for each message received" unless proc
+
+    message_count = nil
+    start_time = nil
+
+    if params[:statistics]
+      message_count = 0
+      start_time = Time.now
+    end
+
+    # Receive messages according to timeout
+    while message = self.get(params) do
+      proc.call(message)
+      message_count += 1 if message_count
+    end
+
+    unless message_count.nil?
+      duration = Time.now - start_time
+      {:messages => message_count,
+        :duration => duration,
+        :messages_per_second => duration > 0 ? (message_count/duration).to_i : 0,
+        :ms_per_msg => message_count > 0 ? (duration*1000.0)/message_count : 0
+      }
+    end
+  end
+
+  # Receive messages in a separate thread when they arrive
+  # Allows messages to be recieved in a separate thread. I.e. Asynchronously
+  # 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.
+  #
+  # Parameters:
+  #   :statistics Capture statistics on how many messages have been read
+  #      true  : This method will capture statistics on the number of messages received
+  #              and the time it took to process them.
+  #              The timer starts when each() is called and finishes when either the last message was received,
+  #              or when Destination::statistics is called. In this case MessageConsumer::statistics
+  #              can be called several times during processing without affecting the end time.
+  #              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
+  #
+  def on_message(params={}, &proc)
+    raise "MessageConsumer::on_message requires a code block to be executed for each message received" unless proc
+
+    @listener = JMS::MessageListenerImpl.new(params,&proc)
+    self.setMessageListener @listener
+  end
+
+  # Return the current statistics for a running MessageConsumer::on_message
+  def on_message_statistics
+    stats = @listener.statistics if @listener
+    raise "First call MessageConsumer::on_message with :statistics=>true before calling MessageConsumer::statistics()" unless stats
+    stats
+  end
+
+end

data/lib/jms/message_listener_impl.rb

@@ -0,0 +1,79 @@
+################################################################################
+#  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.
+################################################################################
+
+module JMS
+
+  private
+  # For internal use only by JMS::Connection
+  class MessageListenerImpl
+    include JMS::MessageListener
+
+    # Parameters:
+    #   :statistics Capture statistics on how many messages have been read
+    #      true  : This method will capture statistics on the number of messages received
+    #              and the time it took to process them.
+    #              The timer starts when the listener instance is created and finishes when either the last message was received,
+    #              or when Destination::statistics is called. In this case MessageConsumer::statistics
+    #              can be called several times during processing without affecting the end time.
+    #              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
+    def initialize(params={}, &proc)
+      @proc = proc
+
+      if params[:statistics]
+        @message_count = 0
+        @start_time = Time.now
+      end
+    end
+
+    # Method called for every message received on the queue
+    # Per the JMS specification, this method will be called sequentially for each message on the queue.
+    # This method will not be called again until its prior invocation has completed.
+    # Must be onMessage() since on_message() does not work for interface methods that must be implemented
+    def onMessage(message)
+      begin
+        if @message_count
+          @message_count += 1
+          @last_time = Time.now
+        end
+        @proc.call message
+      rescue SyntaxError, NameError => boom
+        JMS::logger.error "Unhandled Exception processing JMS Message. Doesn't compile: " + boom
+        JMS::logger.error "Ignoring poison message:\n#{message.inspect}"
+        JMS::logger.error boom.backtrace.join("\n")
+      rescue StandardError => bang
+        JMS::logger.error "Unhandled Exception processing JMS Message. Doesn't compile: " + bang
+        JMS::logger.error "Ignoring poison message:\n#{message.inspect}"
+        JMS::logger.error bang.backtrace.join("\n")
+      rescue => exc
+        JMS::logger.error "Unhandled Exception processing JMS Message. Exception occurred:\n#{exc}"
+        JMS::logger.error "Ignoring poison message:\n#{message.inspect}"
+        JMS::logger.error exc.backtrace.join("\n")
+      end
+    end
+
+    # Return Statistics gathered for this listener
+    def statistics
+      raise "First call MessageConsumer::on_message with :statistics=>true before calling MessageConsumer::statistics()" unless @message_count
+      duration =(@last_time || Time.now) - @start_time
+      {:messages => @message_count,
+        :duration => duration,
+        :messages_per_second => (@message_count/duration).to_i}
+    end
+  end
+end

data/lib/jms/message_producer.rb

@@ -0,0 +1,59 @@
+################################################################################
+#  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.
+################################################################################
+
+# Extend JMS Message Producer Interface with Ruby methods
+#
+# For further help on javax.jms.MessageProducer
+#   http://download.oracle.com/javaee/6/api/javax/jms/MessageProducer.html
+#
+# Interface javax.jms.Producer
+module JMS::MessageProducer
+
+  # Return the Delivery Mode as a Ruby symbol
+  #   :persistent
+  #   :non_persistent
+  #   nil if unknown
+  def delivery_mode_sym
+    case delivery_mode
+    when JMS::DeliveryMode::PERSISTENT
+      :persistent
+    when JMS::DeliveryMode::NON_PERSISTENT
+      :non_persistent
+    else
+      nil
+    end
+  end
+
+  # Set the JMS Delivery Mode from a Ruby Symbol
+  # Valid values for mode
+  #   :persistent
+  #   :non_persistent
+  #
+  # Example:
+  #   producer.delivery_mode_sym = :persistent
+  def delivery_mode_sym=(mode)
+    val = case mode
+    when :persistent
+      JMS::DeliveryMode::PERSISTENT
+    when :non_persistent
+      JMS::DeliveryMode::NON_PERSISTENT
+    else
+      raise "Unknown delivery mode symbol: #{mode}"
+    end
+    self.delivery_mode = val
+  end
+
+end

data/lib/jms/mq_workaround.rb

@@ -0,0 +1,70 @@
+# Workaround for IBM MQ JMS implementation that implements some undocumented methods
+
+begin
+  
+  class com.ibm.mq.jms::MQQueueSession
+    
+    if self.instance_methods.include? "consume"
+      def consume(params, &proc)
+        Java::JavaxJms::Session.instance_method(:consume).bind(self).call(params, &proc)
+      end
+    end
+
+  end
+
+
+  class com.ibm.mq.jms::MQSession
+
+    if self.instance_methods.include? "consume"
+      def consume(params, &proc)
+        Java::JavaxJms::Session.instance_method(:consume).bind(self).call(params, &proc)
+      end
+    end
+    
+    if self.instance_methods.include? "create_destination"
+      def create_destination(params)
+        Java::JavaxJms::Session.instance_method(:create_destination).bind(self).call(params)
+      end
+    end
+
+  end
+
+  
+  class com.ibm.mq.jms::MQQueueBrowser
+
+    if self.instance_methods.include? "each"
+      def each(params, &proc)
+        Java::ComIbmMsgClientJms::JmsQueueBrowser.instance_method(:each).bind(self).call(params, &proc)
+      end
+    end
+  end
+  
+
+  class com.ibm.mq.jms::MQQueueReceiver
+    
+    if self.instance_methods.include? "each"
+      def each(params, &proc)
+        Java::JavaxJms::MessageConsumer.instance_method(:each).bind(self).call(params, &proc)
+      end
+    end
+    
+    if self.instance_methods.include? "get"
+      def get(params={})
+        Java::JavaxJms::MessageConsumer.instance_method(:get).bind(self).call(params)
+      end
+    end
+    
+  end
+  
+  
+  class com.ibm.mq.jms::MQQueue
+    
+    if self.instance_methods.include? "delete"
+    undef_method :delete
+    end
+    
+  end
+
+rescue NameError
+  # Ignore errors (when we aren't using MQ)
+end

data/lib/jms/object_message.rb

@@ -0,0 +1,26 @@
+################################################################################
+#  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.ObjectMessage
+module JMS::ObjectMessage
+  def data
+    getObject
+  end
+
+  def data(val)
+    setObject(val)
+  end
+end

data/lib/jms/oracle_a_q_connection_factory.rb

@@ -0,0 +1,48 @@
+################################################################################
+#  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.
+################################################################################
+
+module JMS
+  # Full Qualified name causes a Java exception
+  java_import 'oracle.jms.AQjmsFactory'
+
+  # Connection Factory to support Oracle AQ
+  class OracleAQConnectionFactory
+    attr_accessor :username, :url
+    #attr_writer :password
+    attr_accessor :password
+
+    # Creates a connection per standard JMS 1.1 techniques from the Oracle AQ JMS Interface
+    def create_connection(*args)
+    # Since username and password are not assigned (see lib/jms/connection.rb:200)
+    # and connection_factory.create_connection expects 2 arguments when username is not null ...
+      if args.length == 2
+        @username = args[0]
+        @password = args[1]
+      end
+
+     # Full Qualified name causes a Java exception
+      #cf = oracle.jms.AQjmsFactory.getConnectionFactory(@url, java.util.Properties.new)
+      cf = AQjmsFactory.getConnectionFactory(@url, java.util.Properties.new)
+
+      if username
+        cf.createConnection(@username, @password)
+      else
+        cf.createConnection()
+      end
+    end
+  end
+
+end

data/lib/jms/queue_browser.rb

@@ -0,0 +1,28 @@
+################################################################################
+#  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.QueueBrowser
+module JMS::QueueBrowser
+  # For each message on the queue call the supplied Proc
+  def each(params={}, &block)
+    raise "JMS::QueueBrowser::each requires a code block to be executed for each message received" unless block
+
+    e = self.getEnumeration
+    while e.hasMoreElements
+      block.call(e.nextElement)
+    end
+  end
+end

data/lib/jms/session.rb

@@ -0,0 +1,473 @@
+################################################################################
+#  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.
+################################################################################
+
+# For each thread that will be processing messages concurrently a separate
+# session is required. All sessions can share a single connection to the same
+# JMS Provider.
+#
+# Interface javax.jms.Session
+#
+# See: http://download.oracle.com/javaee/6/api/javax/jms/Session.html
+#
+# Other methods still directly accessible through this class:
+#
+# create_browser(queue, message_selector)
+#   Creates a QueueBrowser object to peek at the messages on the specified queue using a message selector.
+#
+# create_bytes_message()
+#   Creates a BytesMessage object
+#
+# create_consumer(destination)
+#   Creates a MessageConsumer for the specified destination
+#   See: Connection::consumer
+#
+#   Example:
+#      destination = session.create_destination(:queue_name => "MyQueue")
+#      session.create_consumer(destination)
+#
+#	create_consumer(destination, message_selector)
+#   Creates a MessageConsumer for the specified destination, using a message selector
+#
+#	create_consumer(destination, message_selector, boolean NoLocal)
+#   Creates MessageConsumer for the specified destination, using a message selector
+#
+# create_durable_subscriber(Topic topic, java.lang.String name)
+#   Creates a durable subscriber to the specified topic
+#
+# create_durable_subscriber(Topic topic, java.lang.String name, java.lang.String messageSelector, boolean noLocal)
+#   Creates a durable subscriber to the specified topic, using a message selector and specifying whether messages published by its own connection should be delivered to it.
+#
+#	create_map_Message()
+#   Creates a MapMessage object
+#
+#	create_message()
+#   Creates a Message object
+#
+# create_object_message()
+#   Creates an ObjectMessage object
+#
+# create_object_message(java.io.Serializable object)
+#   Creates an initialized ObjectMessage object
+#
+#	create_producer(destination)
+#   Creates a MessageProducer to send messages to the specified destination
+#
+# create_queue(queue_name)
+#   Creates a queue identity given a Queue name
+#
+# create_stream_message()
+#   Creates a StreamMessage object
+#
+#	create_temporary_queue()
+#   Creates a TemporaryQueue object
+#
+#	create_temporary_topic()
+#   Creates a TemporaryTopic object
+#
+#	create_text_message()
+#   Creates a TextMessage object
+#
+#	create_text_message(text)
+#   Creates an initialized TextMessage object
+#
+# create_topic(topic_name)
+#   Creates a topic identity given a Topic name
+#
+# acknowledge_mode()
+#   Returns the acknowledgement mode of the session
+#
+#	message_listener()
+#   Returns the session's distinguished message listener (optional).
+#
+# transacted?
+#   Indicates whether the session is in transacted mode
+#
+# recover()
+#   Stops message delivery in this session, and restarts message delivery with the oldest unacknowledged message
+#
+# rollback()
+#   Rolls back any messages done in this transaction and releases any locks currently held
+#
+# message_listener=(MessageListener listener)
+#   Sets the session's distinguished message listener (optional)
+#
+# unsubscribe(name)
+#   Unsubscribes a durable subscription that has been created by a client
+#
+# Interface javax.jms.Session
+module JMS::Session
+  # Create a new message instance based on the type of the data being supplied
+  #   String (:to_str)    => TextMessage
+  #   Hash   (:each_pair) => MapMessage
+  # Duck typing is used to determine the type. If the class responds
+  # to :to_str then it is considered a String. Similarly if it responds to
+  # :each_pair it is considered to be a Hash
+  #
+  # If automated duck typing is not desired, the type of the message can be specified
+  # by setting the parameter 'type' to any one of:
+  #    :text   => Creates a Text Message
+  #    :map    => Creates a Map Message
+  #    :bytes  => Creates a Bytes Message
+  def message(data, type=nil)
+    jms_message = nil
+    type ||= if data.respond_to?(:to_str, false)
+      :text
+    elsif data.respond_to?(:each_pair, false)
+      :map
+    else
+      raise "Unknown data type #{data.class.to_s} in Message"
+    end
+
+    case type
+    when :text
+      jms_message = self.createTextMessage
+      jms_message.text = data.to_str
+    when :map
+      jms_message = self.createMapMessage
+      jms_message.data = data
+    when :bytes
+      jms_message = self.createBytesMessage
+      jms_message.write_bytes(data.to_java_bytes)
+    else
+      raise "Invalid type #{type} requested"
+    end
+    jms_message
+  end
+
+  # Create the destination based on the parameter supplied
+  #
+  # The idea behind this method is to allow the decision as to whether
+  # one is sending to a topic or destination to be transparent to the code.
+  # The supplied parameters can be externalized into say a YAML file
+  # so that today it writes to a queue, later it can be changed to write
+  # to a topic so that multiple parties can receive the same messages.
+  #
+  # Note: For Temporary Queues and Topics, remember to delete them when done
+  #       or just use ::destination instead with a block and it will take care
+  #       of deleting them for you
+  #
+  # To create a queue:
+  #   session.create_destination(:queue_name => 'name of queue')
+  #
+  # To create a temporary queue:
+  #   session.create_destination(:queue_name => :temporary)
+  #
+  # To create a queue:
+  #   session.create_destination('queue://queue_name')
+  #
+  # To create a topic:
+  #   session.create_destination(:topic_name => 'name of queue')
+  #
+  # To create a temporary topic:
+  #   session.create_destination(:topic_name => :temporary)
+  #
+  # To create a topic:
+  #   session.create_destination('topic://topic_name')
+  #
+  # Create the destination based on the parameter supplied
+  #
+  # Parameters:
+  #   :queue_name => String: Name of the Queue to return
+  #                  Symbol: :temporary => Create temporary queue
+  #                  Mandatory unless :topic_name is supplied
+  #     Or,
+  #   :topic_name => String: Name of the Topic to write to or subscribe to
+  #                  Symbol: :temporary => Create temporary topic
+  #                  Mandatory unless :queue_name is supplied
+  #     Or,
+  #   :destination=> Explicit javaxJms::Destination to use
+  #
+  # Returns the result of the supplied block
+  def create_destination(params)
+    # Allow a Java JMS destination object to be passed in
+    return params[:destination] if params[:destination] && params[:destination].java_kind_of?(JMS::Destination)
+
+    queue_name = nil
+    topic_name = nil
+
+    if params.is_a? String
+      queue_name = params['queue://'.length..-1] if params.start_with?('queue://')
+      topic_name = params['topic://'.length..-1] if params.start_with?('topic://')
+    else
+      # :q_name is deprecated
+      queue_name = params[:queue_name] || params[:q_name]
+      topic_name = params[:topic_name]
+    end
+
+    raise "Missing mandatory parameter :queue_name or :topic_name to Session::producer, Session::consumer, or Session::browser" unless queue_name || topic_name
+
+    if queue_name
+      queue_name == :temporary ? create_temporary_queue : create_queue(queue_name)
+    else
+      topic_name == :temporary ? create_temporary_topic : create_topic(topic_name)
+    end
+  end
+
+  # Create a queue or topic to send or receive messages from
+  #
+  # A block must be supplied so that if it is a temporary topic or queue
+  # it will be deleted after the proc is complete
+  #
+  # To create a queue:
+  #   session.destination(:queue_name => 'name of queue')
+  #
+  # To create a temporary queue:
+  #   session.destination(:queue_name => :temporary)
+  #
+  # To create a topic:
+  #   session.destination(:topic_name => 'name of queue')
+  #
+  # To create a temporary topic:
+  #   session.destination(:topic_name => :temporary)
+  #
+  # Create the destination based on the parameter supplied
+  #
+  # Parameters:
+  #   :queue_name => String: Name of the Queue to return
+  #                  Symbol: :temporary => Create temporary queue
+  #                  Mandatory unless :topic_name is supplied
+  #     Or,
+  #   :topic_name => String: Name of the Topic to write to or subscribe to
+  #                  Symbol: :temporary => Create temporary topic
+  #                  Mandatory unless :queue_name is supplied
+  #     Or,
+  #   :destination=> Explicit javaxJms::Destination to use
+  #
+  # Returns the result of the supplied block
+  def destination(params={}, &block)
+    raise "Missing mandatory Block when calling JMS::Session#destination" unless block
+    dest = nil
+    begin
+      dest = create_destination(params)
+      block.call(dest)
+    ensure
+      # Delete Temporary Queue / Topic
+      dest.delete if dest && dest.respond_to?(:delete)
+    end
+  end
+
+  # Return the queue matching the queue name supplied
+  # Call the Proc if supplied
+  def queue(queue_name, &block)
+    q = create_queue(queue_name)
+    block.call(q) if block
+    q
+  end
+
+  # Return a temporary queue
+  # The temporary queue is deleted once the block completes
+  # If no block is supplied then it should be deleted by the caller
+  # when no longer needed
+  def temporary_queue(&block)
+    q = create_temporary_queue
+    if block
+      begin
+        block.call(q)
+      ensure
+        # Delete Temporary queue on completion of block
+        q.delete if q
+        q = nil
+      end
+    end
+    q
+  end
+
+  # Return the topic matching the topic name supplied
+  # Call the Proc if supplied
+  def topic(topic_name, &proc)
+    t = create_topic(topic_name)
+    proc.call(t) if proc
+    t
+  end
+
+  # Return a temporary topic
+  # The temporary topic is deleted once the block completes
+  # If no block is supplied then it should be deleted by the caller
+  # when no longer needed
+  def temporary_topic(&block)
+    t = create_temporary_topic
+    if block
+      begin
+        block.call(t)
+      ensure
+        # Delete Temporary topic on completion of block
+        t.delete if t
+        t = nil
+      end
+    end
+    t
+  end
+
+  # Return a producer for the queue name supplied
+  # A producer supports sending messages to a Queue or a Topic
+  #
+  # Call the Proc if supplied, then automatically close the producer
+  #
+  # Parameters:
+  #   :queue_name     => String: Name of the Queue to return
+  #                  Symbol: :temporary => Create temporary queue
+  #                  Mandatory unless :topic_name is supplied
+  #     Or,
+  #   :topic_name => String: Name of the Topic to write to or subscribe to
+  #                  Symbol: :temporary => Create temporary topic
+  #                  Mandatory unless :queue_name is supplied
+  #     Or,
+  #   :destination=> Explicit JMS::Destination to use
+  def producer(params, &proc)
+    p = self.create_producer(self.create_destination(params))
+    if proc
+      begin
+        proc.call(p)
+      ensure
+        p.close
+        p = nil
+      end
+    end
+    p
+  end
+
+  # Return a consumer for the destination
+  # A consumer can read messages from the queue or topic
+  #
+  # Call the Proc if supplied, then automatically close the consumer
+  #
+  # Parameters:
+  #   :queue_name => String: Name of the Queue to return
+  #                  Symbol: :temporary => Create temporary queue
+  #                  Mandatory unless :topic_name is supplied
+  #     Or,
+  #   :topic_name => String: Name of the Topic to write to or subscribe to
+  #                  Symbol: :temporary => Create temporary topic
+  #                  Mandatory unless :queue_name is supplied
+  #     Or,
+  #   :destination=> Explicit javaxJms::Destination to use
+  #
+  #   :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
+  #                  Default: false
+  def consumer(params, &proc)
+    destination = create_destination(params)
+    c = nil
+    if params[:no_local]
+      c = create_consumer(destination, params[:selector] || '', params[:no_local])
+    elsif params[:selector]
+      c = create_consumer(destination, params[:selector])
+    else
+      c = create_consumer(destination)
+    end
+
+    if proc
+      begin
+        proc.call(c)
+      ensure
+        c.close
+        c = nil
+      end
+    end
+    c
+  end
+
+  # Consume all messages for the destination
+  # A consumer can read messages from the queue or topic
+  #
+  # Parameters:
+  #   :queue_name     => String: Name of the Queue to return
+  #                  Symbol: :temporary => Create temporary queue
+  #                  Mandatory unless :topic_name is supplied
+  #     Or,
+  #   :topic_name => String: Name of the Topic to write to or subscribe to
+  #                  Symbol: :temporary => Create temporary topic
+  #                  Mandatory unless :queue_name is supplied
+  #     Or,
+  #   :destination=> Explicit javaxJms::Destination to use
+  #
+  #   :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
+  #                  Default: false
+  #
+  #   :timeout Follows the rules for MQSeries:
+  #     -1 : Wait forever
+  #      0 : Return immediately if no message is available
+  #      x : Wait for x milli-seconds for a message to be received from the broker
+  #           Note: Messages may still be on the queue, but the broker has not supplied any messages
+  #                     in the time interval specified
+  #      Default: 0
+  #
+  def consume(params, &proc)
+    c = self.consumer(params)
+    begin
+      c.each(params, &proc)
+    ensure
+      c.close
+    end
+  end
+
+  # Return a browser for the destination
+  # A browser can read messages non-destructively from the queue
+  # It cannot browse Topics!
+  #
+  # Call the Proc if supplied, then automatically close the consumer
+  #
+  # Parameters:
+  #   :queue_name     => String: Name of the Queue to return
+  #                  Symbol: :temporary => Create temporary queue
+  #                  Mandatory unless :topic_name is supplied
+  #     Or,
+  #   :destination=> Explicit javaxJms::Destination to use
+  #
+  #   :selector   => Filter which messages should be returned from the queue
+  #                  Default: All messages
+  def browser(params, &proc)
+    raise "Session::browser requires a code block to be executed" unless proc
+
+    destination = create_destination(params)
+    b = nil
+    if params[:selector]
+      b = create_browser(destination, params[:selector])
+    else
+      b = create_browser(destination)
+    end
+
+    if proc
+      begin
+        proc.call(b)
+      ensure
+        b.close
+        b = nil
+      end
+    end
+    b
+  end
+
+  # Browse the specified queue, calling the Proc supplied for each message found
+  #
+  # Parameters:
+  #   :queue_name     => String: Name of the Queue to return
+  #                  Symbol: :temporary => Create temporary queue
+  #                  Mandatory unless :topic_name is supplied
+  #     Or,
+  #   :destination=> Explicit javaxJms::Destination to use
+  #
+  #   :selector   => Filter which messages should be returned from the queue
+  #                  Default: All messages
+  def browse(params={}, &proc)
+    self.browser(params) {|b| b.each(params, &proc)}
+  end
+end