Google Git
Sign in
apache / openejb / ff4c3995cf32f0a3fc5fe4b624f529023f76b530 / . / html / old-site / html / tomcat.html
blob: 427cd713fbd29712b7edaf67560166731ec974e0 [file] [log] [blame]
<html><head><META http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>OpenEJB Tomcat Integration</title><link href="default.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>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="http://wiki.codehaus.org/openejb"><span class="menuTopOff">[ w i k i ]</span></a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="http://archive.openejb.codehaus.org/user/"><span class="menuTopOff">[ l i s t s ]</span></a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="http://cvs.openejb.org/"><span class="menuTopOff">[ c v s ]</span></a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="http://jira.codehaus.org/secure/BrowseProject.jspa?id=10401"><span class="menuTopOff">[ b u g s ]</span></a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<br><img border="0" height="2" width="1" src="images/dotTrans.gif"></td><td align="left" valign="top" height="20" width="120">&nbsp;</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">&nbsp;&nbsp;&nbsp;
Welcome!</span></a></td></tr><tr><td align="left" valign="top"><a href="download.html"><span class="subMenuOff">&nbsp;&nbsp;&nbsp;
Download</span></a></td></tr><tr><td align="left" valign="top"><a href="lists.html"><span class="subMenuOff">&nbsp;&nbsp;&nbsp;
Mailing Lists</span></a></td></tr><tr><td align="left" valign="top"><a href="cvs.html"><span class="subMenuOff">&nbsp;&nbsp;&nbsp;
Source Code</span></a></td></tr><tr><td align="left" valign="top"><a href="contributors.html"><span class="subMenuOff">&nbsp;&nbsp;&nbsp;
The Team</span></a></td></tr><tr><td align="left" valign="top"><a href="status.html"><span class="subMenuOff">&nbsp;&nbsp;&nbsp;
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">&nbsp;&nbsp;&nbsp;
Quickstart</span></a></td></tr><tr><td align="left" valign="top"><a href="hello-world.html"><span class="subMenuOff">&nbsp;&nbsp;&nbsp;
Hello World!</span></a></td></tr><tr><td align="left" valign="top"><a href="cmp_entity_postgresql.html"><span class="subMenuOff">&nbsp;&nbsp;&nbsp;
CMP Example</span></a></td></tr><tr><td align="left" valign="top"><a href="cmp_guide.html"><span class="subMenuOff">&nbsp;&nbsp;&nbsp;
CMP Guide</span></a></td></tr><tr><td align="left" valign="top"><a href="deploy.html"><span class="subMenuOff">&nbsp;&nbsp;&nbsp;
Deploy</span></a></td></tr><tr><td align="left" valign="top"><a href="start-command.html"><span class="subMenuOff">&nbsp;&nbsp;&nbsp;
Startup</span></a></td></tr><tr><td align="left" valign="top"><a href="validate.html"><span class="subMenuOff">&nbsp;&nbsp;&nbsp;
Validation</span></a></td></tr><tr><td align="left" valign="top"><a href="config_containers.html"><span class="subMenuOff">&nbsp;&nbsp;&nbsp;
Configuration</span></a></td></tr><tr><td align="left" valign="top"><a href="properties.html"><span class="subMenuOff">&nbsp;&nbsp;&nbsp;
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">&nbsp;&nbsp;&nbsp;
Local Server</span></a></td></tr><tr><td align="left" valign="top"><a href="remote-server.html"><span class="subMenuOff">&nbsp;&nbsp;&nbsp;
Remote Server</span></a></td></tr><tr><td align="left" valign="top"><a href="tomcat.html"><span class="subMenuOff">&nbsp;&nbsp;&nbsp;
Tomcat</span></a></td></tr><tr><td align="left" valign="top"><a href="geronimo.html"><span class="subMenuOff">&nbsp;&nbsp;&nbsp;
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">&nbsp;&nbsp;&nbsp;
Why OpenEJB</span></a></td></tr><tr><td align="left" valign="top"><a href="containersystem.html"><span class="subMenuOff">&nbsp;&nbsp;&nbsp;
Overview</span></a></td></tr><tr><td align="left" valign="top"><a href="design_openejb.html"><span class="subMenuOff">&nbsp;&nbsp;&nbsp;
Design</span></a></td></tr><tr><td align="left" valign="top"><a href="OpenEJB_presentaion.ppt"><span class="subMenuOff">&nbsp;&nbsp;&nbsp;
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">&nbsp;</td><td align="left" valign="top" width="40">&nbsp;</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 Tomcat Integration</span><br><img src="images/dotTrans.gif" hspace="0" height="1" border="0"></td></tr></table><p></p><p></p><br><span class="toc"><a href="#intro">Introduction</a><br></span><span class="toc"><a href="#per-tomcat">OpenEJB per Tomcat instance</a><br></span><span class="toc"><a href="#per-webapp">OpenEJB per webapp</a><br></span><span class="toc"><a href="#tomcat-resource-factory">OpenEJB Tomcat resource factory</a><br></span><span class="toc"><a href="#contribution">How to make the document even more helpful resource</a><br></span><br><a name="intro"><h2>Introduction</h2></a>
<p><span class="bodyBlack">There are a few approaches to integrate OpenEJB and <a href="http://jakarta.apache.org/tomcat">Jakarta Tomcat</a>.
The difference between them is in the visibility of EJBs (deployed onto OpenEJB) amongst web applications (deployed onto Tomcat).
The term <i>visibility</i> means what classloaders handle loading of the EJBs.
<br>OpenEJB configuration by its visibility</br>
<table cellspacing="2" cellpadding="2" border="0"><tr><td height="5" colspan="2"></td></tr><span class="bodyGrey">
<tr><td width="10" valign="top" align="left"><img src="images/grayDot.gif"></td><td valign="top" align="left"><span class="bodyBlack">
<a href="#per-tomcat">OpenEJB per Tomcat instance</a> - deployed EJBs are shared amongst all of the web apps</span></td></tr>
<tr><td width="10" valign="top" align="left"><img src="images/grayDot.gif"></td><td valign="top" align="left"><span class="bodyBlack">
<a href="#per-webap">OpenEJB per webapp</a> - deployed EJBs are visible only to the web apps that declared to load OpenEJB</span></td></tr>
<tr><td width="10" valign="top" align="left"><img src="images/grayDot.gif"></td><td valign="top" align="left"><span class="bodyBlack">
<a href="#tomcat-resource-factory">OpenEJB Tomcat resource factory</a> - an implementation of <a href="http://jakarta.apache.org/tomcat/tomcat-5.0-doc/jndi-resources-howto.html">Tomcat's resource factory</a> mechanism</span></td></tr>
</span></table>
</span></p>
<a name="per-tomcat"><h2>OpenEJB per Tomcat instance</h2></a>
<p><span class="bodyBlack">
Configure OpenEJB per Tomcat instance requires the following steps:
<ol>
<li>Copy the <i>war/openejb-loader-1.0-SNAPSHOT.war</i> into the webapps dir of a running Tomcat install</li>
<table width="440" cellspacing="0" cellpadding="0" border="0"><tr><td bgcolor="#c0c0c0"><i><span class="code-title">Under Unix</span></i></td></tr><tr><td bgcolor="#e0e0e0"><span class="code-block"><pre>
$ cd $OPENEJB_HOME
$ cp war/openejb-loader-1.0-SNAPSHOT.war $CATALINA_HOME/webapps
</pre></span></td></tr></table>
or
<table width="440" cellspacing="0" cellpadding="0" border="0"><tr><td bgcolor="#c0c0c0"><i><span class="code-title">Under Windows</span></i></td></tr><tr><td bgcolor="#e0e0e0"><span class="code-block"><pre>
c:/&gt; cd %OPENEJB_HOME%
%OPENEJB_HOME%&gt; cp war/openejb-loader-1.0-SNAPSHOT.war %CATALINA_HOME%/webapps
</pre></span></td></tr></table>
<li>Update the openejb.home init param (inside the WEB-INF/web.xml file) to point to where OpenEJB was installed. <br>If OpenEJB has been built from the source you can skip it (during the build procedure it is updated automatically)</br></li>
<table width="440" cellspacing="0" cellpadding="0" border="0"><tr><td bgcolor="#c0c0c0"><i><span class="code-title">Under Unix</span></i></td></tr><tr><td bgcolor="#e0e0e0"><span class="code-block"><pre>
$ cd $CATALINA_HOME/webapps
$ jar -xvf openejb-loader-1.0-SNAPSHOT.war WEB-INF/web.xml
...edit WEB-INF/web.xml...
$ jar -uvf openejb-loader-1.0-SNAPSHOT.war WEB-INF/web.xml
$ rm -rf WEB-INF
</pre></span></td></tr></table>
or
<table width="440" cellspacing="0" cellpadding="0" border="0"><tr><td bgcolor="#c0c0c0"><i><span class="code-title">Under Windows</span></i></td></tr><tr><td bgcolor="#e0e0e0"><span class="code-block"><pre>
c:/&gt; cd %CATALINA_HOME%/webapps
%CATALINA_HOME%/webapps&gt; jar -xvf openejb-loader-1.0-SNAPSHOT.war WEB-INF/web.xml
...edit WEB-INF/web.xml...
%CATALINA_HOME%/webapps&gt; jar -uvf openejb-loader-1.0-SNAPSHOT.war WEB-INF/web.xml
%CATALINA_HOME%/webapps&gt; rmdir /S /Q WEB-INF
</pre></span></td></tr></table>
<li>Create the <i>temp</i> directory under Tomcat's home directory</li>
<table bgcolor="#7270c2" width="440" cellspacing="0" cellpadding="0" border="0"><tr><td bgcolor="#7270c2"><span class="note-caption">&nbsp;NOTE</span></td></tr><tr><td bgcolor="#7270c2"><table bgcolor="#7270c2" width="100%" cellspacing="2" cellpadding="7" border="0"><tr><td bgcolor="#FFFFFF"><span class="note">This is because the beans that's been successfully validated are deployed. During validation OpenEJB creates temporary files under the <i>temp.dir</i> directory, which is overriden by Tomcat to its temp directory. Unfortunatelly, the directory doesn't exist and needs to be created manually.</span></td></tr></table></td></tr></table>
<li>Deploy your webapps that are using the beans deployed onto OpenEJB</li>
<li>Start up Tomcat and have fun with the EJBs</li>
</ol>
</span></p>
<a name="per-webapp"><h2>OpenEJB per webapp</h2></a>
<p><span class="bodyBlack">
Configure OpenEJB per webapp requires the following steps:
<ol>
<li>Copy the <i>openejb-loader-*.jar</i> into the WEB-INF/lib directory of the webapp that is to use EJBs deployed onto OpenEJB</li>
<li>Add the <i>loader</i> servlet definition to the WEB-INF/web.xml file of the webapp with a valid value for openejb.home init-param.
<table width="440" cellspacing="0" cellpadding="0" border="0"><tr><td bgcolor="#e0e0e0"><span class="code-block"><pre>
&lt;servlet&gt;
&lt;servlet-name&gt;loader&lt;/servlet-name&gt;
&lt;servlet-class&gt;org.openejb.loader.LoaderServlet&lt;/servlet-class&gt;
&lt;init-param&gt;
&lt;param-name&gt;openejb.loader&lt;/param-name&gt;
&lt;param-value&gt;tomcat-webapp&lt;/param-value&gt;
&lt;/init-param&gt;
&lt;init-param&gt;
&lt;param-name&gt;openejb.home&lt;/param-name&gt;
&lt;param-value&gt;...define OPENEJB_HOME here...&lt;/param-value&gt;
&lt;/init-param&gt;
&lt;load-on-startup&gt;0&lt;/load-on-startup&gt;
&lt;/servlet&gt;
</pre></span></td></tr></table>
<p><span class="bodyBlack">Should you define other OpenEJB configuration settings use another &lt;init-param&gt; stanza. It's just for that. These parameters are directly passed to OpenEJB at initialization of the servlet. Think about the loader servlet as a bridge between OpenEJB's world (EJBs) and Tomcat's world (servlets, JSPs).</span></p>
<p><span class="bodyBlack">At startup OpenEJB prints out all of the configuration settings to Tomcat logs:</span></p>
<table width="440" cellspacing="0" cellpadding="0" border="0"><tr><td bgcolor="#e0e0e0"><span class="code-block"><pre>INFO: Installing web application at context path /openejb from URL file:C:\webapps\openejb
OpenEJB init-params:
param-name: openejb.home, param-value: c:\openejb
param-name: openejb.configuration, param-value: conf\openejb.cfg
param-name: openejb.base, param-value: c:\webapps\openejb\WEB-INF\openejb
param-name: openejb.loader, param-value: tomcat-webapp</pre></span></td></tr></table>
</li>
<li>Start up Tomcat and have fun with the EJBs</li>
</ol>
</span></p>
<a name="tomcat-resource-factory"><h2>OpenEJB Tomcat resource factory</h2></a>
<p><span class="bodyBlack">Read about it <a href="tomcat-object-factory.html">here</a>.</span></p>
<a name="contribution"><h2>How to make the document even more helpful resource</h2></a>
<p><span class="bodyBlack">
This document is a starting point for using OpenEJB in Tomcat and will evolve based
on user contributions. If you wish to contribute to this document, please email the
text to the <a href="lists.html#user">OpenEJB User</a> list.
<table cellspacing="2" cellpadding="2" border="0"><tr><td height="5" colspan="2"></td></tr><span class="bodyGrey">
<tr><td width="10" valign="top" align="left"><img src="images/grayDot.gif"></td><td valign="top" align="left"><span class="bodyBlack">
<A HREF="tomcat-howitworks.html">How does the integration work</A>
</span></td></tr>
<tr><td width="10" valign="top" align="left"><img src="images/grayDot.gif"></td><td valign="top" align="left"><span class="bodyBlack">
<A HREF="tomcat-ejbclasses.html">Where to put your ejb classes</A>
</span></td></tr>
<tr><td width="10" valign="top" align="left"><img src="images/grayDot.gif"></td><td valign="top" align="left"><span class="bodyBlack">
<A HREF="tomcat-ejbrefs.html">How to configure java:comp/env lookups (short)</A>
</span></td></tr>
<tr><td width="10" valign="top" align="left"><img src="images/grayDot.gif"></td><td valign="top" align="left"><span class="bodyBlack">
<a href="tomcat-object-factory.html">How to configure java:comp/env lookups (detailed)</a>
</span></td></tr>
</span></table>
</span></p>
<p><span class="bodyBlack">
<table cellspacing="2" cellpadding="2" border="0"><tr><td height="5" colspan="2"></td></tr><span class="bodyGrey">
Misc:
<tr><td width="10" valign="top" align="left"><img src="images/grayDot.gif"></td><td valign="top" align="left"><span class="bodyBlack">
<a href="tomcat-adapter.html">Basic info</a>
</span></td></tr>
<tr><td width="10" valign="top" align="left"><img src="images/grayDot.gif"></td><td valign="top" align="left"><span class="bodyBlack">
<a href="faq_servlets.html">Servlets FAQ</a>
</span></td></tr>
</span></table>
</span></p>
</td><td align="left" valign="top" height="5" width="120"><img src="images/diagram-tomcat-adapter.gif" width="240" height="500" border="0"><br>
&nbsp;
</td></tr><tr height="5"><td align="left" valign="top" bgcolor="#7270c2" height="5" width="20">&nbsp;</td><td valign="top" bgcolor="#7270c2" height="5" width="95">&nbsp;</td><td align="left" valign="top" bgcolor="#a9a5de" height="5" width="7">&nbsp;</td><td align="left" valign="top" height="5" width="40">&nbsp;</td><td align="left" valign="top" height="5" width="120">&nbsp;</td></tr><tr><td align="left" valign="top" bgcolor="#7270c2" height="5" width="20">&nbsp;</td><td align="left" valign="top" bgcolor="#7270c2" width="95">&nbsp;</td><td align="left" valign="top" bgcolor="#a9a5de" width="7"><img border="0" height="25" width="1" src="images/dotTrans.gif"></td><td align="left" valign="top" width="40"><img border="0" height="25" width="1" src="images/dotTrans.gif"></td><td align="left" valign="top" width="120">&nbsp;</td></tr><tr height="5"><td align="left" valign="bottom" bgcolor="#7270c2" height="100%" rowspan="2" width="20"><img border="0" height="125" width="20" src="images/stripes1.gif"></td><td align="left" valign="bottom" bgcolor="#7270c2" height="100%" rowspan="2" width="95"><img border="0" height="125" width="105" src="images/stripe105.gif"></td><td align="left" valign="top" bgcolor="#a9a5de" height="100%" rowspan="2" width="7">&nbsp;</td><td align="left" valign="top" height="100%" width="40">&nbsp;</td><td align="left" valign="top" height="100%" width="120">&nbsp;</td></tr><tr height="5"><td align="left" valign="top" height="25" width="40">&nbsp;</td><td align="left" valign="bottom" height="25" width="430"><br><br><img height="3" width="430" border="0" src="images/line_light.gif"><br><p></p><span class="bodyGrey"><small><notice>
OpenEJB is a trademark of the OpenEJB Group.
Java, EJB, JDBC, JNDI, JTA, Sun, Sun Microsystems are trademarks or registered
trademarks of Sun Microsystems, Inc. in the United States and in other
countries. XML, XML Schema, XSLT and related standards are trademarks or registered
trademarks of MIT, INRIA, Keio or others, and a product of the World Wide Web
Consortium. All other product names mentioned herein are trademarks of their respective
owners.
</notice><br>&nbsp;<br></small></span><p></p>
&nbsp;
</td><td align="left" valign="top" height="25" width="120">&nbsp;</td></tr></table></body></html>