{section}
{column}

h1. Introduction

Petals ESB provides support for managing the system using the scripting language [Apache Ant|http://ant.apache.org/]. 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.

{info}
Requirements to run this version of the Petals Ant tasks are:
* Java 17 or upper,
* Apache Ant 1.10.14 or upper,

{column}
{column:width=35%}
{panel:title=Table of contents}{toc:outline=true}{panel}
{panel:title=Contributors}{contributors:order=name|mode=list|showAnonymous=true|showCount=true|showLastTime=true}{panel}
{column}
{section}

h1. Petals ESB Ant tasks

h2. General

h3. 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.

{anchor:xmlOutput}
h3. Attribute {{xmlOutput}}

If the {{xmlOutput}} attribute is specified, the task must produce an XML document conforming to the following XML schema:
{code}
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 }*
}
{code}

If {{xmlOutput}} is not specified, an implementation-defined text format MUST be output. An example of such an output is below:
{code}
-----------------------------------------
------------ Service Engines ------------
-----------------------------------------
Name: Test_engine1
State: Started
Description: Test engine with shared library.

Name: ant_test_engine2
State: Shutdown
Description: Yet another test engine.
{code}

An Ant script to produce equivalent XML output, and the output itself is show in the next two listings.
{code}
<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}"/>
{code}
{code}
<?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>
{code}

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.

h2. 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 or URL. If an URL is set, it must be correctly encoded if needed. 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 |

{tip}
Maven URLs are supported by this task: {{<jbi-install-component file="mvn:org.ow2.petals/petals-se-xslt/LATEST/zip" />}}.
{tip}

h3. 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 |

h3. 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.

h3. Example

This example uses script-supplied parameters to provide the configuration data:
{code:xml}
<!-- 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>
{code}

Alternatively, an external file can be used to supply the configuration data:
{code}
<!-- 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
{code}

h2. 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 |

h2. 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 or URL. If an URL is set, it must be correctly encoded if needed. This file is a shared-library installation package. | | Yes |
| failOnError | Signal task failure to Ant. | {{true}} | No |

{tip}
Maven URLs are supported by this task: {{<jbi-shared-library file="mvn:org.ow2.petals/petals-sl-xalan-2.7.1/LATEST/zip" />}}.
{tip}

h2. Task {{jbi-uninstall-shared-library}}

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

{info}
This task is no more fully compliant with JBI specifications: the attribute {{version}} is required.
{info}

|| 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 |
| version | Version of the shared library in the Petals ESB container. | | Yes |
| failOnError | Signal task failure to Ant. | {{true}} | No |

h2. 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 |

h2. 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 |

h2. 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 |

h2. 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 or URL. If an URL is set, it must be correctly encoded if needed. The file should be packaged according to the JBI service assembly packaging. | | Yes |
| failOnError | Signal task failure to Ant. | {{true}} | No |
| failOnComponentError | To fail the task according to {{failOnError}} if an error occurs during interaction(s) with a component. | {{false}} | No |

{tip}
When trying to deploy a service-assembly containing two service-units whose the deployment fails for one service-unit:
* By default ({{failOnError=true}} and {{failOnComponentError=false}}), the task succeeds,
* If {{failOnError=true}}, the task will fail only if {{failOnComponentError=true}}.
{tip}

{tip}
Maven URLs are supported by this task: {{<jbi-deploy-service-assembly file="mvn:org.ow2.petals.samples/sa-xslt/LATEST/zip" />}}.
{tip}

h2. 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 |

h2. 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 |

h2. 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 |

h2. 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 |

h2. 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|#xmlOutput] above.

{info}
This task is no more fully compliant with JBI specifications: the attribute {{sharedLibraryVersion}} is required if the attribute {{sharedLibraryName}} is set.
{info}

|| 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 name. Without this parameter, no shared library dependency is verified. | | No, except if sharedLibraryVersion is given |
| sharedLibraryVersion | List the Engines that are dependent on the specified shared library version. Without this parameter, no shared library dependency is verified. | | No, except if sharedLibraryName is given |
| 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}}|#xmlOutput]. | | No |

h2. 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|#xmlOutput] above.

{info}
This task is no more fully compliant with JBI specifications: the attribute {{sharedLibraryVersion}} is required if the attribute {{sharedLibraryName}} is set.
{info}

|| 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 name. Without this parameter, no shared library dependency is verified. | | No, except if sharedLibraryVersion is given |
| sharedLibraryVersion | List the Engines that are dependent on the specified shared library version. Without this parameter, no shared library dependency is verified. | | No, except if sharedLibraryName is given |
| 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}}|#xmlOutput]. | | No |

h2. Task {{jbi-list-shared-libraries}}

This task prints information about all shared libraries installed in the Petals ESB container.

{info}
This task is no more compliant with JBI specifications:
* the attribute {{sharedLibraryVersion}} is introduced to list all shared libraries having a given version,
* the XML schema of the XML output is dedicated to this task.
{info}

|| 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 name doesn’t exist, an empty component-list report is given. | | No |
| sharedLibraryVersion | If supplied, only the version named shared library is reported. If the shared library version 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. | | 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.
{code}
default namespace = "http://java.sun.com/xml/ns/jbi/shared-library-info-list"
start = element shared-library-info-list {
# version = "1.0" in this revision
attribute version { xsd:decimal },
shared-library-info*
}

shared-library-info =
element shared-library-info {
attribute name { text },
attribute version { text },
element description { text },
element* -this:* { text }*
}
{code}

This schema is used as follows:
* *shared-library-info* contains information about a single shared library. It contains:
** *name*, *version*. The unique shared library identifier composed of name and version, as supplied by its installation descriptor.
** *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.

h2. 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.
{code}
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 }*
}
{code}

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.

h1. Ant tasks relative to MONIT traces

h2. Task {{petals-monit-read-logfiles}}

This task reads your log files containing MONIT traces. MONIT traces are loaded in an internal object through a reference.

|| Attribute || Description || Default ||Required ? ||
| dir | The root directory of MONIT log files to load. | - | Yes, if no nested element '{{dirset}}' is given. |
| id | Reference name of the internal object associated to MONIT traces loaded. | - | Yes |
| failOnError | If {{false}}, the Ant task will never fail even if an error occurs parsing MONIT traces | true | No |

h3. Nested elements

h4. Root directories of MONIT log files: {{dirset}}

The nested element {{<dirset>}} is used to select several root directories to read. The {{dir}} attribute must not be set. More information on attributes of {{dirset}} here: https://ant.apache.org/manual/Types/dirset.html

h2. Task {{petals-extract-flow-step-info}}

This task extracts informations as property from previously loaded MONIT traces. This task is used in association with the task '{{petals-monit-read-logfiles}}' to load MONIT traces. Before to extract information from a flow step, it must be selected using search criteria provided as nested elements.

|| Attribute || Description || Default ||Required ? ||
| refid | Reference name of the internal object associated to MONIT traces loaded. | - | Yes |
| row | Index of the wanted flow step in all flow steps matching criterias | - | Yes, if criteria return more than one flow step. Exclusif with '{{selectRandomly}}'. |
| selectRandomly | If the given criteria match several flow step, one flow step will be selected randomly if this flag is set to '{{true}}'. | false | Yes, if criteria return more than one flow step. Exclusif with '{{row}}'. |

h3. Nested elements

h4. Search criteria: {{flowStepCriteria}}

A search criteria operates as a filter on properties of a flow step. Flow steps for which a property with the given name '{{name}}` has the value given by '{{value}}' are selected.

h4. Flow step information extracted: {{flowStepInfo}}

The property given by its name '{{name}}' is retrieved from the flow step and put into the property with the given name '{{property}}.

h3. Example

{code}
<petals-monit-read-logfiles id="flows" dir="${petals.home}/logs/flow-monitoring" />
<petals-extract-flow-step-info refid="flows">
<flowStepCriteria name="traceCode" value="provideFlowStepBegin" />
<flowStepCriteria name="flowStepInterfaceName" value="{http://petals.ow2.org/samples/se-bpmn/vacationService}vacation" />
<flowStepCriteria name="flowStepOperationName" value="{http://petals.ow2.org/samples/se-bpmn/vacationService}new" />
<flowStepInfo attribute="flowInstanceId" property="initial-flow-instance-id" />
<flowStepInfo attribute="flowStepId" property="initial-flow-step-id" />
</petals-extract-flow-step-info>
<petals-extract-flow-step-info refid="flows">
<flowStepCriteria name="traceCode" value="consumeFlowStepBegin" />
<flowStepCriteria name="correlatedFlowInstanceId" value="${initial-flow-instance-id}" />
<flowStepCriteria name="correlatedFlowStepId" value="${initial-flow-step-id}" />
<flowStepCriteria name="processDefinition" value="vacationRequest" />
<flowStepInfo attribute="flowInstanceId" property="process-instance-flow-instance-id" />
</petals-extract-flow-step-info>
<petals-extract-flow-step-info refid="flows" row="0">
<flowStepCriteria name="traceCode" value="provideFlowStepBegin" />
<flowStepCriteria name="flowStepInterfaceName" value="{http://petals.ow2.org/samples/se-bpmn/vacationService}vacation" />
<flowStepCriteria name="flowStepOperationName" value="{http://petals.ow2.org/samples/se-bpmn/vacationService}validate" />
<flowStepInfo attribute="flowInstanceId" property="validation-flow-instance-id" />
<flowStepInfo attribute="flowStepId" property="validation-flow-step-id" />
</petals-extract-flow-step-info>
{code}

h2. Task {{petals-assert-flow-instance}}

This task applies the given assertions as nested elements to the given flow instance previously read MONIT traces. This task is used in association with the task '{{petals-monit-read-logfiles}}' to load MONIT traces.

|| Attribute || Description || Default ||Required ? ||
| refid | Reference name of the internal object associated to MONIT traces loaded. | - | Yes |
| flowInstanceId | The flow instance identifier on which the given assertions must be validated | - | Yes |

h3. Nested elements

h4. Assertions to apply on a flow step of the flow instance: {{assertFlowStep}}

For the flow step identified by its index '{{flowStepIdx}}'' in the given flow instance:
* the assertions given as nested elements will be executed,
* a check is automatically applied on ending trace to validate its ending status (success or error) according to the attribute '{{endsWithError}}': if '{{true}}', the flow step must end with failure; if '{{false}}' or absent, the flow step must end successfully.
* and, if needed, information can be extracted using '{{flowStepInfo}}'.

Available assertions on a flow step are relative to its attributes:
* '{{attributeEquals}}': the actual value of the property identifier by '{{name}}' must be equals to the value given by '{{value}}',
* '{{attributeSet}}': the flow step must contain a property named '{{name}}'.
By default, assertion operates on attributes available on the beginning MONIT traces. Using '{{onEnd="true"}}' will force to use properties of the ending MONIT traces.

Extracted information from a flow step assertion block are available for next flow step assertion blocks.

h3. Example

{code}
<petals-monit-read-logfiles id="flows" dir="${petals.home}/logs/flow-monitoring" />
<petals-assert-flow-instance refid="flows" flowInstanceId="${process-instance-flow-instance-id}">
<assertFlowStep flowStepIdx="0">
<attributeEquals name="traceCode" value="consumeFlowStepBegin" />
<attributeEquals name="correlatedFlowInstanceId" value="${initial-flow-instance-id}" />
<attributeEquals name="correlatedFlowStepId" value="${initial-flow-step-id}" />
<attributeEquals name="processDefinition" value="vacationRequest" />
<attributeSet name="processInstanceId" />
<flowStepInfo attribute="flowStepId" property="flowStep.0.id" />
</assertFlowStep>
<assertFlowStep flowStepIdx="1">
<attributeEquals name="traceCode" value="provideFlowStepBegin" />
<attributeEquals name="flowStepInterfaceName" value="{http://petals.ow2.org/samples/se-bpmn/notifyVacationService}notifyVacation" />
<attributeEquals name="flowStepServiceName" value="{http://petals.ow2.org/samples/se-bpmn/notifyVacationService}notifyVacationService" />
<attributeEquals name="flowStepOperationName" value="{http://petals.ow2.org/samples/se-bpmn/notifyVacationService}newVacationRequest" />
<attributeSet name="flowStepEndpointName" />
<attributeEquals name="flowPreviousStepId" value="${flowStep.0.id}" />
</assertFlowStep>
<assertFlowStep flowStepIdx="3" endsWithError="false">
<attributeEquals name="traceCode" value="provideFlowStepBegin" />
<attributeEquals name="flowPreviousStepId" value="${flowStep.0.id}" />
<attributeEquals name="taskDefinition" value="handleVacationRequest" />
<attributeEquals onEnd="true" name="correlatedFlowInstanceId" value="${validation-flow-instance-id}" />
<attributeEquals onEnd="true" name="correlatedFlowStepId" value="${validation-flow-step-id}" />
</assertFlowStep>
</petals-assert-flow-instance>
{code}

h2. Task {{petals-monit-build-flow-trees}}

This task builds flow trees from flow instances read through the Ant task '{{petals-monit-read-logfiles}}'. Flow trees are stored in an internal object through a reference.

|| Attribute || Description || Default ||Required ? ||
| refid | Reference name of the internal object associated to MONIT traces previously loaded. | - | Yes |
| id | Reference name of the internal object associated to flow trees built. | - | Yes |
| failOnError | If {{false}}, the Ant task will never fail even if an error occurs building flow trees | true | No |

h3. Example

{code}
<petals-monit-read-logfiles id="flows" dir="${petals.home}/logs/flow-monitoring" />
<petals-monit-build-flow-trees refid="flows" id="flow-trees" />
{code}

h2. Task {{petals-assert-flow-trees}}

This task applies the given assertions to the given flow trees previously built with the task '{{petals-monit-build-flow-trees}}'.

|| Attribute || Description || Default ||Required ? ||
| refid | Reference name of the internal object associated to flow trees previously built. | - | Yes |
| assertsizeequals | Assertion against the number of flow trees built equals to the value of this parameter). | - | No |
| assertsizeupperorequals | Assertion against the number of flow trees built upper or equals to the value of this parameter). | - | No |

h3. Example

{code}
<petals-monit-read-logfiles id="flows" dir="${petals.home}/logs/flow-monitoring" />
<petals-monit-build-flow-trees refid="flows" id="flow-trees" />
<petals-assert-flow-trees refid="flow-trees" assertsizeequals="${expected-flow-tree-number}" />
{code}

h2. Task {{petals-assert-flow-tree}}

This task applies the given assertions as nested elements to the given flow tree previously built from MONIT traces through the Ant task '{{petals-monit-build-flow-trees}}'.

|| Attribute || Description || Default ||Required ? ||
| refid | Reference name of the internal object associated to flow trees previously built. | - | Yes |
| flowInstanceId | The identifier of the flow instance to use as root of the flow tree on which the given assertions must be validated | - | Yes |

h3. Nested elements

h4. Assertions to apply on a flow tree node of the selected flow tree: {{assertFlowTreeNode}}

For the flow tree node identified by its path '{{path}}'' from the flow tree root, the assertions given as nested elements will be executed. {{path}} is an expression matching the pattern {{x.y.t...z}}, as following:
* {{x}}, {{y}}, {{t}} and {{z}} are positive integer numbers starting at {{0}} and separated by '{{.}}',
* an empty value (ie. {{""}}): select the root node of the selected flow tree,
* {{"0"}}: select the 1st child of the root node of the selected flow tree,
* {{"1"}}: select the 2nd child of the root node of the selected flow tree,
* {{"2.5"}}: select the 5th child of the 3rd child of the root node of the selected flow tree.

Available assertions on a flow tree node are:
* '{{flowInstanceIdEquals}}': the flow instance identifier of the flow tree node identified by {{path}} must be equals to the value given by '{{expected}}'.

h3. Example

{code}
<petals-monit-read-logfiles id="flows" dir="${petals.home}/logs/flow-monitoring" />
<petals-monit-build-flow-trees refid="flows" id="flow-trees" />
<petals-extract-flow-step-info refid="flows" row="0">
<flowStepCriteria name="traceCode" value="provideFlowStepBegin" />
<flowStepCriteria name="flowStepInterfaceName" value="{http://petals.ow2.org/samples/se-bpmn/vacationService}vacation" />
<flowStepCriteria name="flowStepServiceName" value="{http://petals.ow2.org/samples/se-bpmn/vacationService}vacationService" />
<flowStepCriteria name="flowStepOperationName" value="{http://petals.ow2.org/samples/se-bpmn/vacationService}new" />
<flowStepInfo attribute="flowInstanceId" property="initial-flow-instance-id" />
<flowStepInfo attribute="flowStepId" property="initial-flow-step-id" />
</petals-extract-flow-step-info>
<petals-extract-flow-step-info refid="flows" row="0">
<flowStepCriteria name="traceCode" value="consumeExtFlowStepBegin" />
<flowStepCriteria name="correlatedFlowInstanceId" value="${initial-flow-instance-id}" />
<flowStepCriteria name="correlatedFlowStepId" value="${initial-flow-step-id}" />
<flowStepInfo attribute="flowInstanceId" property="process-flow-instance-id" />
</petals-extract-flow-step-info>
<petals-assert-flow-tree refid="flow-trees" flowInstanceId="${initial-flow-instance-id}">
<assertFlowTreeNode path="">
<flowInstanceIdEquals expected="${initial-flow-instance-id}" />
</assertFlowTreeNode>
<assertFlowTreeNode path="0">
<flowInstanceIdEquals expected="${process-flow-instance-id}" />
</assertFlowTreeNode>
</petals-assert-flow-tree>
{code}

h1. Petals ESB Ant conditions

h2. Condition {{hasEndpointDeployed}}

The condition '{{hasEndpointDeployed}}' retrieve the endpoints matching criteria, and compare the number of these endpoints with an expected number. If they are equals, the condition is validated.

|| Attribute || Description || Default ||Required ? ||
| {{host}} | the hostname of a Petals container | {{localhost}} | No |
| {{port}} | JMX port of the Petals container | {{7700}} | No |
| {{username}} | JMX username of the Petals container | - | No |
| {{password}} | JMX password of the Petals container | - | No |
| {{interfaceName}} | interface name that the endpoints should match, or {{null}} if any interface is accepted | {{null}} | No |
| {{serviceName}} | service name that the endpoints should match, or {{null}} if any service is accepted | {{null}} | No |
| {{endpointName}} | endpoint name that the endpoints should match, or {{null}} if any endpoint name is accepted | {{null}} | No |
| {{expectedNumber}} | the number of endpoints matching criteria that should be found to validate the condition | 1 | No |

h3. Example

{code}
<waitfor maxwait="30"
maxwaitunit="second"
checkevery="5"
checkeveryunit="second"
timeoutproperty="endpointsPropagationFailed">
<and>
<hasEndpointDeployed host="${container.0.host}"
port="${container.0.jmx-port}"
username="${container.0.username}"
password="${container.0.password}"
interfaceName="{http://petals.ow2.org/}HelloWorldService"
serviceName="{http://petals.ow2.org/}HelloWorldService"
expectedNumber="4" />
<hasEndpointDeployed host="${container.1.0.host}"
port="${container.1.0.jmx-port}"
username="${container.1.0.username}"
password="${container.1.0.password}"
interfaceName="{http://petals.ow2.org/}HelloWorldService"
serviceName="{http://petals.ow2.org/}HelloWorldService"
expectedNumber="4" />
</and>
</waitfor>
{code}

h2. Condition {{isResponseTimeMetricAvailable}}

The condition '{{isResponseTimeMetricAvailable}}' verifies that response time metrics are available for the given component.

|| Attribute || Description || Default ||Required ? ||
| {{host}} | the hostname of a Petals container | {{localhost}} | No |
| {{port}} | JMX port of the Petals container | {{7700}} | No |
| {{username}} | JMX username of the Petals container | - | No |
| {{password}} | JMX password of the Petals container | - | No |
| {{componentName}} | the component identifier for which we want verify that response time metrics are available | - | Yes |

h3. Example

{code}
<waitfor maxwait="${monitoring-sampling-period}"
maxwaitunit="second"
checkevery="1"
checkeveryunit="second"
timeoutproperty="metricsNotAvailable">
<isResponseTimeMetricAvailable componentName="${bc-soap-name}" />
</waitfor>
{code}