jmx4r 0.0.6 → 0.0.7

data/README.rdoc

@@ -0,0 +1,41 @@
+jmx4r[http://github.com/jmesnil/jmx4r/] is a JMX library for JRuby.
+
+It can be used to write simple Ruby scripts running on JRuby[http://jruby.org]
+to manage remote Java applications (e.g. JBoss[http://www.jboss.org],
+Tomcat[http://tomcat.apache.org/]) using 
+JMX[http://java.sun.com/javase/technologies/core/mntr-mgmt/javamanagement/].
+
+jmx4r helps to manage Java applications using JMX in a simple and powerful way:
+* no need to depend on the Java interfaces of the MBean in your management code. This means <em>less deployment issues</em>
+* Thanks to Ruby metaprogramming toolset, you can <em>treat your MBeans as simple objects</em> and jmx4r hides all the complexity to map them to the javax.management API for you
+* you can manage your own JVM (e.g. if you're running a Rails on JRuby application) or a remote JVM in the same way
+
+== Installation
+
+  jruby -S gem install jmx4r
+
+== Usage
+
+  # To trigger a garbage collection on a Java application:
+  
+  require 'rubygems'
+  require 'jmx4r'
+  
+  JMX::MBean.establish_connection :host => "localhost", :port => 3000
+  
+  memory = JMX::MBean.find_by_name "java.lang:type=Memory"
+  # display verbose GC logs
+  memory.verbose = true
+  # trigger a Garbage Collection
+  memory.gc
+
+== Help
+
+* Wiki[http://jmesnil.net/wiki/Jmx4r]
+* RDoc[http://jmx4r.rubyforge.org/doc/]
+ 
+== Source Code
+
+  git clone git://github.com/jmesnil/jmx4r.git
+
+

data/Rakefile

@@ -6,7 +6,7 @@ require "rubygems"
 
 dir     = File.dirname(__FILE__)
 lib     = File.join(dir, "lib", "jmx4r.rb")
-version = "0.0.6"
+version = "0.0.7"
 
 task :default => [:test]
 
@@ -17,9 +17,9 @@ Rake::TestTask.new do |test|
 end
 
 Rake::RDocTask.new do |rdoc|
-  rdoc.rdoc_files.include( "README.txt", "LICENSE.txt", "AUTHORS.txt", 
+  rdoc.rdoc_files.include( "README.rdoc", "LICENSE.txt", "AUTHORS.txt", 
                            "lib/" )
-  rdoc.main     = "README.txt"
+  rdoc.main     = "README.rdoc"
   rdoc.rdoc_dir = "doc/html"
   rdoc.title    = "jmx4r Documentation"
   rdoc.options << "-S"
@@ -40,16 +40,16 @@ spec = Gem::Specification.new do |spec|
 
   spec.test_files       =  "test/ts_all.rb"
   spec.has_rdoc         =  true
-  spec.extra_rdoc_files =  %w{README.txt LICENSE.txt}
+  spec.extra_rdoc_files =  %w{README.rdoc LICENSE.txt}
   spec.rdoc_options     << '--title' << 'jmx4r Documentation' <<
-                           '--main'  << 'README.txt'
+                           '--main'  << 'README.rdoc'
 
   spec.require_path      = 'lib'
 
   spec.author            = "Jeff Mesnil"
   spec.email             = "jmesnil@gmail.com"
   spec.rubyforge_project = "jmx4r"
-  spec.homepage          = "http://code.google.com/p/jmx4r/"
+  spec.homepage          = "http://jmesnil.net/wiki/Jmx4r"
   spec.description       = <<END_DESC
 jmx4r is a JMX library for JRuby
 END_DESC

data/lib/jmx4r.rb

@@ -19,8 +19,34 @@ module JMX
   require 'objectname_helper'
   require 'jruby'
 
+  class MBeanServerConnectionProxy
+    attr_reader :connector
+
+    # Adds a connector attribute to Java's native MBeanServerConnection class.
+    #
+    # The connector attribute can be used to manage the connection (e.g, to close it).
+    # Why this isn't included in the native MBeanServerConnection class is beyond me.
+    #
+    # connector:: JMXConnector instance as returned by JMXConnectorFactory.connect.
+    def initialize(connector)
+      @connector = connector
+      @connection = connector.getMBeanServerConnection
+    end
+
+    # Close the connection (an unfortunate omission from the MBeanServerConnection class, imho)
+    def close
+      @connector.close
+    end
+
+    # Forward all other method messages to the underlying MBeanServerConnection instance.
+    def method_missing(method, *args, &block)
+      @connection.send method, *args, &block
+    end
+  end
+
   class MBean
     include_class 'java.util.HashMap'
+    include_class 'javax.naming.Context'
     include_class 'javax.management.Attribute'
     include_class 'javax.management.ObjectName'
     include_class 'javax.management.remote.JMXConnector'
@@ -28,31 +54,31 @@ module JMX
     include_class 'javax.management.remote.JMXServiceURL'
     JThread = java.lang.Thread
 
-    attr_reader :object_name, :operations, :attributes
+    attr_reader :object_name, :operations, :attributes, :connection
 
     # Creates a new MBean.
     #
     # object_name:: a string corresponding to a valid ObjectName
-    # mbsc::        a connection to a MBean server. If none is passed, 
+    # connection::  a connection to a MBean server. If none is passed,
     #               use the global connection created by 
     #               MBean.establish_connection
-    def initialize(object_name, mbsc=nil)
-      @mbsc = mbsc || @@mbsc
+    def initialize(object_name, connection=nil)
+      @connection = connection || @@connection
       @object_name = object_name
-      info = @mbsc.getMBeanInfo @object_name
+      info = @connection.getMBeanInfo @object_name
       @attributes = Hash.new
       info.attributes.each do | mbean_attr |
         @attributes[mbean_attr.name.snake_case] = mbean_attr.name
         self.class.instance_eval do 
           define_method mbean_attr.name.snake_case do
-            @mbsc.getAttribute @object_name, "#{mbean_attr.name}"
+            @connection.getAttribute @object_name, "#{mbean_attr.name}"
           end
         end
         if mbean_attr.isWritable
           self.class.instance_eval do
             define_method "#{mbean_attr.name.snake_case}=" do |value| 
               attr = Attribute.new mbean_attr.name, value
-              @mbsc.setAttribute @object_name, attr
+              @connection.setAttribute @object_name, attr
             end
           end
         end
@@ -67,7 +93,7 @@ module JMX
     def method_missing(method, *args, &block) #:nodoc:
       if @operations.keys.include?(method.to_s)
         op_name, param_types = @operations[method.to_s]
-        @mbsc.invoke @object_name,
+        @connection.invoke @object_name,
         op_name,
         args.to_java(:Object),
         param_types.to_java(:String)
@@ -76,7 +102,7 @@ module JMX
       end
     end
 
-    @@mbsc = nil
+    @@connection = nil
 
     # establish a connection to a remote MBean server which will
     # be used by all subsequent MBeans.
@@ -89,19 +115,21 @@ module JMX
     #   JMX::MBean.establish_connection :port => "node23", :port => 1090
     #   JMX::MBean.establish_connection :port => "node23", :username => "jeff", :password => "secret"
     def self.establish_connection(args={})
-      @@mbsc ||= create_connection args
+      @@connection ||= create_connection args
     end
 
     def self.remove_connection(args={})
-      @@mbsc = nil
+      if @@connection
+        @@connection.close rescue nil
+      end
+      @@connection = nil
     end
 
     def self.connection(args={})
       if args.has_key? :host or args.has_key? :port
         return create_connection(args)
       else
-        MBean.establish_connection(args) unless @@mbsc
-        return @@mbsc  
+        @@connection ||= MBean.establish_connection(args)
       end
     end
 
@@ -122,6 +150,8 @@ module JMX
     # [:credentials] custom credentials (if the MBean server requires authentication).
     #                No default. It has precedence over :username and :password (i.e. if
     #                :credentials is specified, :username & :password are ignored)   
+    # [:provider_package] use to fill the JMXConnectorFactory::PROTOCOL_PROVIDER_PACKAGES
+    #                No default
     #
     def self.create_connection(args={})
       host= args[:host] || "localhost"
@@ -129,6 +159,7 @@ module JMX
       username = args[:username]
       password = args[:password]
       credentials = args[:credentials]
+      provider_package = args[:provider_package]
       
       # host & port are not taken into account if url is set (see issue #7)
       standard_url = "service:jmx:rmi:///jndi/rmi://#{host}:#{port}/jmxrmi"
@@ -143,6 +174,12 @@ module JMX
       
       env = HashMap.new
       env.put(JMXConnector::CREDENTIALS, credentials) if credentials
+      # only fill the Context and JMXConnectorFactory properties if provider_package is set
+      if provider_package
+        env.put(Context::SECURITY_PRINCIPAL, username) if username
+        env.put(Context::SECURITY_CREDENTIALS, password) if password
+        env.put(JMXConnectorFactory::PROTOCOL_PROVIDER_PACKAGES, provider_package)
+      end
 
       # the context class loader is set to JRuby's classloader when
       # creating the JMX Connection so that classes loaded using 
@@ -153,7 +190,7 @@ module JMX
         JThread.current_thread.context_class_loader = JRuby.runtime.getJRubyClassLoader
         
         connector = JMXConnectorFactory::connect JMXServiceURL.new(url), env
-        connector.getMBeanServerConnection
+        MBeanServerConnectionProxy.new connector
       ensure
         # ... and we reset the previous context class loader
         JThread.current_thread.context_class_loader = context_class_loader
@@ -173,17 +210,45 @@ module JMX
     #
     def self.find_all_by_name(name, args={})
       object_name = ObjectName.new(name)
-      mbsc = args[:connection] || MBean.connection(args)
-      object_names = mbsc.queryNames(object_name, nil)
-      object_names.map { |on| MBean.new(on, mbsc) }
+      connection = args[:connection] || MBean.connection(args)
+      object_names = connection.queryNames(object_name, nil)
+      object_names.map { |on| MBean.new(on, connection) }
     end
 
     # Same as #find_all_by_name but the ObjectName passed in parameter
     # can not be a pattern.
     # Only one single MBean is returned.
     def self.find_by_name(name, args={})
-      mbsc = args[:connection] || MBean.connection(args)
-      MBean.new ObjectName.new(name), mbsc
+      connection = args[:connection] || MBean.connection(args)
+      MBean.new ObjectName.new(name), connection
+    end
+
+    def self.pretty_print (object_name, args={})
+      connection = args[:connection] || MBean.connection(args)
+      info = connection.getMBeanInfo ObjectName.new(object_name)
+      puts "object_name: #{object_name}"
+      puts "class: #{info.class_name}"
+      puts "description: #{info.description}"
+      puts "operations:"
+      info.operations.each do | op |
+        puts "  #{op.name}"
+        op.signature.each do | param |
+          puts "    #{param.name} (#{param.type} #{param.description})"
+        end
+        puts "    ----"
+        puts "    description: #{op.description}"
+        puts "    return_type: #{op.return_type}"
+        puts "    impact: #{op.impact}"
+      end
+      puts "attributes:"
+      info.attributes.each do | attr |
+        puts "  #{attr.name}"
+        puts "    description: #{attr.description}"
+        puts "    type: #{attr.type}"
+        puts "    readable: #{attr.readable}"
+        puts "    writable: #{attr.writable}"
+        puts "    is: #{attr.is}"
+      end
     end
   end
 end

data/test/tc_connection.rb

@@ -6,6 +6,7 @@ require "jmx4r"
 require "jconsole"
 
 class TestConnection < Test::Unit::TestCase
+
   def teardown
     JMX::MBean.remove_connection
   end
@@ -25,7 +26,21 @@ class TestConnection < Test::Unit::TestCase
   def test_establish_connection
     begin
       JConsole::start
-      JMX::MBean.establish_connection
+      connection = JMX::MBean.establish_connection
+      assert(connection.getMBeanCount > 0)
+    ensure
+      JConsole::stop
+    end
+  end
+
+  def test_remove_connection
+    begin
+      JConsole::start
+      connection = JMX::MBean.establish_connection
+      JMX::MBean.remove_connection
+      assert_raise(NativeException) {
+        connection.getMBeanCount
+      }
     ensure
       JConsole::stop
     end

data/test/tc_multiple_connections.rb

@@ -16,7 +16,6 @@ class TestMultipleConnections < Test::Unit::TestCase
 
   def teardown
     @ports.each do |port| 
-      JMX::MBean.remove_connection :port => port
       JConsole::stop port 
     end
   end
@@ -36,7 +35,7 @@ class TestMultipleConnections < Test::Unit::TestCase
   end
 
   def test_same_connection
-    mbsc = JMX::MBean.establish_connection :port => @ports[0]
+    mbsc = JMX::MBean.create_connection :port => @ports[0]
 
     delegate_1 = JMX::MBean.find_by_name @delegate_on, :connection => mbsc
     delegate_2 = JMX::MBean.find_by_name @delegate_on, :connection => mbsc
@@ -61,6 +60,7 @@ class TestMultipleConnections < Test::Unit::TestCase
     delegate_2 = JMX::MBean.find_by_name @delegate_on
 
     assert_equal delegate_1.m_bean_server_id, delegate_2.m_bean_server_id
+    JMX::MBean.remove_connection
   end
 
 end

metadata

@@ -1,11 +1,13 @@
---- !ruby/object:Gem::Specification
+--- !ruby/object:Gem::Specification 
 extensions: []
-homepage: http://code.google.com/p/jmx4r/
+
+homepage: http://jmesnil.net/wiki/Jmx4r
 executables: []
-version: !ruby/object:Gem::Version
-  version: 0.0.6
+
+version: !ruby/object:Gem::Version 
+  version: 0.0.7
 post_install_message: 
-date: 2008-07-31 22:00:00 +00:00
+date: 2009-02-11 23:00:00 +00:00
 files: 
 - examples/class_loading.rb
 - examples/jvm_mngmt.rb
@@ -25,47 +27,50 @@ files:
 - test/tc_multiple_connections.rb
 - test/ts_all.rb
 - Rakefile
-- README.txt
+- README.rdoc
 - LICENSE.txt
-rubygems_version: 1.0.1
+rubygems_version: 1.3.1
 rdoc_options: 
 - --title
 - jmx4r Documentation
 - --main
-- README.txt
+- README.rdoc
 signing_key: 
 cert_chain: []
+
 name: jmx4r
 has_rdoc: true
 platform: ruby
 summary: jmx4r is a JMX library for JRuby
 default_executable: 
 bindir: bin
-required_rubygems_version: !ruby/object:Gem::Requirement
+required_rubygems_version: !ruby/object:Gem::Requirement 
   version: 
   requirements: 
   - - '>='
-    - !ruby/object:Gem::Version
-      version: !str 0
-required_ruby_version: !ruby/object:Gem::Requirement
+    - !ruby/object:Gem::Version 
+      version: "0"
+required_ruby_version: !ruby/object:Gem::Requirement 
   version: 
   requirements: 
   - - '>='
-    - !ruby/object:Gem::Version
-      version: !str 0
+    - !ruby/object:Gem::Version 
+      version: "0"
 require_paths: 
 - lib
 specification_version: 2
 test_files: 
 - test/ts_all.rb
 dependencies: []
+
 description: jmx4r is a JMX library for JRuby
 email: jmesnil@gmail.com
 authors: 
 - Jeff Mesnil
 extra_rdoc_files: 
-- README.txt
+- README.rdoc
 - LICENSE.txt
 requirements: []
+
 rubyforge_project: jmx4r
 autorequire: 

data/README.txt

@@ -1,18 +0,0 @@
-jmx4r is a JMX library for JRuby.
-
-It can be used to write simple Ruby scripts running on JRuby[http://jruby.org]
-to manage remote Java applications (e.g. JBoss[http://www.jboss.org],
-Tomcat[http://tomcat.apache.org/]) using 
-JMX[http://java.sun.com/javase/technologies/core/mntr-mgmt/javamanagement/].
-
-== Examples 
-
-To trigger a garbage collection on a Java application:
-
-  require 'rubygems'
-  require 'jmx4r'
-  
-  JMX::MBean.establish_connection :host => "localhost", :port => 3000
-  memory = JMX::MBean.find_by_name "java.lang:type=Memory"
-  memory.gc
-