jruby-jms 0.9.0 → 0.10.0

data/README.md

@@ -5,11 +5,6 @@ jruby-jms
 
 ### Current Activities & Backward Compatibility
 
-Currently reviewing Logging which uses Apache Commons logging by default.
-For now add the following Apache Commons and log4j libraries to your classpath
-* commons-logging-1.1.1.jar
-* log4j-1.2.16.jar
-
 Please read the source files for now for documentation. Looking into rdoc doc
 generation issue.
 
@@ -18,13 +13,12 @@ There may still be some changes to the API to make things better and/or simpler.
 Once the code goes to V1.0.0 I will make every effort to not break the 
 existing interface in any way.
 
-Feedback is welcome and appreciated :)
-* Need input on Logging and any other tips and tricks on extending Interfaces
-** For example, currently cannot override Interface methods with JRuby versions
-   (See Session::create_session, which is Session::session at this time)
-* Looking for ideas on the best way to specify jar files so that they can be
-  'required' by jruby-jms rather than having to use the classpath
-* Need to get rdoc working for 
+### Feedback is welcome and appreciated :)
+
+### Todo
+
+* Need to get rdoc working
+* More tests, especially pub/sub
 
 ### Introduction
 
@@ -47,7 +41,7 @@ API is available to you at any time.
 
 ### Install
 
-  gem install jruby-jms
+    gem install jruby-jms
 
 ### Simplification
 
@@ -106,58 +100,46 @@ topic they are interested in
 Producers write message to a queue or topic
 
 ActiveMQ Example:
-  require 'rubygems'
-
-  # Include Active MQ Jar files (Not required if already in classpath)
-  require '~/Applications/apache-activemq-5.4.2/activemq-all-5.4.2.jar'
-
-  # Include Apache Commons Logging Jar file (For now, if not already in classpath)
-  require '~/Applications/apache-activemq-5.4.2/lib/commons-logging-1.1.jar'
-  require '~/Applications/apache-activemq-5.4.2/lib/optional/log4j-1.2.14.jar'
-
-  # Include JMS after ActiveMQ
-  require 'jms'
-
-  # Connect to ActiveMQ
-  config = {
-    :factory => 'org.apache.activemq.ActiveMQConnectionFactory',
-    :broker_url => 'tcp://localhost:61616'
-  }
-
-  JMS::Connection.session(config) do |session|
-    session.producer(:q_name => 'ExampleQueue') do |producer|
-      producer.send(session.message("Hello World"))
+    require 'rubygems'
+    
+    # Include JMS after ActiveMQ
+    require 'jms'
+    
+    # Connect to ActiveMQ
+    config = {
+      :factory => 'org.apache.activemq.ActiveMQConnectionFactory',
+      :broker_url => 'tcp://localhost:61616',
+      :require_jars => ["~/Applications/apache-activemq-5.4.2/activemq-all-5.4.2.jar"]
+    }
+
+    JMS::Connection.session(config) do |session|
+      session.producer(:q_name => 'ExampleQueue') do |producer|
+        producer.send(session.message("Hello World"))
+      end
     end
-  end
 
 ### Consumer
 
 Consumers read message from a queue or topic
 
-Example:
-  require 'rubygems'
-
-  # Include Active MQ Jar files (Not required if already in classpath)
-  require '~/Applications/apache-activemq-5.4.2/activemq-all-5.4.2.jar'
-
-  # Include Apache Commons Logging Jar file (For now, if not already in classpath)
-  require '~/Applications/apache-activemq-5.4.2/lib/commons-logging-1.1.jar'
-  require '~/Applications/apache-activemq-5.4.2/lib/optional/log4j-1.2.14.jar'
-
-  # Include JMS after ActiveMQ
-  require 'jms'
-
-  # Connect to ActiveMQ
-  config = {
-    :factory => 'org.apache.activemq.ActiveMQConnectionFactory',
-    :broker_url => 'tcp://localhost:61616'
-  }
-
-  JMS::Connection.session(config) do |session|
-    session.consume(:q_name => 'ExampleQueue', :timeout=>1000) do |message|
-      p message
+ActiveMQ Example:
+    require 'rubygems'
+    
+    # Include JMS after ActiveMQ
+    require 'jms'
+    
+    # Connect to ActiveMQ
+    config = {
+      :factory => 'org.apache.activemq.ActiveMQConnectionFactory',
+      :broker_url => 'tcp://localhost:61616',
+      :require_jars => ["~/Applications/apache-activemq-5.4.2/activemq-all-5.4.2.jar"]
+    }
+    
+    JMS::Connection.session(config) do |session|
+      session.consume(:q_name => 'ExampleQueue', :timeout=>1000) do |message|
+        p message
+      end
     end
-  end
 
 Overview
 --------
@@ -185,15 +167,16 @@ queue or topic match will be passed to the block.
 Logging
 -------
 
-jruby-jms currently uses Apache Commons logging, but this is subject to changes
-since many users of jruby-jms will want to use the Rails logger
+jruby-jms detects the logging available in the current environment.
+When running under Rails it will use the Rails logger, otherwise the standard
+Ruby logger. The logger can also be replaced by calling Connection.logger=
 
 Dependencies
 ------------
 
 ### JRuby
 
-jruby-jms has been tested against JRuby 1.5.1, but should work with any
+jruby-jms has been tested against JRuby 1.5.1 and 1.6, but should work with any
 current JRuby version.
 
 ### JMS
@@ -221,7 +204,7 @@ Contributing
 
 Once you've made your great commits:
 
-1. [Fork][1] Resque
+1. [Fork][1] jruby-jms
 2. Create a topic branch - `git checkout -b my_branch`
 3. Push to your branch - `git push origin my_branch`
 4. Create an [Issue][2] with a link to your branch
@@ -261,7 +244,7 @@ Reid Morrison :: rubywmq@gmail.com :: @reidmorrison
 License
 -------
 
-Copyright 2008, 2009, 2010, 2011  J. Reid Morrison
+Copyright 2008 - 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.

data/Rakefile

@@ -1,6 +1,7 @@
 raise "jruby-jms must be built with JRuby: try again with `jruby -S rake'" unless defined?(JRUBY_VERSION)
 
 require 'rake/clean'
+require 'rake/testtask'
 require 'date'
 require 'java'
 
@@ -8,7 +9,7 @@ desc "Build gem"
 task :gem  do |t|
   gemspec = Gem::Specification.new do |s|
     s.name = 'jruby-jms'
-    s.version = '0.9.0'
+    s.version = '0.10.0'
     s.author = 'Reid Morrison'
     s.email = 'rubywmq@gmail.com'
     s.homepage = 'https://github.com/reidmorrison/jruby-jms'
@@ -20,3 +21,13 @@ task :gem  do |t|
   end
   Gem::Builder.new(gemspec).build
 end
+
+task :test do
+
+  Rake::TestTask.new(:functional) do |t|
+    t.test_files = FileList['test/*_test.rb']
+    t.verbose    = true
+  end
+
+  Rake::Task['functional'].invoke
+end

data/examples/jms.yml

@@ -9,7 +9,9 @@
 activemq:
   :factory: org.apache.activemq.ActiveMQConnectionFactory
   :broker_url: tcp://localhost:61616
-    
+  :require_jars:
+    - ~/Applications/apache-activemq-5.4.2/activemq-all-5.4.2.jar
+
 hornetq:
   # Connect to a local HornetQ Broker using JNDI
   :jndi_name: /ConnectionFactory
@@ -19,4 +21,10 @@ hornetq:
     java.naming.factory.url.pkgs: org.jboss.naming:org.jnp.interfaces
     java.naming.security.principal: guest
     java.naming.security.credentials: guest
-      
+  :require_jars:
+    - ~/Applications/hornetq-2.1.2.Final/lib/hornetq-core-client.jar
+    - ~/Applications/hornetq-2.1.2.Final/lib/hornetq-core.jar
+    - ~/Applications/hornetq-2.1.2.Final/lib/hornetq-jms-client.jar
+    - ~/Applications/hornetq-2.1.2.Final/lib/jboss-jms-api.jar
+    - ~/Applications/hornetq-2.1.2.Final/lib/jnp-client.jar
+    - ~/Applications/hornetq-2.1.2.Final/lib/netty.jar

data/lib/jms.rb

@@ -15,11 +15,5 @@
 ################################################################################
 
 require 'java'
+require 'jms/logging'
 require 'jms/connection'
-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'

data/lib/jms/connection.rb

@@ -52,13 +52,12 @@ module JMS
   # The above code creates a Connection and then a Session. Once the block completes
   # the session is closed and the Connection disconnected.
   #
-  # TODO: Multithreaded example:
+  # See: http://download.oracle.com/javaee/6/api/javax/jms/Connection.html
   #
-
   class Connection
     # Create a connection to the JMS provider, start the connection,
     # call the supplied code block, then close the connection upon completion
-    # 
+    #
     # Returns the result of the supplied block
     def self.start(parms = {}, &proc)
       raise "Missing mandatory Block when calling JMS::Connection.start" unless proc
@@ -70,35 +69,57 @@ module JMS
         connection.close
       end
     end
-    
+
     # Connect to a JMS Broker, create a session and 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
     def self.session(parms = {}, &proc)
       self.start(parms) do |connection|
         connection.session(parms, &proc)
       end
     end
-    
-    # Replace the default logger
-    # 
-    # The supplied logger must respond to the following methods
-    # TODO Add required methods list  ...
-    def self.log=(logger)
-      @@log = logger
-    end
-    
-    # Class level logger
-    def self.log
-      @@log ||= org.apache.commons.logging.LogFactory.getLog('JMS.Connection')
+
+    # Load the required jar files for this JMS Provider and
+    # load JRuby extensions for those classes
+    #
+    # Rather than copying the JMS jar files into the JRuby lib, load them
+    # on demand. JRuby JMS extensions are only loaded once the jar files have been
+    # loaded.
+    #
+    # Can be called multiple times if required, although it would not be performant
+    # to do so regularly.
+    #
+    # Parameter: jar_list is an Array of the path and filenames to jar files
+    #                     to load for this JMS Provider
+    #
+    # Returns nil
+    #
+    # TODO make this a class method
+    def fetch_dependencies(jar_list)
+      jar_list.each do |jar|
+        JMS::logger.info "Loading Jar File:#{jar}"
+        begin
+          require jar
+        rescue Exception => exc
+          JMS::logger.error "Failed to Load Jar File:#{jar}. #{exc.to_s}"
+        end
+      end
+      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'
     end
 
     # Create a connection to the JMS provider
-    # 
+    #
     # Note: Connection::start must be called before any consumers will be
     #       able to receive messages
     #
@@ -166,7 +187,7 @@ module JMS
     #   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
@@ -200,6 +221,10 @@ module JMS
       @sessions = []
       @consumers = []
 
+      # 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]) if params[:require_jars]
+
       connection_factory = nil
       factory = params[:factory]
       if factory
@@ -218,12 +243,12 @@ module JMS
         raise "Missing mandatory parameter :factory or :jndi_name missing in call to Connection::connect"
       end
 
-      Connection.log.debug "Using Factory: #{connection_factory.java_class}" if connection_factory.respond_to? :java_class
+      JMS::logger.debug "Using Factory: #{connection_factory.java_class}" if connection_factory.respond_to? :java_class
       params.each_pair do |key, val|
         method = key.to_s+'='
         if connection_factory.respond_to? method
           connection_factory.send method, val
-          Connection.log.debug "   #{key} = #{connection_factory.send key}" if connection_factory.respond_to? key.to_sym
+          JMS::logger.debug "   #{key} = #{connection_factory.send key}" if connection_factory.respond_to? key.to_sym
         end
       end
       if params[:username]
@@ -233,18 +258,18 @@ module JMS
       end
     end
 
-    # Start delivery of messages over this connection.
+    # Start (or restart) delivery of incoming messages over this connection.
     # By default no messages are delivered until this method is called explicitly
     # Delivery of messages to any asynchronous Destination::each() call will only
-    # start after Connection::start is called
-    #    Corresponds to JMS start call
+    # start after Connection::start is called, or Connection.start is used
     def start
       @jms_connection.start
     end
-
-    # Stop delivery of messages to any asynchronous Destination::each() calls
+      
+    # 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
+    # Call start() to resume receiving messages
     def stop
       @jms_connection.stop
     end
@@ -274,7 +299,7 @@ module JMS
 
     # Create a session over this connection.
     # It is recommended to create separate sessions for each thread
-    # 
+    #
     # Note: Remember to call close on the returned session when it is no longer
     #       needed. Rather use JMS::Connection#session with a block whenever
     #       possible
@@ -284,10 +309,26 @@ 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 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
+    #        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
+    #        With this acknowledgment mode, the client acknowledges a consumed
+    #        message by calling the message's acknowledge method.
+    #     javax.jms.Session::DUPS_OK_ACKNOWLEDGE
+    #        This acknowledgment mode instructs the session to lazily acknowledge
+    #        the delivery of messages.
+    #     javax.jms.Session::SESSION_TRANSACTED
+    #        This value is returned from the method getAcknowledgeMode if the
+    #        session is transacted.
+    #     Default: javax.jms.Session::AUTO_ACKNOWLEDGE
     #
-    def create_session(parms={}, &proc)
+    def create_session(parms={})
       transacted = parms[:transacted] || false
       options = parms[:options] || javax.jms.Session::AUTO_ACKNOWLEDGE
       @jms_connection.create_session(transacted, options)
@@ -304,13 +345,61 @@ 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
+    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)
+    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, 
+    # see: http://download.oracle.com/javaee/6/api/javax/jms/JMSException.html
+    # 
+    # Example:
+    #   connection.on_message do |jms_exception|
+    #     puts "JMS Exception has occurred: #{jms_exception}"
+    #   end
+    #
+    # Returns: nil
+    def on_exception(&block)
+      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
-    #      "Connected to " + metaData.getJMSProviderName() +
-    #        " version " + metaData.getProviderVersion() + " (" +
-    #        metaData.getProviderMajorVersion() + "." + metaData.getProviderMinorVersion() +
-    #        ")";
     #    end
 
     # Receive messages in a separate thread when they arrive
@@ -351,7 +440,7 @@ module JMS
     #   :no_local   => Determine whether messages published by its own connection
     #                  should be delivered to it
     #                  Default: false
-    #                  
+    #
     #   :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.
@@ -369,6 +458,9 @@ module JMS
     #          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
+    #
+    #
     def on_message(parms, &proc)
       raise "JMS::Connection must be connected prior to calling JMS::Connection::on_message" unless @sessions && @consumers
 
@@ -399,68 +491,6 @@ module JMS
 
   end
 
-  # For internal use only
-  private
-  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
-      @log = org.apache.commons.logging.LogFactory.getLog('JMS.MessageListener')
-
-      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
-        @log.error "Unhandled Exception processing JMS Message. Doesn't compile: " + boom
-        @log.error "Ignoring poison message:\n#{message.inspect}"
-        @log.error boom.backtrace.join("\n")
-      rescue StandardError => bang
-        @log.error "Unhandled Exception processing JMS Message. Doesn't compile: " + bang
-        @log.error "Ignoring poison message:\n#{message.inspect}"
-        @log.error boom.backtrace.join("\n")
-      rescue => exc
-        @log.error "Unhandled Exception processing JMS Message. Exception occurred:\n#{exc}"
-        @log.error "Ignoring poison message:\n#{message.inspect}"
-        @log.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
-
   # Wrapper to support Oracle AQ
   class OracleAQConnectionFactory
     attr_accessor :username, :url