The R13B03 release.OTP_R13B03

1 files changed, 737 insertions, 0 deletions

diff --git a/lib/ic/doc/src/ch_java.xml b/lib/ic/doc/src/ch_java.xml
new file mode 100644
index 0000000000..831850f211
--- /dev/null
+++ b/lib/ic/doc/src/ch_java.xml
@@ -0,0 +1,737 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+  <header>
+    <copyright>
+      <year>1999</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>IDL to Java language Mapping</title>
+    <prepared></prepared>
+    <docno></docno>
+    <date>98-09-24</date>
+    <rev>A</rev>
+    <file>ch_java.xml</file>
+  </header>
+
+  <section>
+    <title>Introduction</title>
+    <p>This chapter describes the mapping of OMG IDL constructs to the Java
+      programming language for the generation of native Java - Erlang  
+      communication. </p>
+    <p>This language mapping defines the following:</p>
+    <list type="bulleted">
+      <item>
+        <p>All OMG IDL basic types</p>
+      </item>
+      <item>
+        <p>All OMG IDL constructed types</p>
+      </item>
+      <item>
+        <p>References to constants defined in OMG IDL</p>
+      </item>
+      <item>
+        <p>Invocations of operations, including passing of
+          parameters and receiving of result</p>
+      </item>
+      <item>
+        <p>Access to attributes</p>
+      </item>
+    </list>
+  </section>
+
+  <section>
+    <title>Specialties in the Mapping</title>
+
+    <section>
+      <title>Names Reserved by the Compiler</title>
+      <p>The IDL compiler reserves all identifiers starting with
+        <c>OE_</c> and <c>oe_</c> for internal use.</p>
+    </section>
+  </section>
+
+  <section>
+    <title>Basic OMG IDL Types</title>
+    <p>The mapping of basic types are according to the standard. All basic types have 
+      a special Holder class.</p>
+    <table>
+      <row>
+        <cell align="left" valign="middle">OMG IDL type</cell>
+        <cell align="left" valign="middle">Java type</cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">float</cell>
+        <cell align="left" valign="middle">float</cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">double</cell>
+        <cell align="left" valign="middle">double</cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">short</cell>
+        <cell align="left" valign="middle">short</cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">unsigned short</cell>
+        <cell align="left" valign="middle">short</cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">long</cell>
+        <cell align="left" valign="middle">int</cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">long long</cell>
+        <cell align="left" valign="middle">long</cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">unsigned long</cell>
+        <cell align="left" valign="middle">long</cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">unsigned long long</cell>
+        <cell align="left" valign="middle">long</cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">char</cell>
+        <cell align="left" valign="middle">char</cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">wchar</cell>
+        <cell align="left" valign="middle">char</cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">boolean</cell>
+        <cell align="left" valign="middle">boolean</cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">octet</cell>
+        <cell align="left" valign="middle">octet</cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">string</cell>
+        <cell align="left" valign="middle">java.lang.String</cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">wstring</cell>
+        <cell align="left" valign="middle">java.lang.String</cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">any</cell>
+        <cell align="left" valign="middle">Any</cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">long double</cell>
+        <cell align="left" valign="middle">Not supported</cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">Object</cell>
+        <cell align="left" valign="middle">Not supported</cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">void</cell>
+        <cell align="left" valign="middle">void</cell>
+      </row>
+      <tcaption>OMG IDL basic types</tcaption>
+    </table>
+  </section>
+
+  <section>
+    <title>Constructed OMG IDL Types</title>
+    <p>All constructed types are according to the standard with three (3) major exceptions.</p>
+    <p></p>
+    <list type="bulleted">
+      <item>
+        <p>The IDL Exceptions are not implemented in this Java mapping.</p>
+        <p></p>
+      </item>
+      <item>
+        <p>The functions used for read/write to streams, defined in <c>Helper</c> functions
+          are named unmarshal (instead for read) and marshal (instead for write).  </p>
+        <p></p>
+      </item>
+      <item>
+        <p>The streams used in <c>Helper</c> functions are <c>OtpInputStream</c> for 
+          input and <c>OtpOutputStream</c> for output.</p>
+        <p></p>
+      </item>
+    </list>
+  </section>
+
+  <section>
+    <title>Mapping for Constants</title>
+    <p>Constants are mapped according to the standard.</p>
+  </section>
+
+  <section>
+    <title>Invocations of Operations</title>
+    <p>Operation invocation is implemented according to the standard.
+      The implementation is in the class <c><![CDATA[_<nterfacename>Stub.java]]></c> which implements 
+      the interface in <c><![CDATA[<nterfacename>.java]]></c>.</p>
+    <code type="none">
+test._iStub client;
+
+client.op(10);
+    </code>
+
+    <section>
+      <title>Operation Implementation</title>
+      <p>The server is implemented through extension of the class 
+        <c><![CDATA[_<nterfacename>ImplBase.java]]></c> and implementation of all the methods in the 
+        interface.</p>
+      <code type="none">
+public class server extends test._iImplBase {
+  
+  public void op(int i) throws java.lang.Exception {
+    System.out.println("Received call op()");
+    o.value = i;
+    return i;
+  }
+
+}
+      </code>
+    </section>
+  </section>
+
+  <section>
+    <title>Exceptions</title>
+    <p>While exception mapping is not implemented, the stubs will
+      generate some Java exceptions in case of operation failure.
+      No exceptions are propagated through the communication.</p>
+  </section>
+
+  <section>
+    <title>Access to Attributes</title>
+    <p>Attributes are supported according to the standard.</p>
+  </section>
+
+  <section>
+    <title>Summary of Argument/Result Passing for Java</title>
+    <p>All types (<c>in</c>, <c>out</c> or <c>inout</c>) of user defined parameters are supported
+      in the Java mapping. This is also the case in the Erlang mappings but <em>not</em> in the C 
+      mapping. <c>inout</c> parameters are not supported in the C mapping so if you are going to 
+      do calls to or from a C program <c>inout</c> cannot be used in the IDL specifications.</p>
+    <p><c>out</c> and <c>inout</c> parameters must be of Holder types. There is a jar file ( <c>ic.jar</c>) 
+      with Holder classes for the basic types in the <c>ic</c> application. This library is in the directory
+      <c><![CDATA[$OTPROOT/lib/ic_<version number>/priv]]></c>.</p>
+  </section>
+
+  <section>
+    <title>Communication Toolbox</title>
+    <p>The generated client and server stubs use the classes
+      defined in the <c>jinterface</c> package to communicate 
+      with other nodes.
+      The most important classes are :</p>
+    <list type="bulleted">
+      <item>
+        <p><c>OtpInputStream</c> which is the stream class used for incoming message storage</p>
+        <p></p>
+      </item>
+      <item>
+        <p><c>OtpOutputStream</c> which is the stream class used for outgoing message storage</p>
+        <p></p>
+      </item>
+      <item>
+        <p><c>OtpErlangPid</c> which is the process identification class used to identify processes inside
+          a java node.</p>
+        <p>The recommended constructor function for the OtpErlangPid is 
+          <c>OtpErlangPid(String node, int id, int serial, int creation)</c> where :</p>
+        <p></p>
+        <list type="bulleted">
+          <item>
+            <p><c>String node</c>, is the name of the node where this process runs.</p>
+            <p></p>
+          </item>
+          <item>
+            <p><c>int id</c>, is the identification number for this identity.</p>
+            <p></p>
+          </item>
+          <item>
+            <p><c>int serial</c>, internal information, must be an 18-bit integer.</p>
+            <p></p>
+          </item>
+          <item>
+            <p><c>int creation</c>, internal information, must have value in range 0..3.</p>
+            <p></p>
+          </item>
+        </list>
+      </item>
+      <item>
+        <p><c>OtpConnection</c> which is used to define a connection between nodes.</p>
+        <p>While the connection object is stub side constructed in client stubs, it is
+          returned after calling the <c>accept</c> function from an OtpErlangServer object
+          in server stubs.
+          The following methods used for node connection :</p>
+        <p></p>
+        <list type="bulleted">
+          <item>
+            <p><c>OtpInputStream receiveBuf()</c>, which returns the incoming streams that
+              contain the message arrived.</p>
+            <p></p>
+          </item>
+          <item>
+            <p><c>void sendBuf(OtpErlangPid client, OtpOutputStream reply)</c>, which sends
+              a reply message (in an OtpOutputStream form) to the client node.</p>
+            <p></p>
+          </item>
+          <item>
+            <p><c>void close()</c>, which closes a connection.</p>
+            <p></p>
+          </item>
+        </list>
+      </item>
+      <item>
+        <p><c>OtpServer</c> which is used to define a server node.</p>
+        <p>The recommended constructor function for the OtpServer is :</p>
+        <p></p>
+        <list type="bulleted">
+          <item>
+            <p><c>OtpServer(String node, String cookie)</c>. where :</p>
+            <p></p>
+            <list type="bulleted">
+              <item>
+                <p><c>node</c> is the requested name for the new java node, 
+                  represented as a String object.</p>
+                <p></p>
+              </item>
+              <item>
+                <p><c>cookie</c> is the requested cookie name for the new java node, 
+                  represented as a String object.</p>
+                <p></p>
+              </item>
+            </list>
+          </item>
+        </list>
+        <p>The following methods used for node registration and connection acceptance :</p>
+        <p></p>
+        <list type="bulleted">
+          <item>
+            <p><c>boolean publishPort()</c>, which registers the server node to <c>epmd</c> daemon.</p>
+            <p></p>
+          </item>
+          <item>
+            <p><c>OtpConnection accept()</c>, which waits for a connection and returns the 
+              OtpConnection object which is unique for each client node.</p>
+            <p></p>
+          </item>
+        </list>
+      </item>
+    </list>
+  </section>
+
+  <section>
+    <title>The Package com.ericsson.otp.ic</title>
+    <p>The package <seealso marker="java/com/ericsson/otp/ic/package-summary">com.ericsson.otp.ic</seealso> 
+      contains a number of java classes specially designed for the IC generated java-back-ends :</p>
+    <list type="bulleted">
+      <item>
+        <p>Standard java classes defined through OMG-IDL java mapping :</p>
+        <list type="bulleted">
+          <item>
+            <p><seealso marker="java/com/ericsson/otp/ic/BooleanHolder">BooleanHolder</seealso></p>
+          </item>
+          <item>
+            <p><seealso marker="java/com/ericsson/otp/ic/ByteHolder">ByteHolder</seealso></p>
+          </item>
+          <item>
+            <p><seealso marker="java/com/ericsson/otp/ic/CharHolder">CharHolder</seealso></p>
+          </item>
+          <item>
+            <p><seealso marker="java/com/ericsson/otp/ic/ShortHolder">ShortHolder</seealso></p>
+          </item>
+          <item>
+            <p><seealso marker="java/com/ericsson/otp/ic/IntHolder">IntHolder</seealso></p>
+          </item>
+          <item>
+            <p><seealso marker="java/com/ericsson/otp/ic/LongHolder">LongHolder</seealso></p>
+          </item>
+          <item>
+            <p><seealso marker="java/com/ericsson/otp/ic/FloatHolder">FloatHolder</seealso></p>
+          </item>
+          <item>
+            <p><seealso marker="java/com/ericsson/otp/ic/DoubleHolder">DoubleHolder</seealso></p>
+          </item>
+          <item>
+            <p><seealso marker="java/com/ericsson/otp/ic/StringHolder">StringHolder</seealso></p>
+          </item>
+          <item>
+            <p><seealso marker="java/com/ericsson/otp/ic/Any">Any</seealso>,
+              <seealso marker="java/com/ericsson/otp/ic/AnyHelper">AnyHelper</seealso>,
+              <seealso marker="java/com/ericsson/otp/ic/AnyHolder">AnyHolder</seealso></p>
+          </item>
+          <item>
+            <p><seealso marker="java/com/ericsson/otp/ic/TypeCode">TypeCode</seealso></p>
+          </item>
+          <item>
+            <p><seealso marker="java/com/ericsson/otp/ic/TCKind">TCKind</seealso></p>
+            <p></p>
+          </item>
+        </list>
+      </item>
+      <item>
+        <p>Implementation-dependant classes :</p>
+        <list type="bulleted">
+          <item>
+            <p><seealso marker="java/com/ericsson/otp/ic/Environment">Environment</seealso></p>
+          </item>
+          <item>
+            <p><seealso marker="java/com/ericsson/otp/ic/Holder">Holder</seealso></p>
+            <p></p>
+          </item>
+        </list>
+      </item>
+      <item>
+        <p>Erlang compatibility classes :</p>
+        <list type="bulleted">
+          <item>
+            <p><seealso marker="java/com/ericsson/otp/ic/Pid">Pid</seealso>,
+              <seealso marker="java/com/ericsson/otp/ic/PidHelper">PidHelper</seealso>,
+              <seealso marker="java/com/ericsson/otp/ic/PidHolder">PidHolder</seealso></p>
+            <p>The Pid class originates from <c>OtpErlangPid</c> and is used to 
+              represent the Erlang built-in <c>pid</c> type, a process's identity.
+              PidHelper and PidHolder are helper respectively holder classes for Pid.</p>
+            <p></p>
+          </item>
+          <item>
+            <p><seealso marker="java/com/ericsson/otp/ic/Ref">Ref</seealso>,
+              <seealso marker="java/com/ericsson/otp/ic/RefHelper">RefHelper</seealso>,
+              <seealso marker="java/com/ericsson/otp/ic/RefHolder">RefHolder</seealso></p>
+            <p>The Ref class originates from <c>OtpErlangRef</c> and is used to 
+              represent the Erlang built-in <c>ref</c> type, an Erlang reference.
+              RefHelper and RefHolder are helper respectively holder classes for Ref.</p>
+            <p></p>
+          </item>
+          <item>
+            <p><seealso marker="java/com/ericsson/otp/ic/Port">Port</seealso>,
+              <seealso marker="java/com/ericsson/otp/ic/PortHelper">PortHelper</seealso>,
+              <seealso marker="java/com/ericsson/otp/ic/PortHolder">PortHolder</seealso></p>
+            <p>The Port class originates from <c>OtpErlangPort</c> and is used to 
+              represent the Erlang built-in <c>port</c> type, an Erlang port.
+              PortHelper and PortHolder are helper respectively holder classes for Port.</p>
+            <p></p>
+          </item>
+          <item>
+            <p><seealso marker="java/com/ericsson/otp/ic/Term">Term</seealso>,
+              <seealso marker="java/com/ericsson/otp/ic/TermHelper">TermHelper</seealso>,
+              <seealso marker="java/com/ericsson/otp/ic/TermHolder">TermHolder</seealso></p>
+            <p>The Term class originates from <c>Any</c> and is used to 
+              represent the Erlang built-in <c>term</c> type, an Erlang term.
+              TermHelper and TermHolder are helper respectively holder classes for Term.</p>
+            <p></p>
+          </item>
+        </list>
+        <p>To use the Erlang build-in classes, you will have to include the file <c>erlang.idl</c>
+          located under <c>$OTPROOT/lib/ic/include</c>.</p>
+      </item>
+    </list>
+  </section>
+
+  <section>
+    <title>The Term Class</title>
+    <p>The <c>Term</c> class is intended to represent the Erlang term generic type.
+      It extends the <c>Any</c> class and it is basically used in the same way as
+      in the Any type.</p>
+    <p>The big difference between Term and Any is the use of <c>guard</c> methods
+      instead of <c>TypeCode</c> to determine the data included in the Term.
+      This is especially true when the Term's value class cannot be 
+      determined at compilation time. The guard methods found in Term :</p>
+    <list type="bulleted">
+      <item>
+        <p><c>boolean isAtom()</c> returns <c>true</c> if the Term is an OtpErlangAtom, <c>false</c> otherwise</p>
+        <p></p>
+      </item>
+      <item>
+        <p><c>boolean isConstant()</c> returns <c>true</c> if the Term is neither an OtpErlangList nor an OtpErlangTuple, <c>false</c> otherwise</p>
+        <p></p>
+      </item>
+      <item>
+        <p><c>boolean isFloat()</c> returns <c>true</c> if the Term is an OtpErlangFloat, <c>false</c> otherwise</p>
+        <p></p>
+      </item>
+      <item>
+        <p><c>boolean isInteger()</c> returns <c>true</c> if the Term is an OtpErlangInt, <c>false</c> otherwise</p>
+        <p></p>
+      </item>
+      <item>
+        <p><c>boolean isList()</c> returns <c>true</c> if the Term is an OtpErlangList, <c>false</c> otherwise</p>
+        <p></p>
+      </item>
+      <item>
+        <p><c>boolean isString()</c> returns <c>true</c> if the Term is an OtpErlangString, <c>false</c> otherwise</p>
+        <p></p>
+      </item>
+      <item>
+        <p><c>boolean isNumber()</c> returns <c>true</c> if the Term is an OtpErlangInteger or an OtpErlangFloat, <c>false</c> otherwise</p>
+        <p></p>
+      </item>
+      <item>
+        <p><c>boolean isPid()</c> returns <c>true</c> if the Term is an OtpErlangPid or Pid, <c>false</c> otherwise</p>
+        <p></p>
+      </item>
+      <item>
+        <p><c>boolean isPort()</c> returns <c>true</c> if the Term is an OtpErlangPort or Port, <c>false</c> otherwise</p>
+        <p></p>
+      </item>
+      <item>
+        <p><c>boolean isReference()</c> returns <c>true</c> if the Term is an OtpErlangRef, <c>false</c> otherwise</p>
+        <p></p>
+      </item>
+      <item>
+        <p><c>boolean isTuple()</c> returns <c>true</c> if the Term is an OtpErlangTuple, <c>false</c> otherwise</p>
+        <p></p>
+      </item>
+      <item>
+        <p><c>boolean isBinary()</c> returns <c>true</c> if the Term is an OtpErlangBinary, <c>false</c> otherwise</p>
+        <p></p>
+      </item>
+    </list>
+  </section>
+
+  <section>
+    <title>Stub File Types</title>
+    <p>For each interface, three (3) stub/skeleton files are generated :</p>
+    <list type="bulleted">
+      <item>
+        <p>A java interface file, named after the idl interface.</p>
+        <p></p>
+      </item>
+      <item>
+        <p>A client stub file, named after the convention  <c><![CDATA[_< interface name >Stub]]></c> 
+          which implements the java interface. Example : <c>_stackStub</c>.java</p>
+        <p></p>
+      </item>
+      <item>
+        <p>A server stub file, named after the convention  <c><![CDATA[_< interface name >ImplBase]]></c> 
+          which implements the java interface. Example : <c>_stackImplBase</c>.java</p>
+        <p></p>
+      </item>
+    </list>
+  </section>
+
+  <section>
+    <title>Client Stub Initialization, Methods Exported</title>
+    <p>The recommended constructor function for client stubs accepts four (4) parameters :</p>
+    <p></p>
+    <list type="bulleted">
+      <item>
+        <p><c>String selfNode</c>, the node identification name to be used in the new
+          client node.</p>
+        <p></p>
+      </item>
+      <item>
+        <p><c>String peerNode</c>, the node identification name where the client process is running.</p>
+        <p></p>
+      </item>
+      <item>
+        <p><c>String cookie</c>, the cookie to be used.</p>
+        <p></p>
+      </item>
+      <item>
+        <p><c>Object server</c>, where the java Object can be one of:</p>
+        <p></p>
+        <list type="bulleted">
+          <item>
+            <p><c>OtpErlangPid</c>, the server's process identity under the node where the server 
+              process is running.</p>
+            <p></p>
+          </item>
+          <item>
+            <p><c>String</c>, the server's registered name under the node where the server 
+              process is running.</p>
+            <p></p>
+          </item>
+        </list>
+      </item>
+    </list>
+    <p>The methods exported from the generated client stub are :</p>
+    <p></p>
+    <list type="bulleted">
+      <item>
+        <p><c>void __disconnect()</c>, which disconnects the server connection.</p>
+        <p></p>
+      </item>
+      <item>
+        <p><c>void __reconnect()</c>, which disconnects the server connection if open,
+          and then connects to the same peer.</p>
+        <p></p>
+      </item>
+      <item>
+        <p><c>void __stop()</c>, which sends the standard stop termination call.
+          When connected to an Erlang server, the server will be terminated.
+          When connected to a java server, this will set a stop flag that 
+          denotes that the server must be terminated.</p>
+        <p></p>
+      </item>
+      <item>
+        <p><c>com.ericsson.otp.erlang.OtpErlangRef __getRef()</c>, will return the message reference
+          received from a server that denotes which call it is referring to.
+          This is useful when building asynchronous clients.</p>
+        <p></p>
+      </item>
+      <item>
+        <p><c>java.lang.Object __server()</c>, which returns the server for the current connection.</p>
+        <p></p>
+      </item>
+    </list>
+  </section>
+
+  <section>
+    <title>Server Skeleton Initialization, Server Stub Implementation, Methods Exported</title>
+    <p>The constructor function for server skeleton accepts no parameters.</p>
+    <p>The server skeleton file contains a server <c>switch</c> which
+      decodes messages from the input stream and calls implementation
+      (<c>callback</c>) functions.
+      As the server skeleton is declared <c>abstract</c>, the application 
+      programmer will have to create a stub class that <c>extends</c> the
+      skeleton file. In this class, all operations defined in the interface
+      class, generated under compiling the idl file, are implemented.</p>
+    <p>The server skeleton file exports the following methods:</p>
+    <p></p>
+    <list type="bulleted">
+      <item>
+        <p><c>OtpOutputStrem invoke(OtpInputStream request)</c>, where the input
+          stream <c>request</c> is unmarshalled, the implementation function is called
+          and a reply stream is marshalled.</p>
+        <p></p>
+      </item>
+      <item>
+        <p><c>boolean __isStopped()</c>, which returns true if a stop message is received.
+          The implementation of the stub should always check if such a message is received
+          and terminate if so.</p>
+        <p></p>
+      </item>
+      <item>
+        <p><c>boolean __isStopped(com.ericsson.otp.ic.Environment)</c>, which returns true if 
+          a stop message is received for a certain Environment and Connection.
+          The implementation of the stub should always check if such a message is received
+          and terminate if so.</p>
+        <p></p>
+      </item>
+      <item>
+        <p><c>OtpErlangPid __getCallerPid()</c>, which returns the caller identity for the latest call.</p>
+        <p></p>
+      </item>
+      <item>
+        <p><c>OtpErlangPid __getCallerPid(com.ericsson.otp.ic.Environment)</c>, which returns the caller 
+          identity for the latest call on a certain Environment.</p>
+        <p></p>
+      </item>
+      <item>
+        <p><c>java.util.Dictionary __operations()</c>, which returns the operation dictionary which
+          holds all operations supported by the server skeleton.</p>
+        <p></p>
+      </item>
+    </list>
+  </section>
+
+  <section>
+    <title>A Mapping Example</title>
+    <p>      <marker id="stack_idl"></marker>
+
+      This is a small example of a simple stack. There are two
+      operations on the stack, push and pop. The example shows some of the 
+      generated files.</p>
+    <code type="none">
+// The source IDL file: stack.idl
+
+struct s {
+      long l;
+      string s;
+};
+
+interface stack {
+    void push(in s val);
+    s pop();
+};
+    </code>
+    <p>When this file is compiled it produces eight files. Three important files 
+      are shown below.      <marker id="stack_serv"></marker>
+</p>
+    <p>The public interface is in <em>stack.java</em>.</p>
+    <code type="none">
+
+public interface stack {
+
+/****
+ * Operation "stack::push" interface functions 
+ *
+ */
+
+    void push(s val) throws java.lang.Exception;
+
+/****
+ * Operation "stack::pop" interface functions 
+ *
+ */
+
+    s pop() throws java.lang.Exception;
+
+}
+    </code>
+    <p>For the IDL struct s three files are generated, a public class in <em>s.java</em>.</p>
+    <code type="none">
+
+final public class s {
+   // instance variables
+   public int l;
+   public java.lang.String s;
+
+   // constructors
+   public s() {};
+   public s(int _l, java.lang.String _s) {
+     l = _l;
+     s = _s;
+   };
+
+};
+    </code>
+    <p>A holder class in <em>sHolder.java</em> and a helper class in <em>sHelper.java</em>.
+      The helper class is used for marshalling.</p>
+    <code type="none">
+
+public class sHelper {
+
+   // constructors
+   private sHelper() {};
+
+   // methods
+   public static s unmarshal(OtpInputStream in) 
+      throws java.lang.Exception {
+\011:
+\011:
+   };
+
+   public static void marshal(OtpOutputStream out, s value) 
+      throws java.lang.Exception {
+\011:
+\011:
+   };
+
+};
+    </code>
+  </section>
+
+  <section>
+    <title>Running the Compiled Code</title>
+    <p>When using the generated java code you must have added 
+      <c><![CDATA[$OTPROOT/lib/ic_<version number>/priv]]></c> and 
+      <c><![CDATA[$OTPROOT/lib/jinterface_<version number>/priv]]></c> to your 
+      <c>CLASSPATH</c> variable to get
+      basic Holder types and the communication classes.</p>
+  </section>
+</chapter>
+