diff options
Diffstat (limited to 'lib/ic/doc/src/ch_java.xml')
| -rw-r--r-- | lib/ic/doc/src/ch_java.xml | 737 |
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> + |