2.3. Creating Ant Bundles

Bundles are archive files that is stored on the server and then downloaded by an agent to deploy to a platform or resource. A bundle distribution is comprised of two elements:
  • An Ant recipe file named deploy.xml
  • Any associated application files. These application files can be anything; commonly, they fall into two categories:
    • Archive files (JAR or ZIP files)
    • Raw text configuration files, which can include tokens where users define the values when the bundle is deployed

2.3.1. Using Templatized Configuration Files

A bundle can contain configuration files for an application. These configuration files can use hard-coded values or they can use tokens that are filled in (automatically or with user-supplied values) when the bundle is actually deployed.

NOTE

For a user-defined token to be realized, it must be referenced in the recipe so that the bundle deployment wizard will prompt for the value, using the <rhq:input-property> key in the Ant recipe. For examples, see Section 2.3.2.4.2, “rhq:input-property” and Example 1, “Simple Ant Recipe”.
User-defined tokens can be any property; the values are supplied through the provisioning UI and inserted into the templatized configuration file.
The token key is a simple attribute-value assertion, with the input_field as the element in the UI and the property being the value in the configuration file. The property of user-defined tokens must contain only alphanumeric characters, an underscore (_), or a period (.); no other characters are allowed.
input_field=@@property@@
For example, to set a port number token in a configuration file, define the property:
port=@@listener.port@@
The user-defined token then must be noted in the recipe, so that the provisioning process knows to realize the phrase. To configure a property in an Ant recipe, add a <rhq:input-property> key in the Ant XML file.
For example:
<rhq:input-property
    name="listener.port"
    ... />
The provisioning wizard prompts for a value for all of the user-defined tokens referenced in the recipe.
Port Token During Provisioning

Figure 3. Port Token During Provisioning


Along with user-defined variables that can be specified in the recipe file, there are variables that are made implicitly available to recipes. These tokens can be used in a templatized file as a user-defined variable without having to define the token template in the recipe itself.

Table 1. Variables Defined by JBoss ON

Token Description
rhq.deploy.dir The directory location where the bundle will be installed.
rhq.deploy.id A unique ID assigned to the specific bundle deployment.
rhq.deploy.name The name of the bundle deployment.

Additionally, some tokens can be realized by the provisioning process pulling information from the local system. These values, listed in Table 2, “System-Defined Tokens”, are taken either from the Java API or from Java system properties. They can be inserted directly in the templatized configuration file without having to put a corresponding entry in the recipe. For example:
@@rhq.system.hostname@@

Table 2. System-Defined Tokens

Token Name Taken From... Java API
rhq.system.hostname Java API SystemInfo.getHostname()
rhq.system.os.name Java API SystemInfo.getOperatingSystemName()
rhq.system.os.version Java API SystemInfo.getOperatingSystemVersion()
rhq.system.os.type Java API SystemInfo.getOperatingSystemType().toString()
rhq.system.architecture Java API SystemInfo.getSystemArchitecture()
rhq.system.cpu.count Java API SystemInfo.getNumberOfCpus()
rhq.system.interfaces.java.address Java API InetAddress.getByName(SystemInfo.getHostname()).getHostAddress()
rhq.system.interfaces.network_adapter_name.mac Java API NetworkAdapterInfo.getMacAddress()
rhq.system.interfaces.network_adapter_name.type Java API NetworkAdapterInfo.getType()
rhq.system.interfaces.network_adapter_name.flags Java API NetworkAdapterInfo.getAllFlags()
rhq.system.interfaces.network_adapter_name.address Java API NetworkAdapterInfo.getUnicastAddresses().get(0).getHostAddress()
rhq.system.interfaces.network_adapter_name.multicast.address Java API NetworkAdapterInfo.getMulticastAddresses().get(0).getHostAddress()
rhq.system.sysprop.java.io.tmpdir Java system property
rhq.system.sysprop.file.separator Java system property
rhq.system.sysprop.line.separator Java system property
rhq.system.sysprop.path.separator Java system property
rhq.system.sysprop.java.home Java system property
rhq.system.sysprop.java.version Java system property
rhq.system.sysprop.user.timezone Java system property
rhq.system.sysprop.user.region Java system property
rhq.system.sysprop.user.country Java system property
rhq.system.sysprop.user.language Java system property

2.3.2. Creating Ant Recipes

NOTE

The process and guidelines for actually creating an Ant recipe are outside the scope of this documentation. This document outlines the options and requirements for using Ant recipes specifically to work with the JBoss ON provisioning system.
For basic instructions, options, and tutorials for writing Ant tasks, see the Apache Ant documentation at http://ant.apache.org/manual/index.html.
2.3.2.1. Breakdown of an Ant Recipe
The Ant recipe for JBoss ON bundles is the same basic file as a standard Apache Ant file and is processed by an integrated Ant build system in JBoss ON. This Ant recipe file must be bundled in the top directory of the distribution ZIP file and be named deploy.xml.
The JBoss ON Ant recipes allows all of the standard tasks that are available for Ant builds, which provides flexibility in scripting a deployment for a complex application. The JBoss ON Ant recipe must also provide additional information about the deployment that will be used by the provisioning process; this includes information about the destination and, essentially, metadata about the application itself.

Example 1. Simple Ant Recipe

For provisioning, the Ant recipe is more of a definition file than a true script file, although it can call Ant targets and do pre- and post-provisioning operations. As with other Ant scripts, the JBoss ON Ant recipe uses a standard XML file with a <project> root element and defined targets and tasks. The elements defined in the <rhq:bundle> area pass metadata to the JBoss ON provisioning system when the project is built.
The first part of the deploy.xml file simply identifies the file as an an script and references the provisioning Ant elements.
<?xml version="1.0"?>
<project name="test-bundle" default="main" 
	xmlns:rhq="antlib:org.rhq.bundle">
The next element identifies the specific bundle file itself. The provisioning system can manage and deploy multiple versions of the same application; the <rhq:bundle> element contains information about the specific version of the bundle (including, naturally enough, an optional version number).
    <rhq:bundle name="Example App" version="2.4" description="an example bundle">
All that is required for a recipe is the <rhq:bundle> element that defines the name of the application. However, the bundle element contains all of the information about the application and, importantly, how the provisioning system should handle content contained in the application.
The first item to address is any templatized property that is used in a configuration file. This is covered in Section 2.3.1, “Using Templatized Configuration Files”. Any token used in a configuration file must be defined in the recipe for it to be realized (to have a value supplied) during provisioning. For the port token defined in Section 2.3.1, “Using Templatized Configuration Files”, the <rhq:input-property> element identifies it in the recipe. The name argument is the input_field value in the token, the description argument gives the field description used in the UI and the other arguments set whether the value is required, what its allowed syntax is, and any default values to supply. (This doesn't list the files which use tokens, only the tokens themselves.)
	<rhq:input-property
            name="listener.port"
            description="This is where the product will listen for incoming messages"
            required="true"
            defaultValue="8080"
            type="integer"/>
There is a single element which identifies all of the content deployed by the bundle, the <rhq:deployment-unit> element. The entire application — its name, included ZIP or JAR files, configuration files, Ant targets — are all defined in the <rhq:deployment-unit> parent element.
The name and any Ant targets are defined as arguments on <rhq:deployment-unit> directly. In this, the name is appserver, and one preinstall target and one postinstall target are set.
        <rhq:deployment-unit name="appserver" preinstallTarget="preinstall" postinstallTarget="postinstall" manageRootDir="false">
There is one other critical element on the <rhq:deployment-unit> element: the manageRootDir argument. Provisioning doesn't simply copy over files; as described in Section 2.1.3, “File Handling During Provisioning”, it remakes the directory to match what is in the bundle. If there are any existing files in the deployment directory when the bundle is first deployed, they are deleted by default. Setting manageRootDir to false means that the provisioning process does not manage the deployment directory — meaning any existing files are left alone when the bundle is deployed.
Any configuration file is identified in an <rhq:file> element. The name is the name of the configuration file within the bundle, while the destinationFile is the relative (to the deployment directory) path and filename of the file after it is deployed.
	<rhq:file name="test-v2.properties" destinationFile="conf/test.properties" replace="true"/>
Bundles can contain archive files, either ZIP or JAR files. Every archive file is identified in an <rhq:archive> element within the deployment-unit. The <rhq:archive> element does three things:
  • Identify the archive file by name.
  • Define how to handle the archive. Simply put, it sets whether to copy the archive over to the destination and then leave it as-is, still as an archive, or whether to extract the archive once it is deployed. This is called exploding the archive. If an archive is exploded, then a postinstall task can be called to move or edit files, as necessary.
  • Identify any files within the archive which contain tokens that need to be realized. This is a child element, <rhq:fileset>. This can use wildcards to include types of files or files within subdirectories or it can explicitly state which files to process.
            <rhq:archive name="MyApp.zip" exploded="true">
                <rhq:replace>
                    <rhq:fileset>
                        <include name="**/*.properties"/>
                    </rhq:fileset>
                </rhq:replace>
            </rhq:archive>
Another possible child element sets how to handle any files within the deployment directory that are not part of the bundle. For example, the application may generate log files or it may allow users to upload content. By default, the provisioning process cleans out a directory from non-bundle content every time a bundle is provisioned. However, logs, user-supplied data, and other types of files are data that should remain intact after provisioning. Any files or subdirectories which should be ignored by the provisioning process (and therefore preserved) are identified in the <rhq:ignore> element. In this case, any *.log files within the logs/ directory are saved.
            <rhq:ignore>
                <rhq:fileset>
                    <include name="logs/*.log"/>
                </rhq:fileset>
            </rhq:ignore>
        </rhq:deployment-unit>
    </rhq:bundle>
This only applies to upgrading a bundle, meaning after the initial deployment.
The last elements set the Ant tasks to run before or after deploying the content, as identified initially in the <rhq:deployment-unit> arguments. Most common Ant tasks are supported (as described in Section 2.3.2.3, “Using Ant Tasks”). This uses a preinstall task to print which directory the bundle is being deployed to and whether the operation was successful. The postinstall task prints a message when the deployment is complete.
<target name="main" />

    <target name="preinstall">
        <echo>Deploying Test Bundle v2.4 to ${rhq.deploy.dir}...</echo>
	<property name="preinstallTargetExecuted" value="true"/>
	<rhq:audit status="SUCCESS" action="Preinstall Notice" info="Preinstalling to ${rhq.deploy.dir}" message="Another optional message"> 
		Some additional, optional details regarding 
		the deployment of ${rhq.deploy.dir} 
	</rhq:audit> 
    </target>

    <target name="postinstall">
        <echo>Done deploying Test Bundle v2.4 to ${rhq.deploy.dir}.</echo>
        <property name="postinstallTargetExecuted" value="true"/>
    </target>
</project>

Section 2.3.2.4, “A Reference of JBoss ON Ant Recipe Elements” lists the different JBoss ON elements in the Ant recipe file. For information on standard Ant tasks, see the Apache Ant documentation.
2.3.2.2. Saving Files During Provisioning
One important thing to consider with an Ant recipe is how to handle files in the deployment directory. (This is touched on in Section 2.1.3, “File Handling During Provisioning”.)
By default, deploying or updating a bundle replaces everything in the deployment directory, either by overwriting it or deleting it. The file handling rules are very similar to RPM package upgrade rules. This is very simplified, but the provisioning process responds in one of two ways to existing files the deployment directory:
  1. The file in the current directory is also in the bundle. In this case, the bundle file always overwrites the current file. (There is one exception to this. If the file in the bundle has not been updated and is the same version as the local file, but the local file has modifications. In that case, the local file is preserved.)
  2. The file in the current directory does not exist in the bundle. In that case, the bundle deletes the file in the current directory.
The behavior for #2, when a file is deleted, can be changed by settings in the Ant recipe.
There are three ways to manage if and how files are preserved during provisioning: manageRootDir, <rhq:ignore>, and cleanDeployment.
manageRootDir
All of the information about the application being deployed is defined in the <rhq:deployment-unit> element in a bundle recipe. The manageRootDir attribute on the <rhq:deployment-unit> element sets how the provisioning process should handle existing files in the deployment directory.
The default value is manageRootDir=true which means that the provisioning process deletes any other files in the root directory.
Alternately, the value can be set to false, which tells the provisioning process to ignore any existing files in the root directory, as long as there is not a corresponding file in the bundle.
The manageRootDir attribute applies to both the initial deployment and upgrade operations, so this can be used to preserve files that may exist in a directory before a bundle is ever deployed.

NOTE

When a bundle will no longer be used on a resource, it can be entirely removed from the filesystem. This is called purging. The way that the provisioning system handles files when purging a bundle mirrors that way that it handles files when provisioning a system. By default, purging a bundle deletes everything in the deployment directory. If the manageRootDir option is set in the bundle, then the provisioning process removes all of the files and directories associated with the bundle and leaves unrelated files and directories intact.
<rhq:ignore>
There can be files that are used or created by an application, apart from the bundle, which need to be preserved after a bundle deployment. This can include things like log files, instance-specific configuration files, or user-supplied content like images. These files can be ignored during the provisioning process, which preserves the files instead of removing them.
To save files, use the <rhq:ignore> element and list the directories or files to preserve.
<rhq:ignore>
    <rhq:fileset>
        <include name="logs/*.log"/>
    </rhq:fileset>
</rhq:ignore>
The <rhq:ignore> element only applies when bundles are updated; it does not apply when a bundle is initially provisioned.
Also, the <rhq:ignore> element only applies to file that exist outside the bundle. Any files that are in the bundle will overwrite any corresponding files in the deployment directory, even if they are specified in the <rhq:ignore> element.
Clean Deployment
Both manageRootDir and <rhq:ignore> are set in the recipe. At the time that the bundle is actually provisioned, there is an option to run a clean deployment. The clean deployment option deletes everything in the deployment directory and provisions the bundle in a clean directory, regardless of the manageRootDir and <rhq:ignore> settings in the recipe.
2.3.2.3. Using Ant Tasks
An Ant bundle distribution file is just an Ant recipe and its associated files. As Example 1, “Simple Ant Recipe” shows, the Ant recipe is the expected deploy.xml file with some JBoss ON-specific elements. An Ant bundle distribution file supports more complex Ant configuration, including Ant tasks and targets.
2.3.2.3.1. Supported Ant Tasks
Any standard Ant task can be run as part of the Ant bundle provisioning (with the exception of <antcall> and <macrodef>). This includes common commands like echo, mkdir, and touch — whatever is required to deploy the content fully.

IMPORTANT

The <antcall> element cannot be used with the Ant recipe. <antcall> calls a target within the deploy.xml file, which loops back to the file, which calls the <antcall> task again, which calls the deploy.xml file again. This creates an infinite loop.
To perform the same operations that would be done with <antcall>, use the <ant> task to reference a separate XML file which contains the custom Ant targets. This is described in Section 2.3.2.3.3, “Calling Ant Targets”.

IMPORTANT

The macrodef call, and therefore macro definitions, are not supported with Ant bundles.
Along with the standard Ant tasks, Ant bundle recipes can use optional Ant tasks:
2.3.2.3.2. Using Default, Pre-Install, and Post-Install Targets
As with other Ant tasks, the <project> allows a default target, which is required by the provisioning system. This is a no-op because the Ant recipe mainly defines the metadata for and identifies files used by the provisioning process. Other operations aren't necessary. This target is required by Ant, even though it is a no-op target. Use pre- and post-install targets to perform tasks with the bundle before and after it is unpacked.
For example:
<target name="main" />
Additionally, JBoss ON provisioning tasks can define both pre- and post-install targets. This allows custom tasks, like simple progress messages or setting properties.
2.3.2.3.3. Calling Ant Targets
As mentioned in Section 2.3.2.3.1, “Supported Ant Tasks”, using <antcall> does not work in an Ant bundle recipe; it self-referentially calls the <rhq:bundle> task in an infinite loop. However, it is possible to process tasks that are outside the default target. This can be done using pre- and post install targets (Section 2.3.2.3.2, “Using Default, Pre-Install, and Post-Install Targets”).
  1. In deploy.xml for the Ant recipe, add a <rhq:deployment-unit> element which identifies the Ant target.
    <rhq:deployment-unit name="jar" postinstallTarget="myExampleCall">
  2. Then, define the target.
        <target name="myExampleCall">
           <ant antfile="another.xml" target="doSomething">
              <property name="param1" value="111"></property>
           </ant>
        </target>
    
  3. Create a separate another.xml file in the same directory as the deploy.xml file. This file contains the Ant task.
    <?xml version="1.0"?>
    <project name="another" default="main">
        <target name="doSomething">
           <echo>inside doSomething. param1=${param1}</echo>
        </target>
    </project>
    
2.3.2.4. A Reference of JBoss ON Ant Recipe Elements
2.3.2.4.1. rhq:bundle
Contains the definition for the main JBoss ON-related Ant task that is required for any Ant bundle recipe. This element defines basic information about the bundle and is the parent element for all of the specific details about what is in the bundle and how it should be provisioned.
Element Attributes
Attribute Description Optional or Required
name The name given to the bundle. Required
version The version string for this specific bundle. Bundles can have the same name, but each bundle of that name must have a unique version string. These version strings normally conform to an OSGi style of versioning, such as 1.0 or 1.2.FINAL. Required
description A readable description of this specific bundle version. Optional
Example
<rhq:bundle name="example" version="1.0" description="an example bundle">
2.3.2.4.2. rhq:input-property
Adds a property to the bundle task that defines a template token that must have its value supplied by a user at the time the bundle is deployed. This is similar to standard Ant properties.

NOTE

All of the system properties listed in Table 2, “System-Defined Tokens” and the Ant-specific tokens in Table 1, “Variables Defined by JBoss ON” are available to be used as templatized tokens in bundle configuration without having to set a <rhq:input-property> definition.
All input properties set some parameter that must have its value defined by a user when the bundle is provisioned on a resource, and the fields to enter those values are automatically generated in the JBoss ON UI bundle deployment wizard.
Element Attributes
Attribute Description Optional or Required
name The name of the user-defined property. Within the recipe, this property can be referred to by this name, in the format ${property_name}. Required
description A readable description of the property. This is the text string displayed in the JBoss ON bundle UI when the bundle is deployed. Required
type Sets the syntax accepted for the user-defined value. There are several different options:
  • string
  • longString
  • long
  • password
  • file
  • directory
  • boolean
  • integer
  • float
  • double
Required
required Sets whether the property is required or optional for configuration. The default value is false, which means the property is optional. If this argument isn't given, then it is assumed that the property is optional. Optional
defaultValue Gives a value for the property to use if the user does not define a value when the bundle is deployed. Optional
Example
<rhq:input-property
    name="listener.port"
    description="This is where the product will listen for incoming messages"
    required="true"
    defaultValue="8080"
    type="integer"/>
2.3.2.4.3. rhq:deployment-unit
Defines the bundle content — such as applications or configuration files — being deployed by the bundle. A deployment unit can be simple text files, archives, or a full software product, including an application server, web server, or database. A deployment unit can have multiple archive and configuration files associated with it.
Only a single deployment unit is provisioned at a time by the provisioning process, so there can be only one <rhq:deployment-unit> element in a bundle recipe.
Element Attributes
Attribute Description Optional or Required
name The name of the application. Required
manageRootDir Sets whether JBoss ON should manage all files in the top root directory (deployment directory) where the bundle is deployed. If false, any unrelated files found in the top deployment directory are ignored and will not be overwritten or removed when future bundle updates are deployed. The default is true. Optional
preinstallTarget An Ant target that is invoked before the deployment unit is installed. Optional
postinstallTarget An Ant target that is invoked after the deployment unit is installed. Optional
Example
<rhq:deployment-unit name="appserver" preinstallTarget="preinstall" postinstallTarget="postinstall">
2.3.2.4.4. rhq:archive
Defines any archive file that is associated with deploying the application. An archive can be a ZIP or JAR file. A bundle doesn't require an archive file, so this element is optional.
Element Attributes
Attribute Description Optional or Required
name The filename of the archive file to include in the bundle.

IMPORTANT

If the archive file is packaged with the Ant recipe file inside the bundle distribution ZIP file, then the name must contain the relative path to the location of the archive file in the ZIP file.
Required
exploded Sets whether the archive's contents will be extracted and stored into the bundle destination directory (true) or whether to store the files in the same relative directory as is given in the name attribute (false). If the files are exploded, they are extracted starting in the deployment directory. Post-install targets can be used to move files after they have been extracted. Optional
Example
<rhq:archive name="file.zip">
    <rhq:replace>
         <rhq:fileset>
               <include name="**/*.properties"/>
         </rhq:fileset>
    </rhq:replace>
</rhq:archive>
2.3.2.4.5. rhq:url-archive
Defines remote archive to use, which is accessed through the given URL. This is similar to rhq:archive except that the server accesses the archive over the network rather than including the archive directly in the bundle distribution file.
Element Attributes
Attribute Description Optional or Required
url Gives the URL to the location of the archive file. The archive is downloaded and installed in the deployment directory.

NOTE

For the bundle to be successfully deployed, the URL must be accessible to all agent machines where this bundle is to be deployed. If an agent cannot access the URL, it cannot pull down the archive and thus cannot deploy it on the machine.
Required
name Sets whether the archive's contents will be extracted and stored into the bundle destination directory (true) or whether to store the files in the same relative directory as is given in the name attribute (false). If the files are exploded, they are extracted starting in the deployment directory. Post-install targets can be used to move files after they have been extracted. Optional
Example
<rhq:url-archive url="http://server.example.com/apps/files/archive.zip">
    <rhq:replace>
         <rhq:fileset>
               <include name="**/*.properties"/>
         </rhq:fileset>
    </rhq:replace>
</rhq:url-archive>
2.3.2.4.6. rhq:file
Contains the information to identify and process configuration files for the application which have token values that must be realized. Normally, configuration files are copied directly from the bundle package into the deployment directory. The <rhq:file> element calls out files that require processing before they should be copied to the destination. The attributes on the <rhq:file> element set the name of the raw file in the bundle distribution ZIP file and the name of the target file that it should be copied to.
Raw files can be included with the archive files that contain properties or configuration for the application. These configuration files can be templatized with user-defined or system-defined tokens, like those listed in Section 2.3.1, “Using Templatized Configuration Files”. Any templatized files that are included in the bundle distribution file that are templatized must be listed in the Ant recipe so that they are processed and the tokens are realized.
Element Attributes
Attribute Description Optional or Required
name The name of the raw configuration file.

IMPORTANT

If the configuration file is packaged with the Ant recipe file inside the bundle distribution ZIP file, then the name must contain the relative path to the location of the file within the ZIP file.
Required
destinationFile The full path and filename for the file on the destination resource. Relative paths must be relative to the final deployment directory (defined in the rhq.deploy.dir parameter when the bundle is deployed). It is also possible to use absolute paths, as long as both the directory and the filename are specified.

NOTE

If the destinationDir attribute is used, the destinationFile attribute cannot be used.
Required, unless destinationDir is used
destinationDir The directory where this file is to be copied. If this is a relative path, it is relative to the deployment directory given by the user when the bundle is deployed. If this is an absolute path, that is the location on the filesystem where the file will be copied.
This attribute sets the directory for the file to be copied to. The actual file name is set in the name attribute.
If the destinationFile attribute is used, the destinationDir attribute cannot be used.
Required, unless destinationFile is used
replace Indicates whether the file is templatized and requires additional processing to realize the token values. Required
Example
<rhq:file name="test-v2.properties" destinationFile="subdir/test.properties" replace="true"/>
If neither the destinationDir nor the destinationFile attribute is used, then the raw file is placed in the same location under the deployment directory as its location in the bundle distribution.
2.3.2.4.7. rhq:url-file
As with rhq:file, contains the information to identify and process configuration files for the application which have token values that must be realized. This option specifies a remote file which is downloaded from the given URL, rather than being included in the bundle archive.
Element Attributes
Attribute Description Optional or Required
url Gives the URL to the templatized file. The file is downloaded and installed in the deployment directory.

NOTE

For the bundle to be successfully deployed, the URL must be accessible to all agent machines where this bundle is to be deployed. If an agent cannot access the URL, it cannot pull down the archive and thus cannot deploy it on the machine.
Required
destinationFile The full path and filename for the file on the destination resource. Relative paths must be relative to the final deployment directory (defined in the rhq.deploy.dir parameter when the bundle is deployed). It is also possible to use absolute paths, as long as both the directory and the filename are specified.

NOTE

If the destinationDir attribute is used, the destinationFile attribute cannot be used.
This attribute must give both the path name and the file name.
Required, unless destinationDir is used
destinationDir The directory where this file is to be copied. If this is a relative path, it is relative to the deployment directory given by the user when the bundle is deployed. If this is an absolute path, that is the location on the filesystem where the file will be copied.
This attribute sets the directory for the file to be copied to. The actual file name is set in the name attribute.
If the destinationFile attribute is used, the destinationDir attribute cannot be used.
Required, unless destinationFile is used
replace Indicates whether the file is templatized and requires additional processing to realize the token values. Required
Example
<rhq:url-file url="http://server.example.com/apps/files/test.conf" destinationFile="subdir/test.properties" replace="true"/>
If neither the destinationDir nor the destinationFile attribute is used, then the raw file is placed in the same location under the deployment directory as its location in the bundle distribution.
2.3.2.4.8. rhq:audit
Sets custom audit trail messages to use during the provisioning process. This is useful with complex recipes that perform some additional custom tasks. As the tasks are processed, the rhq:audit configuration sends information to the server about the additional processing steps and their results.
Element Attributes
Attribute Description Optional or Required
status The status of the processing. The possible values are SUCCESS, WARN, and FAILURE. The default is SUCCESS. Optional
action The name of the processing step. Required
info A short summary of what the action is doing, such as the name of the target of the action or an affected filename. Optional
message A brief text string which provides additional information about the action. Optional
Example
<rhq:audit status="SUCCESS" action="Preinstall Notice" info="Preinstalling to ${rhq.deploy.dir}" message="Another optional message"> 
	Some additional, optional details regarding 
	the deployment of ${rhq.deploy.dir} 
</rhq:audit>
2.3.2.4.9. rhq:replace
Lists templatized files, in children <rhq:fileset> elements, contained in the archive which need to have token values realized when the archive is deployed.
Any file which uses a token that must be replaced with a real value is a templatized file. When the provisioning process runs, the token value is substituted with the defined value. This element lists all of the files which are templatized; the only files which are processed by the provisioning system for token substitution are the ones listed in the <rhq:replace> element.
Example
<rhq:archive name="file.zip">
    <rhq:replace>
        <rhq:fileset>
            <include name="**/*.properties"/>
        </rhq:fileset>
    </rhq:replace>
</rhq:archive>
2.3.2.4.10. rhq:ignore
Lists files in the deployment directory which should not be deleted when a new bundle is deployed. This only applies to upgrade operations, not to the initial deployment of a bundle.
Once an application is deployed, instance-specific files — like data files or logs — can be created and should be retained if the application is ever upgraded. This element, much like <rhq:replace>, contains a list of files or directories in the instance to save.

NOTE

If a file is ignored in the recipe, then the file is not deleted when the bundle is deployed. However, if a file of the same name exists in the bundle, then the local file is overwritten.
Do not attempt to ignore files that are packaged in the bundle. Only files generated by the applications, such as log and data files, should be ignored by the provisioning process since they should be preserved for the upgraded instance.

IMPORTANT

It is possible to deploy one bundle to a subdirectory of another bundle (such as Bundle A is deployed to /opt/myapp and Bundle B to /opt/myapp/webapp1).
In that case, set the recipe in Bundle A to ignore the directory to which Bundle B will be deployed. This prevents updates or reversions for Bundle A from overwriting the configuration from Bundle B.
Example
<rhq:ignore>
    <rhq:fileset>
        <include name="logs/*.log"/>
    </rhq:fileset>
</rhq:ignore>
2.3.2.4.11. rhq:fileset
Provides a list of files.
Two JBoss ON elements — <rhq:replace> and <rhq:ignore> — define file lists in either the archive file or the deployment directory. This element contains the list of files.
Child Element
Child Element Description
<include name=filename /> The filename of the file. For <rhq:replace>, this is a file within the archive (JAR or ZIP) file which is templatized and must have its token values realized. For <rhq:ignore>, this is a file in the application's deployment directory which should be ignored and preserved when the bundle is upgraded.
Example
<rhq:replace>
     <rhq:fileset>
         <include name="**/*.properties"/>
     </rhq:fileset>
</rhq:replace>
2.3.2.4.12. rhq:system-service
Points to a script file to launch as part of the provisioning process. This is usually an init file or similar file that can be used by the deployed application to set the application up as a system service.
Element Attributes
Attribute Description Optional or Required
name The name of the script. Required
scriptFile The filename of the script. If the script file is packaged with the Ant recipe file inside the bundle distribution ZIP file, then the scriptFile must contain the relative path to the location of the file in the ZIP file. Required
configFile The name of any configuration or properties file used by the script. If the configuration file is packaged with the Ant recipe file inside the bundle distribution ZIP file, then the configFile must contain the relative path to the location of the file in the ZIP file. Optional
overwriteScript Sets whether to overwrite any existing init file to configure the application as a system service. Optional
startLevels Sets the run level for the application service. Optional
startPriority Sets the start order or priority for the application service. Optional
stopPriority Sets the stop order or priority for the application service. Optional
Example
<rhq:system-service name="example-bundle-init" scriptFile="example-init-script"
      configFile="example-init-config" overwriteScript="true"
      startLevels="3,4,5" startPriority="80" stopPriority="20"/>

2.3.3. Creating an Associated Archive File

The application that is being deployed itself has to be built into an archive file of some kind. JBoss ON allows JAR and ZIP formats. The bundle archive file can also include raw files that are used to configuration the application, such as XML, .conf, and text files. These can be templatized to supply user- and system-specific information (as described in Section 2.3.1, “Using Templatized Configuration Files”).
Any required archive or file must be referenced in the recipe so that the server knows to copy it during deployment.
The bundle files can be uploaded and stored in the JBoss ON server or they can be zipped up, with the recipe files, into a single distribution file.

2.3.4. Testing Bundle Packages

Ant recipes can be complex, so it's important (and useful) to test a bundle before deploying it. JBoss ON includes a command-line tool that can be used to test Ant provisioning bundles quickly.
2.3.4.1. Installing the Bundle Deployer Tool
This tool can be downloaded and installed on any machine, independent of any JBoss ON server or agent.
  1. Click the Administration tab in the top menu.
  2. Select the Downloads in the left menu table.
  3. Scroll to the Bundle Deployer Download section, and click the package download link.
  4. Save the .zip file into the directory where the bundle tool should be installed, such as /opt/.
  5. Unzip the packages.
    cd /opt/
    
    unzip rhq-bundle-deployer-version.zip
2.3.4.2. Using the Bundle Deployer Tool

IMPORTANT

This bundle deployment tool is only to test the provisioning process and deployed application. This tool does not interact with the JBoss ON server or agent, so JBoss ON is unaware of any applications deployed with this tool and cannot manage them.
  1. Unzip the bundle distribution package to check (or copy an unzipped directory that contains the application files). For example:
    mkdir /tmp/test-bundle
    cd /tmp/test-bundle
    unzip MyBundle.zip
  2. Open the top directory of the bundle distribution, where the deploy.xml Ant recipe file is.
  3. Set the bundle deployer tool location in the PATH.
    PATH="/opt/rhq-bundle-deployer-3.0.0/bin:$PATH"
  4. Run the bundle deploy tool, and use the format -Dinput_properties to pass the values to user-defined tokens in the templatized files. For example:
    rhq-ant -Drhq.deploy.dir=/opt/exampleApp -Dlistener.port=7081
    This installs the application in /opt/exampleApp and sets a port value of 7081.

    TIP

    Optionally, use the rhq.deploy.id attribute to set an identifier for the deployment. The default is 0, which means a new deployment. When bundles are deployed in the UI, the server assigns a unique ID to the deployment. Using the rhq.deploy.id attribute on a new deployment simulates the server's ID assignment.
    Using the rhq.deploy.id attribute if there is already a previous deployment allows you to test the upgrade performance of the bundle. Performing an upgrade requires a new, unique ID number.