<?xml version="1.0"?>
<document url="http://openejb.sf.net/embedded.xml" toc="none">
  <properties>
    <title>OpenEJB Deploy Tool</title>
  </properties>
  <body>

<section title="NAME" ref-id="name">
<p>
openejb deploy - OpenEJB Deploy Tool
</p>
</section>
<section title="SYNOPSIS" ref-id="synopsis">
<p>
openejb deploy [options] jarfiles
</p>
</section>

<section title="NOTE" ref-id="note">
<p>
    The OpenEJB Deploy tool is an OPTIONAL tool that creates  the <b>openejb-jar.xml</b> file 
    required for your bean to be loaded into the container system at startup.  If you want to create 
    or maintain that openejb-jar.xml file yourself, you don't need the Deploy tool at all.  For more
    information, see the <a href="faq_openejb-jar.html">openejb-jar.xml FAQ</a>
</p>
<p>
The OpenEJB Deploy tool must be executed from the OPENEJB_HOME directory.  This is the 
directory where OpenEJB was installed or unpacked.  For for the remainder of this document
we will assume you unpacked OpenEJB into the directory C:\openejb.
</p>
<p>
In Windows, the deploy tool can be executed as follows:
</p>
<p>
<command>C:\openejb> openejb deploy -help</command>
</p>
<p>
In UNIX, Linux, or Mac OS X, the deploy tool can be executed as follows:
</p>
<p>
<command>[user@host openejb]# ./openejb.sh deploy -help</command>
</p>
<p>
Depending on your OpenEJB version, you may need to change execution bits to
make the scripts executable.  You can do this with the following command.
</p>
<p>
<command>[user@host openejb]# chmod 755 openejb.sh bin/*.sh</command>
</p>
<p>
From here on out, it will be assumed that you know how to execute the right openejb script
for your operating system and commands will appear in shorthand as show below.
</p>
<p>
<command>openejb deploy -help</command>
</p>

</section>

<section title="DESCRIPTION" ref-id="description">
<p>
The OpenEJB Deploy Tool is responsible for linking or "hooking up" your beans to the 
container system.  It is run as a separate command line tool using the data in your 
OpenEJB configuration file (C:\openejb\conf\openejb.conf).  The next time the system is 
started, all the deplpoyed beans will be loaded.
</p>

<p>
In the OpenEJB configuration file (C:\openejb\conf\openejb.conf), there are a number 
of containers and resources defined.  Each of these has a unique name and will
be loaded at start up with that name.  In order for your beans to be loaded into the 
container system, they must also be named.  This name is called a 
<a href="deploymentids.html">Deployment ID</a> and must be completely unique in comparison 
to all other beans across all jars loaded into the container system.
</p>
<p>
Furthermore, the system must also know which which container
to put a given bean into.  During deployment, the bean's Deployment ID must be mapped
to a Container ID.
</p>
<p>
If the beans has any references to database or other resources using the &lt;resource-ref&gt; 
tag in the jar's META-INF/ejb-jar.xml, those references must be resolved and linked to 
a resource declared in the openejb.conf.
</p>
<p>
All this information is collected by the OpenEJB Deploy Tool.  Using the Deploy Tool
will cause a new file to be added to your jar, META-INF/openejb-jar.xml.  Jars 
in the deployments path containing a META-INF/openejb-jar.xml file will be loaded
when the system starts up and will be usable at runtime.  Any jar containing an invalid
openejb-jar.xml, or conntaining no openejb-jar.xml at all, will simply be overlooked by the 
container system.
</p>
<p>
To effectively "undeploy" a jar, you simply need to remove the META-INF/openejb-jar.xml file 
from the jar then restart the container system/server.  If you wish to temporarily remove
the jar from the container system, you can just rename the jar with a new extention, ".skip" 
for example, then restart the container system/server.
</p>

<p>
The files passed to the Deploy Tool must be valid ejb 1.1 jar files and contain
the META_INF/ejb-jar.xml inside the jar.  This is case sensitive, so meta-inf/Ejb-Jar.xml 
is not the same as META_INF/ejb-jar.xml.
</p>

<p>
Do NOT edit the openejb-jar.xml file unless you 
know exactly what you are doing.
</p>
</section>

<section title="OPTIONS" ref-id="options">
<p>
<options>

<option flag="-m">
Move the jar to the OPENEJB_HOME/beans directory. Will not overwrite the 
jar if there is an existing jar with the same name in the 
OPENEJB_HOME/beans directory. Add the -f option to force the overwrite.    
</option>
 
<option flag="-c">
Copy the jar to the OPENEJB_HOME/beans directory. Will 
not overwrite the jar if there is an existing jar with 
the same name in the OPENEJB_HOME/beans directory. Add 
the -f option to force the overwrite.
</option>

<option flag="-f">
Forces a move or a copy, overwriting any previously
existing jar with the same name.
</option>
 
<option flag="-a">Automate deployment as much as possible.  Applies all automation related flags.</option>
<option flag="-C">Automatically assigns each bean in the jar to the first container of the appropriate bean type.</option>
 
<option flag="-D">Automatically assigns the OpenEJB 
<a href="deploymentids.html">Deployment ID</a>
for each bean by using the &lt;ejb-name&gt; in your 
ejb-jar.xml.  The deployment ID uniquely identifies
the bean in the OpenEJB container system and is used
by most servers as the client-side JNDI name.  No 
two beans can share the same deployment ID.</option>

<option flag="-d" param="dir">Sets the OPENEJB_HOME to the specified directory.</option>

<option flag="-l" param="file">Sets the log4j configuration to the specified file.</option>

<option flag="-conf" param="file">Sets the OpenEJB configuration to the specified file.</option>

<option flag="-version">Print the version.</option>
 
<option flag="-help">Print this help message.</option>

<option flag="-examples">Show examples of how to use the options.</option>
</options>
</p>
</section>

<section title="EXAMPLES" ref-id="examples">
<section title="Deploying multiple jar files" ref-id="using.multiple.jar.files">
 <p>
 <command>openejb deploy myapp\fooEjbs.jar myapp\barEjbs.jar</command>
 </p>
 
 <p>
 Deploys the beans in the fooEjbs.jar first, then deploys the 
 beans in the barEjbs.jar.  Wildcards can be used as well.
 </p>

 <p>
<command>openejb deploy myapp\*.jar</command>
 </p>

</section>

<section title="Using -m " ref-id="using.-m ">

 <p>
<command>openejb deploy -m myapp\myEjbs.jar</command>
 </p>

 <p>
 Deploys the beans in the jar, moving the entire jar from 
 myapp\myEjbs.jar to OPENEJB_HOME\beans\myEjbs.jar.
 </p>

 <p>
 If the jar OPENEJB_HOME\beans\myEjbs.jar already existed, it will 
 not be overwritten.  Supply the -f to force an overwrite.
 </p>

 <p>
<command>openejb deploy -m -f myapp\myEjbs.jar</command>
 </p>

</section>

<section title="Using -c" ref-id="using.-c">

 <p>
<command>openejb deploy -c myapp\myEjbs.jar</command>
 </p>
 
 <p>
 Same as using -m, except the jar is copied not moved. The -f also
 can be used with a -c to force an overwrite if the file is already
 present.
 </p>

</section>

<section title="Using -C" ref-id="using.-C">

 <p>
<command>openejb deploy -C myapp\myEjbs.jar</command>
 </p>
 
 <p>
 Deploys the beans in the jar, does not prompt you to assign each 
 bean to a container.  Instead, each bean will automatically be 
 assigned to the first container of the appropriate type.
 </p>
 
</section>
<section title="Using -D" ref-id="using.-D">

 <p>
<command>openejb deploy -D myapp\myEjbs.jar</command>
 </p>
 
 <p>
 Deploys the beans in the jar, does not prompt you to assign each 
 bean a <a href="deploymentids.html">Deployment ID</a>. Instead, 
 the deployment ID for each bean 
 will automatically be assigned using the &lt;ejb-name&gt; of the bean 
 as it is in the META-INF/ejb-jar.xml of the jar file.
 </p>
 
 <p>
 The deployment ID uniquely identifies the bean in the OpenEJB  
 container system. No two beans can share the same deployment ID.  
 </p>

 <p>
 The deployment ID is also used by most servers as the client-side 
 JNDI name for doing JNDI lookups.
 </p>

</section>
<section title="Using -a" ref-id="using.-a">

 <p>
<command>openejb deploy -a myapp\myEjbs.jar</command>
 </p>
 
 <p>
 Applies all automation related flags.  Currently equivalent to:
 </p>

 <p>
<command>openejb deploy -C -D myapp\myEjbs.jar</command>
 </p>

 <p>
 As more automation options are added, they will also be applied 
 when using the -a option.
 </p>
  
</section>
<section title="Using -d dir" ref-id="using.-d">

 <p>
<command>openejb deploy -d C:\openejb myapp\myEjbs.jar</command>
 </p>
 
 <p>
 Sets the OPENEJB_HOME to the C:\openejb directory.  This will 
 cause the deploy tool to treat the C:\openejb as the directory 
 where OpenEJB was installed.
 </p>

</section>
<section title="Using -conf file" ref-id="using.-conf">

 <p>
<command>openejb deploy -conf C:\openejb\conf\mytest.conf myapp\myEjbs.jar</command>
 </p>
 
 <p>
 Sets the openejb.configuration system variable to the file 
 C:\openejb\conf\mytest.conf.  When the beans are deployed the 
 beans will be to be mapped to the containers and resources in the 
 configuration file C:\openejb\conf\mytest.conf.  If the deploy 
 tool needs update the configuration, the mytest.conf file will be 
 modified.
 </p>
 
</section>
<section title="Using combinations of options " ref-id="using.combinations">

 <p>
<command>openejb deploy -c -a C:\foo\bar.jar D:\my\beans\*.jar</command>
 </p>
 
 <p>
<command>openejb deploy -c -C /foo/bar.jar</command>
 </p>
 
 <p>
<command>openejb deploy -m -a /home/dblevins/mybeans/*.jar</command>
 </p>
 
 <p>
<command>openejb deploy -D -m /home/dblevins/mybeans/*.jar</command>
 </p>
 
 <p>
<command>openejb deploy -a /openejb/beans/*.jar</command>
 </p>
 
 <p>
<command>openejb deploy -a C:\openejb\beans\*.jar</command>
 </p>

</section>
</section>



</body>
</document>

