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

 <?xml version="1.0"?>
 <document url="http://www.openejb.org/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>
	<?xml version="1.0"?>
	<document url="http://www.openejb.org/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 <resource-ref>
	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 <ejb-name> 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 <ejb-name> 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>