
Javasupport Low-level API
-------------------------
$Id: Javasupport-lowlevel.txt,v 1.2 2002/09/24 20:59:30 ndrs Exp $


Java:

    class methods:

    java_to_primitive(obj) -> ruby primitive or obj
        If obj is a Java object and either a boolean, numeric type or
        string, a corresponding instance of a primitive (boolean, numeric or
        string) Ruby type is
        returned.
        Otherwise obj is returned.

    primitive_to_java(obj) -> java primitive or obj
        If obj is of a primitive Ruby type (boolean, numeric or string) a
        corresponding Java object is returned. Otherwise obj is returned.


Java::JavaClass:

    class methods:

    for_name( aString ) -> aJavaClass
        A JavaClass corresponding to the named class is returned.
        If no matching Java class is available a NameError is raised.

        Example:
            Java::JavaClass.for_name("java.util.Random")

    instance methods:

    public? -> true or false
        Returns true if the Java class is public.

    final? -> true or false
        Returns true if the Java class is final.

    interface? -> true or false
        Returns true if the Java class is an Interface.

    array? -> true or false
        Returns true if the Java class represents a Java array.

    name -> aString
        Returns the name of the Java class, i.e "package.name.ClassName".

    to_s -> aString
        Synonym for Java::JavaClass#name.

    superclass -> aJavaClass
        Returns a JavaClass corresponding to the Java super-class of the
        current JavaClass.

    jc <=> aJavaClass -> -1, 0, +1
        Returns -1, 0, +1 depending on whether this class is a subclass,
        the same class, or neither, as aJavaClass.

    java_instance_methods -> anArray
        Returns a list of Java::JavaMethod's for the instance methods
        available on this Java class.

    java_class_methods -> anArray
        Returns a list of Java::JavaMethod instances for the class (or
        "static") methods available on this Java class.

    java_method( aString, [aString]* ) -> aJavaMethod
        Returns a Java::JavaMethod for the method with the given name (first
        argument) and parameter types (remaining arguments).

        Raises NameError if there isn't a matching method.

        Example:
            string_class = Java::JavaClass.for_name("java.lang.String")
            string_class.method("valueOf", "int")

    constructors -> anArray
        Returns a list of Java::JavaConstructor instances for the
        constructors on this Java class.

    constructor( [aString]* ) -> aJavaConstructor
        Returns a Java::JavaConstructor with parameter types given.

        Raises NameError if there isn't a matching constructor.

    cls.array_class -> aJavaClass
        Returns a Java::JavaClass representing arrays of this Java class.

        Example:
            cls = Java::JavaClass.for_name("java.lang.String")
            cls.array?                      # -> false
            array_cls = cls.array_class
            array_cls.array?                # -> true
            array_cls.name                  # -> "[Ljava.lang.String;"

    cls.fields -> anArray
        Returns a list of the names of the fields on this Java class.

    cls.field( aString ) -> aJavaField
        Returns a Java::JavaField for the named field.

        Raises NameError if there is no field by that name.

    cls.interfaces -> anArray
        Returns a list of the names of the interfaces implemented by this
        Java class.

    cls.primitive? -> true or false
        Returns true if the Java class represents a primitive type
        ('int', 'boolean', etc.), false otherwise.

    cls.assignable_from?( aJavaClass ) -> true or false
        Returns true if instances of the given Java class can be assigned
        to variables of this Java class.

        Example:
            object_class.assignable_from?(string_class)  # -> true
            string_class.assignable_from?(object_class)  # -> false

    cls.component_type -> aJavaClass
        If this Java class is an array class, then a JavaClass for the
        type of the elements is returned.

        If this Java class isn't an array class, then a TypeError is
        raised.


Java::JavaMethod:

    instance methods:

    meth.name -> aString
        Returns the name of the method.

        Example:
            java_class.java_method("toString").name  # --> "toString"

    meth.arity -> aFixnum
        Returns the number of arguments on this method.

    meth.public? -> true or false
        Returns true if the Java method is public, false otherwise.

    meth.final? -> true or false
        Returns true if the Java method is final, false otherwise.

    meth.invoke( aJavaObject, [anObject]* ) -> aJavaObject
        Invokes the corresponding Java instance method on the Java object
        given as first arguments. The remaining arguments are passed as
        arguments in the invokation.

        Example:
            meth.name    # -> "indexOf"
            meth.arity   # -> 1
            meth.invoke(java_string, another_java_string)
                         # -> an instance of java.lang.Integer

    meth.invoke_static( [anObject]* ) -> aJavaObject
        Invokes the corresponding Java class ("static") method. All
        arguments are passed as arguments in the invokation.

        Example:
            meth = string_class.java_method("valueOf", "int")
            meth.static?   # -> true
            meth.invoke_static(java_integer_five)
                           # -> the java.lang.String value "5"

    meth.argument_types -> anArray
        Returns a list of the names of the Java argument types.

        Example:
            meth.argument_types  # -> ["int", "java.lang.String"]

    meth.inspect -> aString
        Returns a human-readable representation of this Java method.

    meth.static? -> true or false
        Returns true if this method is a class ("static") method, false
        otherwise.

    meth.return_type -> aString
        Returns the name of the Java return type for this method.

        Example:
            meth = java_obj.java_method("toString")
            meth.return_type                        # -> "java.lang.String"


Java::JavaConstructor:

    instance methods:

    cons.arity -> aFixnum
        Returns the number of arguments on this constructor.

    cons.new_instance( [anObject]* ) -> aJavaObject
        Creates a new instance of the Java class this constructor belongs
        to, with the given arguments.

        Example:

            cons = integer_class.constructor("int")
            result = cons.new_instance(java_integer_ten)
            result.java_type     # -> "java.lang.Integer"


    cons.inspect -> aString
        Returns a human-readable representation of this Java method.

    cons.argument_types -> anArray
        Returns a list of the names of the Java argument types.


Java::JavaField:

    field.static? -> true or false
       Returns true if this is a class ("static") field, false otherwise.

    field.public? -> true or false
       Returns true if this field is public, false otherwise.

    field.final? -> true or false
       Returns true if this field is final, false otherwise.

    field.value( anInstance ) -> aJavaObject
       Returns the value of the instance field on the object given as argument.
        The instance argument must be a JavaObject of the class that this
        field belongs to.

       Example:
           width_field = rectangle_class.field(:width)
           a_rectangle.java_type            # -> "java.awt.Rectangle"
           width_field.value(a_rectangle)   # -> some java.lang.Integer value

    field.set_value( anInstance, aValue ) -> aValue
        Sets the value of this field in the given instance to the given
        value.
        The instance argument must be a JavaObject of the class that this
        field belongs to. The value argument must be a JavaObject of the
        same type as this field.
        The value argument is returned.

    field.name -> aString
        Returns the name of the field.
