blob: c0137d98048f67ff89ccf48d6e43c7def90c0de2 [file] [log] [blame]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML>
<HEAD>
<!-- $PAGETITLE -->
<TITLE>OpenEJB - Deployment ID</TITLE>
<LINK href="http://openejb.apache.org/all.css" rel="stylesheet" type="text/css">
<!--[if IE]><link rel="stylesheet" type="text/css" media="screen, projection" href="openejb.apache.org/ie.css"><![endif]-->
<LINK rel="SHORTCUT ICON" href="http://openejb.apache.org/images/favicon.ico">
<META http-equiv="Content-Type" content="text/html;charset=UTF-8">
<SCRIPT language="javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.1/jquery.min.js" type="text/javascript"></SCRIPT>
<SCRIPT language="javascript" src="http://openejb.apache.org/tweet/jquery.tweet.js" type="text/javascript"></SCRIPT>
<SCRIPT type="text/javascript">
$(document).ready(function(){
$(".tweet").tweet({
avatar_size: 32,
count: 4,
fetch:25,
username: "openejb",
list: "contributors",
template:"{avatar}{text}",
filter: function(t){ return /openejb/i.test(t["tweet_raw_text"]); },
loading_text: "loading list..."
});
});
</SCRIPT>
</HEAD>
<BODY>
<!-- Delay the loading of the external javascript file needed for labels (as it takes too long to load and visibly holds loading of the page body) -->
<!-- To do this without javascript errors over undefined functions, we need to declare stubs here (that are overrided later by the proper implementations) -->
<SCRIPT language="JavaScript" type="text/javascript">
function doAddLabel(hideTextfieldAfterAddParam)
{
// stub
}
function onAddLabel()
{
// stub
}
function showLabelsInput()
{
// stub
}
</SCRIPT>
<A name="top"></A>
<TABLE class="frameTable" cellpadding="0" cellspacing="0" border="0">
<TR class="Row1">
<TD class="Col1"><IMG alt="" src="http://openejb.apache.org/images/dotTrans.gif"></TD>
<TD class="Col2"><IMG alt="" src="http://openejb.apache.org/images/dotTrans.gif"></TD>
<TD class="Col3"><IMG alt="" src="http://openejb.apache.org/images/dotTrans.gif"></TD>
<TD class="Col4"><IMG alt="" src="http://openejb.apache.org/images/dotTrans.gif"></TD>
<TD class="Col5"><IMG alt="" src="http://openejb.apache.org/images/dotTrans.gif"></TD>
</TR>
<TR class="Row2">
<TD class="Col1"><IMG alt="" src="http://openejb.apache.org/images/dotTrans.gif"></TD>
<TD class="Col2">&nbsp;</TD>
<TD class="Col3" id="breadcrumbs">
<!-- $TOP_NAV_BAR -->
<A href="index.html" title="Index">Home</A> | <A href="news.html" title="News">News</A> | <A href="faq.html" title="FAQ">FAQ</A> | <A href="download.html" title="Download">Download</A> | <A href="mailing-lists.html" title="Mailing Lists">Lists</A> | <A href="http://issues.apache.org/jira/browse/OPENEJB" class="external-link" rel="nofollow">Issues</A>
</TD>
<TD class="Col4"><IMG alt="" src="http://openejb.apache.org/images/dotTrans.gif"></TD>
<TD class="Col5">&nbsp;</TD>
</TR>
<TR class="Row3">
<TD class="Col1"><IMG alt="" class="Row3Img" id="thinLine" src="http://openejb.apache.org/images/line_sm.gif"></TD>
<TD class="Col2"><IMG alt="" class="Row3Img" src="http://openejb.apache.org/images/dotTrans.gif"></TD>
<TD class="Col3"><IMG alt="" class="Row3Img" src="http://openejb.apache.org/images/dotTrans.gif"></TD>
<TD class="Col4"><IMG alt="" src="http://openejb.apache.org/images/dotTrans.gif"></TD>
<TD class="Col5"><IMG alt="" class="Row3Img" src="http://openejb.apache.org/images/dotTrans.gif"></TD>
</TR>
<TR class="Row4">
<TD class="Col1">
<SPAN id="Navigation">
<H3><A name="Navigation-Overview"></A>Overview</H3>
<UL class="alternate" type="square">
<LI><A href="index.html" title="Index">Home</A></LI>
<LI><A href="news.html" title="News">News</A></LI>
<LI><A href="faq.html" title="FAQ">FAQ</A></LI>
<LI><A href="download.html" title="Download">Download</A></LI>
<LI><A href="../OPENEJBx30/index.html" title="Index">Documentation</A></LI>
<LI><A href="examples.html" title="Examples">Examples</A></LI>
<LI><A href="http://cwiki.apache.org/confluence/display/OPENEJB/Lightening%20Demos" class="external-link" rel="nofollow">Lightning Demos</A></LI>
<LI><A href="mailing-lists.html" title="Mailing Lists">Mailing Lists</A></LI>
<LI><A href="source-code.html" title="Source Code">Source Code</A></LI>
<LI><A href="http://blogs.apache.org/openejb" class="external-link" rel="nofollow">Project Blog</A></LI>
</UL>
<H3><A name="Navigation-Servers"></A>Servers</H3>
<UL class="alternate" type="square">
<LI><A href="local-server.html" title="Local Server">Local</A></LI>
<LI><A href="remote-server.html" title="Remote Server">Remote</A></LI>
</UL>
<H3><A name="Navigation-Integrations"></A>Integrations</H3>
<UL class="alternate" type="square">
<LI><A href="../OPENEJBx30/tomcat.html" title="Tomcat">Tomcat</A></LI>
<LI><A href="geronimo.html" title="Geronimo">Geronimo</A></LI>
<LI><A href="webobjects.html" title="WebObjects">WebObjects</A></LI>
</UL>
<H3><A name="Navigation-Community"></A>Community</H3>
<UL class="alternate" type="square">
<LI><A href="team.html" title="Team">Team</A></LI>
<LI><A href="articles.html" title="Articles">Articles</A></LI>
<LI><A href="http://webchat.freenode.net/?channels=openejb" class="external-link" rel="nofollow">IRC</A></LI>
</UL>
<H3><A name="Navigation-RelatedProjects"></A>Related Projects</H3>
<UL class="alternate" type="square">
<LI><A href="http://activemq.apache.org/" class="external-link" rel="nofollow">ActiveMQ</A></LI>
<LI><A href="http://openjpa.apache.org/" class="external-link" rel="nofollow">OpenJPA</A></LI>
<LI><A href="http://cxf.apache.org/" class="external-link" rel="nofollow">CXF</A></LI>
</UL>
<H3><A name="Navigation-Index"></A>Index</H3>
<UL class="alternate" type="square">
<LI><A href="space-index.html" title="Space Index">Site Index</A></LI>
<LI><A href="../OPENEJBx30/space-index.html" title="Space Index">Doc Index</A></LI>
</UL>
<H3>
<A name="Navigation-Feeds"></A>
Feeds
</H3>
<UL class="feeds">
<LI>
<A href="http://cwiki.apache.org/confluence/spaces/rss.action?key=OPENEJB&newPages=false">
<IMG src="http://openejb.apache.org/images/rss.gif"></A>
<A class="feedsText" href="http://cwiki.apache.org/confluence/spaces/rss.action?key=OPENEJB&newPages=false">Site</A>
</LI>
<LI><A href="http://cwiki.apache.org/confluence/spaces/blogrss.action?key=OPENEJB">
<IMG src="http://openejb.apache.org/images/rss.gif"></A>
<A class="feedsText" href="http://cwiki.apache.org/confluence/spaces/blogrss.action?key=OPENEJB">News</A>
</LI>
</UL>
</SPAN>
</TD>
<TD class="Col2">&nbsp;</TD>
<TD class="Col3">
<TABLE id="PageHeader" border="0" width="100%">
<TR>
<TD>
<A href="http://openejb.org/">
<IMG hspace="0" src="http://openejb.apache.org/images/logo_openejb.gif" vspace="0">
</A>
</TD>
<TD align="right">
<A href="http://www.apache.org/">
<IMG src="http://www.apache.org/images/asf-logo.gif" width="258" height="66">
</A>
</TD>
</TR>
<TR>
<TD id="page_title">
<!-- $TITLE -->
Deployment ID
</TD>
<TD align="right">
<BR><BR>
<!-- Google CSE Search Box Begins -->
<FORM id="searchbox_010475492895890475512:_t4iqjrgx90" action="http://www.google.com/cse">
<INPUT type="hidden" name="cx" value="010475492895890475512:_t4iqjrgx90">
<INPUT type="hidden" name="cof" value="FORID:0">
<INPUT name="q" type="text" size="25">
<INPUT type="submit" name="sa" value="Search">
</FORM>
<SCRIPT type="text/javascript" src="http://www.google.com/coop/cse/brand?form=searchbox_010475492895890475512:_t4iqjrgx90"></SCRIPT>
<!-- Google CSE Search Box Ends -->
</TD>
</TR>
</TABLE>
<P>
<!-- $BODY -->
<DIV id="PageContent">
<H1><A name="DeploymentID-WhatisaDeploymentID%3F"></A>What is a Deployment ID?</H1>
<P>Every bean deployed in OpenEJB has a unique deployment-id that identifies it within the scope of the entire container system. The server and container system refer beans at run-time using the bean's deployment id.</P>
<H2><A name="DeploymentID-Likeejbname"></A>Like ejb-name</H2>
<P>This deployment id is much like the &lt;ejb-name&gt; element of the ejb-jar.xml , with one very important difference. The &lt;ejb-name&gt; is only required to be unique within the scope of the ejb-jar.xml in the bean's jar. The deployment id is required to be unique across all beans and jars in OpenEJB. This is a subtle, but important, distinction.</P>
<P>Remember that the EJB specification was designed so that enterprise beans could be create, packaged, and sold by vendors (EJB Providers). Furthermore, users should be able to buy a packaged set of beans (a jar with an ejb-jar.xml in it) and deploy it into an EJB Container without modification.</P>
<H2><A name="DeploymentID-Theejbnameisnotunique"></A>The ejb-name is not unique</H2>
<P>Let's consider this, what happens if two vendors each sell a package (jar) that contains a bean with the &lt;ejb-name&gt; PurchaseOrder? Both are completely different in terms functionality and are different beans in every other respect. The EJB spec says, this is fine, ejb-names only have to unique within the jar and that jar's ejb-jar.xml file. It's redictulous to excpect EJB Providers to call each other up and ask, &quot;Are you already using the name 'PurchaseOrder' in your jar?&quot; Remember that the EJB specification was designed so that enterprise beans could be create, packaged, and sold by vendors (EJB Providers). Furthermore, users should be able to buy a packaged set of beans (a jar with an ejb-jar.xml in it) and deploy it into an EJB Container without modification. This is all fine and dandy, but it still leaves it up to the EJB Container/Server providers to settle the difference.</P>
<H2><A name="DeploymentID-Thedeploymentidisunique"></A>The deployment-id is unique</H2>
<P>OpenEJB solves this with the OpenEJB-specific deployment id. By requiring that each bean deployed into OpenEJB has a unique name, we can guarantee that we are always refering to the right bean at all times. Futhermore, it allows you to deploy different versions of the same package several times in the same container system, each time giving the beans new deployment ids.</P>
<H2><A name="DeploymentID-Usingejbnameasdeploymentidanyway"></A>Using ejb-name as deployment-id anyway</H2>
<P>If you're lazy &ndash; as any truly great programmer should be &ndash; and don't want to type a deployment id for each bean every time you deploy a jar, you can use the -D option of the Deploy Tool. This will throw caution to the wind, and automatically assign the bean's ejb-name as the value of the bean's OpenEJB deployment id. This leaves up to you to guarantee that bean's ejb-name will be unique across all beans and jars in the container system. In other words, be very careful with the -D option!</P>
<H1><A name="DeploymentID-Howisitused%3F"></A>How is it used?</H1>
<H2><A name="DeploymentID-Inthecontainersystem"></A>In the container system</H2>
<P>In the container system, the deployment id is used to undex the bean in a system-wide registry. This registry is refered to on every call made in the container system. Being able to safely hash and cache bean information by id is a must. This stresses the importance of unique ids for every bean deployed in OpenEJB.</P>
<H2><A name="DeploymentID-IntheLocalServer"></A>In the Local Server</H2>
<P>The Local (IntraVM) Server is an integral part of the container system and the two are, in many ways, inseparable. The Local Server takes care of all bean to bean and client to bean invocations made inside the virtual machine. For this reason, it often refered to as the IntraVM Server.</P>
<P>For bean to bean communications, the Local Server must create a JNDI namespace (JNDI ENC) for each bean as defined by the bean's &lt;env-entry&gt;, &lt;ejb-ref&gt;, and &lt;resource-ref&gt; elements of the bean's ejb-jar.xml file. Every bean litterally gets its very own JNDI namespace. When a bean makes a JNDI call, the Local Server intercepts this call and uses the deployment id of the calling bean to retreive that bean's private JNDI namespace from the container system's index. The Local Server then carries out the lookup on that bean's namespace.</P>
<P>All non-bean clients share one big global namespace. Since non-bean clients are not deployed and do not have a deployment descriptor like an ejb-jar.xml, the Local Server is unable to taylor a namespace for each non-bean client as it can for bean clients. The Local server cannot identify non-bean clients as they have no deployment id. All JNDI calls made by clients that the Local Server cannot identify go to the public, global namespace. The public, global JNDI namespace contains all beans and resources in the container system. name.</P>
<P>Each bean is added to the public, global namespace using it's deployment id as its JNDI lookup. For example, if a bean had a deployment-id of &quot;/my/bean/foo&quot;, a non-bean client could lookup that bean as follows.</P>
<DIV class="code panel" style="border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;"><B>MyAppClient.java</B></DIV><DIV class="codeContent panelContent">
<PRE class="code-java">
...
<SPAN class="code-object">Object</SPAN> bean = initialContext.lookup(<SPAN class="code-quote">&quot;/my/bean/Foo&quot;</SPAN>);
...
</PRE>
</DIV></DIV>
<P>If a bean in the container system made the above JNDI call, the Local Server would see the bean's identity (deployment id) hidden in the Thread, go get the bean's private JNDI namespace and finish the lookup on that. Since all names in bean's JNDI namespace are required start with &quot;java:comp/env&quot;, the lookup would fail and the bean would receive a javax.naming.NameNotFoundException.</P>
<P>In short...</P>
<P>For beans:</P>
<UL class="alternate" type="square">
<LI>Each bean has it's own private, personalized JNDI namespace</LI>
<LI>The names in it are the same names it uses in its ejb-jar.xml</LI>
<LI>Beans can only access their private namespace, period</LI>
</UL>
<P>For non-beans (everyone else):</P>
<UL class="alternate" type="square">
<LI>Non-bean clients share the public, global JNDI namespace</LI>
<LI>The names in it are the deployment ids of all the beans</LI>
<LI>Non-bean clients can only access the one global namespace</LI>
</UL>
<H2><A name="DeploymentID-IntheRemoteServer"></A>In the Remote Server</H2>
<P>The Remote Server has a public, global namespace just as the Local Server does. The difference being that the Remote Server only serves clients outside the container system and outside the virtual machine. So, all clients from the perspective of the Remote Server are non-bean clients. As a result, the Remote Server only has the one public, global JNDI namespace. Just as in the Local Server, the names in this namespacse consist of the deployment ids of the beans in the container system.</P>
<P>Just as before, clients can lookup beans from the Remote Server using the bean's deployment id. For example, if a bean had a deployment-id of &quot;/my/bean/foo&quot;, a client could lookup that bean as follows.</P>
<DIV class="code panel" style="border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;"><B>MyAppClient.java</B></DIV><DIV class="codeContent panelContent">
<PRE class="code-java">
...
<SPAN class="code-object">Object</SPAN> bean = initialContext.lookup(<SPAN class="code-quote">&quot;/my/bean/Foo&quot;</SPAN>);
...
</PRE>
</DIV></DIV>
<H2><A name="DeploymentID-IntheCORBAAdapter"></A>In the CORBA Adapter</H2>
<P>The CORBA Adapter is separate than the Remote Server. It adapts the OpenEJB Container System and the Local Server into OpenORB as an embedded library. It provides users of OpenORB the ability to lookup and execute beans (EJBs) via the RMI-IIOP protocol. All the EJBHome and EJBObject interfaces of beans in OpenEJB are implemented by OpenORB as CORBA stubs and ties.</P>
<P>The beans are exported into OpenORB's naming service by deployment id. So, just as with the Local Server and Remote Server, clients can lookup beans using the bean's deployment id. OpenORB has a JNDI implementation of their naming service, so lookups can be done just as before.</P>
<DIV class="code panel" style="border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;"><B>MyAppClient.java</B></DIV><DIV class="codeContent panelContent">
<PRE class="code-java">
...
<SPAN class="code-object">Object</SPAN> bean = initialContext.lookup(<SPAN class="code-quote">&quot;/my/bean/Foo&quot;</SPAN>);
...
{}
CORBA clients can also access beans in OpenEJB as CORBA objects. These can be looked up from OpenORB's naming service (CosNaming) as follows.
{code:title=MyCorbaAppClient.java}
...
<SPAN class="code-object">String</SPAN>[] args = ...
<SPAN class="code-comment">// The ORB and <SPAN class="code-object">Object</SPAN>
</SPAN>org.omg.CORBA.ORB orb = <SPAN class="code-keyword">null</SPAN>;
org.omg.CORBA.<SPAN class="code-object">Object</SPAN> bean = <SPAN class="code-keyword">null</SPAN>.
<SPAN class="code-comment">// The Naming Service and <SPAN class="code-object">Object</SPAN> Name
</SPAN>org.omg.CosNaming.NamingContext context = <SPAN class="code-keyword">null</SPAN>;
org.omg.CosNaming.NameComponent[] name = <SPAN class="code-keyword">null</SPAN>;
<SPAN class="code-comment">// Get the ORB
</SPAN>orb = org.omg.CORBA.ORB.init( args, <SPAN class="code-keyword">null</SPAN> );
<SPAN class="code-comment">// Get the Naming Service
</SPAN>org.omg.CORBA.<SPAN class="code-object">Object</SPAN> ref = <SPAN class="code-keyword">null</SPAN>;
ref = orb.resolve_initial_references(<SPAN class="code-quote">&quot;NameService&quot;</SPAN>);
context = org.omg.CosNaming.NamingContextHelper.narrow( ref );
<SPAN class="code-comment">// Get the Name as a component
</SPAN><SPAN class="code-comment">// Note: the string is the bean's deployment id
</SPAN>name = <SPAN class="code-keyword">new</SPAN> org.omg.CosNaming.NameComponent[ 1 ];
name[0] = <SPAN class="code-keyword">new</SPAN> org.omg.CosNaming.NameComponent(<SPAN class="code-quote">&quot;/my/bean/foo&quot;</SPAN>,&quot;&quot;);
<SPAN class="code-comment">// Finally, get the bean as a CORBA object
</SPAN><SPAN class="code-comment">// Equvalent to an InitialContext.lookup(<SPAN class="code-quote">&quot;/my/bean/foo&quot;</SPAN>);
</SPAN>bean = context.resolve( name );
...
</PRE>
</DIV></DIV>
<H1><A name="DeploymentID-WhathappensifthereisaduplicatedeploymentID%3F"></A>What happens if there is a duplicate deployment ID?</H1>
<P>The deployment ID uniquely identifies the bean in the OpenEJB container system. Therefore, no two beans can share the same deployment ID.</P>
<P>If a bean attempts to use a deployment ID that is already in use by another bean, the second bean and all beans in it's jar will not be loaded. In addition, the system will log a warning like the following one asking you to redeploy the jar and choose an different deployment ID for the bean.</P>
<DIV class="panel" style="border-width: 1px;"><DIV class="panelHeader" style="border-bottom-width: 1px;"><B>openejb.log</B></DIV><DIV class="panelContent">
<P>WARN : Jar C:\openejb\beans\fooEjbs.jar cannot be loaded. The <BR>
Deployment ID &quot;/my/bean/foo&quot; is already in use. Please redeploy <BR>
this jar and assign a different deployment ID to the bean with <BR>
the ejb-name &quot;FooBean&quot;.</P>
</DIV></DIV>
<P>For example, the acmeEjbs.jar contains a bean with the ejb-name &quot;DaffyDuckBean&quot;. The disneyEjbs.jar contains contains a bean with the ejb-name &quot;DonaldDuckBean&quot;.</P>
<P>We deploy the acmeEjbs.jar and give the &quot;DaffyDuckBean&quot; the deployment ID of &quot;/my/favorite/duck&quot;. Sometime afterwards, we deploy the disneyEjbs.jar and assign the &quot;DonaldDuckBean&quot; the deployment ID &quot;/my/favorite/duck&quot;, having forgotten that we already gave that unique ID to the &quot;DaffyDuckBean&quot; in the acmeEjbs.jar.</P>
<P>When the container system is started, the system will begin loading all the beans one jar at a time. It will first load the acmeEjbs.jar and index each bean by deployment ID. But, when the system reaches the disneyEjbs.jar, it will discover that it cannot index the &quot;DonaldDuckBean&quot; using the deployment ID &quot;/my/favorite/duck&quot; because that index is already taken.</P>
<P>The system cannot load the &quot;DonaldDuckBean&quot; and must also ignore the rest of the beans in the disneyEjbs.jar as they may need the &quot;DonaldDuckBean&quot; bean to function properly. The disneyEjbs.jar is skipped and the following warning is logged.</P>
<DIV class="panel" style="border-width: 1px;"><DIV class="panelHeader" style="border-bottom-width: 1px;"><B>openejb.log</B></DIV><DIV class="panelContent">
<P>WARN : Jar C:\openejb\beans\disneyEjbs.jar cannot be loaded. The <BR>
Deployment ID &quot;/my/favorite/duck&quot; is already in use. Please redeploy <BR>
this jar and assign a different deployment ID to the bean with <BR>
the ejb-name &quot;DonaldDuckBean&quot;.</P>
</DIV></DIV>
</DIV>
</P>
</TD>
<TD class="Col4"><IMG src="http://openejb.apache.org/images/dotTrans.gif"></TD>
<TD class="Col5">
</TD>
</TR>
<TR class="Row5">
<TD class="Col1">&nbsp;</TD>
<TD class="Col2">&nbsp;</TD>
<TD class="Col3">
<BR>
<BR>
<IMG width="100%" height="1" src="http://openejb.apache.org/images/line_light.gif">
<TABLE width="100%">
<TR>
<TD>
<SPAN class="bodyGrey">
<SMALL>
<NOTICE><!-- $FOOTER -->
Apache OpenEJB is an project of The Apache Software Foundation (ASF)
</NOTICE>
<BR>
Site Powered by
<A href="http://atlassian.com/">Atlassian</A>
<A href="http://atlassian.com/confluence/">Confluence</A>
.
</SMALL>
</SPAN>
</TD>
<TD align="right">
<A style="color:#999;font-size:small;font-weight:normal;" href="https://cwiki.apache.org/confluence/pages/editpage.action?spaceKey=OPENEJB&title=Deployment%20ID">[ edit ]</A>
</TD>
</TR>
</TABLE>
<BR>
</TD>
<TD class="Col4"><IMG src="http://openejb.apache.org/images/dotTrans.gif"></TD>
<TD class="Col5">&nbsp;</TD>
</TR>
</TABLE>
<!-- Needed for composition plugin -->
<!-- delay the loading of large javascript files to the end so that they don't interfere with the loading of page content -->
<SPAN style="display: none">
<SCRIPT type="text/javascript" language="JavaScript" src="http://cwiki.apache.org/confluence/labels-javascript"></SCRIPT>
<SCRIPT src="http://www.google-analytics.com/urchin.js" type="text/javascript">
</SCRIPT>
<SCRIPT type="text/javascript">
_uacct = "UA-2717626-1";
urchinTracker();
</SCRIPT>
</SPAN>
</BODY>
</HTML>