jruby-jms 0.9.0 → 0.10.0

data/lib/jms/javax_jms_session.rb

@@ -19,11 +19,99 @@
 # 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
+#
 module javax.jms::Session
   # Create a new message instance based on the type of the data being supplied
   #   String (:to_str)    => TextMessage
   #   Hash   (:each_pair) => MapMessage
-  # In fact duck typing is used to determine the type. If the class responds
+  # 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
   def message(data)
@@ -40,42 +128,153 @@ module javax.jms::Session
     jms_message
   end
 
-  # Does the session support transactions?
-  # I.e. Can/should commit and rollback be called
-  def transacted?
-    self.getAcknowledgeMode == javax.jms.Session::SESSION_TRANSACTED
+  # 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 topic:
+  #   session.create_destination(:topic_name => 'name of queue')
+  #
+  # To create a temporary topic:
+  #   session.create_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 :q_name is supplied
+  #     Or,
+  #   :destination=> Explicit javaxJms::Destination to use
+  #
+  # Returns the result of the supplied block
+  def create_destination(parms)
+    # Allow a Java JMS destination object to be passed in 
+    return parms[:destination] if parms[:destination] && parms[:destination].java_kind_of?(javax.jms::Destination)
+    
+    # :q_name is deprecated
+    queue_name = parms[:queue_name] || parms[:q_name]
+    topic_name = parms[:topic_name]
+    raise "Missing mandatory parameter :q_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 :q_name is supplied
+  #     Or,
+  #   :destination=> Explicit javaxJms::Destination to use
+  #
+  # Returns the result of the supplied block
+  def destination(parms={}, &block)
+    raise "Missing mandatory Block when calling JMS::Session#destination" unless block
+    dest = nil
+    begin
+      dest = create_destination(parms)
+      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
 
-  # Create and open a queue to put or get from. Once the supplied Proc is complete
-  # the queue is automatically closed. If no Proc is supplied then the queue must
-  # be explicitly closed by the caller.
-  def destination(parms={}, &proc)
-    parms[:jms_session] = self
-    q = JMS::Destination.new(parms)
-    q.open(parms)
-    if proc
+  # 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
-        proc.call(q)
+        block.call(q)
       ensure
-        q.close
+        # Delete Temporary queue on completion of block
+        q.delete if q
         q = nil
       end
     end
     q
   end
 
-  # Return the queue matching the queue name supplied
+  # Return the topic matching the topic name supplied
   # Call the Proc if supplied
-  def queue(q_name, &proc)
-    q = create_queue(q_name)
-    if proc
+  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
-        proc.call(q)
+        block.call(t)
       ensure
-        q = nil
+        # Delete Temporary topic on completion of block
+        t.delete if t
+        t = nil
       end
     end
-    q
+    t
   end
 
   # Return a producer for the queue name supplied
@@ -240,32 +439,6 @@ module javax.jms::Session
   def browse(parms={}, &proc)
     self.browser(parms) {|b| b.each(parms, &proc)}
   end
-
-  private
-  # Create the destination based on the parameter supplied
-  #
-  # Parameters:
-  #   :q_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 :q_name is supplied
-  #     Or,
-  #   :destination=> Explicit javaxJms::Destination to use
-  def create_destination(parms)
-    return parms[:destination] if parms[:destination] && parms[:destination].kind_of?(javaxJms::Destination)
-    q_name = parms[:q_name]
-    topic_name = parms[:topic_name]
-    raise "Missing mandatory parameter :q_name or :topic_name to Session::producer, Session::consumer, or Session::browser" unless q_name || topic_name
-
-    if q_name
-      q_name == :temporary ? create_temporary_queue : create_queue(q_name)
-    else
-      topic_name == :temporary ? create_temporary_topic : create_topic(topic_name)
-    end
-  end
 end
 
 # Workaround for IBM MQ JMS implementation that implements an undocumented consume method

data/lib/jms/logger.rb

@@ -0,0 +1,4 @@
+# Add trace method to Ruby Logger class
+class Logger
+  alias :trace :debug
+end

data/lib/jms/logging.rb

@@ -0,0 +1,29 @@
+# Add HornetQ logging capabilities
+module JMS
+  
+  # Returns the logger being used by jruby-jms
+  def self.logger
+    @logger ||= (rails_logger || default_logger)
+  end
+
+  # Replace the logger for jruby-jms
+  def self.logger=(logger)
+    @logger = logger
+  end
+
+  private
+  def self.rails_logger
+    (defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger) ||
+      (defined?(RAILS_DEFAULT_LOGGER) && RAILS_DEFAULT_LOGGER.respond_to?(:debug) && RAILS_DEFAULT_LOGGER)
+  end
+
+  # By default we use the standard Ruby Logger
+  def self.default_logger
+    require 'logger'
+    require 'jms/logger'
+    l = Logger.new(STDOUT)
+    l.level = Logger::INFO
+    l
+  end
+
+end

data/lib/jms/message_listener.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 MessageListener
+    include javax.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(parms={}, &proc)
+      @proc = proc
+
+      if parms[: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 boom.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/test/connection_test.rb

@@ -0,0 +1,155 @@
+# Allow examples to be run in-place without requiring a gem install
+$LOAD_PATH.unshift File.dirname(__FILE__) + '/../lib'
+
+require 'rubygems'
+require 'test/unit'
+require 'shoulda'
+require 'jms'
+require 'yaml'
+
+class JMSTest < Test::Unit::TestCase
+  context 'JMS Connection' do
+    # Load configuration from jms.yml
+    setup do
+      # To change the JMS provider, edit jms.yml and change :default
+      
+      # Load Connection parameters from configuration file
+      cfg = YAML.load_file(File.join(File.dirname(__FILE__), 'jms.yml'))
+      jms_provider = cfg['default']
+      @config = cfg[jms_provider]
+      raise "JMS Provider option:#{jms_provider} not found in jms.yml file" unless @config
+    end
+
+    should 'Create Connection to the Broker/Server' do
+      connection = JMS::Connection.new(@config)
+      JMS::logger.info connection.to_s
+      assert_not_nil connection
+      connection.close
+    end
+
+    should 'Create and start Connection to the Broker/Server with block' do
+      JMS::Connection.start(@config) do |connection|
+        assert_not_nil connection
+      end
+    end
+   
+    should 'Create and start Connection to the Broker/Server with block and start one session' do
+      JMS::Connection.session(@config) do |session|
+        assert_not_nil session
+      end
+    end
+    
+    should 'Start and stop connection' do
+      connection = JMS::Connection.new(@config)
+      assert_not_nil connection
+      assert_nil connection.start
+      
+      assert_nil connection.stop
+      assert_nil connection.close
+    end
+
+    should 'Create a session from the connection' do
+      connection = JMS::Connection.new(@config)
+      
+      session_parms = { 
+        :transacted => true,
+        :options => javax.jms.Session::AUTO_ACKNOWLEDGE
+      }
+
+      session = connection.create_session
+      assert_not_nil session
+      assert_equal session.transacted?, false
+      assert_nil session.close
+      
+      assert_nil connection.stop
+      assert_nil connection.close
+    end
+
+    should 'Create a session with a block' do
+      connection = JMS::Connection.new(@config)
+      
+      connection.session do |session|
+        assert_not_nil session
+        assert_equal session.transacted?, false
+      end
+      
+      assert_nil connection.stop
+      assert_nil connection.close
+    end
+
+    should 'create a session without a block and throw exception' do
+      connection = JMS::Connection.new(@config)
+      
+      assert_raise(RuntimeError) { connection.session }
+      
+      assert_nil connection.stop
+      assert_nil connection.close
+    end
+
+    should 'Create a session from the connection with parms' do
+      connection = JMS::Connection.new(@config)
+      
+      session_parms = { 
+        :transacted => true,
+        :options => javax.jms.Session::AUTO_ACKNOWLEDGE
+      }
+
+      session = connection.create_session(session_parms)
+      assert_not_nil session
+      assert_equal session.transacted?, true
+      # When session is transacted, options are ignore, so ack mode must be transacted
+      assert_equal session.acknowledge_mode, javax.jms.Session::SESSION_TRANSACTED
+      assert_nil session.close
+      
+      assert_nil connection.stop
+      assert_nil connection.close
+    end
+
+    should 'Create a session from the connection with block and parms' do
+      JMS::Connection.start(@config) do |connection|
+      
+        session_parms = { 
+          :transacted => true,
+          :options => javax.jms.Session::CLIENT_ACKNOWLEDGE
+        }
+
+        connection.session(session_parms) do |session|
+          assert_not_nil session
+          assert_equal session.transacted?, true
+          # When session is transacted, options are ignore, so ack mode must be transacted
+          assert_equal session.acknowledge_mode, javax.jms.Session::SESSION_TRANSACTED
+        end
+      end
+    end
+
+    should 'Create a session from the connection with block and parms opposite test' do
+      JMS::Connection.start(@config) do |connection|
+      
+        session_parms = { 
+          :transacted => false,
+          :options => javax.jms.Session::AUTO_ACKNOWLEDGE
+        }
+
+        connection.session(session_parms) do |session|
+          assert_not_nil session
+          assert_equal session.transacted?, false
+          assert_equal session.acknowledge_mode, javax.jms.Session::AUTO_ACKNOWLEDGE
+        end
+      end
+    end
+  
+    context 'JMS Connection additional capabilities' do
+    
+      should 'start an on_message handler' do
+        JMS::Connection.start(@config) do |connection|
+          value = nil
+          connection.on_message(:transacted => true, :q_name => :temporary) do |message|
+            value = "received"
+          end
+        end
+      end
+      
+    end
+    
+  end
+end