aboutsummaryrefslogtreecommitdiffstats
path: root/lib/jinterface/doc/src
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
downloadotp-84adefa331c4159d432d22840663c38f155cd4c1.tar.gz
otp-84adefa331c4159d432d22840663c38f155cd4c1.tar.bz2
otp-84adefa331c4159d432d22840663c38f155cd4c1.zip
The R13B03 release.OTP_R13B03
Diffstat (limited to 'lib/jinterface/doc/src')
-rw-r--r--lib/jinterface/doc/src/Makefile173
-rw-r--r--lib/jinterface/doc/src/book.xml49
-rw-r--r--lib/jinterface/doc/src/fascicules.xml18
-rw-r--r--lib/jinterface/doc/src/index.html.src98
-rw-r--r--lib/jinterface/doc/src/jinterface.xml49
-rw-r--r--lib/jinterface/doc/src/jinterface_users_guide.xml448
-rw-r--r--lib/jinterface/doc/src/make.dep20
-rw-r--r--lib/jinterface/doc/src/notes.gifbin0 -> 2005 bytes
-rw-r--r--lib/jinterface/doc/src/notes.xml306
-rw-r--r--lib/jinterface/doc/src/notes_history.xml188
-rw-r--r--lib/jinterface/doc/src/part.xml35
-rw-r--r--lib/jinterface/doc/src/part_notes.xml38
-rw-r--r--lib/jinterface/doc/src/part_notes_history.xml36
-rw-r--r--lib/jinterface/doc/src/ref_man.gifbin0 -> 1530 bytes
-rw-r--r--lib/jinterface/doc/src/ref_man.xml36
-rw-r--r--lib/jinterface/doc/src/summary.html.src1
-rw-r--r--lib/jinterface/doc/src/user_guide.gifbin0 -> 1581 bytes
17 files changed, 1495 insertions, 0 deletions
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 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE book SYSTEM "book.dtd">
+
+<book xmlns:xi="http://www.w3.org/2001/XInclude">
+ <header titlestyle="normal">
+ <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>jinterface</title>
+ <prepared>Gordon Beaton, Babbis Xagorarakis</prepared>
+ <docno></docno>
+ <date>2000-08-25</date>
+ <rev>1.2</rev>
+ <file>book.sgml</file>
+ </header>
+ <insidecover>
+ </insidecover>
+ <pagetext>jinterface</pagetext>
+ <preamble>
+ <contents level="2"></contents>
+ </preamble>
+ <parts lift="no">
+ <xi:include href="part.xml"/>
+ </parts>
+ <applications>
+ <xi:include href="ref_man.xml"/>
+ </applications>
+ <releasenotes>
+ <xi:include href="notes.xml"/>
+ </releasenotes>
+ <listofterms></listofterms>
+ <index></index>
+</book>
+
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 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE fascicules SYSTEM "fascicules.dtd">
+
+<fascicules>
+ <fascicule file="part" href="part_frame.html" entry="yes">
+ User Guide
+ </fascicule>
+ <fascicule file="" href="java/index.html" entry="no">
+ Java API
+ </fascicule>
+ <fascicule file="part_notes" href="part_notes_frame.html" entry="no">
+ Release Notes
+ </fascicule>
+ <fascicule file="" href="../../../../doc/print.html" entry="no">
+ Off-Print
+ </fascicule>
+</fascicules>
+
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 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<!-- This file is obsolete -->
+<HTML>
+<!--
+ %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%
+-->
+<HEAD>
+<TITLE>Jinterface %VSN%</TITLE>
+</HEAD>
+
+<BODY BGCOLOR="#FFFFFF">
+
+<CENTER>
+<A HREF="http://www.erlang.se/"><IMG ALT="Erlang/OTP" BORDER=0 SRC="html/min_head.gif"></A><BR>
+
+<FONT SIZE="-1">
+[<A HREF="../../../doc/index.html">Up</A> |
+<A HREF="http://www.erlang.se/">Erlang/OTP</A>]
+</FONT><BR>
+
+<P><FONT SIZE="+3">Jinterface </FONT><BR>
+Version %VSN%
+</CENTER>
+
+<P><TABLE>
+<TR>
+<TD>
+</TD>
+
+<TD>
+<STRONG>Jinterface</STRONG> contains functions,
+which help you integrate programs written in Java and Erlang.
+</TD>
+</TR>
+</TABLE>
+
+<P><CENTER>
+<TABLE CELLPADDING=15>
+<TR>
+
+
+<TD ALIGN=CENTER>
+<A HREF="html/part_frame.html">
+<IMG ALT="User Guide" BORDER=0 SRC="html/user_guide.gif"></A><BR>
+<FONT SIZE="-1">
+<A HREF="html/part_frame.html">User Guide</A>
+</FONT>
+</TD>
+
+
+<TD ALIGN=CENTER>
+<A HREF="html/index.html"><IMG ALT="Java API" BORDER=0 SRC="html/ref_man.gif"></A><BR>
+<FONT SIZE="-1">
+<A HREF="html/index.html">Java API</A>
+</FONT>
+</TD>
+
+
+
+<TD ALIGN=CENTER>
+<A HREF="html/part_notes_frame.html"><IMG ALT="Release Notes" BORDER=0 SRC="html/notes.gif"></A><BR>
+<FONT SIZE="-1">
+<A HREF="html/part_notes_frame.html">Release Notes</A>
+</FONT>
+</TD>
+
+</TR>
+</TABLE>
+</CENTER>
+
+<P><CENTER>
+<HR>
+<FONT SIZE="-1">
+Copyright &copy; 1991-2001
+<A HREF="http://www.erlang.se/">Ericsson Utvecklings AB</A>
+</FONT>
+</CENTER>
+</BODY>
+</HTML>
+
+
+
+
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 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <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>jinterface</title>
+ <prepared></prepared>
+ <docno></docno>
+ <date></date>
+ <rev></rev>
+ </header>
+ <module>jinterface</module>
+ <modulesummary>A Java communication tool to Erlang.</modulesummary>
+ <description>
+ <p>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.</p>
+ <note>
+ <p>By default, the <c>jinterface</c> library is only guaranteed
+ to be compatible with other Erlang/OTP components from the same
+ release as the <c>jinterface</c> library itself. See the documentation
+ of the <c>OtpCompatRel</c> property in the Java API documentation.</p>
+ </note>
+ </description>
+
+ <section>
+ <title>See Also</title>
+ <p>Jinterface User's Guide</p>
+ </section>
+</erlref>
+
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>
+
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
--- /dev/null
+++ b/lib/jinterface/doc/src/notes.gif
Binary files 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 @@
+<?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>Jinterface Release Notes</title>
+ <prepared>otp_appnotes</prepared>
+ <docno>nil</docno>
+ <date>nil</date>
+ <rev>nil</rev>
+ <file>notes.xml</file>
+ </header>
+ <p>This document describes the changes made to the Jinterface application.</p>
+
+<section><title>Jinterface 1.5.2</title>
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ 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.</p>
+ <p>
+ Own Id: OTP-8201</p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
+<section><title>Jinterface 1.5.1</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ 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.</p>
+ <p>
+ Own Id: OTP-7899</p>
+ </item>
+ </list>
+ </section>
+
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ jinterface uses the new environment variable
+ ERL_EPMD_PORT the same way that erl, epmd and
+ erl_interface do since R13A.</p>
+ <p>
+ Own Id: OTP-7885</p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
+<section><title>Jinterface 1.5</title>
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ 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.</p>
+ <p>
+ *** POTENTIAL INCOMPATIBILITY ***</p>
+ <p>
+ Own Id: OTP-7832</p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
+<section><title>Jinterface 1.4.2</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ A bug when Jinterface did not detect remote node
+ disconnects has been corrected.</p>
+ <p>
+ Own Id: OTP-7624</p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
+<section><title>Jinterface 1.4.1</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ 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.</p>
+ <p>
+ Own Id: OTP-7103</p>
+ </item>
+ <item>
+ <p>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.</p>
+ <p>Problem reported and dissected by Alexander Lamb</p>
+ <p>
+ Own Id: OTP-7330</p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
+<section><title>Jinterface 1.4</title>
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>Jinterface has been updated to handle compressed
+ terms, bitstring, new (IEEE) floats and bignums. This has
+ caused a few incompatibilities.</p>
+ <p>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().</p>
+ <p>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.</p>
+ <p>
+ *** POTENTIAL INCOMPATIBILITY ***</p>
+ <p>
+ Own Id: OTP-6809</p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
+ <section>
+ <title>Jinterface 1.3</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p><c>OtpMbox.receive()</c> and <c>OtpMbox.receive(long timeout)</c> can now throw
+ <c>OtpErlangDecodeException</c> if the received message
+ can not be decoded. <c>null</c> is now only returned from
+ <c>OtpMbox.receive(long timeout)</c> if a timeout occurs.
+ <c>OtpMbox.receive()</c> will never return <c>null</c>.</p>
+ <p>*** POTENTIAL INCOMPATIBILITY ***</p>
+ <p>Own Id: OTP-3932 Aux Id: seq5196 </p>
+ </item>
+ <item>
+ <p>Strings longer than 65535 bytes were encoded wrong by
+ jinterface.</p>
+ <p>Own Id: OTP-4883 Aux Id: OTP-4865 </p>
+ </item>
+ <item>
+ <p>Misc bugfixes: </p>
+ <list type="bulleted">
+ <item>
+ <p>A node pinging itself does no
+ longer cause the java program to hang.</p>
+ <p></p>
+ </item>
+ <item>
+ <p><c>OtpMbox.close()</c> uses exit reason
+ <c>'normal'</c> (atom) instead of <c>"normal"</c>
+ (string).</p>
+ <p></p>
+ </item>
+ <item>
+ <p>Added <c>OtpNode.closeMbox(OtpMbox mbox, OtpErlangObject reason)</c>.</p>
+ <p></p>
+ </item>
+ <item>
+ <p>Added <c>OtpMbox.exit(OtpErlangObject reason)</c>
+ and <c>OtpMbox.exit(String reason)</c>.</p>
+ <p></p>
+ </item>
+ <item>
+ <p>Added <c>OtpMbox.exit(OtpErlangPid to, OtpErlangObject reason)</c>.</p>
+ <p></p>
+ </item>
+ <item>
+ <p><c>OtpMbox.exit(OtpErlangPid to, String reason)</c>
+ is now equivalent to <c>OtpMbox.exit(to, new OtpErlangAtom(reason))</c>.</p>
+ <p></p>
+ </item>
+ <item>Exit signals from an Erlang node can now contain
+ any erlang term as reason, not only atoms. </item>
+ </list>
+ <p>Own Id: OTP-5088</p>
+ </item>
+ <item>
+ <p>For java versions 1.3.1 or later, <c>localStatus</c> was
+ not sent to registered status handler when
+ <c>OtpNode.close()</c> was called. This is now corrected.</p>
+ <p>Own Id: OTP-5169</p>
+ </item>
+ </list>
+ </section>
+
+ <section>
+ <title>Improvements and New Features</title>
+ <list type="bulleted">
+ <item>
+ <p>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. </p>
+ <p>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. </p>
+ <p><em>NOTE:</em> By default, the <c>ERTS</c>, and the
+ <c>erl_interface</c>, <c>ei</c>, and <c>jinterface</c>
+ 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. </p>
+ <p>*** POTENTIAL INCOMPATIBILITY ***</p>
+ <p>Own Id: OTP-4968 Aux Id: OTP-4196 </p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Jinterface 1.2.1.2</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>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.</p>
+ <p>Own Id: OTP-4763 Aux Id: seq8024 </p>
+ </item>
+ </list>
+ </section>
+ </section>
+</chapter>
+
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 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+ <header>
+ <copyright>
+ <year>2006</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>Jinteface Release Notes History</title>
+ <prepared></prepared>
+ <docno></docno>
+ <date></date>
+ <rev></rev>
+ </header>
+
+ <section>
+ <title>Jinterface 1.2.1</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>A bug on the constructor for OtpNode which caused
+ NullPointerException, is fixed.</p>
+ <p>Own Id: OTP-3721</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Jinterface 1.2</title>
+
+ <section>
+ <title>Improvements and New features</title>
+ <list type="bulleted">
+ <item>
+ <p>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.</p>
+ </item>
+ <item>
+ <p>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.</p>
+ </item>
+ </list>
+ </section>
+
+ <section>
+ <title>Changes and additions</title>
+ <list type="bulleted">
+ <item>
+ <p>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.</p>
+ </item>
+ <item>
+ <p>OtpServer is now deprecated. Its functionality has
+ been added to OtpSelf.</p>
+ </item>
+ <item>
+ <p>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.</p>
+ </item>
+ <item>
+ <p>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.</p>
+ </item>
+ <item>
+ <p>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.</p>
+ </item>
+ <item>
+ <p>Some of the constructors for OtpErlangPid, OtpErlangPort
+ and OtpErlangRef are now deprecated. The various
+ OtpNode classes provide factory methods instead.</p>
+ </item>
+ <item>
+ <p>OtpErlangObject and all subclasses representing
+ Erlang data types now implement java.io.Serializable and
+ java.lang.Cloneable.</p>
+ </item>
+ <item>
+ <p>A user's guide is now available.</p>
+ <p>Own Id: OTP-3424</p>
+ </item>
+ </list>
+ </section>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>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.</p>
+ <p>Own Id: OTP-3512</p>
+ </item>
+ <item>
+ <p>A bug in OtpErlangList, which caused message corruption
+ when empty list where encoded, is fixed.</p>
+ <p></p>
+ <p>Own Id: OTP-3564</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Jinterface 1.1</title>
+
+ <section>
+ <title>Improvements and new features</title>
+ <list type="bulleted">
+ <item>
+ <p>Modifications for using along with new IC types.</p>
+ <p>Some modifications were done on classes OtpInputStream amd
+ OtpOutputStream in order to work with the new types added
+ on IC.</p>
+ <p>Own Id: OTP-3331</p>
+ </item>
+ <item>
+ <p>Machine-depended character encoding problems fixed.</p>
+ <p>The character encoding (LC_CTYPE) need no longer be
+ defined to an eight bit character set for
+ jinterface connections to work.</p>
+ <p>Own Id: OTP-3512</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Jinterface 1.0</title>
+ <p>New application.</p>
+ </section>
+</chapter>
+
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 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE part SYSTEM "part.dtd">
+
+<part xmlns:xi="http://www.w3.org/2001/XInclude">
+ <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>Jinterface User Guide</title>
+ <prepared>Gordon Beaton, Babbis Xagorarakis</prepared>
+ <docno></docno>
+ <date>2000-08-25</date>
+ <rev></rev>
+ </header>
+ <description>
+ <p>The Jinterface Application is a java communication tool package to erlang.</p>
+ </description>
+ <xi:include href="jinterface_users_guide.xml"/>
+</part>
+
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 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE part SYSTEM "part.dtd">
+
+<part xmlns:xi="http://www.w3.org/2001/XInclude">
+ <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>Jinterface Release Notes</title>
+ <prepared>Gordon Beaton</prepared>
+ <docno></docno>
+ <date>1999-10-25</date>
+ <rev>A</rev>
+ </header>
+ <description>
+ <p>The <em>Jinterface</em> application is a Java-Erlang
+ communication tool package.</p>
+ <p>For information about older versions, see
+ <url href="part_notes_history_frame.html">Release Notes History</url>.</p>
+ </description>
+ <xi:include href="notes.xml"/>
+</part>
+
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 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE part SYSTEM "part.dtd">
+
+<part>
+ <header>
+ <copyright>
+ <year>2006</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>Jinterface Release Notes History</title>
+ <prepared></prepared>
+ <docno></docno>
+ <date></date>
+ <rev></rev>
+ </header>
+ <description>
+ <p>The <em>Jinterface</em> application is a Java-Erlang
+ communication tool package.</p>
+ </description>
+ <include file="notes_history"></include>
+</part>
+
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
--- /dev/null
+++ b/lib/jinterface/doc/src/ref_man.gif
Binary files 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 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE application SYSTEM "application.dtd">
+
+<application xmlns:xi="http://www.w3.org/2001/XInclude">
+ <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>Jinterface Reference Manual</title>
+ <prepared>Gordon Beaton, Babbis Xagorarakis</prepared>
+ <docno></docno>
+ <date>2000-08-25</date>
+ <rev>1.2</rev>
+ <file>application.sgml</file>
+ </header>
+ <description>
+ <p>Jinterface is a Java communication tool package to Erlang.</p>
+ </description>
+ <xi:include href="jinterface.xml"/>
+</application>
+
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
--- /dev/null
+++ b/lib/jinterface/doc/src/user_guide.gif
Binary files differ