aboutsummaryrefslogtreecommitdiffstats
path: root/lib/jinterface/doc/src/jinterface_users_guide.xml
diff options
context:
space:
mode:
authorErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
committerErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
commit84adefa331c4159d432d22840663c38f155cd4c1 (patch)
treebff9a9c66adda4df2106dfd0e5c053ab182a12bd /lib/jinterface/doc/src/jinterface_users_guide.xml
downloadotp-84adefa331c4159d432d22840663c38f155cd4c1.tar.gz
otp-84adefa331c4159d432d22840663c38f155cd4c1.tar.bz2
otp-84adefa331c4159d432d22840663c38f155cd4c1.zip
The R13B03 release.OTP_R13B03
Diffstat (limited to 'lib/jinterface/doc/src/jinterface_users_guide.xml')
-rw-r--r--lib/jinterface/doc/src/jinterface_users_guide.xml448
1 files changed, 448 insertions, 0 deletions
diff --git a/lib/jinterface/doc/src/jinterface_users_guide.xml b/lib/jinterface/doc/src/jinterface_users_guide.xml
new file mode 100644
index 0000000000..7865a0cab4
--- /dev/null
+++ b/lib/jinterface/doc/src/jinterface_users_guide.xml
@@ -0,0 +1,448 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+ <header>
+ <copyright>
+ <year>2000</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>The Jinterface Package</title>
+ <prepared>Gordon Beaton, Babbis Xagorarakis</prepared>
+ <responsible>Gordon Beaton, Babbis Xagorarakis</responsible>
+ <docno></docno>
+ <approved></approved>
+ <checked></checked>
+ <date>000822</date>
+ <rev>A</rev>
+ <file>jinterface_users_guide.xml</file>
+ </header>
+ <p>The <seealso marker="java/com/ericsson/otp/erlang/package-summary">Jinterface</seealso> package provides
+ a set of tools for communication with Erlang processes. It can also be used for communication with
+ other Java processes using the same package, as well as C processes using the Erl_Interface library. </p>
+ <p>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.</p>
+ <p>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
+ <seealso marker="java/com/ericsson/otp/erlang/package-summary">Jinterface</seealso> support the following:</p>
+ <list type="bulleted">
+ <item>manipulation of data represented as Erlang data types</item>
+ <item>conversion of data between Java and Erlang formats</item>
+ <item>encoding and decoding of Erlang data types for transmission or storage</item>
+ <item>communication between Java nodes and Erlang processes</item>
+ </list>
+ <p>In the following sections, these topics are described:</p>
+ <list type="bulleted">
+ <item>mapping of Erlang types to Java</item>
+ <item>encoding, decoding, and sending Erlang terms</item>
+ <item>connecting to a distributed Erlang node</item>
+ <item>using nodes, mailboxes and EPMD</item>
+ <item>sending and receiving Erlang messages and data</item>
+ <item>remote procedure calls</item>
+ <item>linking to remote processes</item>
+ <item>compiling your code for use with Jinterface</item>
+ <item>tracing message flow</item>
+ </list>
+
+ <section>
+ <title>Mapping of Basic Erlang Types to Java</title>
+ <p>This section describes the mapping of Erlang basic types to Java. </p>
+ <table>
+ <row>
+ <cell align="left" valign="middle">Erlang type</cell>
+ <cell align="left" valign="middle">Java type</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">atom</cell>
+ <cell align="left" valign="middle"><seealso marker="java/com/ericsson/otp/erlang/OtpErlangAtom">OtpErlangAtom</seealso></cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">binary</cell>
+ <cell align="left" valign="middle"><seealso marker="java/com/ericsson/otp/erlang/OtpErlangBinary">OtpErlangBinary</seealso></cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">floating point types</cell>
+ <cell align="left" valign="middle"><seealso marker="java/com/ericsson/otp/erlang/OtpErlangFloat">OtpErlangFloat</seealso>or <seealso marker="java/com/ericsson/otp/erlang/OtpErlangDouble">OtpErlangDouble</seealso>, depending on the floating point value size</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">integral types</cell>
+ <cell align="left" valign="middle">One of <seealso marker="java/com/ericsson/otp/erlang/OtpErlangByte">OtpErlangByte</seealso>,<seealso marker="java/com/ericsson/otp/erlang/OtpErlangChar">OtpErlangChar</seealso>,<seealso marker="java/com/ericsson/otp/erlang/OtpErlangShort">OtpErlangShort</seealso>,<seealso marker="java/com/ericsson/otp/erlang/OtpErlangUShort">OtpErlangUShort</seealso>,<seealso marker="java/com/ericsson/otp/erlang/OtpErlangInt">OtpErlangInt</seealso>,<seealso marker="java/com/ericsson/otp/erlang/OtpErlangUInt">OtpErlangUInt</seealso>or<seealso marker="java/com/ericsson/otp/erlang/OtpErlangLong">OtpErlangLong</seealso>, depending on the integral value size and sign</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">list</cell>
+ <cell align="left" valign="middle"><seealso marker="java/com/ericsson/otp/erlang/OtpErlangList">OtpErlangList</seealso></cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">pid</cell>
+ <cell align="left" valign="middle"><seealso marker="java/com/ericsson/otp/erlang/OtpErlangPid">OtpErlangPid</seealso></cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">port</cell>
+ <cell align="left" valign="middle"><seealso marker="java/com/ericsson/otp/erlang/OtpErlangPort">OtpErlangPort</seealso></cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">ref</cell>
+ <cell align="left" valign="middle"><seealso marker="java/com/ericsson/otp/erlang/OtpErlangRef">OtpErlangRef</seealso></cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">tuple</cell>
+ <cell align="left" valign="middle"><seealso marker="java/com/ericsson/otp/erlang/OtpErlangTuple">OtpErlangTuple</seealso></cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">term</cell>
+ <cell align="left" valign="middle"><seealso marker="java/com/ericsson/otp/erlang/OtpErlangObject">OtpErlangObject</seealso></cell>
+ </row>
+ <tcaption>Mapping of Erlang basic types to Java</tcaption>
+ </table>
+ </section>
+
+ <section>
+ <title>Special Mapping Issues</title>
+ <p>The atoms <c>true</c> and <c>false</c> are special atoms, used as boolean values.
+ The class <seealso marker="java/com/ericsson/otp/erlang/OtpErlangBoolean">OtpErlangBoolean</seealso> can be used to represent these.</p>
+ <p>Lists in Erlang are also used to describe sequences of printable characters (strings).
+ A convenience class <seealso marker="java/com/ericsson/otp/erlang/OtpErlangString">OtpErlangString</seealso>
+ is provided to represent Erlang strings.</p>
+ </section>
+
+ <section>
+ <title>Nodes</title>
+ <p>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 "[email protected]". Several
+ such nodes can run on the same host as long as their names are unique.
+ The class <seealso marker="java/com/ericsson/otp/erlang/OtpNode">OtpNode</seealso>
+ represents an Erlang node. It is created with a name
+ and optionally a port number on which it listens for incoming
+ connections. Before creating an instance of
+ <seealso marker="java/com/ericsson/otp/erlang/OtpNode">OtpNode</seealso>,
+ ensure that Epmd is running on the host machine. See the Erlang documentation
+ for more information about Epmd. In this example, the host name is appended
+ automatically to the identifier, and the port number is chosen by the
+ underlying system:</p>
+ <code type="none">
+OtpNode node = new OtpNode("gurka"); </code>
+ </section>
+
+ <section>
+ <title>Mailboxes</title>
+ <p>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.</p>
+ <p>Jinterface provides a similar mechanism with the class
+ <seealso marker="java/com/ericsson/otp/erlang/OtpMbox">OtpMbox</seealso>, a
+ mailbox that can be used to send and receive messages asynchronously.
+ Each OtpMbox is identified with a unique pid and , optionally, a registered
+ name unique within the
+ <seealso marker="java/com/ericsson/otp/erlang/OtpNode">OtpNode</seealso>. </p>
+ <p>Applications are free to create mailboxes as necessary. This is done
+ as follows:</p>
+ <code type="none">
+ OtpMbox mbox = node.createMbox(); </code>
+ <p>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. </p>
+ <p>An application can register a name for a mailbox, either when the
+ mailbox is initially created:</p>
+ <code type="none">
+ OtpMbox mbox = node.createMbox("server"); </code>
+ <p>or later on, as necessary:</p>
+ <code type="none">
+ OtpMbox mbox = node.createMbox();
+ mbox.registerName("server"); </code>
+ <p>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.</p>
+ </section>
+
+ <section>
+ <title>Connections</title>
+ <p>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.</p>
+ <p>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:</p>
+ <code type="none">
+ if (node.ping("remote",2000)) {
+ System.out.println("remote is up");
+ }
+ else {
+ System.out.println("remote is not up");
+ } </code>
+ <p>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.</p>
+ <p>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 <c>.erlang.cookie</c>. When a connection attempt is made, the
+ string is used as part of the authentication process. If you are
+ having trouble getting communication to work, use the trace facility
+ (described later in this document) to show the connection
+ establishment. A likely problem is that the cookies are different.</p>
+ <p>Connections are never broken explicitly. If a node fails or is closed,
+ a connection may be broken however.</p>
+ </section>
+
+ <section>
+ <title>Sending and Receiving Messages</title>
+ <p>Messages sent with this package must be instances of
+ <seealso marker="java/com/ericsson/otp/erlang/OtpErlangObject">OtpErlangObject</seealso>
+ or one of its subclasses. Message can be sent to processes or pids,
+ either by specifying the pid of the remote, or its registered name and
+ node.</p>
+ <p>In this example, we create a message containing our own pid so the
+ echo process can reply:</p>
+ <code type="none">
+ OtpErlangObject[] msg = new OtpErlangObject[2];
+ msg[0] = mbox.self();
+ msg[1] = new OtpErlangAtom("hello, world");
+ OtpErlangTuple tuple = new OtpErlangTuple(msg); </code>
+ <p>When we send the message, a connection will be created:</p>
+ <code type="none">
+ mbox.send("echo", "[email protected]", tuple); </code>
+ <p>And here we receive the reply:</p>
+ <code type="none">
+ OtpErlangObject reply = mbox.receive(); </code>
+ <p>Messages are sent asynchronously, so the call to <c>send()</c> returns as
+ soon as the message has been dispatched to the underlying
+ communication layer. This means that you receive no indication whether
+ the operation completed successfully or the remote even existed. If
+ you need this kind of confirmation, you should wait for a response
+ from the remote process.</p>
+ <p>The echo server itself might look like this:</p>
+ <code type="none">
+ 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);
+ }
+ } </code>
+ <p>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.</p>
+ </section>
+
+ <section>
+ <title>Sending Arbitrary Data</title>
+ <p>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. </p>
+ <p>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.</p>
+ <p>The simplest way to do this is to encapsulate arbitrary data in
+ messages of type
+ <seealso marker="java/com/ericsson/otp/erlang/OtpErlangBinary">OtpErlangBinary</seealso>.
+ The OtpErlangBinary class can be created from arbitrary Java objects that implement the
+ Serializable or Externalizable interface:</p>
+ <code type="none">
+ o = new MyClass(foo);
+ mbox.send(remote,new OtpErlangBinary(o)); </code>
+ <p>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:</p>
+ <code type="none">
+ msg = mbox.receive();
+ if (msg instanceof OtpErlangBinary) {
+ OtpErlangBinary b = (OtpErlangBinary)msg;
+ MyClass o = (MyClass)(b.getObject());
+ } </code>
+ </section>
+
+ <section>
+ <title>Linking to Remote Processes</title>
+ <p>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.</p>
+ <p>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:</p>
+ <code type="none">
+ mbox.link(remote); </code>
+ <p>The link can be removed by either of the processes in a similar manner:</p>
+ <code type="none">
+ mbox.unlink(remote); </code>
+ <p>If the remote process terminates while the link is still in place, an
+ exception will be raised on a subsequent call to receive():</p>
+ <code type="none">
+ 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);
+ } </code>
+ <p>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 <c>finalize()</c> method will call
+ <c>close()</c>. However since Java provides no guarantees about when or even
+ if finalize() will be called, it is important that your application
+ explicitly closes mailboxes when they are no longer needed if you
+ want links to work in a timely manner.
+ </p>
+ </section>
+
+ <section>
+ <title>Using EPMD</title>
+ <p>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.</p>
+ <p>The basic interaction with EPMD is done through instances of
+ <seealso marker="java/com/ericsson/otp/erlang/OtpEpmd">OtpEpmd</seealso> class.
+ Nodes wishing to contact other nodes must first request information
+ from Epmd before a connection can be set up, however this is done automatically
+ by <seealso marker="java/com/ericsson/otp/erlang/OtpSelf#connect(com.ericsson.otp.erlang.OtpPeer)">OtpSelf.connect()</seealso> when necessary. </p>
+ <p>When you use <seealso marker="java/com/ericsson/otp/erlang/OtpSelf#connect(com.ericsson.otp.erlang.OtpPeer)">OtpSelf.connect()</seealso> to connect to an Erlang node,
+ a connection is first made to epmd and, if the node is known, a
+ connection is then made to the Erlang node.</p>
+ <p>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 <seealso marker="java/com/ericsson/otp/erlang/OtpEpmd#publishPort(com.ericsson.otp.erlang.OtpLocalNode)">OtpEpmd.publishPort()</seealso>.</p>
+ <p>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 <seealso marker="java/com/ericsson/otp/erlang/OtpEpmd#unPublishPort(com.ericsson.otp.erlang.OtpLocalNode)">OtpEpmd.unPublishPort()</seealso></p>
+ <p>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.</p>
+ </section>
+
+ <section>
+ <title>Remote Procedure Calls</title>
+ <p>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
+ <seealso marker="java/com/ericsson/otp/erlang/OtpConnection">OtpConnection</seealso>.
+ The following example shows how the
+ <seealso marker="java/com/ericsson/otp/erlang/OtpConnection">OtpConnection</seealso>
+ class is used for remote procedure calls:</p>
+ <code type="none">
+
+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();
+ </code>
+ <p><c>erlang:date/0</c> is just called to get the date tuple
+ from a remote host. </p>
+ </section>
+
+ <section>
+ <title>Compiling and Loading Your Code</title>
+ <p>In order to use any of the <seealso marker="java/com/ericsson/otp/erlang/package-summary">Jinterface</seealso>
+ classes, include the following line in your code:</p>
+ <code type="none">
+import com.ericsson.otp.erlang.*; </code>
+ <p>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:</p>
+ <code type="none">
+Eshell V4.9.1.2 (abort with ^G)
+1> code:root_dir().
+/usr/local/otp </code>
+ <p>To compile your code, make sure that your Java compiler knows where
+ to find the file <c>OtpErlang.jar</c> which contains the package.
+ This is done by specifying an appropriate <c>-classpath</c>
+ argument on the command line, or by adding it to the <c>CLASSPATH</c>
+ definition in your <c>Makefile</c>. The correct value for this path is
+ <c>$OTPROOT/lib/jinterface</c><em>Vsn</em><c>/priv/OtpErlang.jar</c>, where <c>$OTPROOT</c>
+ is the path reported by <c>code:root_dir/0</c> in the above example and <em>Vsn</em> is the version of Jinterface, for example <c>jinterface-1.2</c></p>
+ <code type="none">
+$ javac -classpath ".:/usr/local/otp/lib/jinterface-1.2/priv/OtpErlang.jar"
+ myclass.java </code>
+ <p>When running your program, you will also need to specify the path to
+ <c>OtpErlang.jar</c> in a similar way.</p>
+ <code type="none">
+$ java ".:/usr/local/otp/lib/jinterface-1.2/priv/OtpErlang.jar" myclass </code>
+ </section>
+
+ <section>
+ <title>Tracing</title>
+ <p>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
+ <seealso marker="java/com/ericsson/otp/erlang/OtpConnection">OtpConnection.trace</seealso>
+ to some non-zero value, the communication protocol can be shown in more or
+ less detail. The valid values are:</p>
+ <list type="bulleted">
+ <item>0: no tracing is performed</item>
+ <item>1: only ordinary send and reg-send messages are shown</item>
+ <item>2: control messages such as link, unlink and exit are shown</item>
+ <item>3: connection setup (handshake) is shown</item>
+ <item>4: epmd requests are shown</item>
+ </list>
+ <p>Each level also includes the information shown by all lower levels.</p>
+ </section>
+</chapter>
+