<html><head>
      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   <title>12.&nbsp;Working with Applications</title><link rel="stylesheet" href="css/stylesheet.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.74.0"><link rel="home" href="index.html" title="Virgo User Guide"><link rel="up" href="index.html" title="Virgo User Guide"><link rel="prev" href="ch11s03.html" title="11.3&nbsp;Service Dumps"><link rel="next" href="ch12s02.html" title="12.2&nbsp;Undeploying Artifacts"><!--Begin Google Analytics code--><script type="text/javascript">
			var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
			document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
		</script><script type="text/javascript">
			var pageTracker = _gat._getTracker("UA-2728886-3");
			pageTracker._setDomainName("none");
			pageTracker._setAllowLinker(true);
			pageTracker._trackPageview();
		</script><!--End Google Analytics code--></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">12.&nbsp;Working with Applications</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch11s03.html">Prev</a>&nbsp;</td><th width="60%" align="center">&nbsp;</th><td width="20%" align="right">&nbsp;<a accesskey="n" href="ch12s02.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="deployment"></a>12.&nbsp;Working with Applications</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="deployment-deploying"></a>12.1&nbsp;Deploying Artifacts</h2></div></div></div><p>
			In the context of Virgo Server for Apache Tomcat, <span class="emphasis"><em>deploying</em></span> refers to installing an artifact to the server and then starting it to make it available to users.  Typically, when you install an artifact, VTS automatically starts it as long as the server is able to successfully resolve all its dependencies.  For this reason, the terms <span class="emphasis"><em>deploying</em></span> and <span class="emphasis"><em>installing</em></span> are often used interchangeably. 
		</p><p>You deploy artifacts to Virgo Server for Apache Tomcat using either the hot-deploy directory on the file system or by using the Admin Console.  The artifacts that you can deploy to VTS are:
		</p><div class="itemizedlist"><ul type="disc"><li>Bundles, including Web Application Bundles</li><li>WARs</li><li>PARs</li><li>Plans</li><li>Configuration Files</li></ul></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="deployment-deploying-nested-contexts"></a>Deploying WARs with nested Web-ContextPaths</h3></div></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.gif"></td><th align="left">Note</th></tr><tr><td align="left" valign="top">
                This section currently is ONLY relevant for Virgo Nano.
            </td></tr></table></div><p>
				Virgo Nano Web supports deployment of WAR files which are transformed into Web Application Bundles. This process involves automatic creation of an OSGi manifest with all relevant OSGi header plus the very important Web-ContextPath header. Its value defines how the deployed WAR file can be requested. There is a limitation about this process that the automatic generation only creates a flat context path which equals the name of your WAR file. Virgo Nano Web supports generation of a nested one. 
			</p><p>In order to benefit from this flexibility all you need to do is just to add hashes '#' to your WAR file name in the places where you want to have slashes in your web context path. Here is an example:
                </p><pre class="screen">myWarFile.war would result into "/myWarFile" web context path</pre><p>
                </p><pre class="screen">my#War#File.war would result into "/my/War/File" web context path</pre><p>
                The symbolic name of the resulting WAB file is the same as the WAR file name but the hashes '#' are replaced with dots '.'.
            </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="initial-deployment-deploying-bulk"></a>Initial Bulk Hot Deploy</h3></div></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.gif"></td><th align="left">Note</th></tr><tr><td align="left" valign="top">
                This section currently is ONLY relevant for Virgo Nano.
            </td></tr></table></div><p>
				To hot deploy an artifact initially in bulk mode, copy it into the pickup directory (by default <code class="literal">$SERVER_HOME/pickup</code>) and start up the server. Upon this startup all the artifacts in the <code class="literal">pickup</code> directory will get first installed and resolved and only then they will be started.
			</p><p>
                This solves the problem where artifacts depend on each other and when not in bulk mode the install order is not guaranteed therefore errors could occur.
            </p><p>
                This is only available as part of the initial scan of the <code class="literal">pickup</code> directory. Subsequently it goes back to the known mode of single file handled at a time.
            </p><pre class="programlisting">prompt$ cd /home/applications
prompt$ cp BundleA.jar $SERVER_HOME/pickup
prompt$ cp BundleWithDependencyOnA.jar $SERVER_HOME/pickup
prompt$ cd $SERVER_HOME/bin
prompt$ ./startup.sh</pre><p>
				When the server is started, artifacts are hot deployed and messages similar to the following appear in the log file:
			</p><pre class="screen">[2009-12-10 06:41:01.021] fs-watcher          &lt;HD0001I&gt; Hot deployer processing 'INITIAL' event for file 'BundleA.jar; BundleWithDependencyOnA.jar; '.
[2009-12-10 06:41:01.087] fs-watcher          &lt;DE0000I&gt; Installing bundle 'BundleA' version '0.0.0'.
[2009-12-10 06:41:01.274] fs-watcher          &lt;DE0001I&gt; Installed bundle 'BundleA' version '0.0.0'.
[2009-12-10 06:41:01.087] fs-watcher          &lt;DE0000I&gt; Installing bundle 'BundleWithDependencyOnA' version '0.0.0'.
[2009-12-10 06:41:01.274] fs-watcher          &lt;DE0001I&gt; Installed bundle 'BundleWithDependencyOnA' version '0.0.0'.
[2009-12-10 06:41:01.397] fs-watcher          &lt;DE0004I&gt; Starting bundle 'BundleA' version '0.0.0'.
[2009-12-10 06:41:01.550] start-signalling-1  &lt;DE0005I&gt; Started bundle 'BundleA' version '0.0.0'.
[2009-12-10 06:41:01.397] fs-watcher          &lt;DE0004I&gt; Starting bundle 'BundleWithDependencyOnA' version '0.0.0'.
[2009-12-10 06:41:01.550] start-signalling-1  &lt;DE0005I&gt; Started bundle 'BundleWithDependencyOnA' version '0.0.0'.</pre><p>
				If there is a problem with the deployment, such as the server being unable to resolve all dependencies, the console and log both show an error message to help you with troubleshooting.
			</p><p>If there are no problems, Virgo Nano automatically starts the artifacts so that they are immediately available to users.
			</p><p>Bulk deployment can be disabled and reverted back to the old one-file-at-a-time processing by removing this line from <code class="literal">$SERVER_HOME/configuration/config.ini</code>:
            </p><pre class="programlisting">org.eclipse.virgo.fschecker.initialEventMode=bulk</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="deployment-deploying-hot"></a>Hot Deploy</h3></div></div></div><p>
				To hot deploy an artifact, copy it into the pickup directory (by default <code class="literal">$SERVER_HOME/pickup</code>):
			</p><pre class="programlisting">prompt$ cd /home/applications
prompt$ cp helloWorld.war $SERVER_HOME/pickup</pre><p>
				When the artifact is hot deployed, messages similar to the following appear in the log file:
			</p><pre class="screen">[2009-12-10 06:41:01.021] fs-watcher          &lt;HD0001I&gt; Hot deployer processing 'CREATED' event for file 'helloWorld.war'.
[2009-12-10 06:41:01.087] fs-watcher          &lt;DE0000I&gt; Installing bundle 'helloWorld' version '0.0.0'.
[2009-12-10 06:41:01.274] fs-watcher          &lt;DE0001I&gt; Installed bundle 'helloWorld' version '0.0.0'.
[2009-12-10 06:41:01.397] fs-watcher          &lt;DE0004I&gt; Starting bundle 'helloWorld' version '0.0.0'.
[2009-12-10 06:41:01.414] Thread-3            &lt;WE0000I&gt; Starting web bundle 'helloWorld' version '0.0.0' with context path '/helloWorld'.
[2009-12-10 06:41:01.537] Thread-3            &lt;WE0001I&gt; Started web bundle 'helloWorld' version '0.0.0' with context path '/helloWorld'.
[2009-12-10 06:41:01.550] start-signalling-1  &lt;DE0005I&gt; Started bundle 'helloWorld' version '0.0.0'.</pre><p>
				If there is a problem with the deployment, such as the server being unable to resolve all dependencies, the console and log both show an error message to help you with troubleshooting.
			</p><p>If there are no problems, VTS automatically starts the artifact so that it is immediately available to users.
			</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="deployment-deploying-manual"></a>Deploying Using the Admin Console</h3></div></div></div><p>
				The Admin Console allows you to upload a file, which will be deployed automatically, from your local file system to the Virgo Server for Apache Tomcat. As soon as Virgo Server for Apache Tomcat deploys the artifact,  it appears in the list of artifacts in the Admin Console.  Note that the GUI for uploading varies according to the browser and operating system you use.
			</p><p>See <a class="link" href="ch09s02.html#admin-console-install-artifacts" title="Installing a New Artifact">Installing a New Artifact</a> for details about using the Admin Console to install (deploy) an artifact.  See <a class="link" href="ch09.html" title="9.&nbsp;The Web Admin Console">The Web Admin Console</a> for general information about the Admin Console.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="deployment-deploying-happens"></a>What Happens When You Deploy</h3></div></div></div><p>
				When you deploy an artifact, either using hot-deployment or the Admin Console, Web Server copies the file to its work directory (<code class="literal">SERVER_HOME/work</code>) and registers it in its internal registry. 
				The server then checks any dependencies the artifact might have to see if
				deployment can go ahead, and if all dependencies are resolved, Virgo Server for Apache Tomcat starts the artifact.
				Because of all these additional internal activities, you should NOT simply copy the artifact into the <code class="literal">work</code> directory and assume it will be deployed, because Virgo Server for Apache Tomcat will not do so.
			</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="deployment-deploying-ordering"></a>Deployment Ordering</h3></div></div></div><p>
				When deploying bundles that have dependencies, it is important 
				that you deploy them in the correct order. Virgo Server for Apache Tomcat 
				honors this ordering when it redeploys the artifacts on startup. 
			</p><p>
				If you use hot deployment to deploy your artifacts, be sure to copy the corresponding files into the pickup
				directory one-by-one. Copying the files in one group, for example by using a single <code class="literal">cp</code> command, provides no guarantee of ordering.
			</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="deployment-deploying-shared"></a>Deploying Shared Artifacts</h3></div></div></div><p>
				Artifacts may be shared by plans.
				Sharing occurs when a plan is deployed which references an artifact that was previously deployed or is a child artifact
				of a plan that was previously deployed.
				Sharing also occurs when an artifact is deployed which is already a child of a deployed plan, but in this case the shared
				artifact may <span class="emphasis"><em>not</em></span> appear as a top-level artifact, for example, in the Admin Console, in the shell,
				and in JMX.
			</p><p>
				Sharing is taken into account when artifacts are stopped.
				A shared artifact is stopped only when all the artifacts referencing the shared artifact have been stopped
				and, if the shared artifact was deployed in its own right, the artifact itself has been stopped.
			</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="deployment-deploying-restrictions"></a>Restrictions</h3></div></div></div><p>
				Virgo Server for Apache Tomcat does not support deploying fragment bundles. Typically, fragment bundles should be placed in <code class="literal">$SERVER_HOME/repository/ext</code>
				or <code class="literal">$SERVER_HOME/repository/usr</code> so that they will be installed automatically with their host bundles.
			</p></div></div></div><!--Begin LoopFuse code--><script src="http://loopfuse.net/webrecorder/js/listen.js" type="text/javascript"></script><script type="text/javascript">
			_lf_cid = "LF_48be82fa";
			_lf_remora();
		</script><!--End LoopFuse code--><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch11s03.html">Prev</a>&nbsp;</td><td width="20%" align="center">&nbsp;</td><td width="40%" align="right">&nbsp;<a accesskey="n" href="ch12s02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">11.3&nbsp;Service Dumps&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;12.2&nbsp;Undeploying Artifacts</td></tr></table></div></body></html>