src/doc/tomcat.xml - openejb - Git at Google

 <?xml version="1.0"?>
 <?xml-stylesheet type="text/xsl" href="style\website.xsl"?>
 <document>
     <properties>
         <title>OpenEJB Tomcat Integration</title>
     </properties>
     <body>
         <sideimg src="images/diagram-tomcat-adapter.gif" width="240" height="500"/>

         <section title="Introduction" ref-id="intro">
             <p>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>
                 <ul>
                     <li>
                         <a href="#per-tomcat">OpenEJB per Tomcat instance</a> - deployed EJBs are shared amongst all of the web apps</li>
                     <li>
                         <a href="#per-webap">OpenEJB per webapp</a> - deployed EJBs are visible only to the web apps that declared to load OpenEJB</li>
                     <li>
                         <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</li>
                 </ul>
             </p>
         </section>

         <section title="OpenEJB per Tomcat instance" ref-id="per-tomcat">
             <p>
 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>

 <code name="Under Unix">
 $ cd $OPENEJB_HOME
 $ cp war/openejb-loader-1.0-SNAPSHOT.war $CATALINA_HOME/webapps
 </code>

 or

 <code name="Under Windows">
 c:/> cd %OPENEJB_HOME%
 %OPENEJB_HOME%> cp war/openejb-loader-1.0-SNAPSHOT.war %CATALINA_HOME%/webapps
 </code>

                     <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>

 <code name="Under Unix">
 $ 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
 </code>

 or

 <code name="Under Windows">
 c:/> cd %CATALINA_HOME%/webapps
 %CATALINA_HOME%/webapps> jar -xvf openejb-loader-1.0-SNAPSHOT.war WEB-INF/web.xml
 ...edit WEB-INF/web.xml...
 %CATALINA_HOME%/webapps> jar -uvf openejb-loader-1.0-SNAPSHOT.war WEB-INF/web.xml
 %CATALINA_HOME%/webapps> rmdir /S /Q WEB-INF
 </code>

                    <li>Create the <i>temp</i> directory under Tomcat's home directory</li>
                    <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.</note>
                    <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>
             </p>
         </section>

         <section title="OpenEJB per webapp" ref-id="per-webapp">
             <p>
 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.
                     <code>
 <![CDATA[
   <servlet>
     <servlet-name>loader</servlet-name>
     <servlet-class>org.openejb.loader.LoaderServlet</servlet-class>
     <init-param>
       <param-name>openejb.loader</param-name>
       <param-value>tomcat-webapp</param-value>
     </init-param>
     <init-param>
       <param-name>openejb.home</param-name>
       <param-value>...define OPENEJB_HOME here...</param-value>
     </init-param>
     <load-on-startup>0</load-on-startup>
   </servlet>
 ]]>
 </code>
 <p>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).</p>
             <p>At startup OpenEJB prints out all of the configuration settings to Tomcat logs:</p>
             <code>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</code>
                     </li>
                     <li>Start up Tomcat and have fun with the EJBs</li>
                 </ol>
             </p>
         </section>

         <section title="OpenEJB Tomcat resource factory" ref-id="tomcat-resource-factory">
         <p>Read about it <a href="tomcat-object-factory.html">here</a>.</p>
         </section>

         <section title="How to make the document even more helpful resource" ref-id="contribution">
             <p>
 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.
 <ul>
                     <li>
                         <A HREF="tomcat-howitworks.html">How does the integration work</A>
                     </li>
                     <li>
                         <A HREF="tomcat-ejbclasses.html">Where to put your ejb classes</A>
                     </li>
                     <li>
                         <A HREF="tomcat-ejbrefs.html">How to configure java:comp/env lookups (short)</A>
                     </li>
                     <li>
                         <a href="tomcat-object-factory.html">How to configure java:comp/env lookups (detailed)</a>
                     </li>
                 </ul>
             </p>
             <!--
 <p>
 <ul>
 Local Server:
 <li><a href="tomcat-setup.html">OpenEJB and Tomcat setup (Linux or Windows with Cygwin)</a></li>
 <li><a href="tomcat-setup-win.html">OpenEJB and Tomcat setup (Windows)</a></li>
 </ul>
 </p>
 -->
             <p>
                 <ul>
 Misc:
 <li>
                         <a href="tomcat-adapter.html">Basic info</a>
                     </li>
                     <li>
                         <a href="faq_servlets.html">Servlets FAQ</a>
                     </li>
                 </ul>
             </p>
         </section>
     </body>
 </document>
	<?xml version="1.0"?>
	<?xml-stylesheet type="text/xsl" href="style\website.xsl"?>
	<document>
	<properties>
	<title>OpenEJB Tomcat Integration</title>
	</properties>
	<body>
	<sideimg src="images/diagram-tomcat-adapter.gif" width="240" height="500"/>

	<section title="Introduction" ref-id="intro">
	<p>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>
	<ul>
	<li>
	<a href="#per-tomcat">OpenEJB per Tomcat instance</a> - deployed EJBs are shared amongst all of the web apps</li>
	<li>
	<a href="#per-webap">OpenEJB per webapp</a> - deployed EJBs are visible only to the web apps that declared to load OpenEJB</li>
	<li>
	<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</li>
	</ul>
	</p>
	</section>

	<section title="OpenEJB per Tomcat instance" ref-id="per-tomcat">
	<p>
	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>

	<code name="Under Unix">
	$ cd $OPENEJB_HOME
	$ cp war/openejb-loader-1.0-SNAPSHOT.war $CATALINA_HOME/webapps
	</code>

	or

	<code name="Under Windows">
	c:/> cd %OPENEJB_HOME%
	%OPENEJB_HOME%> cp war/openejb-loader-1.0-SNAPSHOT.war %CATALINA_HOME%/webapps
	</code>

	<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>

	<code name="Under Unix">
	$ 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
	</code>

	or

	<code name="Under Windows">
	c:/> cd %CATALINA_HOME%/webapps
	%CATALINA_HOME%/webapps> jar -xvf openejb-loader-1.0-SNAPSHOT.war WEB-INF/web.xml
	...edit WEB-INF/web.xml...
	%CATALINA_HOME%/webapps> jar -uvf openejb-loader-1.0-SNAPSHOT.war WEB-INF/web.xml
	%CATALINA_HOME%/webapps> rmdir /S /Q WEB-INF
	</code>

	<li>Create the <i>temp</i> directory under Tomcat's home directory</li>
	<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.</note>
	<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>
	</p>
	</section>

	<section title="OpenEJB per webapp" ref-id="per-webapp">
	<p>
	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.
	<code>
	<![CDATA[
	<servlet>
	<servlet-name>loader</servlet-name>
	<servlet-class>org.openejb.loader.LoaderServlet</servlet-class>
	<init-param>
	<param-name>openejb.loader</param-name>
	<param-value>tomcat-webapp</param-value>
	</init-param>
	<init-param>
	<param-name>openejb.home</param-name>
	<param-value>...define OPENEJB_HOME here...</param-value>
	</init-param>
	<load-on-startup>0</load-on-startup>
	</servlet>
	]]>
	</code>
	<p>Should you define other OpenEJB configuration settings use another <init-param> 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).</p>
	<p>At startup OpenEJB prints out all of the configuration settings to Tomcat logs:</p>
	<code>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</code>
	</li>
	<li>Start up Tomcat and have fun with the EJBs</li>
	</ol>
	</p>
	</section>

	<section title="OpenEJB Tomcat resource factory" ref-id="tomcat-resource-factory">
	<p>Read about it <a href="tomcat-object-factory.html">here</a>.</p>
	</section>

	<section title="How to make the document even more helpful resource" ref-id="contribution">
	<p>
	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.
	<ul>
	<li>
	<A HREF="tomcat-howitworks.html">How does the integration work</A>
	</li>
	<li>
	<A HREF="tomcat-ejbclasses.html">Where to put your ejb classes</A>
	</li>
	<li>
	<A HREF="tomcat-ejbrefs.html">How to configure java:comp/env lookups (short)</A>
	</li>
	<li>
	<a href="tomcat-object-factory.html">How to configure java:comp/env lookups (detailed)</a>
	</li>
	</ul>
	</p>
	<!--
	<p>
	<ul>
	Local Server:
	<li><a href="tomcat-setup.html">OpenEJB and Tomcat setup (Linux or Windows with Cygwin)</a></li>
	<li><a href="tomcat-setup-win.html">OpenEJB and Tomcat setup (Windows)</a></li>
	</ul>
	</p>
	-->
	<p>
	<ul>
	Misc:
	<li>
	<a href="tomcat-adapter.html">Basic info</a>
	</li>
	<li>
	<a href="faq_servlets.html">Servlets FAQ</a>
	</li>
	</ul>
	</p>
	</section>
	</body>
	</document>