
<h1>Javasupport High-level API</h1>

<h2>Class: Object</h2>

<h3>instance methods</h3>

<div class="method">
<a name="include_class"><pre class="method-title">
include_class ( aString | anArray ) {|package,className| ... }
</pre></a>

<p>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).</p>

<b>Example:</b><br/>

<pre class="code">
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}")
</pre>

<b>Example2:</b><br/>
   
<pre class="code">
include_class ["Vector", "Hashtable"].map {|e| "java.util." + e}

h = Hashtable.new
</pre>
</div>

<h2>Class: Module</h2>

<h3>instance methods</h3>

<div class="method">
<a name="include_package"><pre class="method-title">
include_package( aString )
</pre></a>

<p>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.</p>

<p>Instead of using 'include_package' consider loading your java classes
via <a href="#include_class">include_class</a>.  <a href="#include_class">
include_class</a> 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.</p>

<b>Example:</b>

<pre class="code">
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
</pre>
</div>


<div class="method">
<a name="java_alias"><pre class="method-title">
java_alias( newId, oldId )
</pre></a>

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

<p>This method should only used in conjunction with <a href="#include_package">
include_package</a>.  If you use, <a href="#include_class">include_class</a>
you can use Rubys 'alias'.</p>

<b>Example:</b><br/>

<pre class="code">
module MyModule
  include_package 'java.lang'
  java_alias :JavaInteger, :Integer
end

MyModule::JavaInteger.new(123) # -> a java.lang.Integer
</pre>
</div>

<h2>Class: JavaUtilities</h2>

<h3>class methods</h3>

<div class="method">
<a name="extend_proxy"><pre class="method-title">
extend_proxy( string_interface/class_name, &block )
</pre></a>

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

<pre class="code">
JavaUtilities.extend_proxy('java.lang.Comparable') {
  include Comparable
  def <=>(a)
    compareTo(a)
  end
}
</pre>

<p>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.</p>

<h2>Ruby Methods in all Java Classes/Objects</h2>

<p>The Java classes made available through include_package or include_class have 
the following properties:</p>

<h3>class methods</h3>

<div class="method">
<a name="new"><pre class="method-title">
cls.new( [ anObject ]* ) -> anObject
</pre></a>

<p>If the Java class is a real class then a new instance of that class is 
returned.  If it is an interface, then a "reflection proxy" for that 
interface is returned (see java.lang.reflect.Proxy).  If it is an array 
type, then the only valid constructor argument is an integer for the wanted 
array length.</p>
</div>

<div class="method">
<a name="java_class"><pre class="method-title">
cls.java_class() -> a Java::JavaClass instance
</pre></a>

<p>Returns the low-level representation of the Java class. Useful only if 
you need to access the inner workings of the Java support.</p>
</div>

<div class="method">
<a name="java_array_class"><pre class="method-title">
cls[] -> aClass
</pre></a>

<p>Returns the Class for the array-type of the current class.</p>

<b>Example:</b><br/>

<pre class="code">
  JFrame[].new(3)  # -> An array of JFrames with length 3.
</pre>
</div>

<h3>instance methods</h3>

<p>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.</p>

<p>If the Java object is an array then the following methods are also
available.</p>

<div class="method">
<a name="length"><pre class="method-title">
javaarray.length -> aFixnum
</pre></a>

<p>Returns the length of the Java array</p>
</div>

<div class="method">
<a name="aref"><pre class="method-title">
javaarray[ anInteger ] -> anObject
</pre></a>

<p>Returns the object stored in the array at the given position.</p>
</div>

<div class="method">
<a name="aset"><pre class="method-title">
javaarray[ anInteger ] = anObject -> anObject
</pre></a>

<p>Sets the value in the given position of the array to the given value. The 
value is also returned.</p>
</div>

<div class="method">
<a name="each"><pre class="method-title">
javaarray.each {|item| ... }
</pre></a>

<p>Calls the block once for every item in the array, with that item as the 
parameter.</p>
</div>

<p>The Java arrays also implement Enumerable.</p>
