The
The set of classes in the package can be divided into two categories: those that provide the actual communication, and those that provide a Java representation of the Erlang data types. The latter are all subclasses of OtpErlangObject, and they are identified by the OtpErlang prefix.
Since this package provides a mechanism for communicating with Erlang,
message recipients can be Erlang processes or instances of
com.ericsson.otp.erlang.OtpMbox, both of which are identified with
pids and possibly registered names. When pids or mailboxes are
mentioned as message senders or recipients in this section, it should
assumed that even Erlang processes are included, unless specified
otherwise.
The classes in
In the following sections, these topics are described:
This section describes the mapping of Erlang basic types to Java.
The atoms
Lists in Erlang are also used to describe sequences of printable characters (strings).
A convenience class
A node as defined by Erlang/OTP is an instance of the Erlang Runtime
System, a virtual machine roughly equivalent to a JVM. Each node has a
unique name in the form of an identifier composed partly of the
hostname on which the node is running, e.g "gurka@sallad.com". Several
such nodes can run on the same host as long as their names are unique.
The class
OtpNode node = new OtpNode("gurka");
Erlang processes running on an Erlang node are identified by process identifiers (pids) and, optionally, by registered names unique within the node. Each Erlang process has an implicit mailbox that is used to receive messages; the mailbox is identified with the pid of the process.
Jinterface provides a similar mechanism with the class
Applications are free to create mailboxes as necessary. This is done as follows:
OtpMbox mbox = node.createMbox();
The mailbox created in the above example has no registered name, although it does have a pid. The pid can be obtained from the mailbox and included in messages sent from the mailbox, so that remote processes are able to respond.
An application can register a name for a mailbox, either when the mailbox is initially created:
OtpMbox mbox = node.createMbox("server");
or later on, as necessary:
OtpMbox mbox = node.createMbox();
mbox.registerName("server");
Registered names are usually necessary in order to start communication, since it is impossible to know in advance the pid of a remote process. If a well-known name for one of the processes is chosen in advance and known by all communicating parties within an application, each mailbox can send an initial message to the named mailbox, which then can identify the sender pid.
It is not necessary to explicitly set up communication with a remote node. Simply sending a message to a mailbox on that node will cause the OtpNode to create a connection if one does not already exist. Once the connection is established, subsequent messages to the same node will reuse the same connection.
It is possible to check for the existence of a remote node before attempting to communicate with it. Here we send a ping message to the remote node to see if it is alive and accepting connections:
if (node.ping("remote",2000)) {
System.out.println("remote is up");
}
else {
System.out.println("remote is not up");
}
If the call to ping() succeeds, a connection to the remote node has been established. Note that it is not necessary to ping remote nodes before communicating with them, but by using ping you can determine if the remote exists before attempting to communicate with it.
Connections are only permitted by nodes using the same security
cookie. The cookie is a short string provided either as an argument
when creating OtpNode objects, or found in the user's home directory
in the file
Connections are never broken explicitly. If a node fails or is closed, a connection may be broken however.
Messages sent with this package must be instances of
In this example, we create a message containing our own pid so the echo process can reply:
OtpErlangObject[] msg = new OtpErlangObject[2];
msg[0] = mbox.self();
msg[1] = new OtpErlangAtom("hello, world");
OtpErlangTuple tuple = new OtpErlangTuple(msg);
When we send the message, a connection will be created:
mbox.send("echo", "gurka@sallad.com", tuple);
And here we receive the reply:
OtpErlangObject reply = mbox.receive();
Messages are sent asynchronously, so the call to
The echo server itself might look like this:
OtpNode self = new OtpNode("gurka");
OtpMbox mbox = self.createMbox("echo");
OtpErlangObject o;
OtpErlangTuple msg;
OtpErlangPid from;
while (true) {
try {
o = mbox.receive();
if (o instanceof OtpErlangTuple) {
msg = (OtpErlangTuple)o;
from = (OtpErlangPid)(msg.elementAt(0));
mbox.send(from,msg.elementAt(1));
}
catch (Exception e) {
System.out.println("" + e);
}
}
In the examples above, only one mailbox was created on each node. however you are free to create as many mailboxes on each node as you like. You are also free to create as many nodes as you like on each JVM, however because each node uses some limited system resources such as file descriptors, it is recommended that you create only a small number of nodes (such as one) on each JVM.
This package was originally intended to be used for communicating between Java and Erlang, and for that reason the send and receive methods all use Java representations of Erlang data types.
However it is possible to use the package to communicate with remote processes written in Java as well, and in these cases it may be desirable to send other data types.
The simplest way to do this is to encapsulate arbitrary data in
messages of type
o = new MyClass(foo);
mbox.send(remote,new OtpErlangBinary(o));
The example above will cause the object to be serialized and encapsulated in an OtpErlangBinary before being sent. The recipient will receive an OtpErlangBinary but can extract the original object from it:
msg = mbox.receive();
if (msg instanceof OtpErlangBinary) {
OtpErlangBinary b = (OtpErlangBinary)msg;
MyClass o = (MyClass)(b.getObject());
}
Erlang defines a concept known as linked processes. A link is an implicit connection between two processes that causes an exception to be raised in one of the processes if the other process terminates for any reason. Links are bidirectional: it does not matter which of the two processes created the link or which of the linked processes eventually terminates; an exception will be raised in the remaining process. Links are also idempotent: at most one link can exist between two given processes, only one operation is necessary to remove the link.
Jinterface provides a similar mechanism. Also here, no distinction is made between mailboxes and Erlang processes. A link can be created to a remote mailbox or process when its pid is known:
mbox.link(remote);
The link can be removed by either of the processes in a similar manner:
mbox.unlink(remote);
If the remote process terminates while the link is still in place, an exception will be raised on a subsequent call to receive():
try {
msg = mbox.receive();
}
catch (OtpErlangExit e) {
System.out.println("Remote pid " + e.pid() + " has terminated");
}
catch (OtpErlangDecodeException f) {
System.out.println("Received message could not be decoded: " + f);
}
When a mailbox is explicitly closed, exit messages will be sent in
order to break any outstanding links. If a mailbox is never closed but
instead goes out of scope, the objects
Epmd is the Erlang Port Mapper Daemon. Distributed Erlang nodes register with epmd on the localhost to indicate to other nodes that they exist and can accept connections. Epmd maintains a register of node and port number information, and when a node wishes to connect to another node, it first contacts epmd in order to find out the correct port number to connect to.
The basic interaction with EPMD is done through instances of
When you use
Java nodes can also register themselves with epmd if they want other
nodes in the system to be able to find and connect to them.
This is done by call to method
Be aware that on some systems (such as VxWorks), a failed node will
not be detected by this mechanism since the operating system does not
automatically close descriptors that were left open when the node
failed. If a node has failed in this way, epmd will prevent you from
registering a new node with the old name, since it thinks that the old
name is still in use. In this case, you must unregister the name
explicitly, by using
This will cause epmd to close the connection from the far end. Note that if the name was in fact still in use by a node, the results of this operation are unpredictable. Also, doing this does not cause the local end of the connection to close, so resources may be consumed.
An Erlang node acting as a client to another Erlang node
typically sends a request and waits for a reply. Such a request is
included in a function call at a remote node and is called a remote
procedure call. Remote procedure calls are supported through the class
OtpSelf self = new OtpSelf("client", "hejsan" );
OtpPeer other = new OtpPeer("server@balin");
OtpConnection connection = self.connect(other);
connection.sendRPC("erlang","date",new OtpErlangList());
OtpErlangObject received = connection.receiveRPC();
In order to use any of the
import com.ericsson.otp.erlang.*;
Determine where the top directory of your OTP installation is. You can find this out by starting Erlang and entering the following command at the Eshell prompt:
Eshell V4.9.1.2 (abort with ^G)
1> code:root_dir().
/usr/local/otp
To compile your code, make sure that your Java compiler knows where
to find the file
$ javac -classpath ".:/usr/local/otp/lib/jinterface-1.2/priv/OtpErlang.jar"
myclass.java
When running your program, you will also need to specify the path to
$ java ".:/usr/local/otp/lib/jinterface-1.2/priv/OtpErlang.jar" myclass
Communication between nodes can be traced by setting a system property
before the communication classes in this package are initialized.
The value system property "OtpConnection.trace" is the default trace
level for all connections. Normally the default trace level is zero,
i.e. no tracing is performed. By setting
Each level also includes the information shown by all lower levels.