This module implements a facility for invoking Java code (methods, constructors, fields) from Erlang, using the JInterface library. Copyright (c) 2011 Lars-Ake Fredlund
Authors: [Lars-Ake Fredlund ([email protected])](mailto:Lars-Ake Fredlund ([email protected])).
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'.
class_ref() = class_name() | object_type()
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()
A Java object reference.
abstract datatype: object_type()
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()} | {enable_gc, boolean()} | {java_options, [string()]} | {enable_proxies, boolean()} | {call_timeout, integer() | infinity}
-
symbolic_nameprovides a symbolic name for the node. -
java_classpathprovides 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_classpathadds additional entries to an existing classpath established by java_classpath. -
java_exception_as_valuedetermines 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_executabledetermines which program will be used to start the Java interpreter (by default "java"). -
java_verboseprovides diagnostic output from the Java interface class using the Java standard logger. -
java_optionspermits specifying command line options to the Java executable. -
erlang_remotespecifies a (possibly remote) Erlang node which is responsible for starting the new Java node. -
enable_gcdetermines whether to garbage collect Java objects communicated to Erlang or not. -
enable_proxiesdetermines whether the proxy facility provided by thejava_proxylibrary can be used. Java objects communicated to Erlang or not. -
call_timeoutsets 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. |
| eq/2 | Checks if two Java objects references refer to the same object. |
| 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. |
| memory_usage/0 | Returns an integer corresponding to the number of Java object that are currently known to the Erlang part of the java library. |
| memory_usage/1 | Returns an integer corresponding to the number of Java object that are currently known to the Java part of the java library, at the node argument. |
| 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. |
| node_is_alive/1 | Returns true if the node is alive, false otherwise. |
| nodes/0 | Returns the set of active Java nodes. |
| print_class/2 | Outputs to standard output a textual representation of what the library knows about a certain Java class. |
| 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. |
| 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 major version number of the JavaErlang library. |
array_to_list(ArrayObj::object_ref()) -> [value()]
Returns the elements of the (one-dimensional) array object argument as an Erlang list of objects.
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.
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.
Connects to an already started Java node. Returns a Java library "node identifier" (not a normal Erlang node identifier).
convert(NodeId::node_id(), Class::number_type(), Number::java_number()) -> java_number()
default_options() -> [option()]
Returns a list with the default options.
eq(X1::object_ref(), X2::object_ref()) -> boolean()
Checks if two Java objects references refer to the same object. Note that using normal Erlang term equality is not safe.
free(Object::object_ref()) -> any()
Lets Java know that an object can be freed.
get(Object::object_ref(), Field::attribute_name()) -> value()
Retrieves the value of an instance attribute.
Example:
java:get(Object,v)', corresponding to 'Object.v.
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.
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.
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.
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.
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_object_ref(X1::any()) -> boolean()
Returns true if its argument is a Java object reference, false otherwise.
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.
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).
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.
memory_usage() -> integer()
Returns an integer corresponding to the number of Java object that are currently known to the Erlang part of the java library.
memory_usage(NodeId::node_id()) -> integer()
Returns an integer corresponding to the number of Java object that are currently known to the Java part of the java library, at the node argument.
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).
node_id(X1::object_ref()) -> node_id()
Returns the node where the object argument is located.
node_is_alive(NodeId::object_ref()) -> boolean()
Returns true if the node is alive, false otherwise.
nodes() -> [node_id()]
Returns the set of active Java nodes.
print_class(NodeId::node_id(), ClassName::class_ref()) -> any()
Outputs to standard output a textual representation of what the library knows about a certain Java class. Mainly useful as a debugging aid.
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.
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.
report_java_exception(Other) -> any()
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.
set(Object::object_ref(), Field::attribute_name(), Value::value()) -> value()
Modifies the value of an instance attribute.
set_loglevel(Level::loglevel()) -> any()
Determines how much debugging information is displayed.
set_static(NodeId::node_id(), ClassName::class_name(), Field::attribute_name(), Value::value()) -> value()
Modifies the value of a static, i.e., class attribute.
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.
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.
string_to_list(String::object_ref()) -> [char()]
Returns the elements of the Java String as an Erlang list.
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.
version() -> string()
Returns the major version number of the JavaErlang library.