You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tomee.apache.org by km...@apache.org on 2011/06/11 23:33:39 UTC
svn commit: r1134776 [19/26] - in /openejb/trunk/website/html/old-site: ./
html/ html/images/ html/spec/ images/
Added: openejb/trunk/website/html/old-site/html/spec.html
URL: http://svn.apache.org/viewvc/openejb/trunk/website/html/old-site/html/spec.html?rev=1134776&view=auto
==============================================================================
--- openejb/trunk/website/html/old-site/html/spec.html (added)
+++ openejb/trunk/website/html/old-site/html/spec.html Sat Jun 11 21:33:33 2011
@@ -0,0 +1,1494 @@
+<html><head><META http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>OpenEJB Specification --
+ for OpenEJB version 0.7.3</title><link href="spec.css" rel="stylesheet"><link href="/images/favicon.ico" rel="SHORTCUT ICON"></head><body marginwidth="0" marginheight="0" leftmargin="0" bottommargin="0" topmargin="0" vlink="#6763a9" link="#6763a9" bgcolor="#ffffff"><a name="top"></a><table height="400" width="712" cellspacing="0" cellpadding="0" border="0"><tr><td bgcolor="#7270c2" align="left" valign="top" width="20"><img border="0" height="1" width="1" src="images/dotTrans.gif"></td><td bgcolor="#7270c2" align="left" valign="top" width="95"><img border="0" height="1" width="1" src="images/dotTrans.gif"></td><td align="left" valign="top" width="7"><img height="1" width="1" border="0" src="images/dotTrans.gif"></td><td align="left" valign="top" width="40"><img border="0" height="6" width="40" src="images/dotTrans.gif"></td><td bgcolor="#5A5CB8" align="left" valign="top" width="430"><img border="0" height="6" width="430" src="images/top_2.gif"></td><td bgcolor="
#E24717" align="left" valign="top" width="120"><img src="images/top_3.gif" width="120" height="6" border="0"></td></tr><tr><td align="left" valign="top" bgcolor="#7270c2" width="20"><img height="1" width="1" border="0" src="images/dotTrans.gif"></td><td align="left" valign="top" bgcolor="#7270c2" width="95"><img height="1" width="1" border="0" src="images/dotTrans.gif"></td><td align="left" valign="top" bgcolor="#ffffff" width="7"></td><td align="left" valign="top" width="40"><img border="0" height="1" width="1" src="images/dotTrans.gif"></td><td align="left" valign="middle" width="430"><a href="faq.html"><span class="menuTopOff">[ f a q ]</span></a> <a href="http://wiki.codehaus.org/openejb"><span class="menuTopOff">[ w i k i ]</span></a> <a href="http://archive.openejb.codehaus.org/user/"><span class="menuTopOff">[ l i s t s ]</span></a> <a href="http://cvs.openejb.org/"><span class="men
uTopOff">[ c v s ]</span></a> <a href="http://jira.codehaus.org/secure/BrowseProject.jspa?id=10401"><span class="menuTopOff">[ b u g s ]</span></a> <br><img border="0" height="2" width="1" src="images/dotTrans.gif"></td><td align="left" valign="top" height="20" width="120"> </td></tr><tr><td align="left" valign="top" bgcolor="#7270c2" width="20"><img border="0" height="3" width="20" src="images/dotTrans.gif"></td><td align="left" valign="top" bgcolor="#7270c2" width="95"><img border="0" height="3" width="105" src="images/line_sm.gif"></td><td align="left" valign="top" bgcolor="#a9a5de" width="7"><img border="0" height="3" width="7" src="images/line_sm.gif"></td><td align="left" valign="top" width="40"><img border="0" height="3" width="40" src="images/line_light.gif"></td><td align="left" valign="top" width="430"><img border="0" height="3" width="430" src="images/line_light.gif"></td><td align="left" valign="top"
width="120"><img height="1" width="1" border="0" src="images/dotTrans.gif"></td></tr><tr><td align="left" valign="top" bgcolor="#7270c2"><img border="0" height="10" width="20" src="images/dotTrans.gif"></td><td align="left" valign="top" bgcolor="#7270c2" width="95"><img border="0" height="2" width="1" src="images/dotTrans.gif"><br><table cellspacing="0" cellpadding="0" border="0"><tr><td align="left" valign="top"><span class="subMenuOn">Main</span></td></tr><tr><td align="left" valign="top"><a href="index.html"><span class="subMenuOff">
+ Welcome!</span></a></td></tr><tr><td align="left" valign="top"><a href="download.html"><span class="subMenuOff">
+ Download</span></a></td></tr><tr><td align="left" valign="top"><a href="lists.html"><span class="subMenuOff">
+ Mailing Lists</span></a></td></tr><tr><td align="left" valign="top"><a href="cvs.html"><span class="subMenuOff">
+ Source Code</span></a></td></tr><tr><td align="left" valign="top"><a href="contributors.html"><span class="subMenuOff">
+ The Team</span></a></td></tr><tr><td align="left" valign="top"><a href="status.html"><span class="subMenuOff">
+ Status</span></a></td></tr></table><table cellspacing="0" cellpadding="0" border="0"><tr><td align="left" valign="top"><span class="subMenuOn">Users</span></td></tr><tr><td align="left" valign="top"><a href="quickstart.html"><span class="subMenuOff">
+ Quickstart</span></a></td></tr><tr><td align="left" valign="top"><a href="hello-world.html"><span class="subMenuOff">
+ Hello World!</span></a></td></tr><tr><td align="left" valign="top"><a href="cmp_entity_postgresql.html"><span class="subMenuOff">
+ CMP Example</span></a></td></tr><tr><td align="left" valign="top"><a href="cmp_guide.html"><span class="subMenuOff">
+ CMP Guide</span></a></td></tr><tr><td align="left" valign="top"><a href="deploy.html"><span class="subMenuOff">
+ Deploy</span></a></td></tr><tr><td align="left" valign="top"><a href="start-command.html"><span class="subMenuOff">
+ Startup</span></a></td></tr><tr><td align="left" valign="top"><a href="validate.html"><span class="subMenuOff">
+ Validation</span></a></td></tr><tr><td align="left" valign="top"><a href="config_containers.html"><span class="subMenuOff">
+ Configuration</span></a></td></tr><tr><td align="left" valign="top"><a href="properties.html"><span class="subMenuOff">
+ Properties</span></a></td></tr></table><table cellspacing="0" cellpadding="0" border="0"><tr><td align="left" valign="top"><span class="subMenuOn">Servers</span></td></tr><tr><td align="left" valign="top"><a href="embedded.html"><span class="subMenuOff">
+ Local Server</span></a></td></tr><tr><td align="left" valign="top"><a href="remote-server.html"><span class="subMenuOff">
+ Remote Server</span></a></td></tr><tr><td align="left" valign="top"><a href="tomcat.html"><span class="subMenuOff">
+ Tomcat</span></a></td></tr><tr><td align="left" valign="top"><a href="geronimo.html"><span class="subMenuOff">
+ Geronimo</span></a></td></tr></table><table cellspacing="0" cellpadding="0" border="0"><tr><td align="left" valign="top"><span class="subMenuOn">Integrators</span></td></tr><tr><td align="left" valign="top"><a href="whyopenejb.html"><span class="subMenuOff">
+ Why OpenEJB</span></a></td></tr><tr><td align="left" valign="top"><a href="containersystem.html"><span class="subMenuOff">
+ Overview</span></a></td></tr><tr><td align="left" valign="top"><a href="design_openejb.html"><span class="subMenuOff">
+ Design</span></a></td></tr><tr><td align="left" valign="top"><a href="OpenEJB_presentaion.ppt"><span class="subMenuOff">
+ Presentation</span></a></td></tr></table><img border="0" height="15" width="1" src="images/dotTrans.gif"><br><img border="0" height="3" width="105" src="images/line_sm.gif"><br><A href="http://codehaus.org"><IMG alt="The Codehaus" border="0" height="17" width="88" src="http://www.openejb.org/codehaus-smaller.png"></A></td><td align="left" valign="top" bgcolor="#a9a5de" width="7"> </td><td align="left" valign="top" width="40"> </td><td valign="top" width="430" rowspan="4"><table width="430" cellspacing="0" cellpadding="0" border="0" rows="2" cols="1"><tr><td align="left" valign="top"><br><img width="200" vspace="0" src="./images/logo_ejb2.gif" hspace="0" height="55" border="0"><br><img src="images/dotTrans.gif" hspace="0" height="7" border="0"><br><span class="pageTitle">OpenEJB Specification</span><br><span class="pageSubTitle">for OpenEJB version 0.7.3</span><br><p><span class="author">by Richard Monson-Haefel and David Blevins</span><br></p><img s
rc="images/dotTrans.gif" hspace="0" height="1" border="0"></td></tr></table><p></p><p></p><br><span class="toc"><a href="#Introduction">1<img border="0" height="1" width="5" src="images/dotTrans.gif">Introduction</a><br></span><span class="toc"><img border="0" height="1" width="15" src="images/dotTrans.gif"><a href="#Overview">1.1<img border="0" height="1" width="5" src="images/dotTrans.gif">Overview</a><br></span><span class="toc"><img border="0" height="1" width="30" src="images/dotTrans.gif"><a href="#modular.design">1.1.1<img border="0" height="1" width="5" src="images/dotTrans.gif">Monolithic vs. Modular Design</a><br></span><span class="toc"><img border="0" height="1" width="30" src="images/dotTrans.gif"><a href="#contract.concept">1.1.2<img border="0" height="1" width="5" src="images/dotTrans.gif">The container-server contract</a><br></span><span class="toc"><img border="0" height="1" width="30" src="images/dotTrans.gif"><a href="#no.formal.contract">1.1.3<img border=
"0" height="1" width="5" src="images/dotTrans.gif">No formal contract in the EJB specification</a><br></span><span class="toc"><img border="0" height="1" width="30" src="images/dotTrans.gif"><a href="#need.contract">1.1.4<img border="0" height="1" width="5" src="images/dotTrans.gif">The need for a contract</a><br></span><span class="toc"><img border="0" height="1" width="15" src="images/dotTrans.gif"><a href="#have.contract">1.2<img border="0" height="1" width="5" src="images/dotTrans.gif">The OpenEJB server-container contract</a><br></span><span class="toc"><img border="0" height="1" width="30" src="images/dotTrans.gif"><a href="#servers.role">1.2.1<img border="0" height="1" width="5" src="images/dotTrans.gif">The application server’s role</a><br></span><span class="toc"><img border="0" height="1" width="30" src="images/dotTrans.gif"><a href="#containers.role">1.2.2<img border="0" height="1" width="5" src="images/dotTrans.gif">The container’s role</a><br></span>
<span class="toc"><img border="0" height="1" width="15" src="images/dotTrans.gif"><a href="#architecture">1.3<img border="0" height="1" width="5" src="images/dotTrans.gif">The Architecture</a><br></span><span class="toc"><img border="0" height="1" width="30" src="images/dotTrans.gif"><a href="#arch.overview">1.3.1<img border="0" height="1" width="5" src="images/dotTrans.gif">Overview</a><br></span><span class="toc"><img border="0" height="1" width="30" src="images/dotTrans.gif"><a href="#containers">1.3.2<img border="0" height="1" width="5" src="images/dotTrans.gif">The containers</a><br></span><span class="toc"><img border="0" height="1" width="30" src="images/dotTrans.gif"><a href="#primary.services">1.3.3<img border="0" height="1" width="5" src="images/dotTrans.gif">The primary services</a><br></span><span class="toc"><img border="0" height="1" width="30" src="images/dotTrans.gif"><a href="#intravm.server">1.3.4<img border="0" height="1" width="5" src="images/dotTrans.gif
">The IntraVM server</a><br></span><span class="toc"><img border="0" height="1" width="30" src="images/dotTrans.gif"><a href="#customizable">1.3.5<img border="0" height="1" width="5" src="images/dotTrans.gif">Customizable</a><br></span><span class="toc"><img border="0" height="1" width="30" src="images/dotTrans.gif"><a href="#flexible">1.3.6<img border="0" height="1" width="5" src="images/dotTrans.gif">Flexible</a><br></span><span class="toc"><img border="0" height="1" width="15" src="images/dotTrans.gif"><a href="#open.source">1.4<img border="0" height="1" width="5" src="images/dotTrans.gif">OpenEJB is Open Source</a><br></span><span class="toc"><img border="0" height="1" width="30" src="images/dotTrans.gif"><a href="#license">1.4.1<img border="0" height="1" width="5" src="images/dotTrans.gif">The OpenEJB License</a><br></span><span class="toc"><img border="0" height="1" width="30" src="images/dotTrans.gif"><a href="#open.source.advantage">1.4.2<img border="0" height="1" wi
dth="5" src="images/dotTrans.gif">The open source advantage</a><br></span><span class="toc"><img border="0" height="1" width="30" src="images/dotTrans.gif"><a href="#community">1.4.3<img border="0" height="1" width="5" src="images/dotTrans.gif">The open source community</a><br></span><span class="toc"><img border="0" height="1" width="30" src="images/dotTrans.gif"><a href="#open.source.synergy">1.4.4<img border="0" height="1" width="5" src="images/dotTrans.gif">The synergy of OpenEJB and open source</a><br></span><span class="toc"><a href="#openejb.contract">2<img border="0" height="1" width="5" src="images/dotTrans.gif">The Server-Container Contract</a><br></span><span class="toc"><img border="0" height="1" width="15" src="images/dotTrans.gif"><a href="#contract.overview">2.1<img border="0" height="1" width="5" src="images/dotTrans.gif">Overview</a><br></span><span class="toc"><img border="0" height="1" width="30" src="images/dotTrans.gif"><a href="#openejb.resp">2.1.1<img
border="0" height="1" width="5" src="images/dotTrans.gif">OpenEJB Responsibilities</a><br></span><span class="toc"><img border="0" height="1" width="30" src="images/dotTrans.gif"><a href="#server.resp">2.1.2<img border="0" height="1" width="5" src="images/dotTrans.gif">Server Responsibilities</a><br></span><span class="toc"><img border="0" height="1" width="30" src="images/dotTrans.gif"><a href="#contract.api">2.1.3<img border="0" height="1" width="5" src="images/dotTrans.gif">The Server-Container Interface</a><br></span><span class="toc"><img border="0" height="1" width="45" src="images/dotTrans.gif"><a href="#openejb.api">2.1.3.1<img border="0" height="1" width="5" src="images/dotTrans.gif">OpenEJB</a><br></span><span class="toc"><img border="0" height="1" width="45" src="images/dotTrans.gif"><a href="#container.api">2.1.3.2<img border="0" height="1" width="5" src="images/dotTrans.gif">Container</a><br></span><span class="toc"><img border="0" height="1" width="45" src="ima
ges/dotTrans.gif"><a href="#rpc.container.api">2.1.3.3<img border="0" height="1" width="5" src="images/dotTrans.gif">RpcContainer</a><br></span><span class="toc"><img border="0" height="1" width="45" src="images/dotTrans.gif"><a href="#deploymentinfo.api">2.1.3.4<img border="0" height="1" width="5" src="images/dotTrans.gif">DeploymentInfo</a><br></span><span class="toc"><img border="0" height="1" width="45" src="images/dotTrans.gif"><a href="#api.proxyinfo">2.1.3.5<img border="0" height="1" width="5" src="images/dotTrans.gif">ProxyInfo</a><br></span><span class="toc"><img border="0" height="1" width="45" src="images/dotTrans.gif"><a href="#api.openejbexception">2.1.3.6<img border="0" height="1" width="5" src="images/dotTrans.gif">OpenEJBException</a><br></span><span class="toc"><img border="0" height="1" width="45" src="images/dotTrans.gif"><a href="#api.applicationexception">2.1.3.7<img border="0" height="1" width="5" src="images/dotTrans.gif">ApplicationException</a><br></
span><span class="toc"><img border="0" height="1" width="45" src="images/dotTrans.gif"><a href="#api.invalidatereferenceexception">2.1.3.8<img border="0" height="1" width="5" src="images/dotTrans.gif">InvalidateReferenceException</a><br></span><span class="toc"><img border="0" height="1" width="45" src="images/dotTrans.gif"><a href="#api.systemexception">2.1.3.9<img border="0" height="1" width="5" src="images/dotTrans.gif">SystemException</a><br></span><span class="toc"><img border="0" height="1" width="45" src="images/dotTrans.gif"><a href="#api.envprops">2.1.3.10<img border="0" height="1" width="5" src="images/dotTrans.gif">EnvProps</a><br></span><span class="toc"><img border="0" height="1" width="15" src="images/dotTrans.gif"><a href="#rpc.container.contract">2.2<img border="0" height="1" width="5" src="images/dotTrans.gif">Server-RpcContainer Contract</a><br></span><span class="toc"><img border="0" height="1" width="30" src="images/dotTrans.gif"><a href="#rpc.invoke.poli
cy">2.2.1<img border="0" height="1" width="5" src="images/dotTrans.gif">Invoke Policies</a><br></span><span class="toc"><img border="0" height="1" width="45" src="images/dotTrans.gif"><a href="#rpc.invoke.parameters">2.2.1.1<img border="0" height="1" width="5" src="images/dotTrans.gif">Parameters</a><br></span><span class="toc"><img border="0" height="1" width="45" src="images/dotTrans.gif"><a href="#rpc.invoke.deployid">2.2.1.1.1<img border="0" height="1" width="5" src="images/dotTrans.gif">deployID</a><br></span><span class="toc"><img border="0" height="1" width="45" src="images/dotTrans.gif"><a href="#rpc.invoke.callmethod">2.2.1.1.2<img border="0" height="1" width="5" src="images/dotTrans.gif">callMethod</a><br></span><span class="toc"><img border="0" height="1" width="45" src="images/dotTrans.gif"><a href="#rpc.invoke.args">2.2.1.1.3<img border="0" height="1" width="5" src="images/dotTrans.gif">args</a><br></span><span class="toc"><img border="0" height="1" width="45" s
rc="images/dotTrans.gif"><a href="#rpc.invoke.primkey">2.2.1.1.4<img border="0" height="1" width="5" src="images/dotTrans.gif">primKey</a><br></span><span class="toc"><img border="0" height="1" width="45" src="images/dotTrans.gif"><a href="#rpc.invoke.securityidentity">2.2.1.1.5<img border="0" height="1" width="5" src="images/dotTrans.gif">securityIdentity</a><br></span><span class="toc"><img border="0" height="1" width="45" src="images/dotTrans.gif"><a href="#rpc.invoke.returnvalues">2.2.1.2<img border="0" height="1" width="5" src="images/dotTrans.gif">Return Values</a><br></span><span class="toc"><img border="0" height="1" width="45" src="images/dotTrans.gif"><a href="#returnvalues.void">2.2.1.2.1<img border="0" height="1" width="5" src="images/dotTrans.gif">void</a><br></span><span class="toc"><img border="0" height="1" width="45" src="images/dotTrans.gif"><a href="#returnvalues.primitives">2.2.1.2.2<img border="0" height="1" width="5" src="images/dotTrans.gif">primitive
types</a><br></span><span class="toc"><img border="0" height="1" width="45" src="images/dotTrans.gif"><a href="#returnvalues.serializable">2.2.1.2.3<img border="0" height="1" width="5" src="images/dotTrans.gif">Serializable types</a><br></span><span class="toc"><img border="0" height="1" width="45" src="images/dotTrans.gif"><a href="#returnvalues.arrays">2.2.1.2.4<img border="0" height="1" width="5" src="images/dotTrans.gif">Array Value types</a><br></span><span class="toc"><img border="0" height="1" width="45" src="images/dotTrans.gif"><a href="#returnvalues.remote.references">2.2.1.2.5<img border="0" height="1" width="5" src="images/dotTrans.gif">Remote References</a><br></span><span class="toc"><img border="0" height="1" width="45" src="images/dotTrans.gif"><a href="#exceptions">2.2.1.3<img border="0" height="1" width="5" src="images/dotTrans.gif">Exceptions</a><br></span><span class="toc"><img border="0" height="1" width="45" src="images/dotTrans.gif"><a href="#applicati
onexception">2.2.1.3.1<img border="0" height="1" width="5" src="images/dotTrans.gif">ApplicationException</a><br></span><span class="toc"><img border="0" height="1" width="45" src="images/dotTrans.gif"><a href="#invalidatereferenceexception">2.2.1.3.2<img border="0" height="1" width="5" src="images/dotTrans.gif">InvalidateReferenceException</a><br></span><span class="toc"><img border="0" height="1" width="45" src="images/dotTrans.gif"><a href="#systemexception">2.2.1.3.3<img border="0" height="1" width="5" src="images/dotTrans.gif">SystemException</a><br></span><span class="toc"><img border="0" height="1" width="30" src="images/dotTrans.gif"><a href="#ejbobject">2.2.2<img border="0" height="1" width="5" src="images/dotTrans.gif">The EJBObject</a><br></span><span class="toc"><img border="0" height="1" width="45" src="images/dotTrans.gif"><a href="#remote.interface">2.2.2.1<img border="0" height="1" width="5" src="images/dotTrans.gif">Remote Interface Methods</a><br></span><sp
an class="toc"><img border="0" height="1" width="45" src="images/dotTrans.gif"><a href="#ejbobject.interface">2.2.2.2<img border="0" height="1" width="5" src="images/dotTrans.gif">EJBObject Interface Methods</a><br></span><span class="toc"><img border="0" height="1" width="45" src="images/dotTrans.gif"><a href="#getEJBHome">2.2.2.2.1<img border="0" height="1" width="5" src="images/dotTrans.gif">getEJBHome</a><br></span><span class="toc"><img border="0" height="1" width="45" src="images/dotTrans.gif"><a href="#getHandle">2.2.2.2.2<img border="0" height="1" width="5" src="images/dotTrans.gif">getHandle</a><br></span><span class="toc"><img border="0" height="1" width="45" src="images/dotTrans.gif"><a href="#getPrimaryKey">2.2.2.2.3<img border="0" height="1" width="5" src="images/dotTrans.gif">getPrimaryKey( )</a><br></span><span class="toc"><img border="0" height="1" width="45" src="images/dotTrans.gif"><a href="#isIdenticial">2.2.2.2.4<img border="0" height="1" width="5" src="
images/dotTrans.gif">isIdenticial</a><br></span><span class="toc"><img border="0" height="1" width="45" src="images/dotTrans.gif"><a href="#remove">2.2.2.2.5<img border="0" height="1" width="5" src="images/dotTrans.gif">remove</a><br></span><span class="toc"><img border="0" height="1" width="30" src="images/dotTrans.gif"><a href="#ejbhome">2.2.3<img border="0" height="1" width="5" src="images/dotTrans.gif">The EJBHome</a><br></span><span class="toc"><img border="0" height="1" width="45" src="images/dotTrans.gif"><a href="#home.interface">2.2.3.1<img border="0" height="1" width="5" src="images/dotTrans.gif">Home Interface Methods</a><br></span><span class="toc"><img border="0" height="1" width="45" src="images/dotTrans.gif"><a href="#ejbhome.interface">2.2.3.2<img border="0" height="1" width="5" src="images/dotTrans.gif">EJBHome Interface Methods</a><br></span><span class="toc"><img border="0" height="1" width="45" src="images/dotTrans.gif"><a href="#getEJBMetaData">2.2.3.2.1
<img border="0" height="1" width="5" src="images/dotTrans.gif">getEJBMetaData</a><br></span><span class="toc"><img border="0" height="1" width="45" src="images/dotTrans.gif"><a href="#getHomeHandle">2.2.3.2.2<img border="0" height="1" width="5" src="images/dotTrans.gif">getHomeHandle</a><br></span><span class="toc"><img border="0" height="1" width="45" src="images/dotTrans.gif"><a href="#remove">2.2.3.2.3<img border="0" height="1" width="5" src="images/dotTrans.gif">remove</a><br></span><span class="toc"><a href="#api.service.provider">3<img border="0" height="1" width="5" src="images/dotTrans.gif">The Service Provider Interface</a><br></span><span class="toc"><img border="0" height="1" width="15" src="images/dotTrans.gif"><a href="#connector.support">3.1<img border="0" height="1" width="5" src="images/dotTrans.gif">Connector Support</a><br></span><span class="toc"><img border="0" height="1" width="30" src="images/dotTrans.gif"><a href="#connector.notes">3.1.1<img border="0"
height="1" width="5" src="images/dotTrans.gif">Note on January 4, 2001</a><br></span><span class="toc"><a href="#The Core OpenEJB Implementation">4<img border="0" height="1" width="5" src="images/dotTrans.gif">The Core OpenEJB Implementation</a><br></span><span class="toc"><a href="#Vendor Interoperability">5<img border="0" height="1" width="5" src="images/dotTrans.gif">Vendor Interoperability</a><br></span><span class="toc"><a href="#customization">6<img border="0" height="1" width="5" src="images/dotTrans.gif">OpenEJB Customization</a><br></span><span class="toc"><img border="0" height="1" width="15" src="images/dotTrans.gif"><a href="#factory">6.1<img border="0" height="1" width="5" src="images/dotTrans.gif">The OpenEJB Factory</a><br></span><br><a name="Introduction"><h2>Introduction</h2></a>
+
+ <a name="Overview"><h3>Overview</h3></a>
+
+ <a name="modular.design"><h4>Monolithic vs. Modular Design</h4></a>
+
+ <p><span class="bodyBlack">OpenEJB represents a
+ revolution in application server design, a view that application servers should
+ be modular, not monolithic. A modular application server is built from
+ subsystems rather than constructed as one huge, tightly coupled platform.
+ Modularization of application server software allows vendors to focus on their
+ core competencies instead of reinventing every subsystem from scratch to create
+ a complete platform. Not only is modularization possible, OpenEJB makes it a
+ reality.</span></p>
+
+ <p><span class="bodyBlack">OpenEJB is an EJB
+ container system - not a monolithic EJB server - that can be plugged into any
+ application server to make it a fully compliant EJB server. </span></p>
+
+ <p><span class="bodyBlack">The Enterprise JavaBeans
+ API itself does not specify a separation of responsibilities among the
+ application server, the container, and the primary services (transaction,
+ security, and connectors). As a result, EJB vendors must build proprietary
+ monolithic application servers to support all the subsystems needed for a
+ complete EJB platform.</span></p>
+
+ <p><span class="bodyBlack">OpenEJB clearly defines
+ the separation of its responsibilities as a container system from those of the
+ application server that hosts it, and from the primary services that support
+ it. This decoupling enables vendors of application servers, transaction
+ managers, and providers of security services and connectors to focus on their
+ own specialties, while OpenEJB focuses on delivering a high-speed container
+ system that combines the services into a single EJB platform.</span></p>
+
+ <p><span class="bodyBlack">This Introduction Section
+ examines the need for a separation of responsibilities among application
+ server, container, and primary services, and how OpenEJB provides a powerful
+ container system and a set of programming interfaces that make this
+ modularization possible.</span></p>
+
+
+
+ <a name="contract.concept"><h4>The container-server contract</h4></a>
+
+ <p><span class="bodyBlack">Enterprise JavaBeans
+ defines a portable server-side component model for enterprise computing. EJB
+ clearly specifies a bean-container contract and a client-server contract that
+ allow developers to switch EJB server products in an enterprise system without
+ significant redevelopment costs. While the EJB specification defines
+ portability in terms of the enterprise-bean and EJB-client programming models,
+ the EJB servers themselves - all the subsystems that lie between the enterprise
+ beans and the client applications - remain proprietary. </span></p>
+
+
+
+
+ <a name="no.formal.contract"><h4>No formal contract in the EJB specification</h4></a>
+
+ <p><span class="bodyBlack">The Enterprise JavaBeans
+ specification does not define a server-container contract. This omission is
+ intentional; it was done to facilitate maximum flexibility for vendors defining
+ EJB server technologies. Beyond isolating the beans from the application
+ server, the container’s responsibility in the EJB system is vague. At the
+ application server level, the EJB specification defines only a bean-container
+ contract and does not define the server-container contract. </span></p>
+
+ <p><span class="bodyBlack">It is difficult to determine
+ exactly, for example, which is responsible for resource management and other
+ services, the container or the application server. Without a clear
+ separation of responsibilities between the container and the application
+ server, EJB vendors must bear the burden of implementing the entire platform,
+ including the distributed-object service, naming, transaction management,
+ security, and EJB container. As a result, commercial EJB servers tend to be
+ complex monolithic platforms with proprietary and hidden implementations. </span></p>
+
+
+
+
+ <a name="need.contract"><h4>The need for a contract</h4></a>
+
+ <p><span class="bodyBlack">The advantage to defining a
+ server-container contract is that it allows third-party vendors to produce
+ containers that can plug into any application server. If the responsibilities
+ of the container and application server are clearly defined, then vendors who
+ specialize in the technologies that support these different responsibilities
+ can focus on developing the container or application server that best matches
+ their core competencies. Web vendors focus on managing web requests; CORBA
+ vendors focus on distributed-object requests; TP monitors focus on transaction
+ management. Meanwhile, the EJB container vendor focus on managing the
+ enterprise beans within the container. Until now this separation of
+ responsibilities did not exist. </span></p>
+
+
+
+
+
+ <a name="have.contract"><h3>The OpenEJB server-container contract</h3></a>
+
+ <p><span class="bodyBlack">OpenEJB is a pre-built,
+ self-contained, portable EJB 1.1 container system that can be plugged into any
+ application server environment. OpenEJB provides a clear separation of
+ responsibilities between the EJB container and the EJB server. The application
+ server and OpenEJB container system interact through an elegant and powerful
+ programming interface, which forms the server-container contact. This contract
+ is defined by the Server-Container Interface (SCI), a small, simple, and
+ refined set of classes and interfaces.</span></p>
+
+
+ <a name="servers.role"><h4>The application server’s role</h4></a>
+
+ <p><span class="bodyBlack">Application servers that
+ use OpenEJB are responsible for providing client applications with naming and
+ remote access to the application server. Its services may include providing
+ JNDI and proxy implementations that fulfill the client-server contract of the EJB
+ programming model. In application servers that will use OpenEJB locally, such
+ as servlet engines, OpenEJB already provides the necessary JNDI and proxy
+ implementations. When a client makes a request on a remote bean reference, the
+ application server delivers the request to the OpenEJB container system, which
+ delegates the request to the appropriate enterprise bean and applies
+ transaction, connectors and security services appropriately. </span></p>
+
+ <p><span class="bodyBlack">The Apache Tomcat server
+ is a good example of an application server that could easily be extended using
+ OpenEJB to provide its servlets with a complete EJB container system. Enydra
+ and OpenORB are other examples of application servers that would benefit from
+ OpenEJB integration.</span></p>
+
+
+
+
+ <a name="containers.role"><h4>The container’s role</h4></a>
+
+ <p><span class="bodyBlack">OpenEJB manages the
+ enterprise bean’s lifecycle and coordinates the application of transactions
+ (distributed or local), connectors, and security as defined by the EJB 1.1
+ specification. To manage these tasks in a way that is flexible and
+ customizable, OpenEJB also enforces a separation of these responsibilities into
+ separate services. OpenEJB provides a Service Provider Interface (SPI) for
+ transaction, connectors and security services. These simple and flexible
+ container-service contracts are based on simple adapters and industry standards
+ like the Connector API and Java Transaction API (JTA), so it is easy for
+ service providers to support the SPI and plug directly into OpenEJB. In
+ addition, services are swappable and are easily configured by the application
+ server vendor as well as the customer. </span></p>
+
+
+
+
+
+ <a name="architecture"><h3>The Architecture</h3></a>
+
+ <a name="arch.overview"><h4>Overview</h4></a>
+
+ <p><span class="bodyBlack">
+
+ OpenEJB is the first EJB container system that allows developers of an EJB
+ platform to assemble it from existing products rather than construct it from
+ scratch. Vendors focus on what they do best while OpenEJB provides the
+ container to host Enterprise JavaBeans. When plugged into any Java compatible
+ application server, the result is a complete, yet modular Enterprise JavaBeans
+ 1.1 container system. Through the server-container interface (SCI), an
+ application server vendor can use the OpenEJB container system to create an
+ instant and customizable EJB 1.1 platform. Through the service-provider
+ interface (SPI), primary services may be interchanged to match any target
+ environment's specific requirements. Figure 1 shows how OpenEJB separates
+ responsibilities of the application server, container, and primary services.</span></p>
+
+
+
+
+
+ <a name="containers"><h4>The containers</h4></a>
+
+ <p><span class="bodyBlack">The OpenEJB container
+ system provides three robust container types, including stateless and stateful
+ session-bean containers, and entity-bean containers for both bean- and
+ container-managed entity beans. These containers are strictly compliant with
+ the EJB 1.1 specification, and provide the full complement of security and
+ transaction behaviors to beans. The OpenEJB containers are very lightweight
+ because they multiplex requests concurrently, requiring less overhead to
+ service more beans. The containers are also extremely fast because they
+ introduce virtually no bottlenecks to service requests, allowing thousands of requests
+ to execute within the container system simultaneously. </span></p>
+
+
+
+
+ <a name="primary.services"><h4>The primary services</h4></a>
+
+ <p><span class="bodyBlack">OpenEJB defines three
+ primary services: Transaction, security, and connectors. The containers use the
+ transaction, security, and connector services while servicing beans and
+ performing other responsibilities: the transaction service provides the
+ container with transactional integrity; the security service provides
+ authorization control; the connectors provides an API for managing resource
+ connections like JDBC and Java Message Service (JMS).</span></p>
+
+
+
+
+ <a name="intravm.server"><h4>The IntraVM server</h4></a>
+
+ <p><span class="bodyBlack">OpenEJB includes an
+ IntraVM server that allows for swift interaction among beans in the same
+ virtual machine. While respecting the remote semantics required by EJB,
+ optimizations in method calls from one bean to another provide for very fast
+ throughput and little or no latency. The IntraVM provides an immediately
+ available platform for application servers that do not need to support client
+ access through distributed objects. For example, an existing servlet engine or
+ web server can use the IntraVM server to integrate the OpenEJB container
+ systems with very little effort. </span></p>
+
+
+
+
+ <a name="customizable"><h4>Customizable</h4></a>
+
+ <p><span class="bodyBlack">OpenEJB provides a core
+ package that is a powerful default implementation of a container system. While
+ this core is well engineered for performance and efficiency, it is possible to
+ replace parts of the core system in favor of custom implementations. For
+ example, the passivation strategy in the stateful container, which currently
+ writes to a file, can be swapped out in favor of one that writes to a RDMBS or
+ some other secondary storage. </span></p>
+
+ <p><span class="bodyBlack">Developers can also add
+ custom containers to extend the scope of the container system. A container that
+ uses JNI to interface with an ERP system, for example, could be integrated with
+ other core OpenEJB containers. Even the configuration system in OpenEJB, which
+ currently uses a flexible XML DTD, can be replaced. A proprietary container
+ assembler could replace the current assembler to build containers from a
+ database - or even read another vendor's configuration file to load a container
+ system at runtime. Practically every feature of OpenEJB is replaceable,
+ providing vendors and customers with unparalleled customization and
+ flexibility. However, customization is not at all necessary. OpenEJB includes a
+ powerful core package that makes it an extremely fast container system. </span></p>
+
+
+
+
+ <a name="flexible"><h4>Flexible</h4></a>
+
+ <p><span class="bodyBlack">The OpenEJB container
+ system defines lightweight and flexible interfaces that allow vendors to
+ integrate OpenEJB into their application server products easily. OpenEJB
+ provides application server vendors without EJB support a fast track to EJB
+ compliance. OpenEJB also opens up the integration of transaction, security, and
+ connector services so that vendors and customers alike can choose the services
+ that are the most appropriate for their EJB platforms. Service providers can
+ quickly adapt their products to OpenEJB SPI, allowing them to compete with
+ other vendors on the quality of their service. </span></p>
+
+
+
+
+
+ <a name="open.source"><h3>OpenEJB is Open Source</h3></a>
+
+ <a name="license"><h4>The OpenEJB License</h4></a>
+
+ <p><span class="bodyBlack">OpenEJB is an open source
+ software project with a BSD license that is similar to the Apache license.
+ Although it's a new open source project, OpenEJB already has several platforms
+ targeted for integration including Apache Tomcat, OpenORB, and OpenJMS.</span></p>
+
+
+
+
+ <a name="open.source.advantage"><h4>The open source advantage</h4></a>
+
+ <p><span class="bodyBlack">Open source exposes all
+ the source code of the software to the world, providing significant advantages
+ to its creators, its customers, and other developers. Unlike proprietary
+ software, open source products contain no mysteries, no hidden "features."
+ The support costs are much lower with open source than for a proprietary
+ product. Customers that encounter anomalous behavior can choose to locate the
+ exact source of the problem themselves and report it. Most important, open
+ source encourages customers and other developers to contribute enhancements to
+ the software, so that an open source product becomes a joint development effort
+ among its creators, its users, and other vendors. </span></p>
+
+
+
+
+ <a name="community"><h4>The open source community</h4></a>
+
+ <p><span class="bodyBlack">A community forms around
+ every open source project, comprising developers and users that employ the
+ software in commercial and non-commercial environments. If an open source
+ project is well designed and useful, it can become wildly successful. Typical
+ and striking examples include Linux, Apache, and Perl, each of which has
+ enjoyed success in both open source and commercial communities.</span></p>
+
+
+
+
+ <a name="open.source.synergy"><h4>The synergy of OpenEJB and open source</h4></a>
+
+ <p><span class="bodyBlack">OpenEJB is especially
+ well suited for open source because its modular design allows it to be
+ integrated into many different platforms. This flexibility makes OpenEJB the
+ universal solution for any application server that needs EJB functionality.
+ OpenEJB represents a revolution in application server design, a view that
+ application servers' subsystems should be built by organizations that
+ specialize in those subsystems, then bolted together to create a single
+ complete platform, turning the potential of modularization into a reality.</span></p>
+
+ <p><span class="bodyBlack">Open source code
+ represents another revolution in software, one that has a special synergy with
+ modular application server development. Open source exposes the code so that
+ everyone understands how the software works; modular application server
+ software like OpenEJB exposes public programming interfaces so that it can be
+ assembled into an endless variety of platforms. Together, open source and
+ modular software form an excellent union of two philosophies.</span></p>
+
+
+
+<a name="openejb.contract"><h2>The Server-Container Contract</h2></a>
+
+ <a name="contract.overview"><h3>Overview</h3></a>
+
+ <p><span class="bodyBlack">The Server-Container
+ Contract defines the separation of responsibilities between the application
+ server and the OpenEJB container system. The server and container systems
+ interact exclusively through the interfaces and classes in the org.openejb package[1], which are collectively refereed to
+ as the Server-Container Interface (SCI). The sever-container contract is
+ defined by the SCI as well as the policies enumerated in this section of the
+ OpenEJB specification.</span></p>
+
+
+ <a name="openejb.resp"><h4>OpenEJB Responsibilities</h4></a>
+
+ <p><span class="bodyBlack">OpenEJB instantiates a
+ container system at runtime. The container system is responsible for managing enterprise
+ beans at runtime according to the information provided in their XML deployment
+ descriptors[2].
+ The container system interposes between requests made by the server and
+ serviced by enterprise beans. The container system interposes to provide transaction,
+ authorization security, and connector support for beans servicing requests from
+ the server. The transaction, security, and connector services used during
+ interposition are those assigned to the container system by the configuration.
+ </span></p>
+
+ <p><span class="bodyBlack">The container system
+ provides a fast minimally synchronized environment for enterprise beans that is
+ conformant with the EJB 1.1 specification.</span></p>
+
+ <p><span class="bodyBlack">The container system
+ provides the server with an API (the SCI) for locating the container that hosts
+ a specific bean deployment and delegating requests to the bean.</span></p>
+
+
+
+
+ <a name="server.resp"><h4>Server Responsibilities</h4></a>
+
+ <p><span class="bodyBlack">The server is any Java
+ application that hosts the OpenEJB container system. The server is responsible
+ for supporting the EJB Client API for distributed clients or some other similar
+ API (CORBA, DCOM, etc.). The server must provide the stubs, network protocol,
+ dispatching, and naming services used to locate and communicate requests with
+ the container system. </span></p>
+
+
+
+
+ <a name="contract.api"><h4>The Server-Container Interface</h4></a>
+
+ <p><span class="bodyBlack">The server and container
+ interact through the server-container interface (SCI). The SCI is made up of
+ the 10 classes and interfaces defined in the org.openejb package. Using the SCI the server
+ will delegate requests to beans to the container system, which may reply with
+ return values or exceptions depending on the outcome of the request and the
+ type of container.</span></p>
+
+ <p><span class="bodyBlack">Several classes and
+ interfaces in the SCI represent a hierarchy for managing and hosting enterprise
+ beans at runtime. The participants in this hierarchy are described below.</span></p>
+
+
+
+ <a name="openejb.api"><h5>OpenEJB</h5></a>
+
+ <p><span class="bodyBlack">OpenEJB is the root of the container system
+ hierarchy. It is responsible for loading the configuration information and
+ manufacturing the containers.
+ The OpenEJB class is a static singleton that provides access to the
+ deployments, containers, transaction manager, and security service.</span></p>
+
+<table width="440" cellspacing="0" cellpadding="0" border="0"><tr><td bgcolor="#e0e0e0"><span class="code-block"><pre>
+ Properties props = new Properties();
+ ...
+ org.openejb.OpenEJB.init(props);
+ TransactionManager txMngr = OpenEJB.getTransactionManager();
+ SecurityService ss = OpenEJB.getSecurityService();
+ Container [] containers = OpenEJB.containers();
+ DeploymentInfo [] deployments = OpenEJB.deployments();
+</pre></span></td></tr></table>
+
+ <p><span class="bodyBlack">One the OpenEJB has been
+ initialized, it can be used to access the containers, deployments and primary
+ services. OpenEJB maintains one container system per Java Virtual Machine and
+ can not be initialized more then once in the life of a process.</span></p>
+
+
+
+ <a name="container.api"><h5>Container</h5></a>
+
+ <p><span class="bodyBlack">The Container manages one or more bean deployments
+ at runtime. The Container interface provides methods for accessing the
+ Container's id and the deployments managed by the container (represented by org.openejb.DeploymentInfo
+ objects). In addition, the container defines the getContainerType() method, which will return Container.ENTITY, Container.STATEFUL, or Container.STATELESS depending
+ on the bean type managed by the container.</span></p>
+
+<table width="440" cellspacing="0" cellpadding="0" border="0"><tr><td bgcolor="#e0e0e0"><span class="code-block"><pre>
+ Container cntr = OpenEJB.getContainer("Accounting");
+
+ DeploymentInfo [] deployments = cntr.deployments();
+
+ DeploymentInfo deployInfo = cntr.getDeployment(someId);
+
+ int type = cntr.getContainerType();
+</pre></span></td></tr></table>
+
+ <p><span class="bodyBlack">The Container interface
+ has been separated from the RpcContainer in order to support future container
+ types that are not based on RPC style communications such as the message-driven
+ bean container in EJB 2.0, which will included in the next release of OpenEJB,
+ OpenEJB 2.0.</span></p>
+
+
+
+
+ <a name="rpc.container.api"><h5>RpcContainer</h5></a>
+
+ <p><span class="bodyBlack">The RPC container is used
+ for SessionBean and EntityBean deployments,
+ which are accessed via remote procedure calls (RPC) from clients. Its called
+ the RPC container (RpcContainer)
+ because it enforces the semantics the Java RMI API, but can be used with any
+ RPC protocol including JRMP, RMI-IIOP, IIOP, SOAP, and, hypothetically, DCE and
+ DCOM. The RpcContainers
+ assume that a call is synchronous and that arguments, return values, and
+ exceptions will adhere to the Java RMI-IIOP API policies defined by the EJB 1.1
+ specification -- the actual protocol can be anything. The server is
+ responsible for translating arguments, return values, and exceptions between
+ the RpcContainer.invoke()
+ method and the distributed object protocol used by the server.</span></p>
+
+ <p><span class="bodyBlack">The RpcContainer extends the Container interface
+ and defines one method, invoke( );
+ The invoke() method
+ is used by the server to delegate bean requests to the RpcContainer.</span></p>
+
+ <p><span class="bodyBlack">
+<table width="440" cellspacing="0" cellpadding="0" border="0"><tr><td bgcolor="#e0e0e0"><span class="code-block"><pre>
+ RpcContainer rmiCntr =
+ (RpcContainer)OpenEJB.getContainer("Accounting");
+
+
+ Object retVal =
+ rmiCntr.invoke(deployID,method,args,null,principal);
+
+</pre></span></td></tr></table>
+ </span></p>
+
+
+
+ <a name="deploymentinfo.api"><h5>DeploymentInfo</h5></a>
+
+ <p><span class="bodyBlack">The DeploymentInfo represents a unique bean
+ deployment in the container system. It maintains all deployment information
+ about the bean that may be useful to the server in determining the behavior and
+ identity of a specific bean deployment. DeploymentInfo objects are uniquely
+ identified within the container system by their deployment-id. The
+ deployment-id can be used in the getDeploymentInfo()
+ method, defined in both the OpenEJB class and Container interface to obtain a
+ specific DeploymentInfo object.</span></p>
+
+<table width="440" cellspacing="0" cellpadding="0" border="0"><tr><td bgcolor="#e0e0e0"><span class="code-block"><pre>
+ Object deployID = deploymentInfo.getDeploymentID();
+ DeploymentInfo di_1 = OpenEJB.getDeploymentInfo(deployID);
+ DeploymentInfo di_2 = container.getDeploymentInf(deployID);
+
+ If(deployID.equals(di_1) &&
+ deployID.equals(di_2))
+ // this condition will always be true
+</pre></span></td></tr></table>
+
+ <p><span class="bodyBlack">Its expected that most
+ servers will associate a deployment-id with a remote reference connection,
+ since the server must supply the deployment-id when invoking the RpcContainer.invoke()
+ method. Servers can use the DeploymentInfo to obtain information about the
+ bean as well as obtaining a direct reference to the bean’s container.</span></p>
+
+ <p><span class="bodyBlack">The deployment-id is
+ often the same as the JNDI lookup name used by remote clients to access the
+ bean. This is not a requirement, but can make it direct client requests to the
+ correct container and DeploymentInfo object. The deployment-id can, however,
+ be any character string as long as deployment-ids are unique with a container
+ system.</span></p>
+
+
+
+ <a name="api.proxyinfo"><h5>ProxyInfo</h5></a>
+
+ <p><span class="bodyBlack">An instance of ProxyInfo class represents
+ a remote reference to a bean in the container system. When a bean method
+ (create, find, or business methods) is defined as returning a remote reference
+ to another bean, the container will replace that reference with the ProxyInfo object if its a
+ local bean. Local beans are those beans deployed in the same container system.</span></p>
+
+ <p><span class="bodyBlack">The ProxyInfo object provides information
+ sufficient for the server to generate a native remote reference that can be
+ used by the calling client. This native remote reference is implemented using
+ the distributed protocol used by the server.</span></p>
+
+
+
+ <a name="api.openejbexception"><h5>OpenEJBException</h5></a>
+
+ <p><span class="bodyBlack">This is the base
+ exception type of the ApplicationException, InvalidateReferenceException and
+ SystemException. It is never thrown directly by the container system to the
+ server.</span></p>
+
+
+
+ <a name="api.applicationexception"><h5>ApplicationException</h5></a>
+
+ <p><span class="bodyBlack">An ApplicationException is thrown when invocation
+ on the bean instance results in a java.rmi.RemoteException
+ or some type of EJB application exception. The server must propagate the cause
+ of the ApplicationException to the client. </span></p>
+
+
+
+ <a name="api.invalidatereferenceexception"><h5>InvalidateReferenceException</h5></a>
+
+ <p><span class="bodyBlack">The InvalidateReferenceException is type of ApplicationException that
+ is thrown when EJB 1.1 policy requires that the server invalidate the client's
+ remote reference. The InvalidateReferenceException
+ is only thrown for stateful session beans when an operation results in the
+ destruction of the bean instance. The server must propagate the cause of the
+ InvalidateReferenceException (usually a RemoteException) and then make the
+ clients remote reference inoperable.</span></p>
+
+
+
+ <a name="api.systemexception"><h5>SystemException</h5></a>
+
+ <p><span class="bodyBlack">The org.openejb.SystemException is used to report a
+ system failure in the container system or one of the service providers
+ (transaction, security, or connectors). The condition that caused the
+ exception is considered a partial or complete failure of the container system
+ that may be isolated to the container or service provider that caused the
+ exception. </span></p>
+
+ <p><span class="bodyBlack">Container may throw a
+ system exception if an abnormal condition exists while handling server
+ request. Examples of abnormal conditions include: An I/O error that occurs
+ passivating stateful bean instances to disk; an invalid deployment-id or call
+ method is used as an argument to a RpcContainer.invoke() method call.</span></p>
+
+ <p><span class="bodyBlack">When a SystemException is thrown,
+ the server can attempt to recover by re-executing the request, removing the
+ container from service, or removing the entire container system from service.
+ The SystemException
+ wrappers the causal exception which may be evaluated to determine the source of
+ the failure. For example: If the causal exception is a javax.jta.SystemException the server knows that
+ the exception was thrown from the transaction service provider. </span></p>
+
+
+
+ <a name="api.envprops"><h5>EnvProps</h5></a>
+
+ <p><span class="bodyBlack">The EnvProps provides a type for standard constants
+ used when initializing the container system.</span></p>
+
+
+
+
+
+
+ <a name="rpc.container.contract"><h3>Server-RpcContainer Contract</h3></a>
+
+ <p><span class="bodyBlack">The server initializes
+ the OpenEJB container system at server start-up or before the first bean
+ request is serviced. Every bean deployment has an id, called the <i>deployment-id</i>,
+ that is unique within a container system. The server must provide its RPC
+ clients with a naming service that maps names to deployment-ids associated with
+ RpcContainers. In many cases the naming service’s name binding may be the same
+ as the deployment-id, but this is not required. When the client performs a name
+ service lookup, the server will return a home reference; a proxy or stub that
+ implements the bean's home interface.</span></p>
+
+ <p><span class="bodyBlack">The server is responsible
+ for providing the distributed communication infrastructure (proxies, network
+ protocol handlers, dispatchers, etc.) for remote references. Every remote
+ reference provided by the server is associated with a specific deployment-id,
+ which in turn maps to a specific RpcContainer.
+ When the client invokes a method on a bean or home reference, the server will
+ either delegate the request to reference's RpcContainer or service the request itself.</span></p>
+
+ <p><span class="bodyBlack">In general, create,
+ remove, finder, and business methods are delegated to the reference's RpcContainer. The values
+ returned or exceptions thrown are propagated to the server's clients. The
+ server itself services all other methods of the EJBHome and EJBObject interfaces because these methods
+ require the creation of distributed communication artifacts specific to the
+ server's distributed object protocol (i.e. Handle and EJBMetaData) or that are easily handled by the
+ server (i.e. EJBObject.isIdentical()
+ and EJBObject.getPrimaryKey()).</span></p>
+
+ <p><span class="bodyBlack">The server delegates all
+ RPC requests to RPC container using the RpcContainer.invoke() method. The invoke() method will either
+ return normally or throw an exception. Normal return values are propagated to
+ client, exceptions are handled according to the exception policies outlined in
+ section "2.2.1.3 Exceptions". </span></p>
+
+
+ <a name="rpc.invoke.policy"><h4>Invoke Policies</h4></a>
+
+ <p><span class="bodyBlack">In general requests by
+ the client on bean's business methods and the home's create, and find methods
+ are delegated to the RpcContainer.
+ The RpcContainer
+ interface defines the invoke( )
+ method which represents much of the server-container contract, which is
+ expressed through parameters, return values, and exceptions that can be thrown
+ by the invoke method to the server.</span></p>
+
+
+ <a name="rpc.invoke.parameters"><h5>Parameters</h5></a>
+
+ <p><span class="bodyBlack">The RpcContainer.invoke( ) method defines declares
+ five parameters. </span></p>
+
+<table width="440" cellspacing="0" cellpadding="0" border="0"><tr><td bgcolor="#e0e0e0"><span class="code-block"><pre>
+ public Object invoke(Object deployID,
+ Method callMethod,
+ Object [] args,
+ Object primKey,
+ Object securityIdentity)
+ throws OpenEJBException;
+</pre></span></td></tr></table>
+
+
+ <a name="rpc.invoke.deployid"><h6>deployID</h6></a>
+
+ <p><span class="bodyBlack">This is the deployment-id
+ of the bean to be invoked. Every bean deployment has a unique deployment-id
+ within the scope of a container system. The deployment-id can be used to
+ obtain the bean's DeploymentInfo object which is used by the container to
+ select the correct bean deployment to service the method request as well as
+ providing other information. ( A container can and often does support several
+ different deployments at the same time.). The deployment-id type is
+ inconsequential to the container system, but is usually a String or Integer
+ type. </span></p>
+
+<table width="440" cellspacing="0" cellpadding="0" border="0"><tr><td bgcolor="#e0e0e0"><span class="code-block"><pre>
+
+ String deploymentID = … get deployment id
+ from request
+
+ DeploymentInfo deployment =
+ OpenEJB.getDeploymentInfo(deploymentID);
+
+ RPCContainer container =
+ (RPCContainer)deployment.getContainer();
+
+ container.invoke(deploymentID,callmethod,
+ args, securityIdentity);
+
+</pre></span></td></tr></table>
+
+
+
+ <a name="rpc.invoke.callmethod"><h6>callMethod</h6></a>
+
+ <p><span class="bodyBlack">This is the java.lang.reflect.Method object
+ that represents the remote interface (home or remote) method that was invoked
+ by the client. This parameter is used by the container to determine whether
+ the method should be delegated directly to the bean or run under a different
+ method (i.e. create()
+ is run as ejbCreate()).
+ In addition, the Method object is used as a key in the container system when
+ determining the transaction and security attributes that must be applied when
+ the operating on the bean instance.</span></p>
+
+
+
+ <a name="rpc.invoke.args"><h6>args</h6></a>
+
+ <p><span class="bodyBlack">The args array is the parameter values used by the
+ client to invoke the remote reference method. The arguments must be indexed in
+ the array in the same order they are declared on the remote interface method.
+ Primitive values (int, double, char, etc.) must be
+ substituted with their primitive wrapper counter parts (Integer, Double, Character, etc.) in the array. The arguments
+ must be copied and not passed by reference from the client. This will be a
+ natural occurrence for most distributed object systems since arguments must be marshaled
+ across the network. Arguments that are remote references must be operational,
+ meaning that they must implement the remote interface and provide network
+ access to their respective bean. </span></p>
+
+
+
+ <a name="rpc.invoke.primkey"><h6>primKey</h6></a>
+
+ <p><span class="bodyBlack">The primary key
+ identifies a unique bean in the container system. For stateful beans the
+ primary key identifies a unique bean instance that maintains a conversational
+ state with a specific client. For entity beans the primary key identifies a
+ unique bean in the database. Stateless session beans do not use a primary key,
+ so the primKey parameter will be null for requests on stateless beans. The primKey is usally null for invocations
+ servicing home interface methods -- home references don't have a primary key.
+ The exception is EJBHome remove methods for which the server must provide the
+ primary key of the bean (stateful or entity) that is to be removed.</span></p>
+
+
+
+ <a name="rpc.invoke.securityidentity"><h6>securityIdentity</h6></a>
+
+ <p><span class="bodyBlack">The securityIdentity is the security identity
+ representing the client. The server is responsible for providing the proper
+ object for the container systems designated security service. The type and
+ implementation of the securityIdentity
+ object is immaterial to the container. It's assumed that the security service
+ used by the container will know how to use it.</span></p>
+
+ <p><span class="bodyBlack">For example, if the
+ container's profile specifies security service provider that uses SSL
+ authentication, then the proper SSL credential may be passed as the securityIdentity
+ parameter. If the security service provider uses Kerberos then the proper
+ Kerberos token may be passed as the securityIdentity parameter.</span></p>
+
+
+
+
+
+ <a name="rpc.invoke.returnvalues"><h5>Return Values</h5></a>
+
+ <p><span class="bodyBlack">The RpcContainer.invoke() method returns an Object
+ type. The value of the return depends on the expected return type of the
+ remote method that was invoked; the declared return type of the home or remote
+ interface. </span></p>
+
+
+ <a name="returnvalues.void"><h6>void</h6></a>
+
+ <p><span class="bodyBlack">If the remote interface
+ method returns a void, the invoke(
+ ) method will return a null value. The remote reference will then
+ return void.</span></p>
+
+
+
+ <a name="returnvalues.primitives"><h6>primitive types</h6></a>
+
+ <p><span class="bodyBlack">If the remote interface
+ method returns a single primitive value (int, double, char, etc.), the invoke() method will return the corresponding
+ primitive wrapper (Integer,
+ Double, Character, etc.) object.
+ The remote reference will then return the primitive value of the wrapper
+ object.</span></p>
+
+
+
+ <a name="returnvalues.serializable"><h6>Serializable types</h6></a>
+
+ <p><span class="bodyBlack">If the remote interface
+ method returns a serializable type, the invoke() method will return an object of that
+ type. The remote reference returns a copy of the serializable object.</span></p>
+
+ <p><span class="bodyBlack">The exception is java.lang.String and
+ primitive wrapper types (Integer,
+ Double, Character, ect.), which
+ are immutable and need not be copied.</span></p>
+
+
+
+ <a name="returnvalues.arrays"><h6>Array Value types</h6></a>
+
+ <p><span class="bodyBlack">If the remote interface
+ method returns an array, the invoke()
+ method will return an array of that type. The remote reference returns a
+ complete copy of the array including the individual elements.</span></p>
+
+
+
+ <a name="returnvalues.remote.references"><h6>Remote References</h6></a>
+
+ <p><span class="bodyBlack">If the remote interface
+ method returns a remote reference, the invoke() method will either return ProxyInfo object or the
+ actual remote reference. ProxyInfo
+ objects are returned for local beans, which are beans managed within the
+ container system. Remote references are returned by for non-local beans, which
+ are beans managed by a different container system or a different EJB vendor
+ (Weblogic, WebSphere, etc.).</span></p>
+
+ <p><span class="bodyBlack">If the method called is a
+ create or single object find method, the invoke() method will return the ProxyInfo that represents
+ the created or found bean. If a business method returns a remote reference to a
+ local bean, the container will return a ProxyInfo object for that bean. The server
+ then, must generate the remote reference based on the ProxyInfo and returned that reference to the
+ client. </span></p>
+
+ <p><span class="bodyBlack">The ProxyInfo object provides information
+ sufficient for the server to generate a remote reference for the local bean
+ including the remote interface to implement (remote or home), the
+ deployment-id, the primary key of the bean, and the a reference to the bean's
+ container.</span></p>
+
+ <p><span class="bodyBlack">If the bean returns a
+ remote reference to a non-local bean, the container will return that same
+ remote reference to the server. The assumption is that the remote reference
+ from the non-local bean (different container system or vendor) is serializable,
+ so otherwise can be transferred between address spaces and remain operational.
+ Problems can occur when the distributed object protocol used by the sever is
+ incompatible with the non-local bean reference's implementation.</span></p>
+
+
+
+
+
+ <a name="exceptions"><h5>Exceptions</h5></a>
+
+ <p><span class="bodyBlack">There are three possible
+ exceptions that can be thrown by the invoke() method: ApplicationException, SystemException, or the InvalidateReferenceException. </span></p>
+
+
+ <a name="applicationexception"><h6>ApplicationException</h6></a>
+
+ <p><span class="bodyBlack">An ApplicationException is thrown when invocation
+ on the bean instance results in a java.rmi.RemoteException
+ or some type of EJB application exception. The server must propagate the cause
+ of the ApplicationException
+ to the client. When an ApplicationException
+ is thrown, the cause is considered to be normal; it does not represent a system
+ failure or require invalidation of the remote reference. The cause should be
+ propagated to the client but no other action need be taken by the server.</span></p>
+
+ <p><span class="bodyBlack">When a bean method throws
+ a custom application exception from a business methods or a standard
+ application exception (CreateException,
+ ObjectNotFoundException,
+ etc.) from a standard business method (ejbCreate, ejbFind, etc.), the container will catch the
+ exception and re-throw it wrapped in an ApplicationException to the server.</span></p>
+
+ <p><span class="bodyBlack">Under some circumstances,
+ a RemoteException may
+ occur while delegating a request to the bean instance. Examples include: A
+ security authorization violation (the client is not authorized to access the
+ bean method); An attempt to propagate a transaction to a bean method declared
+ with the Never
+ transaction attribute; An attempt to perform a loopback on an entity bean that
+ is declared as non-reentrant. In these cases the RemoteException will be wrapped in a
+ ApplicationException by the container and thrown to the server from the invoke() method. The
+ server must treat the RemoteException
+ as it would any custom application exception; the RemoteException should be propagated to the
+ client, but no other action need be taken by the server.</span></p>
+
+
+
+ <a name="invalidatereferenceexception"><h6>InvalidateReferenceException</h6></a>
+
+ <p><span class="bodyBlack">The InvalidateReferenceException is type of ApplicationException that
+ is thrown when EJB 1.1 policy requires that the server invalidate the client's
+ remote reference. The InvalidateReferenceException
+ will nest a RemoteException
+ or standard application exception (i.e. ObjectNotFoundException) that must re-thrown to
+ the client by the bean reference. The InvalidateReferenceException is only thrown for
+ stateful session beans when an operation results in the destruction of the bean
+ instance. Examples include: An EJBException
+ is thrown by a stateful bean method (business method or standard callback
+ method) and the instance is evicted; A client attempts to invoke a method on a
+ stateful bean object that no longer exists.</span></p>
+
+ <p><span class="bodyBlack">When the invoke() method throws an ApplicationException the
+ server must: First throw the nested (cause) exception to the client; Second,
+ invalidate the reference so that any subsequent method invoked on the reference
+ immediately throw a RemoteException.
+ The reference is made inoperable.</span></p>
+
+
+
+ <a name="systemexception"><h6>SystemException</h6></a>
+
+ <p><span class="bodyBlack">A SystemException is
+ thrown by the invoke() method when a partial failure of the container or one of
+ the service providers (transaction, security, connectors) has occurred while
+ servicing the method. Conditions that cause a SystemException and server responsibilities are
+ covered in more detail in Section 2.4: SystemException.</span></p>
+
+ <p><span class="bodyBlack">A SystemException represents a serious error in
+ the container system. It should be assumed if this exception is thrown that the
+ container system is unstable and appropriate action by the server should be
+ taken.</span></p>
+
+
+
+
+
+
+ <a name="ejbobject"><h4>The EJBObject</h4></a>
+
+ <p><span class="bodyBlack">The EJBObject is
+ implemented by server specific stub that acts as a remote reference to a
+ corresponding bean in a RpcContainer. The EJBObject stub must implement both
+ the javax.ejb.EJBObject
+ interface as well as the remote interface (and all its super types) defined by
+ the bean developer. </span></p>
+
+ <p><span class="bodyBlack">When an EJB client
+ creates or finds a bean from a EJBHome reference, the server is responsible for
+ returning a remote reference to that bean. The remote reference, the EJBObject,
+ is implemented according to the server's distributed object protocol and is
+ bound to its bean's RpcContainer at the server. How this is accomplished is up
+ to the server, but it is expected that servers will maintain a mapping between
+ the EJBObject's network connection or logical thread, and the correct
+ RpcContainer using the deployment-id. For stateful and entity beans, the
+ EJBObject reference is mapped to a specific bean instance within a container
+ using the deployment-id and primary key.</span></p>
+
+
+ <a name="remote.interface"><h5>Remote Interface Methods</h5></a>
+
+ <p><span class="bodyBlack">The remote interface
+ methods, those business methods defined by the bean developer in the remote
+ interface, are delegated to the invoke()
+ method of the appropriate RpcContainer
+ (the container that services the bean deployment represented by EJBObject). Invocations on
+ the EJBObject stub
+ are transmitted from client to the server (using the servers distributed object
+ protocol) and then delegated to the appropriate RpcContainer.</span></p>
+
+
+
+ <a name="ejbobject.interface"><h5>EJBObject Interface Methods</h5></a>
+
+ <p><span class="bodyBlack">Except for the remove( ) method, all
+ EJBObject interface methods are implemented by the server. (The remove( ) method is handled
+ by the OpenEJB RpcContainer via the invoke( ) method.) The EJBObject methods are dependent on
+ server specific conventions and distributed object protocol, so the responsibly
+ for implementing these methods falls on the server. </span></p>
+
+
+ <a name="getEJBHome"><h6>getEJBHome</h6></a>
+
+ <p><span class="bodyBlack">The getEJBHome() method is handled by the server
+ which will need to return an application server implementation of the EJBHome
+ stub implementing the appropriate home interface to the client.</span></p>
+
+
+
+ <a name="getHandle"><h6>getHandle</h6></a>
+
+ <p><span class="bodyBlack">The getHandle( ) method is implemented by the
+ application server. The Handle class needs to be serializable, so that it can
+ be written to file or stream. The Handle implementation must be able to
+ re-connect to the server after it is deserialized using the server's
+ distributed object protocol, and return an EJBObject stub for the appropriate
+ bean.</span></p>
+
+
+
+ <a name="getPrimaryKey"><h6>getPrimaryKey( )</h6></a>
+
+ <p><span class="bodyBlack">The server may choose to
+ maintain a reference to the primary key in the stub, or to maintain it at the
+ server. Session beans do not expose their primary keys, so the application
+ server will need to throw a RemoteException when this method is invoked on
+ session EJBObject stubs.</span></p>
+
+
+
+ <a name="isIdenticial"><h6>isIdenticial</h6></a>
+
+ <p><span class="bodyBlack">The isIdenticial(EJBObject obj) method is
+ implemented by the server. The application server should compare container and
+ deployment-ids for an exact match. In addition, the identity (primary key)
+ for entity and stateful session beans must match as well. The primary key and
+ other identifiers may be maintained in the EJBObject stubs or on the server.</span></p>
+
+
+
+ <a name="remove"><h6>remove</h6></a>
+
+ <p><span class="bodyBlack">The remove( ) method is
+ delegated by the server to the invoke(
+ ) method of the proper RpcContainer. When invoked on an EJBObject
+ stub for a stateless bean, the server doesn't not need to delegate the
+ invocation to the container -- EJBObject.remove( ) invocations are not handled
+ by the stateless container. </span></p>
+
+ <p><span class="bodyBlack">Once a remove( ) method has been
+ processed, the server should attempt to invalidate all the EJBObject stubs of
+ the bean that was removed, so that subsequent invocations on that EJBObject
+ stub result in javax.ejb.ObjectNotFoundException
+ being thrown to the client. Subsequent requests by server on behalf of the
+ removed bean will result in the RpcContainer
+ throwing a org.openejb.ApplicationException
+ that wraps a javax.ejb.ObjectNotFoundException.</span></p>
+
+
+
+
+
+
+ <a name="ejbhome"><h4>The EJBHome</h4></a>
+
+ <p><span class="bodyBlack">The EJBHome is implemented
+ by server specific stub that acts as a remote reference to a corresponding
+ deployment in a RpcContainer. The EJBHome stub must implement both the javax.ejb.EJBHome interface
+ as well as the home interface (and all its super types) defined by the bean
+ developer. </span></p>
+
+ <p><span class="bodyBlack">When the client uses a
+ naming service to locate a bean's EJBHome reference, the server is responsible
+ for returning a remote reference to that bean. The home reference, the EJBHome,
+ is implemented according to the server's distributed object protocol and is
+ bound to its bean's RpcContainer at the server. How this is accomplished is up
+ to the server, but it is expected that servers will maintain a mapping between
+ the EJBHome's network connection or logical thread, and the correct RpcContainer
+ using the deployment-id. In some cases the deployment-id and the lookup name
+ may be the same value, but this is not required and is considered a server
+ specific option.</span></p>
+
+
+ <a name="home.interface"><h5>Home Interface Methods</h5></a>
+
+ <p><span class="bodyBlack">The home interface
+ methods, those methods defined by the bean developer in the home interface, are
+ delegated to the invoke()
+ method of the appropriate RpcContainer
+ (the container that services the bean deployment represented by EJBHome). Invocations on
+ the EJBHome stub are
+ transmitted from client to the server (using the servers distributed object
+ protocol) and then delegated to the appropriate RpcContainer.</span></p>
+
+ <p><span class="bodyBlack">In the case of home
+ interface methods, a null
+ value must be passed as the primary key argument in the RpcContainer.invoke() method. Home interface
+ methods are not specific to one bean instance and so have no primary key
+ associated with method requests. The only exception to this is the EJBHome
+ remove methods which are discussed in more detail in section 2.2.3.2.</span></p>
+
+ <p><span class="bodyBlack">When a home interface create method is delegated
+ to the RpcContainer
+ the return value will always be a ProxyInfo
+ object describing the remote reference that should be returned to the client.
+ The remote reference is a distributed object stub implemented according to the
+ server distributed object protocol. </span></p>
+
+ <p><span class="bodyBlack">When a single-value find method (i.e. findByPrimaryKey() ) is
+ delegated to the RpcContainer
+ a single ProxyInfo
+ object will be returned, the same as with the create methods. When a multi-value find method is delegated to
+ the RpcContainer, a java.util.Collection of ProxyInfo objects is
+ returned to the server. The server is then responsible for returning a Collection or Enumeration of remote
+ references to the client. The collection type returned to the client depends on
+ how the find method
+ was declared.</span></p>
+
+
+
+ <a name="ejbhome.interface"><h5>EJBHome Interface Methods</h5></a>
+
+ <p><span class="bodyBlack">Except for the remove( ) method, all EJBHome interface methods
+ are implemented by the server. (The remove( ) method is handled by the OpenEJB
+ RpcContainer via the invoke( )
+ method.) The EJBHome
+ methods are dependent on server specific conventions and distributed object
+ protocol, so the responsibly for implementing these methods falls on the
+ server. </span></p>
+
+
+ <a name="getEJBMetaData"><h6>getEJBMetaData</h6></a>
+
+ <p><span class="bodyBlack">The getEJBMetaData( ) method is implemented by the
+ application server. The EJBMetaData
+ class needs to be serializable, so that it can be written to file or stream.
+ Using the deployment-id, the server can lookup the DeploymentInfo object for that bean, and use it
+ to populate the EJBMetaData
+ object. In addition, the EJBMetaData
+ implementation must be able to re-connect to the server after it is
+ deserialized using the server's distributed object protocol, and return an EJBHome stub from the EJBMetaData.getEJBHome( )
+ method.</span></p>
+
+
+
+ <a name="getHomeHandle"><h6>getHomeHandle</h6></a>
+
+ <p><span class="bodyBlack">The getHomeHandle( ) method is implemented by the
+ application server. The HomeHandle
+ class needs to be serializable, so that it can be written to file or stream.
+ The HomeHandle
+ implementation must be able to re-connect to the server after it is
+ deserialized using the server's distributed object protocol, and return an
+ EJBHome stub for the appropriate bean.</span></p>
+
+
+
+ <a name="remove"><h6>remove</h6></a>
+
+ <p><span class="bodyBlack">The remove( ) methods are delegated by the server
+ to the invoke( )
+ method of the proper RpcContainer.
+ When invoked on a EJBHome
+ stub for a stateless bean, the server doesn't not need to delegate the
+ invocation to the container -- EJBHome.remove(
+ ) invocations are not handled by the stateless container – but
+ doing so will not cause an error. </span></p>
+
+ <p><span class="bodyBlack">Once a remove( ) method has been
+ processed, the server should attempt to invalidate all the EJBObject stubs of the bean that was removed,
+ so that subsequent invocations on that EJBObject stub result in javax.ejb.ObjectNotFoundException being thrown
+ to the client. Subsequent requests by server on behalf of the removed bean will
[... 355 lines stripped ...]