7.7. A Reference of JBoss ON Ant Recipe Elements
7.7.1. rhq:bundle
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
<rhq:bundle name="example" version="1.0" description="an example bundle">
7.7.2. rhq:input-property
Note
<rhq:input-property>
definition.
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:
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
<rhq:input-property name="listener.port" description="This is where the product will listen for incoming messages" required="true" defaultValue="8080" type="integer"/>
7.7.3. rhq:deployment-unit
<rhq:deployment-unit>
element in a bundle recipe.
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.
/home/.rhqdeployments/
resourceID/backup
.
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
<rhq:deployment-unit name="appserver" preinstallTarget="preinstall" postinstallTarget="postinstall">
7.7.4. rhq:archive
Important Attribute Description Optional or Required name The filename of the archive file to include in the bundle.
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
<rhq:archive name="file.zip"> <rhq:replace> <rhq:fileset> <include name="**/*.properties"/> </rhq:fileset> </rhq:replace> </rhq:archive>
7.7.5. rhq:url-archive
rhq:archive
except that the server accesses the archive over the network rather than including the archive directly in the bundle distribution file.
Note Note 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.
Required exploded If true, the archive's contents will be extracted and stored into the bundle destination directory; if false, the zip file will be compressed and stored in the top level destination directory.
Optional
<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>
7.7.6. rhq:file
<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.
Important Note Attribute Description Optional or Required name The name of the raw configuration file.
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.
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.
name
attribute.
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
<rhq:file name="test-v2.properties" destinationFile="subdir/test.properties" replace="true"/>
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.
7.7.7. rhq:url-file
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.
Note Note Attribute Description Optional or Required url Gives the URL to the templatized file. The file is downloaded and installed in the deployment directory.
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.
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.
name
attribute.
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
<rhq:url-file url="http://server.example.com/apps/files/test.conf" destinationFile="subdir/test.properties" replace="true"/>
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.
7.7.8. rhq:audit
rhq:audit
configuration sends information to the server about the additional processing steps and their results.
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
<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>
7.7.9. rhq:replace
<rhq:fileset>
elements, contained in the archive which need to have token values realized when the archive is deployed.
<rhq:replace>
element.
<rhq:archive name="file.zip"> <rhq:replace> <rhq:fileset> <include name="**/*.properties"/> </rhq:fileset> </rhq:replace> </rhq:archive>
7.7.10. rhq:ignore
<rhq:replace>
, contains a list of files or directories in the instance to save.
Note
Important
/opt/myapp
and Bundle B to /opt/myapp/webapp1
).
<rhq:ignore> <rhq:fileset> <include name="logs/*.log"/> </rhq:fileset> </rhq:ignore>
7.7.11. rhq:fileset
<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 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.
<rhq:replace> <rhq:fileset> <include name="**/*.properties"/> </rhq:fileset> </rhq:replace>
7.7.12. rhq:system-service
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
<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"/>