Module java

This module implements a facility for invoking Java code (methods, constructors, fields) from Erlang, using the JInterface library.

Copyright © 2011 Lars-Ake Fredlund

Authors: Lars-Ake Fredlund (lfredlund@fi.upm.es).

Description

This module implements a facility for invoking Java code (methods, constructors, fields) from Erlang, using the JInterface library.

Data Types

array_type()

array_type() = {array, type(), integer()}

array_value()

array_value() = string() | [value()]

attribute_name()

attribute_name() = atom()

A name of a Java attribute, represented as an atom.

class_name()

class_name() = atom() | string()

A Java classname, e.g., the quoted atom 'java.lang.Integer'.

float_type()

float_type() = float | double

int_type()

int_type() = int | long | short | char | byte

java_number()

java_number() = integer() | float()

loglevel()

loglevel() = all | none | alert | critical | debug | emergency | error | info | notice | warning

method_name()

method_name() = atom()

A name of a Java method, e.g., the atom 'toString'.

node_id()

abstract datatype: node_id()

-type node_id() :: integer(). Identifies a connected Java node.

number_type()

number_type() = int_type() | float_type()

object_ref()

abstract datatype: object_ref()

-type object_ref() :: {atom(), integer(), node_id()}. A Java object reference.

option()

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()} | {enable_proxies, boolean()} | {call_timeout, integer() | infinity}

primitive_type()

primitive_type() = int_type() | float_type()

type()

type() = primitive_type() | class_name() | array_type()

The representation of a Java types as an Erlang term.

value()

value() = object_ref() | number() | null | true | false | void | array_value() | value_spec()

value_spec()

value_spec() = {int_type(), integer()} | {float_type(), float()} | {class_name, object_ref()} | {array_type(), array_value()}

Function Index

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/2Connects to an already started Java node.
convert/3Widens 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/1Initializes 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/3Convenience 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/1Returns 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/1Sets the timeout value for Java calls.
start_node/0Starts a Java node and establises the connection to Erlang.
start_node/1Starts 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.

Function Details

start_node/0

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

start_node/1

start_node(UserOptions::[option()]) -> {ok, node_id()} | {error, any()}

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.

connect/2

connect(NodeName::atom(), UserOptions::[option()]) -> {ok, node_id()} | {error, any()}

Connects to an already started Java node. Returns a Java library "node identifier" (not a normal Erlang node identifier).

report_java_exception/1

report_java_exception(Other) -> any()

new/3

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/4

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/3

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/4

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/4

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/5

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/2

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/3

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/3

set(Object::object_ref(), Field::attribute_name(), Value::value()) -> value()

Modifies the value of an instance attribute.

set_static/4

set_static(NodeId::node_id(), ClassName::class_name(), Field::attribute_name(), Value::value()) -> value()

Modifies the value of a static, i.e., class attribute.

eq/2

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.

init/1

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/0

default_options() -> [option()]

Returns a list with the default options.

version/0

version() -> string()

Returns the version number of the JavaErlang library.

node_id/1

node_id(X1::object_ref()) -> node_id()

Returns the node where the object argument is located.

symbolic_name/1

symbolic_name(NodeId::node_id()) -> string()

Returns the symbolic name of a Java node.

nodes/0

nodes() -> [node_id()]

Returns the set of active Java nodes.

reset/1

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/1

terminate(NodeId::node_id()) -> any()

Shuts down and terminates the connection to a Java node.

terminate_all/0

terminate_all() -> any()

Shuts down and terminates the connection to all known Java nodes.

brutally_terminate/1

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.

recreate_node/1

recreate_node(NodeId::node_id()) -> {ok, node_id()} | {error, any()}

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/1

free(Object::object_ref()) -> any()

Lets Java know that an object can be freed.

set_timeout/1

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/1

is_object_ref(X1::any()) -> boolean()

Returns true if its argument is a Java object reference, false otherwise.

array_to_list/1

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/3

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/1

string_to_list(String::object_ref()) -> [char()]

Returns the elements of the Java String as an Erlang list.

list_to_string/2

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/3

convert(NodeId::node_id(), Class::number_type(), Number::java_number()) -> java_number()

Widens or narrows a number.

instanceof/2

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/3

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/1

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/1

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/1

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/1

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.

memory_usage/0

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/1

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.

set_loglevel/1

set_loglevel(Level::loglevel()) -> any()

Determines how much debugging information is displayed.


Generated by EDoc, Feb 13 2014, 16:02:03.