Javasupport High-level API

include_class ( aString | anArray ) {|package,className| ... }

Includes a single (or multiple in array case) class into the current namespace as a constant of the same name. Optionally, a block can be supplied which allows you to choose another name (in case you are including a class which already exists in the current namespace).

require 'java'

include_class "java.util.Random"
include_class("java.lang.String") { |p, name| "J" + name }

s = JString.new("My new random number is #{Random.new.nextInt}")

include_class ["Vector", "Hashtable"].map {|e| "java.util." + e}

h = Hashtable.new

include_package( aString )

Includes a Java package into this class/module. The Java classes in the package will become available in this class/module, unless a constant with the same name as a Java class is already defined.

Instead of using 'include_package' consider loading your java classes via include_class. include_class has the advantage of being loaded anywhere; whereas 'include_package' cannot be used at the top-level. Additionally 'include_package' creates namespace pollution. Since every class name in a package will potentially become a constant in the namespace you include the package into. Finally, 'include_package' does not scale well. If you include five packages via 'include_package', then every time you reference a java class for the first time, you will search all five packages for the java class. This can be a noticeable amount of time.

module MyModule
  include_package "java.util"

  # Create an instance of java.util.Random
  random = Random.new

  # Call a Java method
  random.nextInt                  # -> some Fixnum
  # Call another Java method
  random.nextInt(10)              # -> some Fixnum (0..9)
end

java_alias( newId, oldId )

Defines an alternative name for a Java class, so that Java classes with names colliding with Ruby classes can be accessed.

This method should only used in conjunction with include_package. If you use, include_class you can use Rubys 'alias'.

module MyModule
  include_package 'java.lang'
  java_alias :JavaInteger, :Integer
end

MyModule::JavaInteger.new(123) # -> a java.lang.Integer

extend_proxy( string_interface/class_name, &block )

extend_proxy allows any class which implements or extends the provided class/interface to gain additional ruby behavior. For example:

JavaUtilities.extend_proxy('java.lang.Comparable') {
  include Comparable
  def <=>(a)
    compareTo(a)
  end
}

The above code allows any Java class implementing java.lang.Comparable to become a class capable of being used by anything expecting a Ruby Comparable.

Ruby Methods in all Java Classes/Objects

The Java classes made available through include_package or include_class have the following properties:

class methods

cls.new( [ anObject ]* ) -> anObject

cls.java_class() -> a Java::JavaClass instance

cls[] -> aClass

  JFrame[].new(3)  # -> An array of JFrames with length 3.

instance methods

All public methods on the Java object are made available as Ruby methods. If a method is overloaded (two or more methods with the same name) then then the first one found matching the argument types is called.

If the Java object is an array then the following methods are also available.

javaarray.length -> aFixnum

javaarray[ anInteger ] -> anObject

javaarray[ anInteger ] = anObject -> anObject

javaarray.each {|item| ... }

The Java arrays also implement Enumerable.