Custom Bundle Ant Tasks

In order for Ant bundles to properly be processed, both on the server and agent, they must use certain RHQ custom Ant tasks. These Ant tasks serve two purposes:

They define the behavior of the bundle provisioning (i.e. the typical Ant script usage)
The provide static metadata about the bundle content (i.e. things like bundle name, version, etc)

Because RHQ will be using ANT for more than just builds/scripting, calling these ANT xml files "scripts" may not be fully appropriate. The current RHQ term is "recipe" which, although not 100% ideal due to the connotation "recipe" has with Puppet, it does convey there is more to these ANT "scripts" than just a way to execute a set of tasks on a machine to build/deploy things. These "recipes" also contain metadata and a "model" for what the bundle consists of and how it should be defined.

Below are some prototypes for the ANT tasks.

Task Naming Convention
All RHQ Bundle ANT tasks will:

have task names that start with the XML namespace prefix "rhq:" to distinguish them from other Ant tasks.
have task names that are camelCase (e.g. <rhq:taskName>)
have attribute names that are camelCase (e.g. <rhq:taskName someAttributeName="value">)

Source Code
The source code for the Ant tasks are currently in modules/common/ant-bundle in the package org.rhq.bundle.ant.task.

rhq:bundle

This defines some metadata about the bundle itself. This effectively defines (in the RHQ venacular) the "BundleVersion". Notice you can also predefine tags for the bundle version. This is optional and we may not support this in the first implementation. See Design - Tagging.

<rhq:bundle name="bundleName" version="1.0" description="blah blah blah">
   <rhq:tag name="app:status=untested" />
</rhq:bundle>

I think there should only be one <rhq-bundle> tag in any bundle ANT script. If we detect more than one, we need to error out.

rhq:inputProperty

These define basic properties that the user must provide in order for the bundle to be properly provisioned. If the deployment script is invoked from the GUI, the user will be prompted for values for these properties. If the script is invoked from the command line, the properties must be passed using -D and/or -propertyfile.

<rhq:inputProperty
   name="listener.port"
   description="This is where the product will listen for incoming messages"
   required="true"
   defaultValue="8080"
   type="integer">
</rhq:inputProperty>

Note that these attributes mimic some of those in the configuration definition <simple-property> definitions. These will be used when creating the bundle version ConfigurationDefinition.

There can be 0, 1 or more rhq:inputProperty defined, and they can be defined outside of any rhq:deploy (see below) because these are nothing more than properties under the covers (like the normal ANT <property> tag).

rhq:deploy

This is a biggie. It defines a major deployment that needs to be provisioned. You define 0, 1 or more files that need to be provisions, the files that need to have replacement variables replaced, etc. I think these are going to be our BundleDeployment objects.

<rhq:deploy>
   <rhq:requires>
      <rhq:port value="8080" />
      <rhq:disk-space value="20000000" />
   </rhq:requires>
   <rhq:archive name="jboss-as.zip"
                overwrite="false" /> <!-- I am not sure how we use this -->
   <rhq:file name="control-script.sh"
             destinationDir="/etc/init.d"
             overwrite="true" />
   <rhq:replace file="/etc/init.d/control-script.sh" />
   <rhq:replace file="conf/jboss-service.xml />
   <rhq:ignore location="logs/**" />
</rhq:deploy>

The rhq:file type defines what BundleFile content needs to be provided by the user (these are file uploaded for example).
The rhq:replace type defines what files (after they are laid down on the filesystem) need to have their replacement variables replaced.
The rhq:ignore type defines which files should be ignored when RHQ processes them (for example, ignore everything under the logs dir when comparing if one bundle distro is the same as another).
The rhq:requires has subtags that provide information about what the running product requires - such as a port must be available or the amount of disk space it needs. We won't implement this for now.

Service Management

We might need something that allows us to start, stop and check status of a running service.

rhq-bundle-answers.properties

We need to figure out when, where and how to create and pass a .properties file that contains answers to the bundle questions.

Standalone Ant Launcher

We need to build a standalone jar that can run our bundle ANT recipes without having to go through the entire RHQ GUI workflow. This will allow people to write and test their scripts quickly and easily. This is partly why we need to consider having a rhq-bundle-answers.properties file so we can pass that into the standalone launcher.

Examples

Customized JBoss EAP Install

<?xml version="1.0"?>

<project name="example.com-website" default="deploy" 
         xmlns:rhq="antlib:org.rhq.bundle">    

    <rhq:bundle name="example.com (JBoss EAP 4.3)" version="1.2"
                description="example.com corporate website hosted on JBoss EAP 4.3"/>

    <rhq:inputProperty
       name="http.port"
       description="the HTTP port the JBoss EAP server should listen on"
       required="true"
       type="integer"/>    
    
    <target name="deploy">
        <echo>Deploying example.com website v1.2 to ${rhq.deploy.dir}...</echo>
        <rhq:deploy>
            <rhq:archive name="jboss-eap-4.3.0.GA_CP12.zip"/>
            <rhq:file name="jboss-init.sh" destinationFile="/sbin/init.d/jboss"/>            
            <rhq:replace>
                <!-- If no 'dir' attribute is specified, rhq:fileset defaults to ${rhq.deploy.dir}. -->
                <rhq:fileset includes="jbossas/server/default/conf/jboss-service.xml"/>
            </rhq:replace>
            <rhq:ignore>
                <rhq:fileset>
                   <include name="jbossas/server/default/data/**"/>
                   <include name="jbossas/server/default/logs/**"/>
                   <include name="jbossas/server/default/tmp/**"/>
                   <include name="jbossas/server/default/work/**"/>
                </rhq:fileset>
            </rhq:ignore>
        </rhq:deploy>        
    </target>

</project>

Design-Bundle Ant Tasks