Copyright © 2011 Lars-Ake Fredlund
Authors: Lars-Ake Fredlund (lfredlund@fi.upm.es).
array_type() = {array, type(), integer()}
array_value() = string() | [value()]
attribute_name() = atom()
A name of a Java attribute, represented as an atom.
class_name() = atom() | string()
A Java classname, e.g., the quoted atom 'java.lang.Integer'.
float_type() = float | double
int_type() = int | long | short | char | byte
java_number() = integer() | float()
loglevel() = all | none | alert | critical | debug | emergency | error | info | notice | warning
method_name() = atom()
A name of a Java method, e.g., the atom 'toString'.
abstract datatype: node_id()
-type node_id() :: integer(). Identifies a connected Java node.
number_type() = int_type() | float_type()
abstract datatype: object_ref()
-type object_ref() :: {atom(), integer(), node_id()}. A Java object reference.
option() = {symbolic_name, string()} | {java_class, string()} | {add_to_java_classpath, [string()]} | {java_classpath, [string()]} | {java_exception_as_value, boolean()} | {java_verbose, string()} | {java_executable, string()} | {erlang_remote, string()} | {log_level, loglevel()} | {call_timeout, integer() | infinity}
symbolic_name
provides a symbolic name for the node.java_classpath
provides a classpath to the Java executable.
The default classpath includes the OtpErlang.jar library, and
the Java class files needed by the JavaErl library.add_to_java_classpath
adds additional entries to an
existing classpath established by java_classpath.java_exception_as_value
determines whether exceptions
generated by a Java runtime is delivered as a tuple
"{java_exception,Object}" or as an Erlang exception
with the above tuple as cause.java_executable
determines which program will be used
to start the Java interpreter (by default "java").java_verbose
provides diagnostic output from the
Java interface class using the Java standard logger.erlang_remote
specifies a (possibly remote)
Erlang node which is responsible
for starting the new Java node.call_timeout
sets a timeout value for all calls
to Java from Erlang (default 10 seconds).primitive_type() = int_type() | float_type()
type() = primitive_type() | class_name() | array_type()
The representation of a Java types as an Erlang term.
value() = object_ref() | number() | null | true | false | void | array_value() | value_spec()
value_spec() = {int_type(), integer()} | {float_type(), float()} | {class_name, object_ref()} | {array_type(), array_value()}
array_to_list/1 | Returns the elements of the (one-dimensional) array object argument as an Erlang list of objects. |
brutally_terminate/1 | Brutally shuts down and terminates the connection to a Java node. |
call/3 | Calls a Java instance method. |
call/4 | Calls a Java instance method, explicitely selecting a particular method, using the type argument to distinguish between methods of the same arity. |
call_static/4 | Calls a Java static method (a class method). |
call_static/5 | Calls a Java static method (a class method). |
connect/2 | Connects to an already started Java node. |
convert/3 | Widens or narrows a number. |
default_options/0 | Returns a list with the default options. |
free/1 | Lets Java know that an object can be freed. |
get/2 | Retrieves the value of an instance attribute. |
getClassName/1 | Returns the classname (as returned by the method getName() in java.lang.Class) of Java object parameter. |
getSimpleClassName/1 | Returns the simple classname (as returned by the method getSimplename() in java.lang.Class) of Java object parameter. |
get_stacktrace/1 | Returns the Java stacktrace as an Erlang list. |
get_static/3 | Retrieves the value of a class attribute. |
init/1 | Initializes the Java interface library providing default options. |
instanceof/2 | Returns true if the first parameter (a Java object) is an instant of the class named by the second parameter. |
is_object_ref/1 | Returns true if its argument is a Java object reference, false otherwise. |
is_subtype/3 | Convenience method for determining subype relationship. |
list_to_array/3 | Creates a one-dimensional Java array populated with the elements from the Erlang list argument, using the type specification as an element recipe. |
list_to_string/2 | Converts the Erlang string argument to a Java string. |
new/3 | Calls the constructor of a Java class. |
new/4 | Calls the constructor of a Java class, explicitely selecting a particular constructor. |
node_id/1 | Returns the node where the object argument is located. |
nodes/0 | Returns the set of active Java nodes. |
print_stacktrace/1 | Prints the Java stacktrace on the standard error file error descriptor that resulted in the throwable object argument. |
recreate_node/1 | Recreates a possibly dead node. |
report_java_exception/1 | |
reset/1 | Resets the state of a Java node, i.e., the object proxy is reset. |
set/3 | Modifies the value of an instance attribute. |
set_loglevel/1 | Determines how much debugging information is displayed. |
set_static/4 | Modifies the value of a static, i.e., class attribute. |
set_timeout/1 | Sets the timeout value for Java calls. |
start_node/0 | Starts a Java node and establises the connection to Erlang. |
start_node/1 | Starts a Java node and establishes the connection to Erlang. |
string_to_list/1 | Returns the elements of the Java String as an Erlang list. |
symbolic_name/1 | Returns the symbolic name of a Java node. |
terminate/1 | Shuts down and terminates the connection to a Java node. |
terminate_all/0 | Shuts down and terminates the connection to all known Java nodes. |
version/0 | Returns the version number of the JavaErlang library. |
start_node() -> {ok, node_id()} | {error, any()}
Starts a Java node and establises the connection to Erlang. Returns a Java library "node identifier" (not a normal Erlang node identifier).
Starts a Java node and establishes the connection
to Erlang. UserOptions provides options for how
Java is started.
Returns a "Java library node identifier" (not a normal
Erlang node identifier).
To make your Java classes (and Jar files) visible to the library
the option add_to_java_classpath
should be provided to
java:start_node/1
. An example:
{ok,NodeId} = java:start_node([{add_to_java_classpath,["classes"]}]).Adds the directory
classes
to the classpath of the started Java interpreter.
Connects to an already started Java node. Returns a Java library "node identifier" (not a normal Erlang node identifier).
report_java_exception(Other) -> any()
new(NodeId::node_id(), ClassName::class_name(), Args::[value()]) -> object_ref()
Calls the constructor of a Java class. Returns an object reference.
Example: java:new(NodeId,'java.util.HashSet',[])
,
corresponding to the statement new HashSet()
.
Due to the rules of Java method application (see explanation note in
module description)
it is possible that the correct constructor
for its arguments cannot be found. In that case,
new/4
should be used intead.
new(NodeId::node_id(), ClassName::class_name(), ArgTypes::[type()], Args::[value()]) -> object_ref()
Calls the constructor of a Java class, explicitely selecting a particular constructor. Returns an object reference.
Example:
java:new(NodeId,'java.lang.Integer',[int],[42])
,
corresponding to the statement
new Integer(42)
.
call(Object::object_ref(), Method::method_name(), Args::[value()]) -> value()
Calls a Java instance method.
Example:
java:call(Object,toString,[])
,
corresponding to the call Object.toString()
.
call(Object::object_ref(), Method::method_name(), ArgTypes::[type()], Args::[value()]) -> value()
Calls a Java instance method, explicitely selecting a particular method, using the type argument to distinguish between methods of the same arity.
call_static(NodeId::node_id(), ClassName::class_name(), Method::method_name(), Args::[value()]) -> value()
Calls a Java static method (a class method).
Example:
java:call_static(NodeId,'java.lang.Integer',reverseBytes,[22])
,
corresponding to the call Integer.reverseBytes(22)
.
call_static(NodeId::node_id(), ClassName::class_name(), Method::method_name(), ArgTypes::[type()], Args::[value()]) -> value()
Calls a Java static method (a class method). Explicitely selects which method to call using the types argument.
get(Object::object_ref(), Field::attribute_name()) -> value()
Retrieves the value of an instance attribute.
Example:
java:get(Object,v)', corresponding to 'Object.v
.
get_static(NodeId::node_id(), ClassName::class_name(), Field::attribute_name()) -> value()
Retrieves the value of a class attribute.
Example:
java:get_static(NodeId,'java.lang.Integer','SIZE')
,
corresponding to Integer.SIZE
.
set(Object::object_ref(), Field::attribute_name(), Value::value()) -> value()
Modifies the value of an instance attribute.
set_static(NodeId::node_id(), ClassName::class_name(), Field::attribute_name(), Value::value()) -> value()
Modifies the value of a static, i.e., class attribute.
init(UserOptions::[option()]) -> boolean()
Initializes the Java interface library
providing default options.
It is called automatically by start_node/0
and
standard_node/1
. Calling init/1
explicitely is
useful to customize the library when multiple
Java connections are used.
default_options() -> [option()]
Returns a list with the default options.
version() -> string()
Returns the version number of the JavaErlang library.
node_id(X1::object_ref()) -> node_id()
Returns the node where the object argument is located.
symbolic_name(NodeId::node_id()) -> string()
Returns the symbolic name of a Java node.
nodes() -> [node_id()]
Returns the set of active Java nodes.
reset(NodeId::node_id()) -> any()
Resets the state of a Java node, i.e., the object proxy is reset. This operation will cause all Java object references existing to become invalid (i.e., not referring to any Java object), but references to Java methods, constructors or fields are not affected. In addition all threads created are eventually stopped, and a new thread created to service future calls. Note that the function call may return before all threads have stopped.
terminate(NodeId::node_id()) -> any()
Shuts down and terminates the connection to a Java node.
terminate_all() -> any()
Shuts down and terminates the connection to all known Java nodes.
brutally_terminate(NodeId::node_id()) -> any()
Brutally shuts down and terminates the connection to a Java node. Does not send a termination message to the Java node, instead it attempts to kill the Unix process corresponding to the Java runtime system of the node. This will obviously only work under Unix/Linux.
Recreates a possibly dead node. Obviously any ongoing computations, object bindings, and so on are forgotten, but the classpaths and other node options are restored.
free(Object::object_ref()) -> any()
Lets Java know that an object can be freed.
set_timeout(Timeout::integer() | infinity) -> any()
Sets the timeout value for Java calls. Calls to Java from the current Erlang process will henceforth fail after Timeout seconds (or never is the argument is the atom infinity). Implementation note: this function stores data in the Erlang process dictionary.
is_object_ref(X1::any()) -> boolean()
Returns true if its argument is a Java object reference, false otherwise.
array_to_list(ArrayObj::object_ref()) -> [value()]
Returns the elements of the (one-dimensional) array object argument as an Erlang list of objects.
list_to_array(NodeId::node_id(), List::[value()], Type::type()) -> object_ref()
Creates a one-dimensional Java array populated with the elements
from the Erlang list argument, using the type specification
as an element recipe. Example:
java:list_to_array(NodeId,"Hello World!",char).
string_to_list(String::object_ref()) -> [char()]
Returns the elements of the Java String as an Erlang list.
list_to_string(NodeId::node_id(), List::string()) -> object_ref()
Converts the Erlang string argument to a Java string. This function is for convenience only; it is implementable using the rest of the Java API.
convert(NodeId::node_id(), Class::number_type(), Number::java_number()) -> java_number()
Widens or narrows a number.
instanceof(Obj::object_ref(), ClassName::class_name()) -> boolean()
Returns true if the first parameter (a Java object) is an instant of the class named by the second parameter. This function is for convenience only; it is implementable using the rest of the Java API.
is_subtype(NodeId::node_id(), Class1::class_name(), Class2::class_name()) -> boolean()
Convenience method for determining subype relationship. Returns true if the first argument is a subtype of the second.
getClassName(Object::object_ref()) -> class_name()
Returns the classname (as returned by the method getName() in java.lang.Class) of Java object parameter. This function is for convenience only; it is implementable using the rest of the Java API.
getSimpleClassName(Object::object_ref()) -> class_name()
Returns the simple classname (as returned by the method getSimplename() in java.lang.Class) of Java object parameter. This function is for convenience only; it is implementable using the rest of the Java API.
print_stacktrace(Exception::object_ref()) -> any()
Prints the Java stacktrace on the standard error file error descriptor that resulted in the throwable object argument. This function is for convenience only; it is implementable using the rest of the Java API.
get_stacktrace(Exception::object_ref()) -> list()
Returns the Java stacktrace as an Erlang list. This function is for convenience only; it is implementable using the rest of the Java API.
set_loglevel(Level::loglevel()) -> any()
Determines how much debugging information is displayed.
Generated by EDoc, Dec 18 2013, 12:32:48.