aboutsummaryrefslogtreecommitdiffstats
path: root/lib/ic/doc/src/ch_java.xml
diff options
context:
space:
mode:
authorErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
committerErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
commit84adefa331c4159d432d22840663c38f155cd4c1 (patch)
treebff9a9c66adda4df2106dfd0e5c053ab182a12bd /lib/ic/doc/src/ch_java.xml
downloadotp-84adefa331c4159d432d22840663c38f155cd4c1.tar.gz
otp-84adefa331c4159d432d22840663c38f155cd4c1.tar.bz2
otp-84adefa331c4159d432d22840663c38f155cd4c1.zip
The R13B03 release.OTP_R13B03
Diffstat (limited to 'lib/ic/doc/src/ch_java.xml')
-rw-r--r--lib/ic/doc/src/ch_java.xml737
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>
+