diff options
Diffstat (limited to 'lib/jinterface/doc')
| -rw-r--r-- | lib/jinterface/doc/html/.gitignore | 0 | ||||
| -rw-r--r-- | lib/jinterface/doc/pdf/.gitignore | 0 | ||||
| -rw-r--r-- | lib/jinterface/doc/src/Makefile | 173 | ||||
| -rw-r--r-- | lib/jinterface/doc/src/book.xml | 49 | ||||
| -rw-r--r-- | lib/jinterface/doc/src/fascicules.xml | 18 | ||||
| -rw-r--r-- | lib/jinterface/doc/src/index.html.src | 98 | ||||
| -rw-r--r-- | lib/jinterface/doc/src/jinterface.xml | 49 | ||||
| -rw-r--r-- | lib/jinterface/doc/src/jinterface_users_guide.xml | 448 | ||||
| -rw-r--r-- | lib/jinterface/doc/src/make.dep | 20 | ||||
| -rw-r--r-- | lib/jinterface/doc/src/notes.gif | bin | 0 -> 2005 bytes | |||
| -rw-r--r-- | lib/jinterface/doc/src/notes.xml | 306 | ||||
| -rw-r--r-- | lib/jinterface/doc/src/notes_history.xml | 188 | ||||
| -rw-r--r-- | lib/jinterface/doc/src/part.xml | 35 | ||||
| -rw-r--r-- | lib/jinterface/doc/src/part_notes.xml | 38 | ||||
| -rw-r--r-- | lib/jinterface/doc/src/part_notes_history.xml | 36 | ||||
| -rw-r--r-- | lib/jinterface/doc/src/ref_man.gif | bin | 0 -> 1530 bytes | |||
| -rw-r--r-- | lib/jinterface/doc/src/ref_man.xml | 36 | ||||
| -rw-r--r-- | lib/jinterface/doc/src/summary.html.src | 1 | ||||
| -rw-r--r-- | lib/jinterface/doc/src/user_guide.gif | bin | 0 -> 1581 bytes |
19 files changed, 1495 insertions, 0 deletions
diff --git a/lib/jinterface/doc/html/.gitignore b/lib/jinterface/doc/html/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/lib/jinterface/doc/html/.gitignore diff --git a/lib/jinterface/doc/pdf/.gitignore b/lib/jinterface/doc/pdf/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/lib/jinterface/doc/pdf/.gitignore 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 © 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 Binary files differnew file mode 100644 index 0000000000..e000cca26a --- /dev/null +++ b/lib/jinterface/doc/src/notes.gif 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 Binary files differnew file mode 100644 index 0000000000..b13c4efd53 --- /dev/null +++ b/lib/jinterface/doc/src/ref_man.gif 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 Binary files differnew file mode 100644 index 0000000000..e6275a803d --- /dev/null +++ b/lib/jinterface/doc/src/user_guide.gif |
