| <html><head> |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| <title>4.3 Creating Plans</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 Programmer Guide"><link rel="up" href="ch04.html" title="4. Developing Applications"><link rel="prev" href="ch04s02.html" title="4.2 Creating PARs and WARs"><link rel="next" href="ch04s04.html" title="4.4 Creating and Using Configuration 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">4.3 Creating Plans</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch04s02.html">Prev</a> </td><th width="60%" align="center">4. Developing Applications</th><td width="20%" align="right"> <a accesskey="n" href="ch04s04.html">Next</a></td></tr></table><hr></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="developing-applications-plans"></a>4.3 Creating Plans</h2></div></div></div><p> |
| Plans are similar to PARs in that they encapsulate the artifacts of an application as a single unit. As a consequence, they have similar benefits; for details of the benefits common to PARs and plans, see <a class="link" href="ch04s02.html#developing-applications-packaging-par" title="PARs">PARs</a>. |
| </p><p> |
| Plans have the following additional benefits, which is why we recommend that you use plans rather than PARs when defining an application: |
| </p><div class="itemizedlist"><ul type="disc"><li>Virgo Web Server deploys the artifacts in the plan in the order in which they are listed in the XML file, which gives you complete control over deployment order. With a PAR, the order of deployment of the included artifacts is not guaranteed.</li><li>Plans describe their contents by reference (using an XML file) as opposed to PARs that are JAR files that physically contain the included artifacts. For this reason, it is easier to share content between plans as well as update individual parts of a plan without having to physically repackage (re-JAR) it.</li><li>You can enable or disable whether a plan is scoped or atomic; PARs are always scoped and atomic.</li></ul></div><p> |
| Plans always get their dependencies from the VWS repository. This means, for example, that if you drop one of the plan’s dependencies in the <code class="code">pickup</code> directory rather than adding it to the repository, the plan will fail to deploy because it will not find the dependency. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="developing-applications-plans-create"></a>Creating the Plan XML File</h3></div></div></div><p> |
| Plans are XML files that have a <code class="code">.plan</code> file extension, such as <code class="code">multi-artifact.plan</code>. |
| The structure of the XML file is simple: |
| the root element is <code class="code"><plan></code> with attributes specifying the name of the plan, the version, atomicity, and scoping. |
| Then, for each artifact that makes up your application, |
| you add a <code class="code"><artifact></code> element, using its attributes to specify the type of artifact and its name and version. |
| The following is a simple example of a plan’s XML file: |
| </p><pre class="programlisting"><<span class="hl-tag">?xml version="1.0" encoding="UTF-8"?</span>> |
| <<span class="hl-tag">plan</span> <span class="hl-attribute">name</span>=<span class="hl-value">"multi-artifact.plan"</span> <span class="hl-attribute">version</span>=<span class="hl-value">"1.0.0"</span> <span class="hl-attribute">scoped</span>=<span class="hl-value">"true"</span> <span class="hl-attribute">atomic</span>=<span class="hl-value">"true"</span> |
| <span class="hl-attribute">xmlns</span>=<span class="hl-value">"http://www.springsource.org/schema/dm-server/plan"</span> |
| <span class="hl-attribute">xmlns:xsi</span>=<span class="hl-value">"http://www.w3.org/2001/XMLSchema-instance"</span> |
| <span class="hl-attribute">xsi:schemaLocation</span>=<span class="hl-value">" |
| http://www.springsource.org/schema/dm-server/plan |
| http://www.springsource.org/schema/dm-server/plan/springsource-dm-server-plan.xsd"</span>> |
| |
| <<span class="hl-tag">artifact</span> <span class="hl-attribute">type</span>=<span class="hl-value">"configuration"</span> <span class="hl-attribute">name</span>=<span class="hl-value">"app-properties"</span> <span class="hl-attribute">version</span>=<span class="hl-value">"1.0.0"</span>/> |
| <<span class="hl-tag">artifact</span> <span class="hl-attribute">type</span>=<span class="hl-value">"bundle"</span> <span class="hl-attribute">name</span>=<span class="hl-value">"com.springsource.exciting.app"</span> <span class="hl-attribute">version</span>=<span class="hl-value">"[2.0.0, 3.1.0)"</span>/> |
| |
| <<span class="hl-tag">/plan</span>></pre><p> |
| In the preceding example, the name of the plan is <code class="code">multi-artifact.plan</code> and its version is <code class="code">1.0.0</code>. |
| The plan is both scoped and atomic. The plan contains two artifacts: one is a bundle called <code class="code">com.springsource.exciting.app</code> and the other is a configuration file called <code class="code">app-properties</code>. |
| </p><p> |
| The following table describes the attributes of the <code class="code"><plan></code> element. |
| </p><div class="table"><a name="developing-applications-plans-create-plan-attributes"></a><p class="title"><b>Table 4.2. Attributes of the <plan> Element</b></p><div class="table-contents"><table summary="Attributes of the <plan> Element" style="border-collapse: collapse;border-top: 1.0pt solid ; border-bottom: 1.0pt solid ; border-left: 1.0pt solid ; border-right: 1.0pt solid ; "><colgroup><col><col><col></colgroup><thead><tr><th style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">Attribute</th><th style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">Description</th><th style="border-bottom: 1.0pt solid ; ">Required?</th></tr></thead><tbody><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="literal">name</code></td><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">Specifies the name of this plan. Virgo Web Server uses the name as one component of the unique identifier of this plan. </td><td style="border-bottom: 1.0pt solid ; ">Yes.</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="literal">version</code></td><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">Specifies the version of this plan. You must use OSGi version specification syntax, such as <code class="code">2.1.0</code>. Virgo Web Server uses the version as one component of the unique identifier of this plan. </td><td style="border-bottom: 1.0pt solid ; ">Yes.</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="literal">scoped</code></td><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">Specifies whether Virgo Web Server should install the artifacts into plan-specific scope so that only the application described by this plan has access to the artifacts. If you disable scoping, then Virgo Web Server installs the artifacts into the global scope, which means they are then available for access by all other deployed artifacts. Set the attribute to <code class="code">true</code> to enable scoping or <code class="code">false</code> to disable it.</td><td style="border-bottom: 1.0pt solid ; ">Yes.</td></tr><tr><td style="border-right: 1.0pt solid ; "><code class="literal">atomic</code></td><td style="border-right: 1.0pt solid ; ">Specifies whether you want to tie together the lifecycle of the artifacts in this plan. Making a plan atomic means that if you install, start, stop, or uninstall a single artifact in the plan, Virgo Web Server escalates the event to all artifacts in the plan. Also, in an atomic plan, Virgo Web Server prevents artifacts from being in inconsistent states. For example, if one artifact should fail to start, then Virgo Web Server stops all artifacts in the plan. Set this attribute to <code class="code">true</code> to enable atomicity or <code class="code">false</code> to disable it. </td><td style="">Yes.</td></tr></tbody></table></div></div><br class="table-break"><p> |
| The following table describes the attributes of the <code class="code"><artifact></code> element. |
| </p><div class="table"><a name="developing-applications-plans-create-artifact-attributes"></a><p class="title"><b>Table 4.3. Attributes of the <artifact> Element</b></p><div class="table-contents"><table summary="Attributes of the <artifact> Element" style="border-collapse: collapse;border-top: 1.0pt solid ; border-bottom: 1.0pt solid ; border-left: 1.0pt solid ; border-right: 1.0pt solid ; "><colgroup><col><col><col></colgroup><thead><tr><th style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">Attribute</th><th style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">Description</th><th style="border-bottom: 1.0pt solid ; ">Required?</th></tr></thead><tbody><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="literal">type</code></td><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">Specifies the type of the artifact. Valid values are: |
| <div class="itemizedlist"><ul type="disc"><li><code class="code">bundle</code>: Specifies an OSGi bundle. Use this artifact type for WAR files and Web application bundles. </li><li><code class="code">configuration</code>: Specifies that the artifact is a configuration file. Configuration files contain name/value pairs that set initial values for configuration properties of a bundle. </li><li><code class="code">plan</code>: Specifies that the artifact is a plan. </li><li><code class="code">par</code>: Specifies that the artifact is a PAR. </li></ul></div> |
| </td><td style="border-bottom: 1.0pt solid ; ">Yes.</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="literal">name</code></td><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">Specifies the name of the artifact. |
| |
| <p>See <a class="link" href="">Artifact Names</a> for guidelines for determining the name of an artifact.</p> |
| </td><td style="border-bottom: 1.0pt solid ; ">Yes.</td></tr><tr><td style="border-right: 1.0pt solid ; "><code class="literal">version</code></td><td style="border-right: 1.0pt solid ; ">Specifies the version or range of versions of this artifact that VWS should look up in its repositories and then install and deploy. You must use OSGi version specification syntax, such as <code class="code">[1.0.0, 2.0.0)</code>. </td><td style="">No. If not specified, defaults to <code class="code">0</code>, which in OSGi means 0 to infinity, or any version.</td></tr></tbody></table></div></div><br class="table-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="names-of-artifacts"></a>Artifact Names</h3></div></div></div><p>When you create a plan, you use the <code class="code">name</code> attribute of the <code class="code"><artifact></code> element to specify the name of all the plan’s dependencies. This section describes how to determine the name of an artifact, which is not always obvious.</p><p>Use the following guidelines to determine the name of an artifact:</p><div class="itemizedlist"><ul type="disc"><li><p><span class="bold"><strong>Bundle</strong></span>: In this context, a <span class="emphasis"><em>bundle</em></span> refers to a standard OSGi bundle as well as a Web application bundles and WAR file. The name of a bundle is the value of the <code class="code">Bundle-SymbolicName</code> header in the <code class="code">META-INF/MANIFEST.MF</code> file of the <code class="code">*.jar</code> or <code class="code">*.war</code> file. The following <code class="code">MANIFEST.MF</code> snippet shows a bundle with name <code class="code">com.springsource.exciting.app</code>:</p><pre class="screen">Bundle-SymbolicName: org.eclispe.virgo.exciting.app</pre><p>If the bundle does not contain a <code class="code">META-INF/MANIFEST.MF</code> file, then the name of the bundle is its filename minus the <code class="code">.jar</code> or <code class="code">.war</code> extension.</p></li><li><p><span class="bold"><strong>Configuration File</strong></span>: The name of a configuration file is its filename minus the <code class="code">.properties</code> extension. </p></li><li><p><span class="bold"><strong>Plan</strong></span>: The name of a plan is the value of the required <code class="code">name</code> attribute of the <code class="code"><plan></code> element in the plan’s XML file. In the following XML snippet, the plan name is <code class="code">multi-artifact.plan</code>:</p><pre class="screen"><?xml version="1.0" encoding="UTF-8"?> |
| <plan name="<span class="bold"><strong>multi-artifact.plan</strong></span>" version="1.0.0" scoped="true" atomic="true" |
| xmlns="http://www.springsource.org/schema/dm-server/plan" |
| ...</pre></li><li><p><span class="bold"><strong>PAR</strong></span>: The name of a PAR is the value of the <code class="code">Application-SymbolicName</code> header in the <code class="code">META-INF/MANIFEST.MF</code> file of the <code class="code">*.par</code> file. The following <code class="code">MANIFEST.MF</code> snippet shows a PAR with name <code class="code">com.springsource.my.par</code>:</p><pre class="screen">Application-SymbolicName: org.eclipse.virgo.my.par</pre><p>If the PAR does not contain a <code class="code">META-INF/MANIFEST.MF</code> file, then the name of the PAR is its filename minus the <code class="code">.par</code> extension.</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="developing-applications-plans-use"></a>Using the Plan</h3></div></div></div><p> |
| Because a plan is a list of artifacts, rather than a physical file that contains the artifacts, there are a few additional steps you must perform before you deploy it to VWS. |
| </p><div class="orderedlist"><ol type="1"><li><p>Copy the artifacts that make up the plan to the <code class="code">usr</code> repository, which by default is the <code class="code">$SERVER_HOME/repository/usr</code> directory, where <code class="code">$SERVER_HOME</code> refers to the top-level installation directory of VWS. Note that you might have configured the server differently; in which case, copy the artifacts to your custom repository directory.</p></li><li><p>Restart VWS.</p></li><li><p>After the server has started, either use the Admin Console to deploy the plan, or manually deploy it by copying the plan’s XML file into the <code class="code">$SERVER_HOME/pickup</code> directory. </p><p>This results in VWS deploying the plan with the same semantics as a PAR file.</p></li><li><p>To undeploy the plan, use the Admin Console, or simply delete it from the <code class="code">$SERVER_HOME/pickup</code> directory.</p></li></ol></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="developing-applications-plans-scoping"></a>Plans and Scoping</h3></div></div></div><p>As described in previous sections, you can specify that a plan be <span class="emphasis"><em>scoped</em></span>. This means that Virgo Web Server installs the artifacts that make up the plan into a plan-specific scope so that only the application described by the plan has access to the artifacts. If you disable scoping, then Virgo Web Server installs the artifacts into the global scope, which means they are available for access by all other deployed artifacts. This section describes scoping in a bit more detail. It also describes how you can change the default behavior of scoping, with respect to services, so that a service that is in a scope can be made globally available. </p><p>If a bundle in a given scope imports a package and a bundle in the same scope exports the package, then the import may only be satisfied by the bundle in the scope, and not by any bundles outside the scope, including the global scope. Similarly, package exports from bundles in a scope are not visible to bundles in the global scope.</p><p>If a bundle in a scope uses Spring DM (or the blueprint service) to obtain a service reference and a bundle in the same scope uses Spring DM (or the blueprint service) to publish a matching service, then the service reference may only bind to the service published in the scope (and not to any services outside the scope). Services published by bundles in a scope are not visible to bundles in the global scope. </p><p>However, sometimes it is useful to make a service in a scope globally available to artifacts outside the scope. To do this, publish the service with the <code class="literal">org.eclipse.virgo.service.scope</code> service property set to <code class="literal">global</code>. Use the <code class="literal"><service-properties></code> child element of <code class="literal"><service></code>, as shown in the following example: </p><pre class="programlisting"><service id="publishIntoGlobal" interface="java.lang.CharSequence"> |
| <span class="bold"><strong><service-properties> |
| <beans:entry key="org.eclipse.virgo.service.scope" value="global" /> |
| </service-properties></strong></span> |
| <beans:bean class="java.lang.String"> |
| <beans:constructor-arg value="foo"/> |
| </beans:bean> |
| </service></pre></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="ch04s02.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch04.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch04s04.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">4.2 Creating PARs and WARs </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 4.4 Creating and Using Configuration Artifacts</td></tr></table></div></body></html> |
