2008-08-12T00:42:34Z
Added a section on catching and throwing Java exceptions in Ruby.
131
CallingJavaFromJRuby
20
33925
[[Home|» JRuby Project Wiki Home Page]]
<h1>Scripting Java from JRuby</h1>
__TOC__
== An example ==
As of JRuby 1.0, a special <tt>require</tt> <tt>'java'</tt> directive in your file will give you access to the bundled Java libraries. However, this will ''not'' give you access to non-bundled libraries. A bit more is needed for that, which will be discussed later.
All the following examples can be tested using '''jirb_swing''', the Swing-based IRB console that comes with JRuby.
The following code shows this. Unless it was messed up while adding wiki tags, it should pop up a small window showing "Hello" on your screen.
<pre name="ruby">
# Valid as of JRuby 1.0
# This is the 'magical Java require line'.
require 'java'
# With the 'require' above, we can now refer to things that are part of the
# standard Java platform via their full paths.
frame = javax.swing.JFrame.new("Window") # Creating a Java JFrame
label = javax.swing.JLabel.new("Hello")
# We can transparently call Java methods on Java objects, just as if they were defined in Ruby.
frame.getContentPane.add(label) # Invoking the Java method 'getContentPane'.
frame.setDefaultCloseOperation(javax.swing.JFrame::EXIT_ON_CLOSE)
frame.pack
frame.setVisible(true)
</pre>
'''Note:''' If you are testing the example above in the Swing IRB console '''jirb_swing''', change the default close operation to DISPOSE_ON_CLOSE, or HIDE_ON_CLOSE unless you want '''jirb_swing''' to also close when you close the second window.
Here's another example (showing results from testing these statements in the '''jirb''' console).
Let's say you wanted to get a list of network interfaces. You can get Java API docs at <tt>[http://java.sun.com/j2se/1.5.0/docs/api/index.html/ java.net.NetworkInterface]</tt>.
Here's how to access the methods from this Java Class from from JRuby:
irb(main):013:0> ni = java.net.NetworkInterface.networkInterfaces
=> #<#<Class:01x7e666f>:0x855a27 @java_object=java.net.NetworkInterface$1@821453>
'''<tt>ni</tt>''' is a Ruby variable holding a Java Enumeration of NetworkInterfaces. You can see the Class ancestry for <tt>ni</tt> like this:
irb(main):029:0> ni.class.ancestors
=> [#<Class:01x7e666f>, Java::JavaUtil::Enumeration, Enumerable, Java::JavaLang::Object,
ConcreteJavaProxy, JavaProxy, JavaProxyMethods, Object, Java, Kernel]
Enumeration elements can't be accessed using Array#[] syntax but they do appear as Arrays for many other purposes. You can find out both the Java and Ruby methods for an Enumeration of NetworkInterfaces like this:
irb(main):032:0> java.net.NetworkInterface.networkInterfaces.methods
=> ["__jsend!", "has_more_elements", "hasMoreElements", "next_element", "nextElement",
"each", "reject", "member?", "grep", "include?", "min", "sort", "any?", "partition",
"each_with_index", "collect", "find_all", "to_a", "inject", "detect", "map", "zip",
"sort_by", "max", "entries", "all?", "find", "select", "hashCode", "notifyAll",
"getClass", "to_string", "toString", "get_class", "notify_all", "equals",
"hash_code", "wait", "notify", "__jcreate!", "java_class", "eql?", "synchronized",
"to_java_object", "equal?", "java_object", "java_object=", "to_s", "==", "hash",
"java_kind_of?", "handle_different_imports", "include_class", "display",
"object_id", "frozen?", "org", "__id__", "clone", "__send__", "id", "__jtrap",
"instance_eval", "singleton_methods", "is_a?", "extend",
"instance_variable_set", "freeze", "remove_instance_variable", "=~",
"private_methods", "methods", "instance_variable_get", "nil?", "send",
"untaint", "com", "type", "class", "===", "instance_of?",
"protected_methods", "tainted?", "kind_of?", "javax", "inspect", "java",
"instance_exec", "taint", "dup", "public_methods", "instance_variable_defined?",
"respond_to?", "method", "instance_variables"]
Because JRuby supports the <tt>#each</tt> method on Java Enumerations you can do this:
irb(main):011:0> java.net.NetworkInterface.networkInterfaces.each {|i| puts i; puts }
name:en1 (en1) index: 5 addresses:
/63.138.152.170;
/fe80:0:0:0:21b:63ff:febf:4a9d%5;
name:en0 (en0) index: 4 addresses:
/63.138.152.125;
/fe80:0:0:0:21b:63ff:fe1e:b2da%4;
name:lo0 (lo0) index: 1 addresses:
/127.0.0.1;
/fe80:0:0:0:0:0:0:1%1;
/0:0:0:0:0:0:0:1%0;
== Accessing and Importing Java Classes ==
=== Require a jar file to make resources in the jar discoverable within JRuby ===
To use resources within a jar file from JRuby, the jar file must either be on the classpath or be made available with the <tt>require</tt> method:
require 'path/to/mycode.jar'
This <tt>require</tt> makes the resources in <tt>mycode.jar</tt> discoverable by commands like <tt>import</tt> and <tt>include_package</tt>.
Note that loading jar-files via <tt>require</tt> searches along the RUBYLIB path, like normal ruby files.
=== Naming a Java Class ===
You can name a Java class in JRuby in at least three different ways. The idea is to map Java names like <tt>org.foo.department.Widget</tt> to Ruby nested modules. This works as follows:
Java: org.foo.department.Widget
Ruby: Java::OrgFooDepartment::Widget
That is:
* Java packages reside in the <tt>Java</tt> module.
* The package path is transformed by removing the dots and converting to ''CamelCase''
This also means that, just as in Java, packages are not nested.
* For the top-level Java packages <tt>java</tt>, <tt>javax</tt>, <tt>org</tt>, and <tt>com</tt> you can type in a fully qualified class name basically as in Java, for example, <tt>java.lang.System</tt>.
You can get the same effect for your own top-level packages, as follows. Let's assume that your packages are called <tt>edu.school.department.Class</tt>. Then, you define
def edu
Java::Edu
end
And you can use the usual Java package names.
As of JRuby-1.1.5, the <tt>import</tt> statement only works with either Java-style names or strings, but not with the <tt>Java::PackagePath::Class</tt> variant.
=== Import a Java Class to Use It Without The Full Path Name ===
You can always access any Java class that has been loaded or is in the classpath by specifying its full name. With the <tt>java_import</tt> statement or <tt>import</tt> statement, you can make the Java class available only by its name, just as in Java.
'''Example''': import and use the <tt>java.lang.System</tt> class.
require 'java'
java_import java.lang.System
version = System.getProperties["java.runtime.version"]
'''Note:''' As noted in [http://jira.codehaus.org/browse/JRUBY-3171 this bug report], <tt>java_import</tt> is the preferred, and safer, way to import Java classes.
=== Use include_package within a Ruby Module to import a Java Package ===
Use <tt>include_package "package_name"</tt> in a Ruby Module to support namespaced access to the Java classes in the package. It is also legal to use <tt>import "package_name"</tt>.
'''Example''': create a Ruby Module called <tt>JavaLang</tt> that includes the classes in the Java package <tt>java.lang</tt>.
module JavaLang
include_package "java.lang"
# alternately, use the #import method
import "java.lang"
end
Prefix the Class name with <tt>JavaLang::</tt> to access the included Classes:
version = JavaLang::System.getProperties["java.runtime.version"]
=> "1.5.0_13-b05-237"
processors = JavaLang::Runtime.getRuntime.availableProcessors
=> 2
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.
The use of the Module name to scope access to the imported Java class is also helpful in cases where the Java class has the same name as an existing Ruby class.
For example if you need to create an instance of a <tt>java.io.File</tt> object, this code will work:
import java.io.File
newfile = File.new("file.txt")
=> #<Java::JavaIo::File:0xdc6f00 @java_object=file.txt>
However you've now redefined the Ruby constant File and can no longer access the Ruby File class. Executing this:
File.open('README', 'r') {|f| puts f.readline }
Will produce this error:
NoMethodError: private method `open' called for Java::JavaIo::File:Class
If instead you create a module called <tt>JavaIO</tt> and include the package in the module definition:
module JavaIO
include_package "java.io"
end
You can now create a new instance of the Java class File without shadowing the Ruby version of the File class:
newfile = JavaIO::File.new("file.txt")
=> #<Java::JavaIo::File:0x15619c @java_object=file.txt>
The Ruby File class is still accessible:
File.open('README', 'r') {|f| puts f.readline }
JRuby - A Java implementation of the Ruby language
=> nil
=== Accessing Java Enumerations ===
Java <tt>enum</tt>s are accessible from Ruby code as constants:
lock.try_lock(5000, java.util.concurrent.TimeUnit::MILLISECONDS)
or
java_import java.util.concurrent.TimeUnit
lock.try_lock(5000, TimeUnit::MILLISECONDS)
=== Gotchas ===
JRuby automatically binds the following names in the context of a class to the top-level Java packages: com, org, java, javax. This means that you can reference these packages without having to explicitly require or import them. This takes effect for all Ruby classes in an application where a require 'java' appears. This binding takes place in precedence to the classes "method_missing" handling.
If you do not want this behaviour for a specific class, you can undefine it for that class. Here's an example that will execute identically under Ruby and JRuby:
<pre>
# Note: Comment out for Ruby test. Uncomment for JRuby test.
require 'java'
class MethodMissing
# JRuby: Undefine the standard "automatic" bindings to Java, to avoid any automatic binding.
undef org, com, java, javax
def method_missing(m, *args)
puts "method_missing: #{m}."
"This is what I return from method missing."
end
end
mm = MethodMissing.new
result = mm.org
puts "Result: #{result} Type: #{result.class.name}"
</pre>
== Calling a Java Method ==
=== Alternative Names and Beans Convention ===
In Ruby, one usually prefers <tt>method_names_like_this</tt>, while Java traditionally uses <tt>methodNamesLikeThis</tt>. If you want, you can use Ruby-style method names instead of the Java ones.
For example, these two calls are equivalent
java.lang.System.currentTimeMillis
java.lang.System.current_time_millis
JRuby also translates methods following the 'beans-convention':
x.getSomething becomes x.something
x.setSomething(newValue) becomes x.something = new_value
x.isSomething becomes x.something?
You don't have to use these alternatives, but they can make the interaction with Java code feel more Ruby-like.
=== Beware of Java generics ===
If a Java class is defined with Java generics, the types are erased during compilation for backwards compatibility. As a result. JRuby will have problems with automatic type conversion. For example, if you have a <tt>Map<String,String></tt>, it will be seen as a simple <tt>Map</tt>, and JRuby will not be able to determine the correct types using reflection.
=== Additional Methods ===
JRuby defines a number of additional methods for Java objects.
* <tt>java_class</tt> returns the Java class of an object.
* <tt>java_kind_of?</tt> works like the <tt>instanceof</tt> operator.
* <tt>java_object</tt> returns the underlying Java object. This is useful for reflection.
* <tt>java_send</tt> overrides JRuby's dispatch rules and forces the execution of a named Java method on a Java object. This is useful for Java methods, such as <tt>initialize</tt>, with names that conflict with built-in Ruby methods. More below. ''Added in JRuby 1.4''
* <tt>java_method</tt> retrieves a bound or unbound handle for a Java method to avoid the reflection inherent in <tt>java_send</tt>. More below. ''Added in JRuby 1.4''
=== Calling masked or unreachable Java methods with <tt>java_send</tt> ===
Sometimes you need to call <tt>initialize</tt> AFTER the <tt>.new()</tt> call, for example the <tt>RTPManager</tt> class in JMF. Unfortunately, this method is masked by Ruby's <tt>initialize</tt> constructor method. As of JRuby 1.4, the <tt>java_send</tt> method can be used to call this, and any other, masked method:
@mgr = javax.media.rtp.RTPManager.newInstance
localhost = java.net.InetAddress.getByName("127.0.0.1")
localaddr = javax.media.rtp.SessionAddress.new(localhost, 21000, localhost, 21001)
@mgr.java_send :initialize, [javax.media.rtp.SessionAddress], localaddr
In previous versions of JRuby, the same thing can be accomplised with reflection:
@mgr = javax.media.rtp.RTPManager.newInstance
localhost = java.net.InetAddress.getByName("127.0.0.1")
localaddr = javax.media.rtp.SessionAddress.new(localhost, 21000, localhost, 21001)
method = @mgr.java_class.declared_method(:initialize, javax.media.rtp.SessionAddress )
method.invoke @mgr.java_object, localaddr.java_object
Here is another example of calling the <tt>ArrayList.add</tt> method with <tt>java_send</tt>:
import java.util.ArrayList
list = ArrayList.new
list.java_send :add, [Java::int, java.lang.Object], 0, 'foo'
puts list.java_send :toString # => "[foo]"
Note the second argument, which is an array of types indicating the exact method signature desired. This is useful for disambiguating methods that are overloaded on similar types such as <tt>int</tt> and <tt>long</tt>.
=== Bound and Unbound Java methods with <tt>java_method</tt> ===
<tt>java_send</tt> relies on reflection and may lead to poor performance in some cases. Each time it is called, the desired method must be relocated. With the <tt>java_method</tt> method you can get a reference to any overloaded Java method as a Ruby Method object:
# get a bound Method based on the add(int, Object) method from ArrayList
add = list.java_method :add, [Java::int, java.lang.Object]
add.call(0, 'foo')
Similarly, an Unbound method object can be retrieved:
# get an UnboundMethod from the ArrayList class:
toString = ArrayList.java_method :toString
toString.bind(list).call # => [foo, foo]
=== Conversion of Types ===
==== Ruby to Java ====
''See the JRuby rspec source code dir'' <tt>spec/java_integration</tt> ''for many more examples.''
When calling Java from JRuby, primitive Ruby types are converted to default boxed Java types:
{| border="1" style="text-align:left;" cellspacing="2" cellpadding="5"
|- style="background:silver"
|'''Ruby Type'''
|'''Java Type'''
|-
| "foo" || <tt>java.lang.String</tt>
|-
| 1 || <tt>java.lang.Long</tt>
|-
| 1.0 || <tt>java.lang.Double</tt>
|-
| true, false || <tt>java.lang.Boolean</tt>
|-
| 1 << 128 || <tt>java.math.BigInteger</tt>
|}
However, this does not mean that you cannot call methods expecting a primitive type. You can also pass an integer to a method expecting a double value. JRuby usually tries quite hard to find a method that can understand your parameters.
If JRuby cannot find a matching method, it tries to pass the actual JRuby objects instead (that is, the Java objects from the JRuby implementation). A consequence of this is that if this fails you will see an error message stating that JRuby hasn't found a method taking an object of class <tt>org.jruby.RubyObject</tt> instead of the actual type.
If JRuby is not finding the exact method you want to call, perhaps because of extreme ambiguity like <tt>foo(int)</tt> vs. <tt>foo(long)</tt>, the <tt>java_send</tt> method can be used to disambiguate. See below.
==== Java to Ruby ====
When primitive Java types are passed to JRuby they are converted to the following Ruby types:
{| border="1" style="text-align:left;" cellspacing="2" cellpadding="5"
|- style="background:silver"
|'''Java Type'''||'''Ruby Type'''
|-
| <tt>public String</tt> || <tt>String</tt>
|-
| <tt>public byte</tt> || <tt>Fixnum</tt>
|-
| <tt>public short</tt> || <tt>Fixnum</tt>
|-
| <tt>public char</tt> || <tt>Fixnum</tt>
|-
| <tt>public int</tt> || <tt>Fixnum</tt>
|-
| <tt>public long</tt> || <tt>Fixnum</tt>
|-
| <tt>public float</tt> || <tt>Float</tt>
|-
| <tt>public double</tt> || <tt>Float</tt>
|}
The Java Booleans true and false are coerced to the Ruby singleton classes TrueClass and FalseClass which are represented in Ruby with the instances true and false.
The null Java object is coerced to the Ruby class NilClass which is represented in Ruby as the instance nil.
==== Java Primitive Classes ====
Java primitive classes can be found in the Java module. For example, <code>Java::byte</code> represents the primitive type byte in java. You can get its class as follows:
{| border="1"
|- style="background:silver"
|'''Ruby Code''' ||'''Java Class'''
|-
| <tt>Java::JavaClass.for_name("byte") </tt> || <tt>Java::byte.java_class</tt>
|-
| <tt>Java::JavaClass.for_name("boolean") </tt> || <tt> Java::boolean.java_class</tt>
|-
| <tt>Java::JavaClass.for_name("byte") </tt> || <tt> Java::byte.java_class</tt>
|-
| <tt>Java::JavaClass.for_name("short") </tt> || <tt> Java::short.java_class</tt>
|-
| <tt>Java::JavaClass.for_name("char") </tt> || <tt> Java::char.java_class</tt>
|-
| <tt>Java::JavaClass.for_name("int") </tt> || <tt> Java::int.java_class</tt>
|-
| <tt>Java::JavaClass.for_name("long") </tt> || <tt> Java::long.java_class</tt>
|-
| <tt>Java::JavaClass.for_name("float") </tt> || <tt> Java::float.java_class</tt>
|-
| <tt>Java::JavaClass.for_name("double") </tt> || <tt> Java::double.java_class</tt>
|}
== Arrays ==
There are two ways of constructing Java arrays. One is to use the <code>to_java</code> method of the class Array. The other is to use the <tt>[]</tt> method for the primitive Java types.
==== Converting a Ruby Array to a Java Array ====
The <tt>to_java</tt> method constructs a Java array from a Ruby array:
[1,2,3].to_java
=> [Ljava.lang.Object;@1a32ea4
By default, <tt>to_java</tt> constructs <tt>Object</tt> arrays. You can specify the parameter with an additional argument which can either be a symbol or a primitive class like <tt>Java::double</tt>
["a","b","c"].to_java(:string)
=> [Ljava.lang.String;@170984c
[1, 2, 3.5].to_java Java::double
=> [D@9bc984
==== Constructing Empty Java Arrays ====
Sometimes a Java library will need a fixed-length array, say for example a byte buffer for a stream to read into. For this, you can use the <tt>[]</tt> method of the primitive types in the Java module:
bytes = Java::byte[1024].new # Equivalent to Java's bytes = new byte[1024];
=== Ruby String to Java Bytes and back again ===
bytes = 'a string'.to_java_bytes
=> #<#<Class:01x9fcffd>:0x40e825 @java_object=[B@3d476c>
string = String.from_java_bytes bytes
=> "a string"
=== Convert a Java InputStream to a ruby IO object ===
io = Java.java_to_ruby(org.jruby.RubyIO.new(JRuby.runtime, input_stream).java_object)
[http://logs.jruby.org/jruby/2009-06-23.html#T21-34-32 from ribrdb on irc]
== Referencing a <tt>java.lang.Class</tt> object ==
If you call a Java class from JRuby and need to pass a Java class as an argument, if you use this form:
DoSomethingWithJavaClass(MyJavaClass.class)
you'll get this error:
TypeError: expected [java.lang.Class];
got: [org.jruby.RubyClass]; error: argument type mismatch
Instead use the method <tt>java_class</tt>.
DoSomethingWithJavaClass(MyJavaClass.java_class)
== Integrating JRuby and Java Classes and Interfaces ==
=== Classes ===
==== Reopening Java Classes ====
In Ruby, classes are always open, which means that you can later add methods to existing classes. This also works with Java classes.
This comes in handy when adding syntactic sugar like overloaded operators to Java classes, or other methods to make them behave more Ruby-like.
Note that these additions will only be visible on the JRuby side.
==== Subclassing a Java class ====
You can subclass (i.e. extend) a Java class and then use the JRuby class whenever Java expects the superclass.
==== Gotchas ====
If you have a class name ambiguity between Java and Ruby, the class name will reference the Ruby construct within the Ruby code. For instance, if you import <tt>java.lang.Thread</tt> and then write <tt>JThread < Thread</tt>, <tt>JThread</tt> will in fact inherit the Ruby <tt>Thread</tt> object, not the Java <tt>Thread</tt>. The solution is to use the full Java Class name, such as:
JThread < java.lang.Thread
=== Interfaces ===
Java interfaces are mapped to modules in JRuby. This means that you can also reopen the corresponding module and add further methods on the JRuby side.
==== Implementing Java Interfaces in JRuby ====
JRuby classes can now implement more than one Java interface. Since Java interfaces are mapped to modules in JRuby, you implement them not by subclassing, but by mixing them in.
class SomeJRubyObject
include java.lang.Runnable
include java.lang.Comparable
end
==== Closure conversion ====
JRuby sports a feature called ''closure conversion'', where a Ruby block or closure is converted to an appropriate Java interface. For example:
button = javax.swing.JButton.new "Press me!"
button.add_action_listener {|event| event.source.text = "You did it!"}
In this example, the <tt>JButton</tt>'s <tt>addActionListener</tt> method takes one parameter, a <tt>java.awt.event.ActionListener</tt>. The block is converted to a <tt>Proc</tt> object, which is then decorated with a java interface proxy that invokes the block for any method called on the interface.
This not only works for event listeners or <tt>Runnable</tt>, but basically for any interface. When calling a method that expects an interface, JRuby checks if a block is passed and automatically converts the block to an object implementing the interface.
=== Java classes can't inherit from a JRuby class ===
Hopefully this feature will be added in the planned re-write of the Java integration layer in a future release of JRuby.
== Exception Handling ==
Native Java exceptions can be caught in Ruby code as expected:
begin
java.lang.Integer.parse_int("asdf")
rescue java.lang.NumberFormatException => e
puts "Failed to parse integer: #{e.message}"
end
Furthermore, Ruby code can throw Java exceptions:
begin
raise java.lang.IllegalArgumentException.new("Bad param")
rescue java.lang.IllegalArgumentException => e
puts "Illegal argument: #{e}"
end
This is useful if you happen to be implementing a Java interface in Ruby that requires a particular exception to be thrown on error.
Note that this can also be written:
begin
raise Java::JavaLang::IllegalArgumentException.new("Bad param")
rescue Java::JavaLang::IllegalArgumentException => e
puts "Illegal argument: #{e}"
end
== Synchronization in JRuby ==
When interacting with Java APIs from JRuby, it is occasionally necessary to synchronize on an object for thread safety. In JRuby, a <tt>synchronize</tt> method is provided on every wrapped Java object to support this functionality. For example, the following Java code:
synchronized(obj) {
obj.wait(1000);
}
is implement like this in Ruby:
obj.synchronized do
obj.wait 1000
end
The expression evaluates to the result of the block, e.g.,
obj.synchronized { 99 } # => 99
== Material from Before JRuby 1.0 ==
One powerful feature of JRuby is its ability to invoke the classes of the Java Platform. The following example uses JRuby 0.9.2 to create a Java <tt>JFrame</tt> with a <tt>JLabel</tt>.
'''Note:''' Several package paths are magic: <tt>java</tt>, <tt>javax</tt>, <tt>org</tt>, <tt>com</tt>. Many package paths will need to be prefixed with <tt>Java</tt>:
<pre name="ruby">
require 'java'
JFrame = javax.swing.JFrame
JLabel = javax.swing.JLabel
frame = JFrame.new()
frame.getContentPane().add(JLabel.new("This is an example."))
frame.pack()
frame.setVisible(true)
MyClass = Java::my.package.MyClass
myClass = MyClass.new()
myClass.doit()
</pre>
'''Note:''' Older versions of JRuby require you to use the following code as the import preamble:
<pre name="ruby">
require 'java'
include_class "javax.swing.JFrame"
include_class "javax.swing.JLabel"
</pre>
JRuby also allows you to call Java code by using the more Ruby-like <tt>underscore_method_naming</tt> and to refer to JavaBean properties as attributes. The translation rule is that the Java method name is split by capital letters, lowercased, and prepended with <tt>_</tt>.
<pre name="ruby">
frame.content_pane.add(label)
frame.visible = true
</pre>
JRuby also lets you call Java libraries ''not'' included in the standard set of class libraries associated with the Java Platform. By copying jars to <tt>$JRUBY_HOME/lib</tt> or by modifying the CLASSPATH environment variable, you can access third-party Java libraries from JRuby scripts or from jirb, an interactive JRuby shell. It is also possible to add a jar to the classpath by requiring the jar (if it exists in the JRuby library load path):
<pre name="ruby">
require 'whatever.jar'
com.whatever.Whatever.doSomething
</pre>
== Related Articles ==
* [http://mikiobraun.blogspot.com/2008/11/java-integration-in-jruby.html Java Integration in JRuby] Short overview article on JRuby and Java integration.
* [http://blogs.sun.com/sundararajan/entry/java_integration_javascript_groovy_and Java Integration: JavaScript, Groovy and JRuby] Side-by-side comparison of Java integration in JavaScript, Groovy and JRuby.
* [http://jruby.codehaus.org/Java+Integration Java Integration] From the JRuby main page.
* [http://jtestr.codehaus.org/ JtestR] A testing framework for Java based on JRuby.
* [http://github.com/leandrosilva/sparrow Sparrow] A JMS client for messaging based on JRuby.
<p><a href='<?url_for_page Home?>' class='internal'>» JRuby Project Wiki Home Page</a><h1>Scripting Java from JRuby</h1></p><div id='toc' class='toc'>
<div id='toctitle' class='toc-title'>
<span>Contents</span>
</div>
<div id='toccontents' class='toc-contents'><ul><ul><li>1 <a href='#An_example'> An example </a></li>
<li>2 <a href='#Accessing_and_Importing_Java_Classes'> Accessing and Importing Java Classes </a></li>
<ul><li>2.1 <a href='#Require_a_jar_file_to_make_resources_in_the_jar_discoverable_within_JRuby'> Require a jar file to make resources in the jar discoverable within JRuby </a></li>
<li>2.2 <a href='#Naming_a_Java_Class'> Naming a Java Class </a></li>
<li>2.3 <a href='#Import_a_Java_Class_to_Use_It_Without_The_Full_Path_Name'> Import a Java Class to Use It Without The Full Path Name </a></li>
<li>2.4 <a href='#Use_include_package_within_a_Ruby_Module_to_import_a_Java_Package'> Use include_package within a Ruby Module to import a Java Package </a></li>
<li>2.5 <a href='#Accessing_Java_Enumerations'> Accessing Java Enumerations </a></li>
<li>2.6 <a href='#Gotchas'> Gotchas </a></li>
</ul><li>3 <a href='#Calling_a_Java_Method'> Calling a Java Method </a></li>
<ul><li>3.1 <a href='#Alternative_Names_and_Beans_Convention'> Alternative Names and Beans Convention </a></li>
<li>3.2 <a href='#Beware_of_Java_generics'> Beware of Java generics </a></li>
<li>3.3 <a href='#Additional_Methods'> Additional Methods </a></li>
<li>3.4 <a href='#Calling_masked_or_unreachable_Java_methods_with_java_send'> Calling masked or unreachable Java methods with <tt>java_send</tt> </a></li>
<li>3.5 <a href='#Bound_and_Unbound_Java_methods_with_java_method'> Bound and Unbound Java methods with <tt>java_method</tt> </a></li>
<li>3.6 <a href='#Conversion_of_Types'> Conversion of Types </a></li>
<ul><li>3.6.1 <a href='#Ruby_to_Java'> Ruby to Java </a></li>
<li>3.6.2 <a href='#Java_to_Ruby'> Java to Ruby </a></li>
<li>3.6.3 <a href='#Java_Primitive_Classes'> Java Primitive Classes </a></li>
</ul></ul><li>4 <a href='#Arrays'> Arrays </a></li>
<ul><ul><li>4.1 <a href='#Converting_a_Ruby_Array_to_a_Java_Array'> Converting a Ruby Array to a Java Array </a></li>
<li>4.2 <a href='#Constructing_Empty_Java_Arrays'> Constructing Empty Java Arrays </a></li>
</ul><li>4.1 <a href='#Ruby_String_to_Java_Bytes_and_back_again'> Ruby String to Java Bytes and back again </a></li>
<li>4.2 <a href='#Convert_a_Java_InputStream_to_a_ruby_IO_object'> Convert a Java InputStream to a ruby IO object </a></li>
</ul><li>5 <a href='#Referencing_a_java.lang.Class_object'> Referencing a <tt>java.lang.Class</tt> object </a></li>
<li>6 <a href='#Integrating_JRuby_and_Java_Classes_and_Interfaces'> Integrating JRuby and Java Classes and Interfaces </a></li>
<ul><li>6.1 <a href='#Classes'> Classes </a></li>
<ul><li>6.1.1 <a href='#Reopening_Java_Classes'> Reopening Java Classes </a></li>
<li>6.1.2 <a href='#Subclassing_a_Java_class'> Subclassing a Java class </a></li>
<li>6.1.3 <a href='#Gotchas'> Gotchas </a></li>
</ul><li>6.2 <a href='#Interfaces'> Interfaces </a></li>
<ul><li>6.2.1 <a href='#Implementing_Java_Interfaces_in_JRuby'> Implementing Java Interfaces in JRuby </a></li>
<li>6.2.2 <a href='#Closure_conversion'> Closure conversion </a></li>
</ul><li>6.3 <a href='#Java_classes_can_t_inherit_from_a_JRuby_class'> Java classes can't inherit from a JRuby class </a></li>
</ul><li>7 <a href='#Exception_Handling'> Exception Handling </a></li>
<li>8 <a href='#Synchronization_in_JRuby'> Synchronization in JRuby </a></li>
<li>9 <a href='#Material_from_Before_JRuby_1.0'> Material from Before JRuby 1.0 </a></li>
<li>10 <a href='#Related_Articles'> Related Articles </a></li>
</ul></ul></div>
</div><h2><a name='An_example'></a> An example </h2>
<p>
As of JRuby 1.0, a special <tt>require</tt> <tt>'java'</tt> directive in your file will give you access to the bundled Java libraries. However, this will <i>not</i> give you access to non-bundled libraries. A bit more is needed for that, which will be discussed later.
</p><p>All the following examples can be tested using <b>jirb_swing</b>, the Swing-based IRB console that comes with JRuby.
</p><p>The following code shows this. Unless it was messed up while adding wiki tags, it should pop up a small window showing "Hello" on your screen.
<pre name="code" class="ruby">
# Valid as of JRuby 1.0
# This is the 'magical Java require line'.
require 'java'
# With the 'require' above, we can now refer to things that are part of the
# standard Java platform via their full paths.
frame = javax.swing.JFrame.new("Window") # Creating a Java JFrame
label = javax.swing.JLabel.new("Hello")
# We can transparently call Java methods on Java objects, just as if they were defined in Ruby.
frame.getContentPane.add(label) # Invoking the Java method 'getContentPane'.
frame.setDefaultCloseOperation(javax.swing.JFrame::EXIT_ON_CLOSE)
frame.pack
frame.setVisible(true)
</pre>
</p><p><b>Note:</b> If you are testing the example above in the Swing IRB console <b>jirb_swing</b>, change the default close operation to DISPOSE_ON_CLOSE, or HIDE_ON_CLOSE unless you want <b>jirb_swing</b> to also close when you close the second window.
</p><p>Here's another example (showing results from testing these statements in the <b>jirb</b> console).
</p><p>Let's say you wanted to get a list of network interfaces. You can get Java API docs at <tt><a class='external' href="http://java.sun.com/j2se/1.5.0/docs/api/index.html/">java.net.NetworkInterface</a></tt>.
</p><p>Here's how to access the methods from this Java Class from from JRuby:
</p><pre> irb(main):013:0> ni = java.net.NetworkInterface.networkInterfaces
=> #<#<Class:01x7e666f>:0x855a27 @java_object=java.net.NetworkInterface$1@821453>
</pre><p><b><tt>ni</tt></b> is a Ruby variable holding a Java Enumeration of NetworkInterfaces. You can see the Class ancestry for <tt>ni</tt> like this:
</p><pre> irb(main):029:0> ni.class.ancestors
=> [#<Class:01x7e666f>, Java::JavaUtil::Enumeration, Enumerable, Java::JavaLang::Object,
ConcreteJavaProxy, JavaProxy, JavaProxyMethods, Object, Java, Kernel]
</pre><p>
Enumeration elements can't be accessed using Array#[] syntax but they do appear as Arrays for many other purposes. You can find out both the Java and Ruby methods for an Enumeration of NetworkInterfaces like this:
</p><pre> irb(main):032:0> java.net.NetworkInterface.networkInterfaces.methods
=> ["__jsend!", "has_more_elements", "hasMoreElements", "next_element", "nextElement",
"each", "reject", "member?", "grep", "include?", "min", "sort", "any?", "partition",
"each_with_index", "collect", "find_all", "to_a", "inject", "detect", "map", "zip",
"sort_by", "max", "entries", "all?", "find", "select", "hashCode", "notifyAll",
"getClass", "to_string", "toString", "get_class", "notify_all", "equals",
"hash_code", "wait", "notify", "__jcreate!", "java_class", "eql?", "synchronized",
"to_java_object", "equal?", "java_object", "java_object=", "to_s", "==", "hash",
"java_kind_of?", "handle_different_imports", "include_class", "display",
"object_id", "frozen?", "org", "__id__", "clone", "__send__", "id", "__jtrap",
"instance_eval", "singleton_methods", "is_a?", "extend",
"instance_variable_set", "freeze", "remove_instance_variable", "=~",
"private_methods", "methods", "instance_variable_get", "nil?", "send",
"untaint", "com", "type", "class", "===", "instance_of?",
"protected_methods", "tainted?", "kind_of?", "javax", "inspect", "java",
"instance_exec", "taint", "dup", "public_methods", "instance_variable_defined?",
"respond_to?", "method", "instance_variables"]
</pre><p>
Because JRuby supports the <tt>#each</tt> method on Java Enumerations you can do this:
</p><pre> irb(main):011:0> java.net.NetworkInterface.networkInterfaces.each {|i| puts i; puts }
name:en1 (en1) index: 5 addresses:
/63.138.152.170;
/fe80:0:0:0:21b:63ff:febf:4a9d%5;
name:en0 (en0) index: 4 addresses:
/63.138.152.125;
/fe80:0:0:0:21b:63ff:fe1e:b2da%4;
name:lo0 (lo0) index: 1 addresses:
/127.0.0.1;
/fe80:0:0:0:0:0:0:1%1;
/0:0:0:0:0:0:0:1%0;
</pre><h2><a name='Accessing_and_Importing_Java_Classes'></a> Accessing and Importing Java Classes </h2>
<h3><a name='Require_a_jar_file_to_make_resources_in_the_jar_discoverable_within_JRuby'></a> Require a jar file to make resources in the jar discoverable within JRuby </h3>
<p>To use resources within a jar file from JRuby, the jar file must either be on the classpath or be made available with the <tt>require</tt> method:
</p><pre> require 'path/to/mycode.jar'
</pre><p>
This <tt>require</tt> makes the resources in <tt>mycode.jar</tt> discoverable by commands like <tt>import</tt> and <tt>include_package</tt>.
</p><p>Note that loading jar-files via <tt>require</tt> searches along the RUBYLIB path, like normal ruby files.
</p><h3><a name='Naming_a_Java_Class'></a> Naming a Java Class </h3>
<p>You can name a Java class in JRuby in at least three different ways. The idea is to map Java names like <tt>org.foo.department.Widget</tt> to Ruby nested modules. This works as follows:
</p><pre> Java: org.foo.department.Widget
Ruby: Java::OrgFooDepartment::Widget
</pre><p>
That is:
</p><ul><li> Java packages reside in the <tt>Java</tt> module.
</li><li> The package path is transformed by removing the dots and converting to <i>CamelCase</i></li></ul><p>
This also means that, just as in Java, packages are not nested.
</p><ul><li> For the top-level Java packages <tt>java</tt>, <tt>javax</tt>, <tt>org</tt>, and <tt>com</tt> you can type in a fully qualified class name basically as in Java, for example, <tt>java.lang.System</tt>.
</li></ul><p>
You can get the same effect for your own top-level packages, as follows. Let's assume that your packages are called <tt>edu.school.department.Class</tt>. Then, you define
</p><pre> def edu
Java::Edu
end
</pre><p>
And you can use the usual Java package names.
</p><p>As of JRuby-1.1.5, the <tt>import</tt> statement only works with either Java-style names or strings, but not with the <tt>Java::PackagePath::Class</tt> variant.
</p><h3><a name='Import_a_Java_Class_to_Use_It_Without_The_Full_Path_Name'></a> Import a Java Class to Use It Without The Full Path Name </h3>
<p>
You can always access any Java class that has been loaded or is in the classpath by specifying its full name. With the <tt>java_import</tt> statement or <tt>import</tt> statement, you can make the Java class available only by its name, just as in Java.
</p><p><b>Example</b>: import and use the <tt>java.lang.System</tt> class.
</p><pre> require 'java'
java_import java.lang.System
version = System.getProperties["java.runtime.version"]
</pre><p><b>Note:</b> As noted in <a class='external' href="http://jira.codehaus.org/browse/JRUBY-3171">this bug report</a>, <tt>java_import</tt> is the preferred, and safer, way to import Java classes.
</p><h3><a name='Use_include_package_within_a_Ruby_Module_to_import_a_Java_Package'></a> Use include_package within a Ruby Module to import a Java Package </h3>
<p>
Use <tt>include_package "package_name"</tt> in a Ruby Module to support namespaced access to the Java classes in the package. It is also legal to use <tt>import "package_name"</tt>.
</p><p><b>Example</b>: create a Ruby Module called <tt>JavaLang</tt> that includes the classes in the Java package <tt>java.lang</tt>.
</p><pre> module JavaLang
include_package "java.lang"
# alternately, use the #import method
import "java.lang"
end
</pre><p>
Prefix the Class name with <tt>JavaLang::</tt> to access the included Classes:
</p><pre> version = JavaLang::System.getProperties["java.runtime.version"]
=> "1.5.0_13-b05-237"
</pre><pre> processors = JavaLang::Runtime.getRuntime.availableProcessors
=> 2
</pre><p>
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.
</p><p>The use of the Module name to scope access to the imported Java class is also helpful in cases where the Java class has the same name as an existing Ruby class.
</p><p>For example if you need to create an instance of a <tt>java.io.File</tt> object, this code will work:
</p><pre> import java.io.File
newfile = File.new("file.txt")
=> #<Java::JavaIo::File:0xdc6f00 @java_object=file.txt>
</pre><p>
However you've now redefined the Ruby constant File and can no longer access the Ruby File class. Executing this:
</p><pre> File.open('README', 'r') {|f| puts f.readline }
</pre><p>
Will produce this error:
</p><pre> NoMethodError: private method `open' called for Java::JavaIo::File:Class
</pre><p>
If instead you create a module called <tt>JavaIO</tt> and include the package in the module definition:
</p><pre> module JavaIO
include_package "java.io"
end
</pre><p>
You can now create a new instance of the Java class File without shadowing the Ruby version of the File class:
</p><pre> newfile = JavaIO::File.new("file.txt")
=> #<Java::JavaIo::File:0x15619c @java_object=file.txt>
</pre><p>
The Ruby File class is still accessible:
</p><pre> File.open('README', 'r') {|f| puts f.readline }
JRuby - A Java implementation of the Ruby language
=> nil
</pre><h3><a name='Accessing_Java_Enumerations'></a> Accessing Java Enumerations </h3>
<p>Java <tt>enum</tt>s are accessible from Ruby code as constants:
</p><pre> lock.try_lock(5000, java.util.concurrent.TimeUnit::MILLISECONDS)
</pre><p>
or
</p><pre> java_import java.util.concurrent.TimeUnit
lock.try_lock(5000, TimeUnit::MILLISECONDS)
</pre><h3><a name='Gotchas'></a> Gotchas </h3>
<p>
JRuby automatically binds the following names in the context of a class to the top-level Java packages: com, org, java, javax. This means that you can reference these packages without having to explicitly require or import them. This takes effect for all Ruby classes in an application where a require 'java' appears. This binding takes place in precedence to the classes "method_missing" handling.
</p><p>If you do not want this behaviour for a specific class, you can undefine it for that class. Here's an example that will execute identically under Ruby and JRuby:
</p><p><pre>
# Note: Comment out for Ruby test. Uncomment for JRuby test.
require 'java'
class MethodMissing
# JRuby: Undefine the standard "automatic" bindings to Java, to avoid any automatic binding.
undef org, com, java, javax
def method_missing(m, *args)
puts "method_missing: #{m}."
"This is what I return from method missing."
end
end
mm = MethodMissing.new
result = mm.org
puts "Result: #{result} Type: #{result.class.name}"
</pre>
</p><h2><a name='Calling_a_Java_Method'></a> Calling a Java Method </h2>
<h3><a name='Alternative_Names_and_Beans_Convention'></a> Alternative Names and Beans Convention </h3>
<p>
In Ruby, one usually prefers <tt>method_names_like_this</tt>, while Java traditionally uses <tt>methodNamesLikeThis</tt>. If you want, you can use Ruby-style method names instead of the Java ones.
</p><p>For example, these two calls are equivalent
</p><pre> java.lang.System.currentTimeMillis
java.lang.System.current_time_millis
</pre><p>
JRuby also translates methods following the 'beans-convention':
</p><pre> x.getSomething becomes x.something
x.setSomething(newValue) becomes x.something = new_value
x.isSomething becomes x.something?
</pre><p>
You don't have to use these alternatives, but they can make the interaction with Java code feel more Ruby-like.
</p><h3><a name='Beware_of_Java_generics'></a> Beware of Java generics </h3>
<p>
If a Java class is defined with Java generics, the types are erased during compilation for backwards compatibility. As a result. JRuby will have problems with automatic type conversion. For example, if you have a <tt>Map<String,String></tt>, it will be seen as a simple <tt>Map</tt>, and JRuby will not be able to determine the correct types using reflection.
</p><h3><a name='Additional_Methods'></a> Additional Methods </h3>
<p>
JRuby defines a number of additional methods for Java objects.
</p><ul><li> <tt>java_class</tt> returns the Java class of an object.
</li><li> <tt>java_kind_of?</tt> works like the <tt>instanceof</tt> operator.
</li><li> <tt>java_object</tt> returns the underlying Java object. This is useful for reflection.
</li><li> <tt>java_send</tt> overrides JRuby's dispatch rules and forces the execution of a named Java method on a Java object. This is useful for Java methods, such as <tt>initialize</tt>, with names that conflict with built-in Ruby methods. More below. <i>Added in JRuby 1.4</i></li><li> <tt>java_method</tt> retrieves a bound or unbound handle for a Java method to avoid the reflection inherent in <tt>java_send</tt>. More below. <i>Added in JRuby 1.4</i></li></ul><h3><a name='Calling_masked_or_unreachable_Java_methods_with_java_send'></a> Calling masked or unreachable Java methods with <tt>java_send</tt> </h3>
<p>Sometimes you need to call <tt>initialize</tt> AFTER the <tt>.new()</tt> call, for example the <tt>RTPManager</tt> class in JMF. Unfortunately, this method is masked by Ruby's <tt>initialize</tt> constructor method. As of JRuby 1.4, the <tt>java_send</tt> method can be used to call this, and any other, masked method:
</p><pre> @mgr = javax.media.rtp.RTPManager.newInstance
localhost = java.net.InetAddress.getByName("127.0.0.1")
localaddr = javax.media.rtp.SessionAddress.new(localhost, 21000, localhost, 21001)
@mgr.java_send :initialize, [javax.media.rtp.SessionAddress], localaddr
</pre><p>
In previous versions of JRuby, the same thing can be accomplised with reflection:
</p><pre> @mgr = javax.media.rtp.RTPManager.newInstance
localhost = java.net.InetAddress.getByName("127.0.0.1")
localaddr = javax.media.rtp.SessionAddress.new(localhost, 21000, localhost, 21001)
method = @mgr.java_class.declared_method(:initialize, javax.media.rtp.SessionAddress )
method.invoke @mgr.java_object, localaddr.java_object
</pre><p>
Here is another example of calling the <tt>ArrayList.add</tt> method with <tt>java_send</tt>:
</p><pre>
import java.util.ArrayList
list = ArrayList.new
list.java_send :add, [Java::int, java.lang.Object], 0, 'foo'
puts list.java_send :toString # => "[foo]"
</pre><p>
Note the second argument, which is an array of types indicating the exact method signature desired. This is useful for disambiguating methods that are overloaded on similar types such as <tt>int</tt> and <tt>long</tt>.
</p><h3><a name='Bound_and_Unbound_Java_methods_with_java_method'></a> Bound and Unbound Java methods with <tt>java_method</tt> </h3>
<p><tt>java_send</tt> relies on reflection and may lead to poor performance in some cases. Each time it is called, the desired method must be relocated. With the <tt>java_method</tt> method you can get a reference to any overloaded Java method as a Ruby Method object:
</p><pre>
# get a bound Method based on the add(int, Object) method from ArrayList
add = list.java_method :add, [Java::int, java.lang.Object]
add.call(0, 'foo')
</pre><p>
Similarly, an Unbound method object can be retrieved:
</p><pre> # get an UnboundMethod from the ArrayList class:
toString = ArrayList.java_method :toString
toString.bind(list).call # => [foo, foo]
</pre><h3><a name='Conversion_of_Types'></a> Conversion of Types </h3>
<h4><a name='Ruby_to_Java'></a> Ruby to Java </h4>
<p><i>See the JRuby rspec source code dir</i> <tt>spec/java_integration</tt> <i>for many more examples.</i>
</p><p>When calling Java from JRuby, primitive Ruby types are converted to default boxed Java types:
</p><div style="overflow-x: auto;"><div style="margin: 0px 2px 0px 2px;">
<table border="1" style="text-align:left;" cellspacing="2" cellpadding="5"><tr style="background:silver"><td><b>Ruby Type</b></td><td><b>Java Type</b></td></tr>
<tr ><td> "foo" </td><td> <tt>java.lang.String</tt></td></tr>
<tr><td> 1 </td><td> <tt>java.lang.Long</tt></td></tr>
<tr><td> 1.0 </td><td> <tt>java.lang.Double</tt></td></tr>
<tr><td> true, false </td><td> <tt>java.lang.Boolean</tt></td></tr>
<tr><td> 1 << 128 </td><td> <tt>java.math.BigInteger</tt>
</td></tr>
</table>
</div></div>
<p>
However, this does not mean that you cannot call methods expecting a primitive type. You can also pass an integer to a method expecting a double value. JRuby usually tries quite hard to find a method that can understand your parameters.
</p><p>If JRuby cannot find a matching method, it tries to pass the actual JRuby objects instead (that is, the Java objects from the JRuby implementation). A consequence of this is that if this fails you will see an error message stating that JRuby hasn't found a method taking an object of class <tt>org.jruby.RubyObject</tt> instead of the actual type.
</p><p>If JRuby is not finding the exact method you want to call, perhaps because of extreme ambiguity like <tt>foo(int)</tt> vs. <tt>foo(long)</tt>, the <tt>java_send</tt> method can be used to disambiguate. See below.
</p><h4><a name='Java_to_Ruby'></a> Java to Ruby </h4>
<p>When primitive Java types are passed to JRuby they are converted to the following Ruby types:
</p><div style="overflow-x: auto;"><div style="margin: 0px 2px 0px 2px;">
<table border="1" style="text-align:left;" cellspacing="2" cellpadding="5"><tr style="background:silver"><td><b>Java Type</b></td><td><b>Ruby Type</b></td></tr>
<tr ><td> <tt>public String</tt> </td><td> <tt>String</tt></td></tr>
<tr><td> <tt>public byte</tt> </td><td> <tt>Fixnum</tt></td></tr>
<tr><td> <tt>public short</tt> </td><td> <tt>Fixnum</tt></td></tr>
<tr><td> <tt>public char</tt> </td><td> <tt>Fixnum</tt></td></tr>
<tr><td> <tt>public int</tt> </td><td> <tt>Fixnum</tt></td></tr>
<tr><td> <tt>public long</tt> </td><td> <tt>Fixnum</tt></td></tr>
<tr><td> <tt>public float</tt> </td><td> <tt>Float</tt></td></tr>
<tr><td> <tt>public double</tt> </td><td> <tt>Float</tt></td></tr>
</table>
</div></div>
<p>
The Java Booleans true and false are coerced to the Ruby singleton classes TrueClass and FalseClass which are represented in Ruby with the instances true and false.
</p><p>The null Java object is coerced to the Ruby class NilClass which is represented in Ruby as the instance nil.
</p><h4><a name='Java_Primitive_Classes'></a> Java Primitive Classes </h4>
<p>
Java primitive classes can be found in the Java module. For example, <code>Java::byte</code> represents the primitive type byte in java. You can get its class as follows:
</p><div style="overflow-x: auto;"><div style="margin: 0px 2px 0px 2px;">
<table border="1"><tr style="background:silver"><td><b>Ruby Code</b> </td><td><b>Java Class</b>
</td></tr>
<tr ><td> <tt>Java::JavaClass.for_name("byte") </tt> </td><td> <tt>Java::byte.java_class</tt></td></tr>
<tr ><td> <tt>Java::JavaClass.for_name("boolean") </tt> </td><td> <tt> Java::boolean.java_class</tt></td></tr>
<tr ><td> <tt>Java::JavaClass.for_name("byte") </tt> </td><td> <tt> Java::byte.java_class</tt></td></tr>
<tr ><td> <tt>Java::JavaClass.for_name("short") </tt> </td><td> <tt> Java::short.java_class</tt></td></tr>
<tr ><td> <tt>Java::JavaClass.for_name("char") </tt> </td><td> <tt> Java::char.java_class</tt></td></tr>
<tr ><td> <tt>Java::JavaClass.for_name("int") </tt> </td><td> <tt> Java::int.java_class</tt></td></tr>
<tr ><td> <tt>Java::JavaClass.for_name("long") </tt> </td><td> <tt> Java::long.java_class</tt></td></tr>
<tr ><td> <tt>Java::JavaClass.for_name("float") </tt> </td><td> <tt> Java::float.java_class</tt></td></tr>
<tr ><td> <tt>Java::JavaClass.for_name("double") </tt> </td><td> <tt> Java::double.java_class</tt></td></tr>
</table>
</div></div>
<h2><a name='Arrays'></a> Arrays </h2>
<p>There are two ways of constructing Java arrays. One is to use the <code>to_java</code> method of the class Array. The other is to use the <tt>[]</tt> method for the primitive Java types.
</p><h4><a name='Converting_a_Ruby_Array_to_a_Java_Array'></a> Converting a Ruby Array to a Java Array </h4>
<p>The <tt>to_java</tt> method constructs a Java array from a Ruby array:
</p><pre> [1,2,3].to_java
=> [Ljava.lang.Object;@1a32ea4
</pre><p>
By default, <tt>to_java</tt> constructs <tt>Object</tt> arrays. You can specify the parameter with an additional argument which can either be a symbol or a primitive class like <tt>Java::double</tt>
</p><pre> ["a","b","c"].to_java(:string)
=> [Ljava.lang.String;@170984c
</pre><pre> [1, 2, 3.5].to_java Java::double
=> [D@9bc984
</pre><h4><a name='Constructing_Empty_Java_Arrays'></a> Constructing Empty Java Arrays </h4>
<p>Sometimes a Java library will need a fixed-length array, say for example a byte buffer for a stream to read into. For this, you can use the <tt>[]</tt> method of the primitive types in the Java module:
</p><pre> bytes = Java::byte[1024].new # Equivalent to Java's bytes = new byte[1024];
</pre><h3><a name='Ruby_String_to_Java_Bytes_and_back_again'></a> Ruby String to Java Bytes and back again </h3>
<pre> bytes = 'a string'.to_java_bytes
=> #<#<Class:01x9fcffd>:0x40e825 @java_object=[B@3d476c>
</pre><pre> string = String.from_java_bytes bytes
=> "a string"
</pre><h3><a name='Convert_a_Java_InputStream_to_a_ruby_IO_object'></a> Convert a Java InputStream to a ruby IO object </h3>
<pre> io = Java.java_to_ruby(org.jruby.RubyIO.new(JRuby.runtime, input_stream).java_object)
</pre><p><a class='external' href="http://logs.jruby.org/jruby/2009-06-23.html#T21-34-32">from ribrdb on irc</a></p><pre>
</pre><h2><a name='Referencing_a_java.lang.Class_object'></a> Referencing a <tt>java.lang.Class</tt> object </h2>
<p>If you call a Java class from JRuby and need to pass a Java class as an argument, if you use this form:
</p><pre> DoSomethingWithJavaClass(MyJavaClass.class)
</pre><p>
you'll get this error:
</p><pre> TypeError: expected [java.lang.Class];
got: [org.jruby.RubyClass]; error: argument type mismatch
</pre><p>
Instead use the method <tt>java_class</tt>.
</p><pre> DoSomethingWithJavaClass(MyJavaClass.java_class)
</pre><h2><a name='Integrating_JRuby_and_Java_Classes_and_Interfaces'></a> Integrating JRuby and Java Classes and Interfaces </h2>
<h3><a name='Classes'></a> Classes </h3>
<h4><a name='Reopening_Java_Classes'></a> Reopening Java Classes </h4>
<p>In Ruby, classes are always open, which means that you can later add methods to existing classes. This also works with Java classes.
</p><p>This comes in handy when adding syntactic sugar like overloaded operators to Java classes, or other methods to make them behave more Ruby-like.
</p><p>Note that these additions will only be visible on the JRuby side.
</p><h4><a name='Subclassing_a_Java_class'></a> Subclassing a Java class </h4>
<p>You can subclass (i.e. extend) a Java class and then use the JRuby class whenever Java expects the superclass.
</p><h4><a name='Gotchas'></a> Gotchas </h4>
<p>If you have a class name ambiguity between Java and Ruby, the class name will reference the Ruby construct within the Ruby code. For instance, if you import <tt>java.lang.Thread</tt> and then write <tt>JThread < Thread</tt>, <tt>JThread</tt> will in fact inherit the Ruby <tt>Thread</tt> object, not the Java <tt>Thread</tt>. The solution is to use the full Java Class name, such as:
</p><pre> JThread < java.lang.Thread
</pre><h3><a name='Interfaces'></a> Interfaces </h3>
<p>Java interfaces are mapped to modules in JRuby. This means that you can also reopen the corresponding module and add further methods on the JRuby side.
</p><h4><a name='Implementing_Java_Interfaces_in_JRuby'></a> Implementing Java Interfaces in JRuby </h4>
<p>JRuby classes can now implement more than one Java interface. Since Java interfaces are mapped to modules in JRuby, you implement them not by subclassing, but by mixing them in.
</p><pre> class SomeJRubyObject
include java.lang.Runnable
include java.lang.Comparable
end
</pre><h4><a name='Closure_conversion'></a> Closure conversion </h4>
<p>JRuby sports a feature called <i>closure conversion</i>, where a Ruby block or closure is converted to an appropriate Java interface. For example:
</p><pre> button = javax.swing.JButton.new "Press me!"
button.add_action_listener {|event| event.source.text = "You did it!"}
</pre><p>
In this example, the <tt>JButton</tt>'s <tt>addActionListener</tt> method takes one parameter, a <tt>java.awt.event.ActionListener</tt>. The block is converted to a <tt>Proc</tt> object, which is then decorated with a java interface proxy that invokes the block for any method called on the interface.
</p><p>This not only works for event listeners or <tt>Runnable</tt>, but basically for any interface. When calling a method that expects an interface, JRuby checks if a block is passed and automatically converts the block to an object implementing the interface.
</p><pre>
</pre><h3><a name='Java_classes_can_t_inherit_from_a_JRuby_class'></a> Java classes can't inherit from a JRuby class </h3>
<p>Hopefully this feature will be added in the planned re-write of the Java integration layer in a future release of JRuby.
</p><h2><a name='Exception_Handling'></a> Exception Handling </h2>
<p>Native Java exceptions can be caught in Ruby code as expected:
</p><pre> begin
java.lang.Integer.parse_int("asdf")
rescue java.lang.NumberFormatException => e
puts "Failed to parse integer: #{e.message}"
end
</pre><p>
Furthermore, Ruby code can throw Java exceptions:
</p><pre> begin
raise java.lang.IllegalArgumentException.new("Bad param")
rescue java.lang.IllegalArgumentException => e
puts "Illegal argument: #{e}"
end
</pre><p>
This is useful if you happen to be implementing a Java interface in Ruby that requires a particular exception to be thrown on error.
</p><p>Note that this can also be written:
</p><pre> begin
raise Java::JavaLang::IllegalArgumentException.new("Bad param")
rescue Java::JavaLang::IllegalArgumentException => e
puts "Illegal argument: #{e}"
end
</pre><h2><a name='Synchronization_in_JRuby'></a> Synchronization in JRuby </h2>
<p>When interacting with Java APIs from JRuby, it is occasionally necessary to synchronize on an object for thread safety. In JRuby, a <tt>synchronize</tt> method is provided on every wrapped Java object to support this functionality. For example, the following Java code:
</p><pre>
synchronized(obj) {
obj.wait(1000);
}
</pre><p>
is implement like this in Ruby:
</p><pre>
obj.synchronized do
obj.wait 1000
end
</pre><p>The expression evaluates to the result of the block, e.g.,
</p><pre>
obj.synchronized { 99 } # => 99
</pre><h2><a name='Material_from_Before_JRuby_1.0'></a> Material from Before JRuby 1.0 </h2>
<p>One powerful feature of JRuby is its ability to invoke the classes of the Java Platform. The following example uses JRuby 0.9.2 to create a Java <tt>JFrame</tt> with a <tt>JLabel</tt>.
</p><p><b>Note:</b> Several package paths are magic: <tt>java</tt>, <tt>javax</tt>, <tt>org</tt>, <tt>com</tt>. Many package paths will need to be prefixed with <tt>Java</tt>:
</p><p><pre name="code" class="ruby">
require 'java'
JFrame = javax.swing.JFrame
JLabel = javax.swing.JLabel
frame = JFrame.new()
frame.getContentPane().add(JLabel.new("This is an example."))
frame.pack()
frame.setVisible(true)
MyClass = Java::my.package.MyClass
myClass = MyClass.new()
myClass.doit()
</pre>
</p><p><b>Note:</b> Older versions of JRuby require you to use the following code as the import preamble:
</p><p><pre name="code" class="ruby">
require 'java'
include_class "javax.swing.JFrame"
include_class "javax.swing.JLabel"
</pre>
</p><p>JRuby also allows you to call Java code by using the more Ruby-like <tt>underscore_method_naming</tt> and to refer to JavaBean properties as attributes. The translation rule is that the Java method name is split by capital letters, lowercased, and prepended with <tt>_</tt>.
<pre name="code" class="ruby">
frame.content_pane.add(label)
frame.visible = true
</pre>
</p><p>JRuby also lets you call Java libraries <i>not</i> included in the standard set of class libraries associated with the Java Platform. By copying jars to <tt>$JRUBY_HOME/lib</tt> or by modifying the CLASSPATH environment variable, you can access third-party Java libraries from JRuby scripts or from jirb, an interactive JRuby shell. It is also possible to add a jar to the classpath by requiring the jar (if it exists in the JRuby library load path):
<pre name="code" class="ruby">
require 'whatever.jar'
com.whatever.Whatever.doSomething
</pre>
</p><h2><a name='Related_Articles'></a> Related Articles </h2>
<ul><li> <a class='external' href="http://mikiobraun.blogspot.com/2008/11/java-integration-in-jruby.html">Java Integration in JRuby</a> Short overview article on JRuby and Java integration.
</li><li> <a class='external' href="http://blogs.sun.com/sundararajan/entry/java_integration_javascript_groovy_and">Java Integration: JavaScript, Groovy and JRuby</a> Side-by-side comparison of Java integration in JavaScript, Groovy and JRuby.
</li><li> <a class='external' href="http://jruby.codehaus.org/Java+Integration">Java Integration</a> From the JRuby main page.
</li><li> <a class='external' href="http://jtestr.codehaus.org/">JtestR</a> A testing framework for Java based on JRuby.
</li><li> <a class='external' href="http://github.com/leandrosilva/sparrow">Sparrow</a> A JMS client for messaging based on JRuby.
</li></ul><p><br />
</p>
2009-12-02T03:57:47Z
320