Petals Documentation > Petals ESB > Petals Components > Petals ANT Tasks > Petals ANT Tasks 2.4.0+

Petals ANT Tasks 2.4.0+

Introduction

Petals ESB provides support for managing the system using the scripting language Apache Ant 1.5 (or newer). This section details the mapping of the management functions provided through JMX management beans to Ant tasks.

Ant scripts are written using XML. Each task is defined syntactically as named XML attributes and XML elements. Each task defines an element; nested elements are contained within the task element.

Writers of Ant scripts should promote portability of such scripts by supplying necessary Ant task parameters explicitly, rather than depend on implementation-specific default values. Parameterization of scripts, using Ant properties, is a good practice.

This documentation is a part of the JBI specifications.
Table of contents
Contributors
No contributors found for: authors on selected page(s)

General

Error Suppression

All Petals ESB Ant tasks include an optional attribute, “failOnError”, which defaults to true. If this attribute’s
value is false, the task will never fail even if an error occurs during the Ant task execution.

Attribute xmlOutput

If the xmlOutput attribute is specified, the task must produce an XML document conforming to the following XML schema:

default namespace = "http://java.sun.com/xml/ns/jbi/component-info-list"
   start = element component-info-list {
   # version = "1.0" in this revision
   attribute version { xsd:decimal },
   component-info*
   }

   component-info =
   element component-info {
      attribute type { "service-engine" | "binding-component" | "shared-library" },
      attribute name { text },
      attribute state { "Shutdown" | "Started" | "Stopped" | "Unknown" },
      element description { text },
      element* -this:* { text }*
   }

If xmlOutput is not specified, an implementation-defined text format MUST be output. An example of such an output is below:

-----------------------------------------
------------ Service Engines ------------
-----------------------------------------
Name:        Test_engine1
State:       Started
Description: Test engine with shared library.

Name:        ant_test_engine2
State:       Shutdown
Description: Yet another test engine.

An Ant script to produce equivalent XML output, and the output itself is show in the next two listings.

<jbi-list-service-engines xmlOutput="jbi.output"/>
<!-- The value of the property ${jbi.output} contains the XML output of the task. -->
<!-- The user can acccess the XML text using the property value. For instance: -->
<echo message="${jbi.output}"/>

<?xml version="1.0" encoding="utf-8"?>
<component-info-list xmlns="http://java.sun.com/xml/ns/jbi/component-info-list" version="1.0">
   <component-info type="service-engine" name="Test_engine1" state="Started">
      <description>Test engine with shared library.</description>
   </component-info>
   <component-info type="service-engine" name="ant_test_engine2" state="Shutdown">
      <description>Yet another test engine.</description>
   </component-info>
</component-info-list>

The schema is used as follows:

  • component-info contains information about a single component. It contains:
    • type. This indicates the component type.
    • name. The unique component name, as supplied by its installation descriptor.
    • state. The execution state of the component. Note that extension states are substates of the “Started” state, and that if the component is in an extended state it will show as “started” in this attribute.
    • description. The description of the component, as supplied by its installation descriptor.
    • optional extension elements. This area allows the implementation to provide extra, implementation-specific component information.

Petals ESB Ant tasks

Task jbi-install-component

This task installs a JBI component (a service engine or binding component) into a Petals ESB container. The installation process provided by this task load and install the component. This task takes optional installation configuration parameters as name/value pairs for setting the attributes of the InstallerConfigurationMBean during the installation. The task takes the configuration parameters as
optional nested <param> elements, or using an optional params attribute if the parameters are in a file.

Attribute Description Default Required ?
host Target Petals ESB container. localhost No
port JMX Remote port on the target server. 7700 No
username User name for security. "" No
password Password for security. "" No
file Fully qualified installation file path name. The file contains a component installation package.   Yes
failOnError Signal task failure to Ant. true No
params Location of a text file (e.g. configuration.properties) that contains name/value pairs corresponding to the properties of the configuration MBean.   No

Nested element <param>

This nested element is an optional child element containing an installation configuration parameter which will be passed to the install task. Multiple parameters require multiple <param> elements, one per parameter. This element takes a name/value pair for setting the property of the InstallerConfigurationMBean implemented by the installer of the component.
Note that the attribute name value is case sensitive. For example, if the configuration MBean has a attribute Foo as a “setFoo” not as a “setfoo”, then the name attribute value for the param element must be “Foo”. Passing the name attribute value as “foo” will result in a property not found error.

Attribute Description Default Required ?
name Name of the property on the InstallerConfigurationMBean. Note that the attribute name is case sensitive. For example, if the ConfigurationMBean has a attribute Foo as a “setFoo” not as a “setfoo”, then the name attribute for the param element should be “Foo”. Passing the name attribute as “foo” will result in a property not found error.   Yes
value Value of the property to be set.   Yes

Attribute params

This attribute is optional, indicating the location of a file containing installation configuration parameters which will be passed to the install task. This attribute specifies the location of a file that contains a set of name/value pairs corresponding to the attributes of the InstallerConfigurationMBean implemented by the Bootstrap implementation of the component. The Ant task read the indicated file as a java.util.Properties file, and use each named property to set equivalent attributes of the installer extension MBean.
If the jbi-install-component element contains a <param> child element, as well as a params attribute, the Ant task combine the two parameter lists, giving precedence to those defined in the properties file indicated by the params attribute. This precedence rule allows tools to generate properties files that can customize standard Ant scripts for performing installation of components.

Example

This example uses script-supplied parameters to provide the configuration data:

<!-- install component -->
<jbi-install-component host = "localhost" port="7890" file = "${my.dev.dir.path}/bpel-engine.zip" />
   <param name="Foo1" value="bar1" />
   <param name="Foo2" value="bar2" />
</jbi-install-component>

Alternatively, an external file can be used to supply the configuration data:

<!-- install component -->
<jbi-install-component file="dir/component.zip" params="dir/params.properties" port="555"/>
where the contents of the dir/params.properties file are:
Foo1=bar1
Foo2=bar2

Task jbi-uninstall-component

This task uninstalls a previously installed JBI component (service engine or binding) from the Petals ESB container.

Attribute Description Default Required ?
host Target Petals ESB container. localhost No
port JMX Remote port on the target server. 7700 No
username User name for security. "" No
password Password for security. "" No
name Name of the JBI component in the Petals ESB container. This is the unique name specified in the component’s installation descriptor.   Yes
failOnError Signal task failure to Ant. true No

Task jbi-install-shared-library

This task installs a shared library into a Petals ESB container.

Attribute Description Default Required ?
host Target Petals ESB container. localhost No
port JMX Remote port on the target server. 7700 No
username User name for security. "" No
password Password for security. "" No
file Shared library installation file path/name. This file is a shared-library installation package.   Yes
failOnError Signal task failure to Ant. true No

Task jbi-uninstall-shared-library

This task uninstalls a previously installed share library from a JBI environment.

Attribute Description Default Required ?
host Target Petals ESB container. localhost No
port JMX Remote port on the target server. 7700 No
username User name for security. "" No
password Password for security. "" No
name Name of the shared library in the Petals ESB container.   Yes
failOnError Signal task failure to Ant. true No

Task jbi-start-component

This task starts a particular JBI component (service engine or binding component) in a Petals ESB container.

Attribute Description Default Required ?
host Target Petals ESB container. localhost No
port JMX Remote port on the target server. 7700 No
username User name for security. "" No
password Password for security. "" No
name Name of the JBI component in the Petals ESB container to start.   Yes
failOnError Signal task failure to Ant. true No

Task jbi-stop-component

This task stops a particular JBI component (service engine or binding component) in the Petals ESB container.

Attribute Description Default Required ?
host Target Petals ESB container. localhost No
port JMX Remote port on the target server. 7700 No
username User name for security. "" No
password Password for security. "" No
name Name of the JBI component in the Petals ESB container to stop.   Yes
failOnError Signal task failure to Ant. true No

Task jbi-shut-down-component

This task shuts down a particular JBI component (service engine or binding component) in a Petals ESB container.

Attribute Description Default Required ?
host Target Petals ESB container. localhost No
port JMX Remote port on the target server. 7700 No
username User name for security. "" No
password Password for security. "" No
name Name of the JBI component in the Petals ESB container to shutdown.   Yes
failOnError Signal task failure to Ant. true No

Task jbi-deploy-service-assembly

This task deploys a service assembly into a Petals ESB container.

Attribute Description Default Required ?
host Target Petals ESB container. localhost No
port JMX Remote port on the target server. 7700 No
username User name for security. "" No
password Password for security. "" No
file Fully qualified service assembly file path. The file should be packaged according to the JBI service assembly packaging.   Yes
failOnError Signal task failure to Ant. true No

Task jbi-undeploy-service-assembly

This task undeploys a previously deployed service assembly from a Petals ESB container.

Attribute Description Default Required ?
host Target Petals ESB container. localhost No
port JMX Remote port on the target server. 7700 No
username User name for security. "" No
password Password for security. "" No
name Name of the service assembly that is in the Petals ESB container.   Yes
failOnError Signal task failure to Ant. true No

Task jbi-start-service-assembly

This task starts a particular service assembly in a Petals ESB container. The attributes for this task are listed below:

Attribute Description Default Required ?
host Target Petals ESB container. localhost No
port JMX Remote port on the target server. 7700 No
username User name for security. "" No
password Password for security. "" No
name Name of the service assembly that is in the Petals ESB container.   Yes
failOnError Signal task failure to Ant. true No

Task jbi-stop-service-assembly

This task stops a particular service assembly in a Petals ESB container. The attributes for this task are listed below:

Attribute Description Default Required ?
host Target Petals ESB container. localhost No
port JMX Remote port on the target server. 7700 No
username User name for security. "" No
password Password for security. "" No
name Name of the service assembly that is in the Petals ESB container.   Yes
failOnError Signal task failure to Ant. true No

Task jbi-shut-down-service-assembly

This task shuts down a particular service assembly in a Petals ESB container. The attributes for this task are listed below:

Attribute Description Default Required ?
host Target Petals ESB container. localhost No
port JMX Remote port on the target server. 7700 No
username User name for security. "" No
password Password for security. "" No
name Name of the service assembly that is in the Petals ESB container.   Yes
failOnError Signal task failure to Ant. true No

Task jbi-list-service-engines

This task prints information about all of the Service Engines in a Petals ESB container. The attributes for this task
are listed below. When the xmlOutput attribute value is specified, the format of the output is conform to the schema described here above.

Attribute Description Default Required ?
host Target Petals ESB container. localhost No
port JMX Remote port on the target server. 7700 No
username User name for security. "" No
password Password for security. "" No
state Lists the Engines that are in the specified state. Without this parameter, list engines with all states. Valid states are: “shutdown”, “started”, “stopped” (not case sensitive)   No
sharedLibraryName List the Engines that are dependent on the specified shared library Without this parameter, no shared library dependency is verified.   No
serviceAssemblyName List the Engines that have Service Units deployed to them as part of the Service Assembly deployed in the Petals ESB contaienr. Without this parameter, no Service Assembly dependency is verified.   No
serviceEngineName If supplied, only the named service engine is reported. If the engine doesn’t exist, an empty component-list report is given.   No
failOnError Signal task failure to Ant. true No
xmlOutput If supplied, set the given Ant property name value to the XML version of this listing task. See Attribute xmlOutput.   No

Task jbi-list-binding-components

This task prints information about the binding components installed in a Petals ESB container. When the xmlOutput attribute value is specified, the format of the output is conform to the schema described here above.

Attribute Description Default Required ?
host Target Petals ESB container. localhost No
port JMX Remote port on the target server. 7700 No
username User name for security. "" No
password Password for security. "" No
state Lists the Engines that are in the specified state. Without this parameter, list engines with all states. Valid states are: “shutdown”, “started”, “stopped” (not case sensitive)   No
sharedLibraryName List the Engines that are dependent on the specified shared library Without this parameter, no shared library dependency is verified.   No
serviceAssemblyName List the Engines that have Service Units deployed to them as part of the Service Assembly deployed in the Petals ESB contaienr. Without this parameter, no Service Assembly dependency is verified.   No
bindingComponentName If supplied, only the named binding component is reported. If the binding doesn’t exist, an empty component-list report is given.   No
failOnError Signal task failure to Ant. true No
xmlOutput If supplied, set the given Ant property name value to the XML version of this listing task. See Attribute xmlOutput.   No

Task jbi-list-shared-libraries

This task prints information about all shared libraries installed in the Petals ESB container. When the xmlOutput attribute value is specified, the format of the output is conform to the schema described here above.

Attribute Description Default Required ?
host Target Petals ESB container. localhost No
port JMX Remote port on the target server. 7700 No
username User name for security. "" No
password Password for security. "" No
componentName List the shared libraries that the component depends on. Without this parameter, all the shared libraries in the Petals ESB container are displayed.   No
sharedLibraryName If supplied, only the named shared library is reported. If the shared library doesn’t exist, an empty component-list report is given.   No
failOnError Signal task failure to Ant. true No
xmlOutput If supplied, set the given Ant property name value to the XML version of this listing task. See Attribute xmlOutput.   No

Task jbi-list-service-assemblies

This task prints information about service assemblies deployed in a JBI environment.

Attribute Description Default Required ?
host Target Petals ESB container. localhost No
port JMX Remote port on the target server. 7700 No
username User name for security. "" No
password Password for security. "" No
state Lists the service assemblies that are in the specified state.With out this parameter, list service assemblies with all states. Valid states are: “shutdown”, “started”, “stopped” (not case sensitive)   No
componentName List the service assemblies that has service units deployed to this component. Without this parameter, all the service assemblies that are deployed in the Petals ESB container will be displayed.   No
serviceAssemblyName If supplied, only the named service assembly is reported. If the service assembly doesn’t exist, an empty service-assembly-list is reported.   No
failOnError Signal task failure to Ant. true No
xmlOutput If supplied, set the given Ant property name value to the XML version of this listing task.   No

If the value of the xmlOutput attribute of the task is specified, the format of the output is conform to the schema described below. If xmlOutput is not supplied, the format is free.

default namespace = "http://java.sun.com/xml/ns/jbi/service-assembly-info-list"
start = element service-assembly-info-list {
  # version is 1.0 in this revision of JBI
  attribute version { xsd:decimal },
  service-assembly-info*
  }

service-assembly-info =
  element service-assembly-info {
    attribute name { text },
    attribute state { "Started" | "Stopped" | "Shutdown" | "Unknown" },
    element description { text },
    service-unit-info+,
    element* -this:* { text }*
  }

service-unit-info =
  element service-unit-info {
    attribute name { text },
    attribute state { "Started" | "Stopped" | "Shutdown" | "Unknown" },
    attribute deployed-on { text },
    element description { text },
    element* -this:* { text }*
  }

This schema is used as follows:

  • service-assembly-info-list. This contains a list of information elements about zero or more service
    assemblies, as returned by the query task invoked.
  • service-assembly-info. This element contains information about a particular service assembly, including
    the service units which constitute the service assembly.
    • name. The unique name of the service assembly, as assigned by the service assembly’s deployment
      descriptor.
    • state. The execution state of the service assembly.
    • description. The description of the service assembly, as given in the service assembly’s deployment
      descriptor.
    • service unit information. Information about all of the service units that are contained in the service unit
      described.
    • extension elements. Optional, implementation-specific information about the service assembly.
  • service-unit-info contains information about a particular service unit, which is part of the service assembly
    described by the XML element within which it is contained.
    • name. The name of the service unit, as assigned by the service assembly’s deployment descriptor.
    • state. The execution state of the service unit.
    • deployed-on. The unique name of the component to which the service unit was deployed.
    • description. The description of the service unit, as given in the service assembly’s deployment
      descriptor.
    • extension elements. Optional, implementation-specific information about the service unit.
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.