blob: 57bc9a399701a93672f42dddd59e076091a0d796 [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 - Manual Installation</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">
<SCRIPT language="JavaScript" src="http://cwiki.apache.org/confluence/pages/viewpage.action?spaceKey=OPENEJB&title=functions.js" type="text/javascript"></SCRIPT>
<META http-equiv="Content-Type" content="text/html;charset=UTF-8">
</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="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-Configuration"></A>Configuration</H3>
<UL class="alternate" type="square">
<LI><A href="configuration.html" title="Configuration">General</A></LI>
<LI><A href="../OPENEJBx30/deployments.html" title="Deployments">Deployments</A></LI>
<LI><A href="containers.html" title="Containers">Containers</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="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="irc://irc.freenode.net/#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 -->
Manual Installation
</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="ManualInstallation-Overview"></A>Overview</H1>
<P>The manual installation process is significantly harder then the <A href="tomcat.html" title="Tomcat">automatic installation</A> which we normally recommend. In this installation process you will do the following:</P>
<OL>
<LI>Install openejb.war
<OL>
<LI>Download openejb.war from the <A href="http://people.apache.org/~dain/openejb-temp" class="external-link" rel="nofollow">OpenEJB download page</A></LI>
<LI>Make webapps/openejb directory</LI>
<LI>Change to new webapps/openejb directory</LI>
<LI>Unpack the openejb.war file in the new directory</LI>
</OL>
</LI>
<LI>Add the OpenEJB listener the conf/server.xml file</LI>
<LI>Update the non-compliant Tomcat annotations-api.jar</LI>
<LI>Add the OpenEJB JavaAgent to the bin/catalina.bat or bin/catalina.bat script</LI>
</OL>
<H1><A name="ManualInstallation-Installopenejb.war"></A><A name="ManualInstallation-installopenejb"></A>Install openejb.war</H1>
<P>Once Tomcat has been <A href="tomcat-installation.html" title="Tomcat Installation">installed</A>, the OpenEJB plugin for Tomcat can be installed. The war can be obtained from the <A href="http://people.apache.org/~dain/openejb-temp" class="external-link" rel="nofollow">OpenEJB download page</A>. The commands in this example are executed from within the Tomcat installation directory.</P>
<H2><A name="ManualInstallation-UnpackOpenEJBTomcatplugininTomcatwebappsdirectory"></A>Unpack OpenEJB Tomcat plugin in Tomcat webapps directory</H2>
<DIV class="panelMacro"><TABLE class="warningMacro"><COLGROUP><COL width="24"><COL></COLGROUP><TR><TD valign="top"><IMG src="http://cwiki.apache.org/confluence/images/icons/emoticons/forbidden.gif" width="16" height="16" align="absmiddle" alt="" border="0"></TD><TD><B>Be Careful</B><BR>This is the most error prone step. A web application does not contain a root directory, so if you unpack it in the wrong directory, it is difficult to undo. Please, follow this step closely, and most importantly <B>make sure you execute the unpack command from within the new webapps/openejb directory</B>.</TD></TR></TABLE></DIV>
<P>Due to the structure of war files, you must create a new directory for OpenEJB, change to the new directory and execute the unpack command from within the new directory. If you get this wrong, it is difficult to undo, so follow the steps closely.</P>
<DIV id="deck:unpack tomcat" class="deck" tablocation="top" style="display: none" loopcards="false"><DIV class="cards tabbed">
<P><DIV class="card" label="Windows" labelrendered="Windows"><PRE>C:\apache-tomcat-6.0.14&gt;mkdir webapps\openejb
C:\apache-tomcat-6.0.14&gt;cd webapps\openejb
C:\apache-tomcat-6.0.14\webapps\openejb&gt;jar -xvf \openejb.war
created: WEB-INF/
created: WEB-INF/classes/
created: WEB-INF/classes/org/
created: WEB-INF/classes/org/apache/
created: WEB-INF/classes/org/apache/openejb/
...snip...
C:\apache-tomcat-6.0.14\webapps\openejb&gt;dir
Volume in drive C has no label.
Volume Serial Number is 0000-0000
Directory of C:\apache-tomcat-6.0.14\webapps\openejb
09/21/2007 10:19 AM &lt;DIR&gt; .
09/21/2007 10:19 AM &lt;DIR&gt; ..
09/21/2007 10:19 AM 1,000 index.html
09/21/2007 10:19 AM &lt;DIR&gt; lib
09/21/2007 10:19 AM 11,358 LICENSE
09/21/2007 10:19 AM &lt;DIR&gt; META-INF
09/21/2007 10:19 AM 11,649 NOTICE
09/21/2007 10:19 AM 1,018 openejb.xml
09/21/2007 10:19 AM 1,886 README.txt
09/21/2007 10:19 AM &lt;DIR&gt; tomcat
09/21/2007 10:19 AM &lt;DIR&gt; WEB-INF
5 File(s) 26,911 bytes
6 Dir(s) 4,633,796,608 bytes free
C:\apache-tomcat-6.0.14\webapps\openejb&gt;cd ..\..
C:\apache-tomcat-6.0.14&gt;
</PRE></DIV><BR>
<DIV class="card" label="Unix" labelrendered="Unix"><PRE>apache-tomcat-6.0.14$ mkdir webapps/openejb
apache-tomcat-6.0.14$ cd webapps/openejb/
apache-tomcat-6.0.14/webapps/openejb$ jar -xvf path/to/openejb.war
created: WEB-INF/
created: WEB-INF/classes/
created: WEB-INF/classes/org/
created: WEB-INF/classes/org/apache/
created: WEB-INF/classes/org/apache/openejb/
...snip...
apache-tomcat-6.0.14/webapps/openejb$ ls
LICENSE META-INF/ NOTICE README.txt WEB-INF/ index.html lib/ openejb.xml tomcat/
apache-tomcat-6.0.14/webapps/openejb$ cd ../..
apache-tomcat-6.0.14$
</PRE></DIV></P>
</DIV></DIV>
<H2><A name="ManualInstallation-AddtheOpenEJBlistenertoTomcat"></A>Add the OpenEJB listener to Tomcat </H2>
<P>All Tomcat listener classes must be available in the Tomcat common class loader, so the openejb-loader jar must be copied into the Tomcat lib directory.</P>
<DIV id="deck:copy openejb loader" class="deck" tablocation="top" style="display: none" loopcards="false"><DIV class="cards tabbed">
<P><DIV class="card" label="Windows" labelrendered="Windows"><PRE>C:\apache-tomcat-6.0.14&gt;copy webapps\openejb\lib\openejb-loader-3.0.0-SNAPSHOT.jar lib\openejb-loader.jar
1 file(s) copied.
</PRE></DIV><BR>
<DIV class="card" label="Unix" labelrendered="Unix"><PRE>apache-tomcat-6.0.14$ cp webapps/openejb/lib/openejb-loader-*.jar lib/openejb-loader.jar
</PRE></DIV></P>
</DIV></DIV>
<P>Add the following <SPAN class="" style="background-color: #FFFFC0;">highlighted lines</SPAN>
to your conf/server.xml file to load the OpenEJB listener:</P>
<DIV class="panel" style="border-width: 1px;"><DIV class="panelHeader" style="border-bottom-width: 1px;"><B>conf/server.xml</B></DIV><DIV class="panelContent">
<P>&lt;!-- Note: A &quot;Server&quot; is not itself a &quot;Container&quot;, so you may not<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;define subcomponents such as &quot;Valves&quot; at this level.<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Documentation at /docs/config/server.html<BR>
--&gt;<BR>
&lt;Server port=&quot;8005&quot; shutdown=&quot;SHUTDOWN&quot;&gt;<BR>
&nbsp;&nbsp;<SPAN class="" style="background-color: #FFFFC0;">&lt;!-- OpenEJB plugin for tomcat --&gt;</SPAN>
<BR>
&nbsp;&nbsp;<SPAN class="" style="background-color: #FFFFC0;">&lt;Listener className=&quot;org.apache.openejb.loader.OpenEJBListener&quot; /&gt;</SPAN>
</P>
<P>&nbsp;&nbsp;&lt;!--APR library loader. Documentation at /docs/apr.html --&gt;<BR>
&nbsp;&nbsp;&lt;Listener className=&quot;org.apache.catalina.core.AprLifecycleListener&quot; SSLEngine=&quot;on&quot; /&gt;<BR>
...snip...</P>
</DIV></DIV>
<H2><A name="ManualInstallation-UpdatetheTomcatannotationsapi.jarfile"></A>Update the Tomcat annotations-api.jar file</H2>
<P>Tomcat contains an old non-compliant version of the javax.annotation classes and these invalid classes must be updated so OpenEJB can process annotations. Simply, replace the annotations-api.jar in the Tomcat lib directory with the updated annotations-api.jar in the OpenEJB war.</P>
<DIV id="deck:update annotations-api.jar" class="deck" tablocation="top" style="display: none" loopcards="false"><DIV class="cards tabbed">
<P><DIV class="card" label="Windows" labelrendered="Windows"><PRE>C:\apache-tomcat-6.0.14&gt;copy webapps\openejb\tomcat\annotations-api.jar lib\annotations-api.jar
Overwrite lib\annotations-api.jar? (Yes/No/All): y
1 file(s) copied.
</PRE></DIV><BR>
<DIV class="card" label="Unix" labelrendered="Unix"><PRE>apache-tomcat-6.0.14$ cp webapps/openejb/tomcat/annotations-api.jar lib/annotations-api.jar
</PRE></DIV></P>
</DIV></DIV>
<H2><A name="ManualInstallation-AddOpenEJBjavaagenttoTomcatstartup"></A><A name="ManualInstallation-javaagent"></A> Add OpenEJB javaagent to Tomcat startup</H2>
<P>OpenJPA, the Java Persistence implementation used by OpenEJB, currently must enhanced persistence classes to function properly, and this requires the installation of a javaagent into the Tomcat startup process.</P>
<P>First, copy the OpenEJB JavaAgent jar into the lib directory.</P>
<DIV id="deck:unpack tomcat" class="deck" tablocation="top" style="display: none" loopcards="false"><DIV class="cards tabbed">
<P><DIV class="card" label="Windows" labelrendered="Windows"><PRE>C:\apache-tomcat-6.0.14&gt;copy webapps\openejb\lib\openejb-javaagent-3.0.0-SNAPSHOT.jar lib\openejb-javaagent.jar
1 file(s) copied.
</PRE></DIV><BR>
<DIV class="card" label="Unix" labelrendered="Unix"><PRE>apache-tomcat-6.0.14$ cp webapps/openejb/lib/openejb-javaagent-*.jar lib/openejb-javaagent.jar
</PRE></DIV></P>
</DIV></DIV>
<P>Simply, add the following <SPAN class="" style="background-color: #FFFFC0;">highlighted lines</SPAN>
to the bin/catalina.bat (Windows) or bin/catalina.sh (Unix) file to enable the OpenEJB javaagent:</P>
<DIV id="deck:update script" class="deck" tablocation="top" style="display: none" loopcards="false"><DIV class="cards tabbed">
<DIV class="card" label="Windows" labelrendered="Windows">
<DIV class="panel" style="border-width: 1px;"><DIV class="panelHeader" style="border-bottom-width: 1px;"><B>bin/catalina.bat</B></DIV><DIV class="panelContent">
<P>...snip...<BR>
if not exist &quot;%CATALINA_BASE%\conf\logging.properties&quot; goto noJuli<BR>
set JAVA_OPTS=%JAVA_OPTS% -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager -Djava.util.logging.config.file=&quot;%CATALINA_BASE%\conf\logging.properties&quot;<BR>
:noJuli</P>
<SPAN class="" style="background-color: #FFFFC0;">rem Add OpenEJB javaagent<BR>
if not exist &quot;%CATALINA_BASE%\webapps\openejb\lib\openejb-javaagent.jar&quot; goto noOpenEJBJavaagent<BR>
set JAVA_OPTS=&quot;-javaagent:%CATALINA_BASE%\webapps\openejb\lib\openejb-javaagent.jar&quot; %JAVA_OPTS%<BR>
:noOpenEJBJavaagent</SPAN>
<P>rem ----- Execute The Requested Command ---------------------------------------</P>
<P>echo Using CATALINA_BASE: %CATALINA_BASE%<BR>
echo Using CATALINA_HOME: %CATALINA_HOME%<BR>
...snip...</P>
</DIV></DIV>
</DIV>
<DIV class="card" label="Unix" labelrendered="Unix">
<DIV class="panel" style="border-width: 1px;"><DIV class="panelHeader" style="border-bottom-width: 1px;"><B>bin/catalina.sh</B></DIV><DIV class="panelContent">
<P>...snip...<BR>
&#35; Set juli LogManager if it is present<BR>
if [ -r &quot;$CATALINA_BASE&quot;/conf/logging.properties ]; then<BR>
&nbsp;&nbsp;JAVA_OPTS=&quot;$JAVA_OPTS &quot;-Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager&quot; &quot;-Djava.util.logging.config.file=&quot;$CATALINA_BASE/conf/logging.properties&quot;<BR>
fi</P>
<SPAN class="" style="background-color: #FFFFC0;">&#35; Add OpenEJB javaagent<BR>
if [ -r &quot;$CATALINA_BASE&quot;/webapps/lib/openejb-javaagent.jar ]; then<BR>
&nbsp;&nbsp;JAVA_OPTS=&quot;&quot;-javaagent:$CATALINA_BASE/lib/openejb-javaagent.jar&quot; $JAVA_OPTS&quot;<BR>
fi</SPAN>
<P>&#35; ----- Execute The Requested Command -----------------------------------------</P>
<P>&#35; Bugzilla 37848: only output this if we have a TTY<BR>
if [ $have_tty -eq 1 ]; then<BR>
&nbsp;&nbsp;echo &quot;Using CATALINA_BASE: $CATALINA_BASE&quot;<BR>
...snip...</P>
</DIV></DIV>
</DIV>
</DIV></DIV>
<P><B>NOTE:</B> The example above is an excerpt from the middle of the bin/catalina.sh file. Search for &quot;Execute&quot; in the file to locate the correct position in the file to add the new lines.</P>
</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="http://cwiki.apache.org/confluence/pages/editpage.action?spaceKey=OPENEJB&title=Manual%20Installation">[ 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>