diff options
Diffstat (limited to 'lib/ic/doc/src/ch_java.xml')
| -rw-r--r-- | lib/ic/doc/src/ch_java.xml | 738 |
1 files changed, 0 insertions, 738 deletions
diff --git a/lib/ic/doc/src/ch_java.xml b/lib/ic/doc/src/ch_java.xml deleted file mode 100644 index a733adaf65..0000000000 --- a/lib/ic/doc/src/ch_java.xml +++ /dev/null @@ -1,738 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE chapter SYSTEM "chapter.dtd"> - -<chapter> - <header> - <copyright> - <year>1999</year><year>2016</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions 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 { - : - : - }; - - public static void marshal(OtpOutputStream out, s value) - throws java.lang.Exception { - : - : - }; - -}; - </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> - |