<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html xmlns:fn="http://www.w3.org/2005/02/xpath-functions">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" href="../../../../doc/otp_doc.css" type="text/css">
<title>Erlang -- IDL to Java language Mapping</title>
</head>
<body bgcolor="white" text="#000000" link="#0000ff" vlink="#ff00ff" alink="#ff0000"><div id="container">
<script id="js" type="text/javascript" language="JavaScript" src="../../../../doc/js/flipmenu/flipmenu.js"></script><script id="js2" type="text/javascript" src="../../../../doc/js/erlresolvelinks.js"></script><script language="JavaScript" type="text/javascript">
<!--
function getWinHeight() {
var myHeight = 0;
if( typeof( window.innerHeight ) == 'number' ) {
//Non-IE
myHeight = window.innerHeight;
} else if( document.documentElement && ( document.documentElement.clientWidth ||
document.documentElement.clientHeight ) ) {
//IE 6+ in 'standards compliant mode'
myHeight = document.documentElement.clientHeight;
} else if( document.body && ( document.body.clientWidth || document.body.clientHeight ) ) {
//IE 4 compatible
myHeight = document.body.clientHeight;
}
return myHeight;
}
function setscrollpos() {
var objf=document.getElementById('loadscrollpos');
document.getElementById("leftnav").scrollTop = objf.offsetTop - getWinHeight()/2;
}
function addEvent(obj, evType, fn){
if (obj.addEventListener){
obj.addEventListener(evType, fn, true);
return true;
} else if (obj.attachEvent){
var r = obj.attachEvent("on"+evType, fn);
return r;
} else {
return false;
}
}
addEvent(window, 'load', setscrollpos);
//--></script><div id="leftnav"><div class="innertube">
<img alt="Erlang logo" src="../../../../doc/erlang-logo.png"><br><small><a href="users_guide.html">User's Guide</a><br><a href="index.html">Reference Manual</a><br><a href="release_notes.html">Release Notes</a><br><a href="../pdf/ic-4.2.31.pdf">PDF</a><br><a href="../../../../doc/index.html">Top</a></small><p><strong>ic</strong><br><strong>User's Guide</strong><br><small>Version 4.2.31</small></p>
<br><a href="javascript:openAllFlips()">Expand All</a><br><a href="javascript:closeAllFlips()">Contract All</a><p><small><strong>Chapters</strong></small></p>
<ul class="flipMenu" imagepath="../../../../doc/js/flipmenu">
<li id="no" title="Using the IC Compiler" expanded="false">Using the IC Compiler<ul>
<li><a href="ch_introduction.html">
Top of chapter
</a></li>
<li title="Introduction"><a href="ch_introduction.html#id62832">Introduction</a></li>
<li title="Compilation of IDL Files"><a href="ch_introduction.html#id60118">Compilation of IDL Files</a></li>
</ul>
</li>
<li id="no" title="OMG IDL" expanded="false">OMG IDL<ul>
<li><a href="ch_basic_idl.html">
Top of chapter
</a></li>
<li title="OMG IDL - Overview"><a href="ch_basic_idl.html#id61149">OMG IDL - Overview</a></li>
</ul>
</li>
<li id="no" title="IC Protocol" expanded="false">IC Protocol<ul>
<li><a href="ch_ic_protocol.html">
Top of chapter
</a></li>
<li title="Introduction"><a href="ch_ic_protocol.html#id66622">Introduction</a></li>
<li title="Language mappings and IDL operations"><a href="ch_ic_protocol.html#id63114">Language mappings and IDL operations</a></li>
<li title="IC Protocol"><a href="ch_ic_protocol.html#id64104">IC Protocol</a></li>
<li title="Gen_server Protocol"><a href="ch_ic_protocol.html#id65537">Gen_server Protocol</a></li>
<li title="Erlang Distribution Protocol"><a href="ch_ic_protocol.html#id65584">Erlang Distribution Protocol</a></li>
</ul>
</li>
<li id="no" title="Using the Plain Erlang Back-end" expanded="false">Using the Plain Erlang Back-end<ul>
<li><a href="ch_erl_plain.html">
Top of chapter
</a></li>
<li title="Introduction"><a href="ch_erl_plain.html#id63664">Introduction</a></li>
<li title="Compiling the Code"><a href="ch_erl_plain.html#id63678">Compiling the Code</a></li>
<li title="Writing the Implementation File"><a href="ch_erl_plain.html#id63697">Writing the Implementation File</a></li>
<li title="An Example"><a href="ch_erl_plain.html#id63754">An Example</a></li>
</ul>
</li>
<li id="no" title="Using the Erlang Generic Server Back-end" expanded="false">Using the Erlang Generic Server Back-end<ul>
<li><a href="ch_erl_genserver.html">
Top of chapter
</a></li>
<li title="Introduction"><a href="ch_erl_genserver.html#id63935">Introduction</a></li>
<li title="Compiling the Code"><a href="ch_erl_genserver.html#id63953">Compiling the Code</a></li>
<li title="Writing the Implementation File"><a href="ch_erl_genserver.html#id63977">Writing the Implementation File</a></li>
<li title="An Example"><a href="ch_erl_genserver.html#id69038">An Example</a></li>
</ul>
</li>
<li id="no" title="IDL to C mapping" expanded="false">IDL to C mapping<ul>
<li><a href="ch_c_mapping.html">
Top of chapter
</a></li>
<li title="Introduction"><a href="ch_c_mapping.html#id69337">Introduction</a></li>
<li title="C Mapping Characteristics"><a href="ch_c_mapping.html#id69440">C Mapping Characteristics</a></li>
<li title="Basic OMG IDL Types"><a href="ch_c_mapping.html#id69638">Basic OMG IDL Types</a></li>
<li title="Constructed OMG IDL Types"><a href="ch_c_mapping.html#id70147">Constructed OMG IDL Types</a></li>
<li title="OMG IDL Constants"><a href="ch_c_mapping.html#id71595">OMG IDL Constants</a></li>
<li title="OMG IDL Operations"><a href="ch_c_mapping.html#id71622">OMG IDL Operations</a></li>
<li title="Exceptions"><a href="ch_c_mapping.html#id71884">Exceptions</a></li>
<li title="Access to Attributes"><a href="ch_c_mapping.html#id71897">Access to Attributes</a></li>
<li title="Summary of Argument/Result Passing for the C-client"><a href="ch_c_mapping.html#id71908">Summary of Argument/Result Passing for the C-client</a></li>
<li title="Supported Memory Allocation Functions"><a href="ch_c_mapping.html#id73513">Supported Memory Allocation Functions</a></li>
<li title="Special Memory Deallocation Functions"><a href="ch_c_mapping.html#id73642">Special Memory Deallocation Functions</a></li>
<li title="Exception Access Functions"><a href="ch_c_mapping.html#id73681">Exception Access Functions</a></li>
<li title="Special Types"><a href="ch_c_mapping.html#id73720">Special Types</a></li>
<li title="A Mapping Example"><a href="ch_c_mapping.html#id73844">A Mapping Example</a></li>
</ul>
</li>
<li id="no" title="The C Client Back-end" expanded="false">The C Client Back-end<ul>
<li><a href="ch_c_client.html">
Top of chapter
</a></li>
<li title="Introduction"><a href="ch_c_client.html#id73982">Introduction</a></li>
<li title="Generated Stub Files"><a href="ch_c_client.html#id74007">Generated Stub Files</a></li>
<li title="C Interface Functions"><a href="ch_c_client.html#id74057">C Interface Functions</a></li>
<li title="Generating, Compiling and Linking"><a href="ch_c_client.html#id74134">Generating, Compiling and Linking</a></li>
<li title="An Example"><a href="ch_c_client.html#id74198">An Example</a></li>
</ul>
</li>
<li id="no" title="The C Server Back-end" expanded="false">The C Server Back-end<ul>
<li><a href="ch_c_server.html">
Top of chapter
</a></li>
<li title="Introduction"><a href="ch_c_server.html#id74326">Introduction</a></li>
<li title="Generated Stub Files"><a href="ch_c_server.html#id74352">Generated Stub Files</a></li>
<li title="C Skeleton Functions"><a href="ch_c_server.html#id74402">C Skeleton Functions</a></li>
<li title="The Server Loop"><a href="ch_c_server.html#id74461">The Server Loop</a></li>
<li title="Generating, Compiling and Linking"><a href="ch_c_server.html#id74488">Generating, Compiling and Linking</a></li>
<li title="An Example"><a href="ch_c_server.html#id74553">An Example</a></li>
</ul>
</li>
<li id="no" title="CORBA_Environment C Structure" expanded="false">CORBA_Environment C Structure<ul>
<li><a href="ch_c_corba_env.html">
Top of chapter
</a></li>
<li title="C Structure"><a href="ch_c_corba_env.html#id74686">C Structure</a></li>
<li title="The CORBA Compatibility Part"><a href="ch_c_corba_env.html#id74758">The CORBA Compatibility Part</a></li>
<li title="The External Part"><a href="ch_c_corba_env.html#id74811">The External Part</a></li>
<li title="The Internal Part"><a href="ch_c_corba_env.html#id74944">The Internal Part</a></li>
<li title="Creating and Initiating the CORBA_Environment Structure"><a href="ch_c_corba_env.html#id75066">Creating and Initiating the CORBA_Environment Structure</a></li>
<li title="Setting System Exceptions"><a href="ch_c_corba_env.html#id75376">Setting System Exceptions</a></li>
</ul>
</li>
<li id="loadscrollpos" title="IDL to Java language Mapping" expanded="true">IDL to Java language Mapping<ul>
<li><a href="ch_java.html">
Top of chapter
</a></li>
<li title="Introduction"><a href="ch_java.html#id75488">Introduction</a></li>
<li title="Specialties in the Mapping"><a href="ch_java.html#id75549">Specialties in the Mapping</a></li>
<li title="Basic OMG IDL Types"><a href="ch_java.html#id75576">Basic OMG IDL Types</a></li>
<li title="Constructed OMG IDL Types"><a href="ch_java.html#id75983">Constructed OMG IDL Types</a></li>
<li title="Mapping for Constants"><a href="ch_java.html#id76049">Mapping for Constants</a></li>
<li title="Invocations of Operations"><a href="ch_java.html#id76060">Invocations of Operations</a></li>
<li title="Exceptions"><a href="ch_java.html#id76110">Exceptions</a></li>
<li title="Access to Attributes"><a href="ch_java.html#id76123">Access to Attributes</a></li>
<li title="Summary of Argument/Result Passing for Java"><a href="ch_java.html#id76134">Summary of Argument/Result Passing for Java</a></li>
<li title="Communication Toolbox"><a href="ch_java.html#id76192">Communication Toolbox</a></li>
<li title="The Package com.ericsson.otp.ic"><a href="ch_java.html#id76492">The Package com.ericsson.otp.ic</a></li>
<li title="The Term Class"><a href="ch_java.html#id76892">The Term Class</a></li>
<li title="Stub File Types"><a href="ch_java.html#id77170">Stub File Types</a></li>
<li title="Client Stub Initialization, Methods Exported"><a href="ch_java.html#id77234">Client Stub Initialization, Methods Exported</a></li>
<li title="Server Skeleton Initialization, Server Stub Implementation, Methods Exported"><a href="ch_java.html#id77415">Server Skeleton Initialization, Server Stub Implementation, Methods Exported</a></li>
<li title="A Mapping Example"><a href="ch_java.html#id77546">A Mapping Example</a></li>
<li title="Running the Compiled Code"><a href="ch_java.html#id77630">Running the Compiled Code</a></li>
</ul>
</li>
</ul>
</div></div>
<div id="content">
<div class="innertube">
<h1>10 IDL to Java language Mapping</h1>
<h3><a name="id75488">10.1
Introduction</a></h3>
<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>
<ul>
<li>
<p>All OMG IDL basic types</p>
</li>
<li>
<p>All OMG IDL constructed types</p>
</li>
<li>
<p>References to constants defined in OMG IDL</p>
</li>
<li>
<p>Invocations of operations, including passing of
parameters and receiving of result</p>
</li>
<li>
<p>Access to attributes</p>
</li>
</ul>
<h3><a name="id75549">10.2
Specialties in the Mapping</a></h3>
<h4>Names Reserved by the Compiler</h4>
<p>The IDL compiler reserves all identifiers starting with
<span class="code">OE_</span> and <span class="code">oe_</span> for internal use.</p>
<h3><a name="id75576">10.3
Basic OMG IDL Types</a></h3>
<p>The mapping of basic types are according to the standard. All basic types have
a special Holder class.</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle">OMG IDL type</td>
<td align="left" valign="middle">Java type</td>
</tr>
<tr>
<td align="left" valign="middle">float</td>
<td align="left" valign="middle">float</td>
</tr>
<tr>
<td align="left" valign="middle">double</td>
<td align="left" valign="middle">double</td>
</tr>
<tr>
<td align="left" valign="middle">short</td>
<td align="left" valign="middle">short</td>
</tr>
<tr>
<td align="left" valign="middle">unsigned short</td>
<td align="left" valign="middle">short</td>
</tr>
<tr>
<td align="left" valign="middle">long</td>
<td align="left" valign="middle">int</td>
</tr>
<tr>
<td align="left" valign="middle">long long</td>
<td align="left" valign="middle">long</td>
</tr>
<tr>
<td align="left" valign="middle">unsigned long</td>
<td align="left" valign="middle">long</td>
</tr>
<tr>
<td align="left" valign="middle">unsigned long long</td>
<td align="left" valign="middle">long</td>
</tr>
<tr>
<td align="left" valign="middle">char</td>
<td align="left" valign="middle">char</td>
</tr>
<tr>
<td align="left" valign="middle">wchar</td>
<td align="left" valign="middle">char</td>
</tr>
<tr>
<td align="left" valign="middle">boolean</td>
<td align="left" valign="middle">boolean</td>
</tr>
<tr>
<td align="left" valign="middle">octet</td>
<td align="left" valign="middle">octet</td>
</tr>
<tr>
<td align="left" valign="middle">string</td>
<td align="left" valign="middle">java.lang.String</td>
</tr>
<tr>
<td align="left" valign="middle">wstring</td>
<td align="left" valign="middle">java.lang.String</td>
</tr>
<tr>
<td align="left" valign="middle">any</td>
<td align="left" valign="middle">Any</td>
</tr>
<tr>
<td align="left" valign="middle">long double</td>
<td align="left" valign="middle">Not supported</td>
</tr>
<tr>
<td align="left" valign="middle">Object</td>
<td align="left" valign="middle">Not supported</td>
</tr>
<tr>
<td align="left" valign="middle">void</td>
<td align="left" valign="middle">void</td>
</tr>
</table>
<em>Table
10.1:
OMG IDL basic types</em>
<h3><a name="id75983">10.4
Constructed OMG IDL Types</a></h3>
<p>All constructed types are according to the standard with three (3) major exceptions.</p>
<p></p>
<ul>
<li>
<p>The IDL Exceptions are not implemented in this Java mapping.</p>
<p></p>
</li>
<li>
<p>The functions used for read/write to streams, defined in <span class="code">Helper</span> functions
are named unmarshal (instead for read) and marshal (instead for write). </p>
<p></p>
</li>
<li>
<p>The streams used in <span class="code">Helper</span> functions are <span class="code">OtpInputStream</span> for
input and <span class="code">OtpOutputStream</span> for output.</p>
<p></p>
</li>
</ul>
<h3><a name="id76049">10.5
Mapping for Constants</a></h3>
<p>Constants are mapped according to the standard.</p>
<h3><a name="id76060">10.6
Invocations of Operations</a></h3>
<p>Operation invocation is implemented according to the standard.
The implementation is in the class <span class="code">_<nterfacename>Stub.java</span> which implements
the interface in <span class="code"><nterfacename>.java</span>.</p>
<div class="example"><pre>
test._iStub client;
client.op(10);
</pre></div>
<h4>Operation Implementation</h4>
<p>The server is implemented through extension of the class
<span class="code">_<nterfacename>ImplBase.java</span> and implementation of all the methods in the
interface.</p>
<div class="example"><pre>
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;
}
}
</pre></div>
<h3><a name="id76110">10.7
Exceptions</a></h3>
<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>
<h3><a name="id76123">10.8
Access to Attributes</a></h3>
<p>Attributes are supported according to the standard.</p>
<h3><a name="id76134">10.9
Summary of Argument/Result Passing for Java</a></h3>
<p>All types (<span class="code">in</span>, <span class="code">out</span> or <span class="code">inout</span>) of user defined parameters are supported
in the Java mapping. This is also the case in the Erlang mappings but <strong>not</strong> in the C
mapping. <span class="code">inout</span> parameters are not supported in the C mapping so if you are going to
do calls to or from a C program <span class="code">inout</span> cannot be used in the IDL specifications.</p>
<p><span class="code">out</span> and <span class="code">inout</span> parameters must be of Holder types. There is a jar file ( <span class="code">ic.jar</span>)
with Holder classes for the basic types in the <span class="code">ic</span> application. This library is in the directory
<span class="code">$OTPROOT/lib/ic_<version number>/priv</span>.</p>
<h3><a name="id76192">10.10
Communication Toolbox</a></h3>
<p>The generated client and server stubs use the classes
defined in the <span class="code">jinterface</span> package to communicate
with other nodes.
The most important classes are :</p>
<ul>
<li>
<p><span class="code">OtpInputStream</span> which is the stream class used for incoming message storage</p>
<p></p>
</li>
<li>
<p><span class="code">OtpOutputStream</span> which is the stream class used for outgoing message storage</p>
<p></p>
</li>
<li>
<p><span class="code">OtpErlangPid</span> which is the process identification class used to identify processes inside
a java node.</p>
<p>The recommended constructor function for the OtpErlangPid is
<span class="code">OtpErlangPid(String node, int id, int serial, int creation)</span> where :</p>
<p></p>
<ul>
<li>
<p><span class="code">String node</span>, is the name of the node where this process runs.</p>
<p></p>
</li>
<li>
<p><span class="code">int id</span>, is the identification number for this identity.</p>
<p></p>
</li>
<li>
<p><span class="code">int serial</span>, internal information, must be an 18-bit integer.</p>
<p></p>
</li>
<li>
<p><span class="code">int creation</span>, internal information, must have value in range 0..3.</p>
<p></p>
</li>
</ul>
</li>
<li>
<p><span class="code">OtpConnection</span> 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 <span class="code">accept</span> function from an OtpErlangServer object
in server stubs.
The following methods used for node connection :</p>
<p></p>
<ul>
<li>
<p><span class="code">OtpInputStream receiveBuf()</span>, which returns the incoming streams that
contain the message arrived.</p>
<p></p>
</li>
<li>
<p><span class="code">void sendBuf(OtpErlangPid client, OtpOutputStream reply)</span>, which sends
a reply message (in an OtpOutputStream form) to the client node.</p>
<p></p>
</li>
<li>
<p><span class="code">void close()</span>, which closes a connection.</p>
<p></p>
</li>
</ul>
</li>
<li>
<p><span class="code">OtpServer</span> which is used to define a server node.</p>
<p>The recommended constructor function for the OtpServer is :</p>
<p></p>
<ul>
<li>
<p><span class="code">OtpServer(String node, String cookie)</span>. where :</p>
<p></p>
<ul>
<li>
<p><span class="code">node</span> is the requested name for the new java node,
represented as a String object.</p>
<p></p>
</li>
<li>
<p><span class="code">cookie</span> is the requested cookie name for the new java node,
represented as a String object.</p>
<p></p>
</li>
</ul>
</li>
</ul>
<p>The following methods used for node registration and connection acceptance :</p>
<p></p>
<ul>
<li>
<p><span class="code">boolean publishPort()</span>, which registers the server node to <span class="code">epmd</span> daemon.</p>
<p></p>
</li>
<li>
<p><span class="code">OtpConnection accept()</span>, which waits for a connection and returns the
OtpConnection object which is unique for each client node.</p>
<p></p>
</li>
</ul>
</li>
</ul>
<h3><a name="id76492">10.11
The Package com.ericsson.otp.ic</a></h3>
<p>The package <span class="bold_code"><a href="java/com/ericsson/otp/ic/package-summary.html">com.ericsson.otp.ic</a></span>
contains a number of java classes specially designed for the IC generated java-back-ends :</p>
<ul>
<li>
<p>Standard java classes defined through OMG-IDL java mapping :</p>
<ul>
<li>
<p><span class="bold_code"><a href="java/com/ericsson/otp/ic/BooleanHolder.html">BooleanHolder</a></span></p>
</li>
<li>
<p><span class="bold_code"><a href="java/com/ericsson/otp/ic/ByteHolder.html">ByteHolder</a></span></p>
</li>
<li>
<p><span class="bold_code"><a href="java/com/ericsson/otp/ic/CharHolder.html">CharHolder</a></span></p>
</li>
<li>
<p><span class="bold_code"><a href="java/com/ericsson/otp/ic/ShortHolder.html">ShortHolder</a></span></p>
</li>
<li>
<p><span class="bold_code"><a href="java/com/ericsson/otp/ic/IntHolder.html">IntHolder</a></span></p>
</li>
<li>
<p><span class="bold_code"><a href="java/com/ericsson/otp/ic/LongHolder.html">LongHolder</a></span></p>
</li>
<li>
<p><span class="bold_code"><a href="java/com/ericsson/otp/ic/FloatHolder.html">FloatHolder</a></span></p>
</li>
<li>
<p><span class="bold_code"><a href="java/com/ericsson/otp/ic/DoubleHolder.html">DoubleHolder</a></span></p>
</li>
<li>
<p><span class="bold_code"><a href="java/com/ericsson/otp/ic/StringHolder.html">StringHolder</a></span></p>
</li>
<li>
<p><span class="bold_code"><a href="java/com/ericsson/otp/ic/Any.html">Any</a></span>,
<span class="bold_code"><a href="java/com/ericsson/otp/ic/AnyHelper.html">AnyHelper</a></span>,
<span class="bold_code"><a href="java/com/ericsson/otp/ic/AnyHolder.html">AnyHolder</a></span></p>
</li>
<li>
<p><span class="bold_code"><a href="java/com/ericsson/otp/ic/TypeCode.html">TypeCode</a></span></p>
</li>
<li>
<p><span class="bold_code"><a href="java/com/ericsson/otp/ic/TCKind.html">TCKind</a></span></p>
<p></p>
</li>
</ul>
</li>
<li>
<p>Implementation-dependant classes :</p>
<ul>
<li>
<p><span class="bold_code"><a href="java/com/ericsson/otp/ic/Environment.html">Environment</a></span></p>
</li>
<li>
<p><span class="bold_code"><a href="java/com/ericsson/otp/ic/Holder.html">Holder</a></span></p>
<p></p>
</li>
</ul>
</li>
<li>
<p>Erlang compatibility classes :</p>
<ul>
<li>
<p><span class="bold_code"><a href="java/com/ericsson/otp/ic/Pid.html">Pid</a></span>,
<span class="bold_code"><a href="java/com/ericsson/otp/ic/PidHelper.html">PidHelper</a></span>,
<span class="bold_code"><a href="java/com/ericsson/otp/ic/PidHolder.html">PidHolder</a></span></p>
<p>The Pid class originates from <span class="code">OtpErlangPid</span> and is used to
represent the Erlang built-in <span class="code">pid</span> type, a process's identity.
PidHelper and PidHolder are helper respectively holder classes for Pid.</p>
<p></p>
</li>
<li>
<p><span class="bold_code"><a href="java/com/ericsson/otp/ic/Ref.html">Ref</a></span>,
<span class="bold_code"><a href="java/com/ericsson/otp/ic/RefHelper.html">RefHelper</a></span>,
<span class="bold_code"><a href="java/com/ericsson/otp/ic/RefHolder.html">RefHolder</a></span></p>
<p>The Ref class originates from <span class="code">OtpErlangRef</span> and is used to
represent the Erlang built-in <span class="code">ref</span> type, an Erlang reference.
RefHelper and RefHolder are helper respectively holder classes for Ref.</p>
<p></p>
</li>
<li>
<p><span class="bold_code"><a href="java/com/ericsson/otp/ic/Port.html">Port</a></span>,
<span class="bold_code"><a href="java/com/ericsson/otp/ic/PortHelper.html">PortHelper</a></span>,
<span class="bold_code"><a href="java/com/ericsson/otp/ic/PortHolder.html">PortHolder</a></span></p>
<p>The Port class originates from <span class="code">OtpErlangPort</span> and is used to
represent the Erlang built-in <span class="code">port</span> type, an Erlang port.
PortHelper and PortHolder are helper respectively holder classes for Port.</p>
<p></p>
</li>
<li>
<p><span class="bold_code"><a href="java/com/ericsson/otp/ic/Term.html">Term</a></span>,
<span class="bold_code"><a href="java/com/ericsson/otp/ic/TermHelper.html">TermHelper</a></span>,
<span class="bold_code"><a href="java/com/ericsson/otp/ic/TermHolder.html">TermHolder</a></span></p>
<p>The Term class originates from <span class="code">Any</span> and is used to
represent the Erlang built-in <span class="code">term</span> type, an Erlang term.
TermHelper and TermHolder are helper respectively holder classes for Term.</p>
<p></p>
</li>
</ul>
<p>To use the Erlang build-in classes, you will have to include the file <span class="code">erlang.idl</span>
located under <span class="code">$OTPROOT/lib/ic/include</span>.</p>
</li>
</ul>
<h3><a name="id76892">10.12
The Term Class</a></h3>
<p>The <span class="code">Term</span> class is intended to represent the Erlang term generic type.
It extends the <span class="code">Any</span> 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 <span class="code">guard</span> methods
instead of <span class="code">TypeCode</span> 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>
<ul>
<li>
<p><span class="code">boolean isAtom()</span> returns <span class="code">true</span> if the Term is an OtpErlangAtom, <span class="code">false</span> otherwise</p>
<p></p>
</li>
<li>
<p><span class="code">boolean isConstant()</span> returns <span class="code">true</span> if the Term is neither an OtpErlangList nor an OtpErlangTuple, <span class="code">false</span> otherwise</p>
<p></p>
</li>
<li>
<p><span class="code">boolean isFloat()</span> returns <span class="code">true</span> if the Term is an OtpErlangFloat, <span class="code">false</span> otherwise</p>
<p></p>
</li>
<li>
<p><span class="code">boolean isInteger()</span> returns <span class="code">true</span> if the Term is an OtpErlangInt, <span class="code">false</span> otherwise</p>
<p></p>
</li>
<li>
<p><span class="code">boolean isList()</span> returns <span class="code">true</span> if the Term is an OtpErlangList, <span class="code">false</span> otherwise</p>
<p></p>
</li>
<li>
<p><span class="code">boolean isString()</span> returns <span class="code">true</span> if the Term is an OtpErlangString, <span class="code">false</span> otherwise</p>
<p></p>
</li>
<li>
<p><span class="code">boolean isNumber()</span> returns <span class="code">true</span> if the Term is an OtpErlangInteger or an OtpErlangFloat, <span class="code">false</span> otherwise</p>
<p></p>
</li>
<li>
<p><span class="code">boolean isPid()</span> returns <span class="code">true</span> if the Term is an OtpErlangPid or Pid, <span class="code">false</span> otherwise</p>
<p></p>
</li>
<li>
<p><span class="code">boolean isPort()</span> returns <span class="code">true</span> if the Term is an OtpErlangPort or Port, <span class="code">false</span> otherwise</p>
<p></p>
</li>
<li>
<p><span class="code">boolean isReference()</span> returns <span class="code">true</span> if the Term is an OtpErlangRef, <span class="code">false</span> otherwise</p>
<p></p>
</li>
<li>
<p><span class="code">boolean isTuple()</span> returns <span class="code">true</span> if the Term is an OtpErlangTuple, <span class="code">false</span> otherwise</p>
<p></p>
</li>
<li>
<p><span class="code">boolean isBinary()</span> returns <span class="code">true</span> if the Term is an OtpErlangBinary, <span class="code">false</span> otherwise</p>
<p></p>
</li>
</ul>
<h3><a name="id77170">10.13
Stub File Types</a></h3>
<p>For each interface, three (3) stub/skeleton files are generated :</p>
<ul>
<li>
<p>A java interface file, named after the idl interface.</p>
<p></p>
</li>
<li>
<p>A client stub file, named after the convention <span class="code">_< interface name >Stub</span>
which implements the java interface. Example : <span class="code">_stackStub</span>.java</p>
<p></p>
</li>
<li>
<p>A server stub file, named after the convention <span class="code">_< interface name >ImplBase</span>
which implements the java interface. Example : <span class="code">_stackImplBase</span>.java</p>
<p></p>
</li>
</ul>
<h3><a name="id77234">10.14
Client Stub Initialization, Methods Exported</a></h3>
<p>The recommended constructor function for client stubs accepts four (4) parameters :</p>
<p></p>
<ul>
<li>
<p><span class="code">String selfNode</span>, the node identification name to be used in the new
client node.</p>
<p></p>
</li>
<li>
<p><span class="code">String peerNode</span>, the node identification name where the client process is running.</p>
<p></p>
</li>
<li>
<p><span class="code">String cookie</span>, the cookie to be used.</p>
<p></p>
</li>
<li>
<p><span class="code">Object server</span>, where the java Object can be one of:</p>
<p></p>
<ul>
<li>
<p><span class="code">OtpErlangPid</span>, the server's process identity under the node where the server
process is running.</p>
<p></p>
</li>
<li>
<p><span class="code">String</span>, the server's registered name under the node where the server
process is running.</p>
<p></p>
</li>
</ul>
</li>
</ul>
<p>The methods exported from the generated client stub are :</p>
<p></p>
<ul>
<li>
<p><span class="code">void __disconnect()</span>, which disconnects the server connection.</p>
<p></p>
</li>
<li>
<p><span class="code">void __reconnect()</span>, which disconnects the server connection if open,
and then connects to the same peer.</p>
<p></p>
</li>
<li>
<p><span class="code">void __stop()</span>, 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>
</li>
<li>
<p><span class="code">com.ericsson.otp.erlang.OtpErlangRef __getRef()</span>, 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>
</li>
<li>
<p><span class="code">java.lang.Object __server()</span>, which returns the server for the current connection.</p>
<p></p>
</li>
</ul>
<h3><a name="id77415">10.15
Server Skeleton Initialization, Server Stub Implementation, Methods Exported</a></h3>
<p>The constructor function for server skeleton accepts no parameters.</p>
<p>The server skeleton file contains a server <span class="code">switch</span> which
decodes messages from the input stream and calls implementation
(<span class="code">callback</span>) functions.
As the server skeleton is declared <span class="code">abstract</span>, the application
programmer will have to create a stub class that <span class="code">extends</span> 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>
<ul>
<li>
<p><span class="code">OtpOutputStrem invoke(OtpInputStream request)</span>, where the input
stream <span class="code">request</span> is unmarshalled, the implementation function is called
and a reply stream is marshalled.</p>
<p></p>
</li>
<li>
<p><span class="code">boolean __isStopped()</span>, 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>
</li>
<li>
<p><span class="code">boolean __isStopped(com.ericsson.otp.ic.Environment)</span>, 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>
</li>
<li>
<p><span class="code">OtpErlangPid __getCallerPid()</span>, which returns the caller identity for the latest call.</p>
<p></p>
</li>
<li>
<p><span class="code">OtpErlangPid __getCallerPid(com.ericsson.otp.ic.Environment)</span>, which returns the caller
identity for the latest call on a certain Environment.</p>
<p></p>
</li>
<li>
<p><span class="code">java.util.Dictionary __operations()</span>, which returns the operation dictionary which
holds all operations supported by the server skeleton.</p>
<p></p>
</li>
</ul>
<h3><a name="id77546">10.16
A Mapping Example</a></h3>
<p> <a name="stack_idl"></a>
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>
<div class="example"><pre>
// The source IDL file: stack.idl
struct s {
long l;
string s;
};
interface stack {
void push(in s val);
s pop();
};
</pre></div>
<p>When this file is compiled it produces eight files. Three important files
are shown below. <a name="stack_serv"></a>
</p>
<p>The public interface is in <strong>stack.java</strong>.</p>
<div class="example"><pre>
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;
}
</pre></div>
<p>For the IDL struct s three files are generated, a public class in <strong>s.java</strong>.</p>
<div class="example"><pre>
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;
};
};
</pre></div>
<p>A holder class in <strong>sHolder.java</strong> and a helper class in <strong>sHelper.java</strong>.
The helper class is used for marshalling.</p>
<div class="example"><pre>
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 {
:
:
};
};
</pre></div>
<h3><a name="id77630">10.17
Running the Compiled Code</a></h3>
<p>When using the generated java code you must have added
<span class="code">$OTPROOT/lib/ic_<version number>/priv</span> and
<span class="code">$OTPROOT/lib/jinterface_<version number>/priv</span> to your
<span class="code">CLASSPATH</span> variable to get
basic Holder types and the communication classes.</p>
</div>
<div class="footer">
<hr>
<p>Copyright © 1998-2012 Ericsson AB. All Rights Reserved.</p>
</div>
</div>
</div></body>
</html>
