From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- lib/jinterface/doc/src/Makefile | 173 +++++++++ lib/jinterface/doc/src/book.xml | 49 +++ lib/jinterface/doc/src/fascicules.xml | 18 + lib/jinterface/doc/src/index.html.src | 98 +++++ lib/jinterface/doc/src/jinterface.xml | 49 +++ lib/jinterface/doc/src/jinterface_users_guide.xml | 448 ++++++++++++++++++++++ lib/jinterface/doc/src/make.dep | 20 + lib/jinterface/doc/src/notes.gif | Bin 0 -> 2005 bytes lib/jinterface/doc/src/notes.xml | 306 +++++++++++++++ lib/jinterface/doc/src/notes_history.xml | 188 +++++++++ lib/jinterface/doc/src/part.xml | 35 ++ lib/jinterface/doc/src/part_notes.xml | 38 ++ lib/jinterface/doc/src/part_notes_history.xml | 36 ++ lib/jinterface/doc/src/ref_man.gif | Bin 0 -> 1530 bytes lib/jinterface/doc/src/ref_man.xml | 36 ++ lib/jinterface/doc/src/summary.html.src | 1 + lib/jinterface/doc/src/user_guide.gif | Bin 0 -> 1581 bytes 17 files changed, 1495 insertions(+) create mode 100644 lib/jinterface/doc/src/Makefile create mode 100644 lib/jinterface/doc/src/book.xml create mode 100644 lib/jinterface/doc/src/fascicules.xml create mode 100644 lib/jinterface/doc/src/index.html.src create mode 100644 lib/jinterface/doc/src/jinterface.xml create mode 100644 lib/jinterface/doc/src/jinterface_users_guide.xml create mode 100644 lib/jinterface/doc/src/make.dep create mode 100644 lib/jinterface/doc/src/notes.gif create mode 100644 lib/jinterface/doc/src/notes.xml create mode 100644 lib/jinterface/doc/src/notes_history.xml create mode 100644 lib/jinterface/doc/src/part.xml create mode 100644 lib/jinterface/doc/src/part_notes.xml create mode 100644 lib/jinterface/doc/src/part_notes_history.xml create mode 100644 lib/jinterface/doc/src/ref_man.gif create mode 100644 lib/jinterface/doc/src/ref_man.xml create mode 100644 lib/jinterface/doc/src/summary.html.src create mode 100644 lib/jinterface/doc/src/user_guide.gif (limited to 'lib/jinterface/doc/src') diff --git a/lib/jinterface/doc/src/Makefile b/lib/jinterface/doc/src/Makefile new file mode 100644 index 0000000000..c4cfde0e9c --- /dev/null +++ b/lib/jinterface/doc/src/Makefile @@ -0,0 +1,173 @@ +# -*-Makefile-*- + +# +# %CopyrightBegin% +# +# Copyright Ericsson AB 2000-2009. All Rights Reserved. +# +# 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. +# +# %CopyrightEnd% +# +include $(ERL_TOP)/make/target.mk +include $(ERL_TOP)/make/$(TARGET)/otp.mk + +# ---------------------------------------------------- +# Application version +# ---------------------------------------------------- +include ../../vsn.mk +VSN=$(JINTERFACE_VSN) +APPLICATION=jinterface + +# ---------------------------------------------------- +# Release directory specification +# ---------------------------------------------------- +RELSYSDIR = $(RELEASE_PATH)/lib/$(APPLICATION)-$(VSN) + +# ---------------------------------------------------- +# Target Specs +# ---------------------------------------------------- + +# Renamed this var to fool otp.mk.in +XML_APP_FILES = ref_man.xml +XML_REF3_FILES = jinterface.xml + +XML_PART_FILES = \ + part.xml \ + part_notes.xml \ + part_notes_history.xml + +XML_CHAPTER_FILES = \ + notes.xml \ + notes_history.xml \ + jinterface_users_guide.xml + +BOOK_FILES = book.xml + +GIF_FILES = \ + notes.gif \ + ref_man.gif \ + user_guide.gif + +#------------------------------------------------------ + + +HTML_REF_MAN_FILE = $(HTMLDIR)/index.html + +TOP_PDF_FILE = $(PDFDIR)/$(APPLICATION)-$(VSN).pdf + + +JAVADOC = javadoc +JAVADOC_PKGS = com.ericsson.otp.erlang +JAVA_PKG_PATH = com/ericsson/otp/erlang +JAVADOC_TITLE = 'Java-Erlang Interface Library' +JAVADOC_DEST = ../doc/html/java +JAVA_SRC_PATH = $(ERL_TOP)/lib/$(APPLICATION)/java_src/$(JAVA_PKG_PATH) + +# don't add filenames to the Makefile! +# all java sourcefiles listed in common include file +include $(JAVA_SRC_PATH)/java_files + +JAVA_SRC_FILES = $(JAVA_FILES:%=$(JAVA_SRC_PATH)/%.java) + +JAVA_DOC_FILES = \ + overview-tree.html \ + index-all.html \ + deprecated-list.html \ + allclasses-frame.html \ + index.html \ + serialized-form.html \ + package-list \ + stylesheet.css \ + help-doc.html + +INFO_FILE = ../../info +JAVA_EXTRA_FILES = $(JAVA_DOC_FILES:%=$(HTMLDIR)/java/%) + +JAVA_GEN_FILES = \ + $(JAVA_FILES:%=$(JAVADOC_DEST)/$(JAVA_PKG_PATH)/%.html) \ + $(JAVADOC_DEST)/$(JAVA_PKG_PATH)/package-summary.html \ + $(JAVADOC_DEST)/$(JAVA_PKG_PATH)/package-tree.html \ + $(JAVADOC_DEST)/$(JAVA_PKG_PATH)/package-frame.html + + +# ---------------------------------------------------- + + +HTML_FILES = \ + $(XML_PART_FILES:%.xml=$(HTMLDIR)/%.html) + +TOP_HTML_FILES = $(INDEX_TARGET) + +INDEX_FILE = index.html +INDEX_SRC = $(INDEX_FILE).src +INDEX_TARGET = $(DOCDIR)/$(INDEX_FILE) + +# ---------------------------------------------------- +# FLAGS +# ---------------------------------------------------- +XML_FLAGS += +DVIPS_FLAGS += + +# ---------------------------------------------------- +# Targets +# ---------------------------------------------------- +$(HTMLDIR)/%.gif: %.gif + $(INSTALL_DATA) $< $@ + +docs: pdf html jdoc man + +$(TOP_PDF_FILE): $(XML_FILES) + +pdf: $(TOP_PDF_FILE) + +html: gifs $(HTML_REF_MAN_FILE) + +clean clean_docs: + rm -rf $(HTMLDIR)/* + rm -f $(MAN3DIR)/* + rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo) + rm -f errs core *~ + +jdoc:$(JAVA_SRC_FILES) + (cd ../../java_src;$(JAVADOC) -sourcepath . -d $(JAVADOC_DEST) \ + -windowtitle $(JAVADOC_TITLE) $(JAVADOC_PKGS)) + +man: + +gifs: $(GIF_FILES:%=$(HTMLDIR)/%) + +#$(INDEX_TARGET): $(INDEX_SRC) ../../vsn.mk +# sed -e 's;%VSN%;$(VSN);' $< > $@ + +debug opt: + +# ---------------------------------------------------- +# Release Target +# ---------------------------------------------------- +include $(ERL_TOP)/make/otp_release_targets.mk + +release_docs_spec: docs + $(INSTALL_DIR) $(RELSYSDIR)/doc/pdf + $(INSTALL_DATA) $(TOP_PDF_FILE) $(RELSYSDIR)/doc/pdf + $(INSTALL_DIR) $(RELSYSDIR)/doc/html + $(INSTALL_DIR) $(RELSYSDIR)/doc/html/java/$(JAVA_PKG_PATH) + $(INSTALL_DATA) $(INFO_FILE) $(RELSYSDIR) + (/bin/cp -rf ../html $(RELSYSDIR)/doc) + +# $(INSTALL_DATA) $(GIF_FILES) $(EXTRA_FILES) $(HTML_FILES) \ +# $(RELSYSDIR)/doc/html +# $(INSTALL_DATA) $(JAVA_EXTRA_FILES) $(RELSYSDIR)/doc/html/java +# $(INSTALL_DATA) $(TOP_HTML_FILES) $(RELSYSDIR)/doc + + +release_spec: diff --git a/lib/jinterface/doc/src/book.xml b/lib/jinterface/doc/src/book.xml new file mode 100644 index 0000000000..ce40510643 --- /dev/null +++ b/lib/jinterface/doc/src/book.xml @@ -0,0 +1,49 @@ + + + + +
+ + 20002009 + Ericsson AB. All Rights Reserved. + + + 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. + + + + jinterface + Gordon Beaton, Babbis Xagorarakis + + 2000-08-25 + 1.2 + book.sgml +
+ + + jinterface + + + + + + + + + + + + + + + + diff --git a/lib/jinterface/doc/src/fascicules.xml b/lib/jinterface/doc/src/fascicules.xml new file mode 100644 index 0000000000..099e50c332 --- /dev/null +++ b/lib/jinterface/doc/src/fascicules.xml @@ -0,0 +1,18 @@ + + + + + + User Guide + + + Java API + + + Release Notes + + + Off-Print + + + diff --git a/lib/jinterface/doc/src/index.html.src b/lib/jinterface/doc/src/index.html.src new file mode 100644 index 0000000000..76c304d4fe --- /dev/null +++ b/lib/jinterface/doc/src/index.html.src @@ -0,0 +1,98 @@ + + + + + +Jinterface %VSN% + + + + +
+Erlang/OTP
+ + +[Up | +Erlang/OTP] +
+ +

Jinterface
+Version %VSN% +

+ +

+ + + + + +
+ +Jinterface contains functions, +which help you integrate programs written in Java and Erlang. +
+ +

+ + + + + + + + + + + + + + +
+ +User Guide
+ +User Guide + +		 +Java API
+ +Java API + +		 +Release Notes
+ +Release Notes + +
+
+ +

+
+ +Copyright © 1991-2001 +Ericsson Utvecklings AB + +
+ + + + + + diff --git a/lib/jinterface/doc/src/jinterface.xml b/lib/jinterface/doc/src/jinterface.xml new file mode 100644 index 0000000000..bf3a531749 --- /dev/null +++ b/lib/jinterface/doc/src/jinterface.xml @@ -0,0 +1,49 @@ + + + + +
+ + 20002009 + Ericsson AB. All Rights Reserved. + + + 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. + + + + jinterface + + + + +
+ jinterface + A Java communication tool to Erlang. + +

Jinterface Java package contains java classes, which help you + integrate programs written in Java with Erlang. The reference + documentation is available only on the web in Javadoc format.

+ +

By default, the jinterface library is only guaranteed + to be compatible with other Erlang/OTP components from the same + release as the jinterface library itself. See the documentation + of the OtpCompatRel property in the Java API documentation.

+ + + +
+ See Also +

Jinterface User's Guide

+
+ + 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 @@ + + + + +
+ + 20002009 + Ericsson AB. All Rights Reserved. + + + 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. + + + + The Jinterface Package + Gordon Beaton, Babbis Xagorarakis + Gordon Beaton, Babbis Xagorarakis + + + + 000822 + A + jinterface_users_guide.xml +
+

The Jinterface 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.

+

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 + Jinterface support the following:

+ + manipulation of data represented as Erlang data types + conversion of data between Java and Erlang formats + encoding and decoding of Erlang data types for transmission or storage + communication between Java nodes and Erlang processes + +

In the following sections, these topics are described:

+ + mapping of Erlang types to Java + encoding, decoding, and sending Erlang terms + connecting to a distributed Erlang node + using nodes, mailboxes and EPMD + sending and receiving Erlang messages and data + remote procedure calls + linking to remote processes + compiling your code for use with Jinterface + tracing message flow + + +
+ Mapping of Basic Erlang Types to Java +

This section describes the mapping of Erlang basic types to Java.

+ + + Erlang type + Java type + + + atom + OtpErlangAtom + + + binary + OtpErlangBinary + + + floating point types + OtpErlangFloator OtpErlangDouble, depending on the floating point value size + + + integral types + One of OtpErlangByte,OtpErlangChar,OtpErlangShort,OtpErlangUShort,OtpErlangInt,OtpErlangUIntorOtpErlangLong, depending on the integral value size and sign + + + list + OtpErlangList + + + pid + OtpErlangPid + + + port + OtpErlangPort + + + ref + OtpErlangRef + + + tuple + OtpErlangTuple + + + term + OtpErlangObject + + Mapping of Erlang basic types to Java +
+
+ +
+ Special Mapping Issues +

The atoms true and false are special atoms, used as boolean values. + The class OtpErlangBoolean can be used to represent these.

+

Lists in Erlang are also used to describe sequences of printable characters (strings). + A convenience class OtpErlangString + is provided to represent Erlang strings.

+
+ +
+ Nodes +

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 + 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 + OtpNode, + 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:

+ +OtpNode node = new OtpNode("gurka"); +
+ +
+ Mailboxes +

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 + OtpMbox, 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 + OtpNode.

+

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.

+
+ +
+ Connections +

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 .erlang.cookie. 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.

+

Connections are never broken explicitly. If a node fails or is closed, + a connection may be broken however.

+
+ +
+ Sending and Receiving Messages +

Messages sent with this package must be instances of + OtpErlangObject + 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.

+

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

+

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.

+
+ +
+ Sending Arbitrary Data +

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 + OtpErlangBinary. + The OtpErlangBinary class can be created from arbitrary Java objects that implement the + Serializable or Externalizable interface:

+ + 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()); + } +
+ +
+ Linking to Remote Processes +

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 finalize() method will call + close(). 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. +

+
+ +
+ Using EPMD +

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 + OtpEpmd 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 OtpSelf.connect() when necessary.

+

When you use OtpSelf.connect() 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.

+

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 OtpEpmd.publishPort().

+

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 OtpEpmd.unPublishPort()

+

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.

+
+ +
+ Remote Procedure Calls +

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 + OtpConnection. + The following example shows how the + OtpConnection + class is used for remote procedure calls:

+ + +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(); + +

erlang:date/0 is just called to get the date tuple + from a remote host.

+
+ +
+ Compiling and Loading Your Code +

In order to use any of the Jinterface + classes, include the following line in your code:

+ +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 OtpErlang.jar which contains the package. + This is done by specifying an appropriate -classpath + argument on the command line, or by adding it to the CLASSPATH + definition in your Makefile. The correct value for this path is + $OTPROOT/lib/jinterfaceVsn/priv/OtpErlang.jar, where $OTPROOT + is the path reported by code:root_dir/0 in the above example and Vsn is the version of Jinterface, for example jinterface-1.2

+ +$ 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 + OtpErlang.jar in a similar way.

+ +$ java ".:/usr/local/otp/lib/jinterface-1.2/priv/OtpErlang.jar" myclass +
+ +
+ Tracing +

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 + OtpConnection.trace + to some non-zero value, the communication protocol can be shown in more or + less detail. The valid values are:

+ + 0: no tracing is performed + 1: only ordinary send and reg-send messages are shown + 2: control messages such as link, unlink and exit are shown + 3: connection setup (handshake) is shown + 4: epmd requests are shown + +

Each level also includes the information shown by all lower levels.

+
+ + diff --git a/lib/jinterface/doc/src/make.dep b/lib/jinterface/doc/src/make.dep new file mode 100644 index 0000000000..a1b3c322c6 --- /dev/null +++ b/lib/jinterface/doc/src/make.dep @@ -0,0 +1,20 @@ +# ---------------------------------------------------- +# >>>> Do not edit this file <<<< +# This file was automaticly generated by +# /home/otp/bin/docdepend +# ---------------------------------------------------- + + +# ---------------------------------------------------- +# TeX files that the DVI file depend on +# ---------------------------------------------------- + +book.dvi: book.tex jinterface.tex jinterface_users_guide.tex \ + part.tex ref_man.tex + +# ---------------------------------------------------- +# Source inlined when transforming from source to LaTeX +# ---------------------------------------------------- + +book.tex: ref_man.xml + diff --git a/lib/jinterface/doc/src/notes.gif b/lib/jinterface/doc/src/notes.gif new file mode 100644 index 0000000000..e000cca26a Binary files /dev/null and b/lib/jinterface/doc/src/notes.gif differ diff --git a/lib/jinterface/doc/src/notes.xml b/lib/jinterface/doc/src/notes.xml new file mode 100644 index 0000000000..90ac2991f3 --- /dev/null +++ b/lib/jinterface/doc/src/notes.xml @@ -0,0 +1,306 @@ + + + + +
+ + 20002009 + Ericsson AB. All Rights Reserved. + + + 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. + + + + Jinterface Release Notes + otp_appnotes + nil + nil + nil + notes.xml +
+

This document describes the changes made to the Jinterface application.

+ +
Jinterface 1.5.2 + +
Improvements and New Features + + +

+ The documentation is now built with open source tools + (xsltproc and fop) that exists on most platforms. One + visible change is that the frames are removed.

+

+ Own Id: OTP-8201

+ + +
+ +
+ +
Jinterface 1.5.1 + +
Fixed Bugs and Malfunctions + + +

+ Many Erlang classes, e.g. OtpErlangRef, was missing an + implementation of the hashCode() method, making it futile + to put them in hash structures such as HashMap. Bug and + patch provided by Paul Guyot. We extended the patch to + all classes and improved (?) on the hash algorithm.

+

+ Own Id: OTP-7899

+ + +
+ + +
Improvements and New Features + + +

+ jinterface uses the new environment variable + ERL_EPMD_PORT the same way that erl, epmd and + erl_interface do since R13A.

+

+ Own Id: OTP-7885

+ + +
+ +
+ +
Jinterface 1.5 + +
Improvements and New Features + + +

+ A number of fixes and improvements from the ErlIDE group; + Vlad Dumitrescu and Jakob Cederlund: JDK 1.5 is now a + minimal requirement for building Jinterface. New method: + OtpEpmd.lookupNames. OtpErlangList is now iterable. + Non-proper lists are now allowed - you have to test if a + list is proper or not. Non-proper lists can also be + created. New methods: isProper, getHead, getTail and + getNthTail. The get tail methods creates a sublist object + that re-uses the original list. OtpErlangPid is now + Comparable. Empty atoms can now be constructed, a missing + feature pointed out by Sebastien Boisgerault on + erlang-questions.

+

+ *** POTENTIAL INCOMPATIBILITY ***

+

+ Own Id: OTP-7832

+ + +
+ +
+ +
Jinterface 1.4.2 + +
Fixed Bugs and Malfunctions + + +

+ A bug when Jinterface did not detect remote node + disconnects has been corrected.

+

+ Own Id: OTP-7624

+ + +
+ +
+ +
Jinterface 1.4.1 + +
Fixed Bugs and Malfunctions + + +

+ Jinterface has been fixed to use the loopback interface + when connecting to the Erlang Port Mapper Daemon - epmd. + This facilitates firewall configuration and saves + resources.

+

+ Own Id: OTP-7103

+ + +

Jinterface now refuses to connect to another node that + does not agree on the other node's name. This has been a + problem in that a connection was set up, but not used on + a following send, which caused a second erroneous + connection attempt to fail since the other (Erlang) node + rejects a connection due to name disagreement.

+

Problem reported and dissected by Alexander Lamb

+

+ Own Id: OTP-7330

+ + +
+ +
+ +
Jinterface 1.4 + +
Improvements and New Features + + +

Jinterface has been updated to handle compressed + terms, bitstring, new (IEEE) floats and bignums. This has + caused a few incompatibilities.

+

com.ericsson.otp.erlang.OtpOutputStream now extends + java.io.ByteArrayOutputStream, previously + java.lang.Object, and hence the method size() now return + the number of bytes in the stream as dictated by the new + parent class and not the buffer length as before. The new + method length() returns what the old size() did return. + The method count() is deprecated as it returns the same + as the new size().

+

com.ericsson.otp.erlang.OtpErlangLong now can handle + larger values than 64-bit. Previously when larger than + 64-bit integers were sent to a Jinterface node, it caused + an com.ericsson.otp.erlang.OtpDecodeException. Now the + integer is accepted, but the return value of longValue() + is silently truncated, as opposed to the return value of + intValue() that now and previously raises an + com.ericsson.otp.erlang.OtpRangeException for + unrepresentable values. The new methods isLong() and + isULong() can be used to determine if the value fits in a + long.

+

+ *** POTENTIAL INCOMPATIBILITY ***

+

+ Own Id: OTP-6809

+ + +
+ +
+ +
+ Jinterface 1.3 + +
+ Fixed Bugs and Malfunctions + + +

OtpMbox.receive() and OtpMbox.receive(long timeout) can now throw + OtpErlangDecodeException if the received message + can not be decoded. null is now only returned from + OtpMbox.receive(long timeout) if a timeout occurs. + OtpMbox.receive() will never return null.

+

*** POTENTIAL INCOMPATIBILITY ***

+

Own Id: OTP-3932 Aux Id: seq5196

+ + +

Strings longer than 65535 bytes were encoded wrong by + jinterface.

+

Own Id: OTP-4883 Aux Id: OTP-4865

+ + +

Misc bugfixes:

+ + +

A node pinging itself does no + longer cause the java program to hang.

+

+ + +

OtpMbox.close() uses exit reason + 'normal' (atom) instead of "normal" + (string).

+

+ + +

Added OtpNode.closeMbox(OtpMbox mbox, OtpErlangObject reason).

+

+ + +

Added OtpMbox.exit(OtpErlangObject reason) + and OtpMbox.exit(String reason).

+

+ + +

Added OtpMbox.exit(OtpErlangPid to, OtpErlangObject reason).

+

+ + +

OtpMbox.exit(OtpErlangPid to, String reason) + is now equivalent to OtpMbox.exit(to, new OtpErlangAtom(reason)).

+

+ + Exit signals from an Erlang node can now contain + any erlang term as reason, not only atoms. + +

Own Id: OTP-5088

+ + +

For java versions 1.3.1 or later, localStatus was + not sent to registered status handler when + OtpNode.close() was called. This is now corrected.

+

Own Id: OTP-5169

+ + +
+ +
+ Improvements and New Features + + +

Process identifiers and port identifiers have been + made more unique. Previously 18 bits were used as id in + the internal representation of process and port + identifiers. Now 28 bits are used.

+

The maximum + limit on the number of concurrently existing processes + due to the representation of pids has been increased to + 268435456 processes. The same is true for ports. This + limit will at least on a 32-bit architecture be + impossible to reach due to memory shortage.

+

NOTE: By default, the ERTS, and the + erl_interface, ei, and jinterface + libraries are now only guaranteed to be compatible with + other Erlang/OTP components from the same release. It is + possible to set each component in compatibility mode of + an earlier release, though. See the documentation for + respective component on how to set it in compatibility + mode.

+

*** POTENTIAL INCOMPATIBILITY ***

+

Own Id: OTP-4968 Aux Id: OTP-4196

+ + +
+
+ +
+ Jinterface 1.2.1.2 + +
+ Fixed Bugs and Malfunctions + + +

Output of Java long was truncated to 32 bits. IDL long + long and unsigned long long could not be used in a struct + for the Java backend. All unsigned integer types for the + Java backend had broken marshalling for large values. + These bugs has now been fixed.

+

Own Id: OTP-4763 Aux Id: seq8024

+ + +
+
+ + diff --git a/lib/jinterface/doc/src/notes_history.xml b/lib/jinterface/doc/src/notes_history.xml new file mode 100644 index 0000000000..8627eb182a --- /dev/null +++ b/lib/jinterface/doc/src/notes_history.xml @@ -0,0 +1,188 @@ + + + + +
+ + 20062009 + Ericsson AB. All Rights Reserved. + + + 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. + + + + Jinteface Release Notes History + + + + +
+ +
+ Jinterface 1.2.1 + +
+ Fixed Bugs and Malfunctions + + +

A bug on the constructor for OtpNode which caused + NullPointerException, is fixed.

+

Own Id: OTP-3721

+ + +
+
+ +
+ Jinterface 1.2 + +
+ Improvements and New features + + +

A new class, AbstractConnection, has been added to deal + with most of the aspects of the Erlang communication + protocol, and which can be subclassed in order to provide + different levels of support to the application as necessary. + OtpConnection is now a subclass to AbstractConnection.

+ + +

OtpCookedConnection is a new subclass to + AbstractConnection, which together with OtpNode provides an + intuitive mailbox-based communication mechanism. By using + this interface, applications are no longer required to + manage connections explicitly, since the OtpNode now opens + and manages connections to remote nodes as needed. Outgoing + messages are sent through mailboxes and automatically + dispatched through the correct connections to + the destination node, while incoming messages are queued in + the destination mailbox. This allows parts of an + application to communicate with several peers + simultaneously without the need to sort and dispatch + incoming messages. Additionally, mailboxes can be linked + with Erlang processes or with each other, in much the same + manner that Erlang processes can be linked together.

+ + +
+ +
+ Changes and additions + + +

The node class hierarchy has changed. The top class + is now AbstractNode, and direct subclasses are OtpPeer and + OtpLocalNode, of which the latter is extended by OtpNode and + OtpSelf. This does not change the functionality of any of + the existing classes or methods that take node arguments, + however it was necessary in order to group OtpNode and + OtpSelf and to provide some common methods for them.

+ + +

OtpServer is now deprecated. Its functionality has + been added to OtpSelf.

+ + +

An open OtpConnection no longer requires service on + a regular basis in order to keep the remote Erlang node from + disconnecting. OtpConnection now extends java.lang.Thread so + it can keep the connection open and respond to ticks when + needed, without intervention from the application. Incoming + messages are automatically received and queued for + subsequent retrieval through one of the receive methods.

+ + +

Tracing of inter-node communication can now be set + on a per-connection basis. The system property + OtpConnection. Trace is still used as before, but now sets + only the initial trace level for new connections. Once a + connection has been created, its current trace level can be + set or retrieved through new methods setTraceLevel and + getTraceLevel.

+ + +

Constructors for OtpErlangAtom and OtpErlangTuple + previously declared that OtpErlangDataException would be + thrown for certain types of input. These constructors now + throw java.lang.IllegalArgumentException instead, which is + a runtime exception and is therefore not declared + explicitly, nor is it necessary for the caller to + explicitly catch it. The rules for creating atoms and + tuples have not changed however.

+ + +

Some of the constructors for OtpErlangPid, OtpErlangPort + and OtpErlangRef are now deprecated. The various + OtpNode classes provide factory methods instead.

+ + +

OtpErlangObject and all subclasses representing + Erlang data types now implement java.io.Serializable and + java.lang.Cloneable.

+ + +

A user's guide is now available.

+

Own Id: OTP-3424

+ + +
+ +
+ Fixed Bugs and Malfunctions + + +

A bug in the MD5 handshaking code, that could cause the + connection to fail when the Java node was run in a 7-bit + character encoding environment, has now been fixed.

+

Own Id: OTP-3512

+ + +

A bug in OtpErlangList, which caused message corruption + when empty list where encoded, is fixed.

+

+

Own Id: OTP-3564

+ + +
+
+ +
+ Jinterface 1.1 + +
+ Improvements and new features + + +

Modifications for using along with new IC types.

+

Some modifications were done on classes OtpInputStream amd + OtpOutputStream in order to work with the new types added + on IC.

+

Own Id: OTP-3331

+ + +

Machine-depended character encoding problems fixed.

+

The character encoding (LC_CTYPE) need no longer be + defined to an eight bit character set for + jinterface connections to work.

+

Own Id: OTP-3512

+ + +
+
+ +
+ Jinterface 1.0 +

New application.

+
+ + diff --git a/lib/jinterface/doc/src/part.xml b/lib/jinterface/doc/src/part.xml new file mode 100644 index 0000000000..413c9b9cd9 --- /dev/null +++ b/lib/jinterface/doc/src/part.xml @@ -0,0 +1,35 @@ + + + + +
+ + 20002009 + Ericsson AB. All Rights Reserved. + + + 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. + + + + Jinterface User Guide + Gordon Beaton, Babbis Xagorarakis + + 2000-08-25 + +
+ +

The Jinterface Application is a java communication tool package to erlang.

+ + + + diff --git a/lib/jinterface/doc/src/part_notes.xml b/lib/jinterface/doc/src/part_notes.xml new file mode 100644 index 0000000000..555efe319e --- /dev/null +++ b/lib/jinterface/doc/src/part_notes.xml @@ -0,0 +1,38 @@ + + + + +
+ + 20002009 + Ericsson AB. All Rights Reserved. + + + 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. + + + + Jinterface Release Notes + Gordon Beaton + + 1999-10-25 + A +
+ +

The Jinterface application is a Java-Erlang + communication tool package.

+

For information about older versions, see + Release Notes History.

+ + + + diff --git a/lib/jinterface/doc/src/part_notes_history.xml b/lib/jinterface/doc/src/part_notes_history.xml new file mode 100644 index 0000000000..b5442e98c1 --- /dev/null +++ b/lib/jinterface/doc/src/part_notes_history.xml @@ -0,0 +1,36 @@ + + + + +
+ + 20062009 + Ericsson AB. All Rights Reserved. + + + 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. + + + + Jinterface Release Notes History + + + + +
+ +

The Jinterface application is a Java-Erlang + communication tool package.

+ + + + diff --git a/lib/jinterface/doc/src/ref_man.gif b/lib/jinterface/doc/src/ref_man.gif new file mode 100644 index 0000000000..b13c4efd53 Binary files /dev/null and b/lib/jinterface/doc/src/ref_man.gif differ diff --git a/lib/jinterface/doc/src/ref_man.xml b/lib/jinterface/doc/src/ref_man.xml new file mode 100644 index 0000000000..43cf7accc8 --- /dev/null +++ b/lib/jinterface/doc/src/ref_man.xml @@ -0,0 +1,36 @@ + + + + +
+ + 20002009 + Ericsson AB. All Rights Reserved. + + + 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. + + + + Jinterface Reference Manual + Gordon Beaton, Babbis Xagorarakis + + 2000-08-25 + 1.2 + application.sgml +
+ +

Jinterface is a Java communication tool package to Erlang.

+ + + + diff --git a/lib/jinterface/doc/src/summary.html.src b/lib/jinterface/doc/src/summary.html.src new file mode 100644 index 0000000000..beb3305d58 --- /dev/null +++ b/lib/jinterface/doc/src/summary.html.src @@ -0,0 +1 @@ +Low level interface to Java. \ No newline at end of file diff --git a/lib/jinterface/doc/src/user_guide.gif b/lib/jinterface/doc/src/user_guide.gif new file mode 100644 index 0000000000..e6275a803d Binary files /dev/null and b/lib/jinterface/doc/src/user_guide.gif differ -- cgit v1.2.3