4.3 Creating Plans

4.3 Creating Plans
Prev	4. Developing Applications	Next

Plans are similar to PARs in that they encapsulate the bundles 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 PARs.

Plans have the following additional benefits, which is why SpringSource recommends that you use plans rather than PARs when defining an application:

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.
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 reasons, 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.
You can enable or disable whether a plan is scoped or atomic; PARs are always scoped and atomic.

Creating the Plan XML File

Plans are XML files that have a .plan file extension, such as myapplication.plan. The structure of the XML file is simple: the root element is <plan> 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 <artifact> 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:

<?xml version="1.0" encoding="UTF-8"?>
<plan name="multi-artifact.plan" version="1.0.0" scoped="true" atomic="true"
        xmlns="http://www.springsource.org/schema/dm-server/plan"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="
            http://www.springsource.org/schema/dm-server/plan 
            http://www.springsource.org/schema/dm-server/plan/springsource-dm-server-plan.xsd">

    <artifact type="bundle" name="simple.bundle.one" version="[1.0.0, 2.0.0)"/>
    <artifact type="bundle" name="simple.bundle.two" version="[2.0.0, 3.1.0)"/>
</plan>

In the preceding example, the name of the plan is multi-artifact.plan and its version is 1.0.0. The plan is both scoped and atomic. The plan contains two artifacts, both of which are bundles.

The following table describes the attributes of the <plan> element.

Table 4.2. Attributes of the <plan> Element

Attribute	Description	Required?
`name`	Specifies the name of this plan. uses the name as one component of the unique identifier of this plan.	Yes.
`version`	Specifies the version of this plan. You must use OSGi version specification syntax, such as `2.1.0`. uses the version as one component of the unique identifier of this plan.	Yes.
`scoped`	Specifies whether 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 installs the artifacts into the global scope, which means they are then available for access by all other deployed artifacts. Set the attribute to `true` to enable scoping or `false` to disable it.	Yes.
`atomic`	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, escalates the event to all artifacts in the plan. Also, in an atomic plan, prevents artifacts from being in inconsistent states. For example, if one artifact should fail to start, then stops all artifacts in the plan. Set this attribute to `true` to enable atomicity or `false` to disable it.	Yes.

The following table describes the attributes of the <artifact> element.

Table 4.3. Attributes of the <artifact> Element

Attribute	Description	Required?
`type`	Specifies the type of the artifact. In this release, the only valid value is `bundle` which specifies that the artifact is an OSGi bundle.	Yes.
`name`	Specifies the name of the artifact.	Yes.
`version`	Specifies the version or range of versions of this artifact that should look up in its repositories and then install and deploy. You must use OSGi version specification syntax, such as `[1.0.0, 2.0.0)`.	No. If not specified, defaults to `0`, which in OSGi means 0 to infinity, or any version.

Using the Plan

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 .

Copy the bundles that make up the plan to the bundles-usr repository, which by default is the $DMS_HOME/repository/bundles/usr directory, where $DMS_HOME refers to the top-level installation directory of . Note that you might have configured the server differently; in which case, copy the bundles to your custom repository directory.
Restart .
After the server has started, copy the plan's XML file into the $DMS_HOME/pickup directory.
This results in deploying the plan with the same semantics as a PAR file.
To undeploy the plan, simply delete it from the $DMS_HOME/pickup directory.

Prev	Up	Next
4.2 Creating PARs and WARs	Home	4.4 Programmatic Access to Personality-specific Features