{section}
{column}
{multi-excerpt-include:Petals-SE-Activity|name=features|nopanel=true}
{column}
{column:width=350px}
{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. Creating a service-unit for a process definition
h2. Creating the service contract
The SE Activity provides a service with several operation for a process definition. A WSDL is associated to this service. This WSDL wan be written freely. The user can use its own namespace, its own names, ... It is only constraint by the following rules:
* the operations of the port type *are annotated* to link them to the supported operations (create an instance of the process definition, complete the current task of the process instance, ...)
* the mandatory parameters of the operation *are annotated* to retrieve the right values.
h3. Identifying operations
h4. Create an instance of a process definition
Because operation in WSDL 1.1 does not allow attribute extensibility, an operation is annotated by adding an {{operationAttr}} element as a child of the operation element. The {{operation}} attribute of {{operationAttr}} specifies the annotation. The value {{createProcInstOp}} identifies the operation creating a new instance of the process definition. An example of such an annotation is shown below.
{code}
<wsdl:portType name="Order">
<wsdl:operation name="newOrder">
<psa:operationAttr xmlns:psa="http://petals.ow2.org/se/activity/1.0"
operation="createProcInstOp" />
<wsdl:input message="NewOrderRequestMessage" />
<wsdl:output message="NewOrderResponseMessage" />
</wsdl:operation>
</wsdl:portType>
{code}
If several operation are annotated by {{createProcInstOp}}, an error is thrown, and the deployment of the service unit is interrupted.
All parameters of the operation are used as parameter to create the instance of the process definition. {color:red}*Peut être ajouter un mapping pour indiquer nom de la variable coté process et type ? Comment gérer les arborescences ?*{color}
h4. Complete the current task of a process instance
Because operation in WSDL 1.1 does not allow attribute extensibility, an operation is annotated by adding an {{operationAttr}} element as a child of the operation element. The {{operation}} attribute of {{operationAttr}} specifies the annotation. The value {{completeTaskOp}} identifies the operation creating a new instance of the process definition. An example of such an annotation is shown below.
{code}
<wsdl:portType name="Order">
<wsdl:operation name="validOrder">
<psa:operationAttr xmlns:psa="http://petals.ow2.org/se/activity/1.0"
operation="completeTaskOp" />
<wsdl:input message="ValidOrderRequestMessage" />
<wsdl:output message="ValidOrderResponseMessage" />
</wsdl:operation>
</wsdl:portType>
{code}
If several operation are annotated by {{completeTaskOp}}, an error is thrown, and the deployment of the service unit is interrupted.
Some parameters are expected for this operation:
* identifier of the process instance,
* identifier of the task to complete,
* completion status.
These parameters are also annotated into the WSDL, more precisely in the XSD part. {color:red}*Est ce mieux dans le XSD ou dans la definition de l'operation ? Ne serait-il pas mieux d'utiliser l'annotation au niveau de l'operation et de donner les paramètres par une expression XPath ? Même question pour les valeurs OK, KO de completaion de la tache ?*{color}
h4. Retrieve process instances
Because operation in WSDL 1.1 does not allow attribute extensibility, an operation is annotated by adding an {{operationAttr}} element as a child of the operation element. The {{operation}} attribute of {{operationAttr}} specifies the annotation. The value {{retrieveProcInst}} identifies the operation creating a new instance of the process definition. An example of such an annotation is shown below.
{code}
<wsdl:portType name="Order">
<wsdl:operation name="searchOrder">
<psa:operationAttr xmlns:psa="http://petals.ow2.org/se/activity/1.0"
operation="createProcInstOp" />
<wsdl:input message="SearchOrderRequestMessage" />
<wsdl:output message="SearchOrderResponseMessage" />
</wsdl:operation>
</wsdl:portType>
{code}
If several operation are annotated by {{retrieveProcInst}}, an error is thrown, and the deployment of the service unit is interrupted.
Some search criteria parameters are expected for this operation. These parameters are also annotated into the WSDL, more precisely in the XSD part. {color:red}*Est ce mieux dans le XSD ou dans la definition de l'operation ? Ne serait-il pas mieux d'utiliser l'annotation au niveau de l'operation et de donner les paramètres par une expression XPath ?*{color}
h1. Configuring the component
The component is be configured through the parameters of its JBI descriptor file. These parameters are divided in following groups:
* *JBI parameters* that have not to be changed otherwise the component will not work,
* *CDK parameters* that are parameters driving the processing of the CDK layer,
* and *Activity parametrs" that are relative to the engine "Activity".
{color:red}*TODO: Mettre une copie en exemple d'un descripteur JBI du SE*{color}
{code:lang=xml}<?xml version="1.0" encoding="UTF-8"?>
<jbi
version="1.0"
xmlns='http://java.sun.com/xml/ns/jbi'
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-5"
xmlns:xslt="http://petals.ow2.org/components/activity/version-1">
<component type="service-engine">
<identification>
<name>petals-se-activity</name>
<description>An Activity Service Engine</description>
</identification>
<component-class-name description="Activity Component class">org.ow2.petals.se.activity.ActivitySe</component-class-name>
<component-class-path><path-element/></component-class-path>
<bootstrap-class-name>org.ow2.petals.component.framework.DefaultBootstrap</bootstrap-class-name>
<bootstrap-class-path><path-element/></bootstrap-class-path>
<petalsCDK:acceptor-pool-size>3</petalsCDK:acceptor-pool-size>
<petalsCDK:processor-pool-size>10</petalsCDK:processor-pool-size>
<petalsCDK:processor-max-pool-size>50</petalsCDK:processor-max-pool-size>
<petalsCDK:properties-file></petalsCDK:properties-file>
<petalsCDK:jbi-listener-class-name>org.ow2.petals.se.activity.ActivityJBIListener</petalsCDK:jbi-listener-class-name>
</component>
</jbi>{code}
h2. CDK parameters
The component configuration includes the configuration of the CDK. The following parameters correspond to the CDK configuration.
{include:0 CDK Component Configuration Table 5.4.0}
{include:0 CDK Parameter scope}
{include:0 CDK Component Interceptor configuration}
h2. Component specific parameters
These parameters are extracted from parameters available for Activity 5.1.3:
* database parameters. Your are responsible to provide this database according to your needs. And especially, you must assume that the database is highly available to have a SE Activity highly available.
h3. Database parameters
{center}{*}Configuration of the component, Specific parameter part, Database*{center}
{table-plus}
|| {color:#333333}Parameter{color} || {color:#333333}Description{color} || {color:#333333}Default{color} || {color:#333333}Required{color} || Scope ||
| jdbc-url | URL of the database. The default database is an in-memory database | {center}jdbc:h2:mem:activiti;DB_CLOSE_DELAY=1000{center} | {center}Yes{center} | {center}Installation{center} |
| jdbc-driver | JDBC driver. Except for the default JDBC driver, it *must* be provided as shared-library. | {center}org.h2.Driver{center} | {center}Yes{center} | {center}Installation{center} |
| jdbc-username | Username used for the database connection. | {center}sa{center} | {center}Yes{center} | {center}Installation{center} |
| jdbc-password | Passwrd used for the database connection. | {center}""{center} | {center}Yes{center} | {center}Installation{center} |
| jdbc-max-active-connections | The number of idle connections that the database connection pool at maximum at any time can contain. | {center}10{center} | {center}No{center} | {center}Runtime{center} |
| jdbc-max-idle-connections | The number of active connections that the database connection pool at maximum at any time can contain. | {center}-{center} | {center}No{center} | {center}Runtime{center} |
| jdbc-max-checkout-time | The amount of time in milliseconds a connection can be 'checked out' from the connection pool before it is forcefully returned. | {center}20000 (20 seconds){center} | {center}No{center} | {center}Runtime{center} |
| jdbc-max-wait-time | This is a low level setting that gives the pool a chance to print a log status and re-attempt the acquisition of a connection in the case that it’s taking unusually long (to avoid failing silently forever if the pool is misconfigured). | {center}20000 (20 seconds){center} | {center}No{center} | {center}Runtime{center} |
h1. Logging
To enable traces of the Activity engine, you add in the logging configuration file of Petals ESB the following logger with the right level: {{xxxx}}
h1. Monitoring the component
{warning}In this documentation, the term "Allocated threads" must be understood as "Active threads", see [PETALSDISTRIB-37|https://jira.petalslink.com/browse/PETALSDISTRIB-37]. This naming error will be fixed in the next version.{warning}
h2. Using metrics
Several probes providing metrics are included in the component, and are available through the JMX MBean '{{org.ow2.petals:type=custom,name=monitoring_*<component-id>*}}', where {{*<component-id>*}} is the unique JBI identifier of the component.
h3. Common metrics
{include:0 CDK Component Monitoring Metrics 5.4.0}
h3. Dedicated metrics
No dedicated metric is available.
h2. Receiving alerts
Several alerts are notified by the component through notification of the JMX MBean '{{org.ow2.petals:type=custom,name=monitoring_*<component-id>*}}', where {{*<component-id>*}} is the unique JBI identifier of the component.
{tip}To integrate these alerts with Nagios, see [petalsesbsnapshot:Receiving Petals ESB defects in Nagios].{tip}
h3. Common alerts
{include:0 CDK Component Monitoring Alerts 5.4.0}
h3. Dedicated alerts
No dedicated alert is available.
{column}
{multi-excerpt-include:Petals-SE-Activity|name=features|nopanel=true}
{column}
{column:width=350px}
{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. Creating a service-unit for a process definition
h2. Creating the service contract
The SE Activity provides a service with several operation for a process definition. A WSDL is associated to this service. This WSDL wan be written freely. The user can use its own namespace, its own names, ... It is only constraint by the following rules:
* the operations of the port type *are annotated* to link them to the supported operations (create an instance of the process definition, complete the current task of the process instance, ...)
* the mandatory parameters of the operation *are annotated* to retrieve the right values.
h3. Identifying operations
h4. Create an instance of a process definition
Because operation in WSDL 1.1 does not allow attribute extensibility, an operation is annotated by adding an {{operationAttr}} element as a child of the operation element. The {{operation}} attribute of {{operationAttr}} specifies the annotation. The value {{createProcInstOp}} identifies the operation creating a new instance of the process definition. An example of such an annotation is shown below.
{code}
<wsdl:portType name="Order">
<wsdl:operation name="newOrder">
<psa:operationAttr xmlns:psa="http://petals.ow2.org/se/activity/1.0"
operation="createProcInstOp" />
<wsdl:input message="NewOrderRequestMessage" />
<wsdl:output message="NewOrderResponseMessage" />
</wsdl:operation>
</wsdl:portType>
{code}
If several operation are annotated by {{createProcInstOp}}, an error is thrown, and the deployment of the service unit is interrupted.
All parameters of the operation are used as parameter to create the instance of the process definition. {color:red}*Peut être ajouter un mapping pour indiquer nom de la variable coté process et type ? Comment gérer les arborescences ?*{color}
h4. Complete the current task of a process instance
Because operation in WSDL 1.1 does not allow attribute extensibility, an operation is annotated by adding an {{operationAttr}} element as a child of the operation element. The {{operation}} attribute of {{operationAttr}} specifies the annotation. The value {{completeTaskOp}} identifies the operation creating a new instance of the process definition. An example of such an annotation is shown below.
{code}
<wsdl:portType name="Order">
<wsdl:operation name="validOrder">
<psa:operationAttr xmlns:psa="http://petals.ow2.org/se/activity/1.0"
operation="completeTaskOp" />
<wsdl:input message="ValidOrderRequestMessage" />
<wsdl:output message="ValidOrderResponseMessage" />
</wsdl:operation>
</wsdl:portType>
{code}
If several operation are annotated by {{completeTaskOp}}, an error is thrown, and the deployment of the service unit is interrupted.
Some parameters are expected for this operation:
* identifier of the process instance,
* identifier of the task to complete,
* completion status.
These parameters are also annotated into the WSDL, more precisely in the XSD part. {color:red}*Est ce mieux dans le XSD ou dans la definition de l'operation ? Ne serait-il pas mieux d'utiliser l'annotation au niveau de l'operation et de donner les paramètres par une expression XPath ? Même question pour les valeurs OK, KO de completaion de la tache ?*{color}
h4. Retrieve process instances
Because operation in WSDL 1.1 does not allow attribute extensibility, an operation is annotated by adding an {{operationAttr}} element as a child of the operation element. The {{operation}} attribute of {{operationAttr}} specifies the annotation. The value {{retrieveProcInst}} identifies the operation creating a new instance of the process definition. An example of such an annotation is shown below.
{code}
<wsdl:portType name="Order">
<wsdl:operation name="searchOrder">
<psa:operationAttr xmlns:psa="http://petals.ow2.org/se/activity/1.0"
operation="createProcInstOp" />
<wsdl:input message="SearchOrderRequestMessage" />
<wsdl:output message="SearchOrderResponseMessage" />
</wsdl:operation>
</wsdl:portType>
{code}
If several operation are annotated by {{retrieveProcInst}}, an error is thrown, and the deployment of the service unit is interrupted.
Some search criteria parameters are expected for this operation. These parameters are also annotated into the WSDL, more precisely in the XSD part. {color:red}*Est ce mieux dans le XSD ou dans la definition de l'operation ? Ne serait-il pas mieux d'utiliser l'annotation au niveau de l'operation et de donner les paramètres par une expression XPath ?*{color}
h1. Configuring the component
The component is be configured through the parameters of its JBI descriptor file. These parameters are divided in following groups:
* *JBI parameters* that have not to be changed otherwise the component will not work,
* *CDK parameters* that are parameters driving the processing of the CDK layer,
* and *Activity parametrs" that are relative to the engine "Activity".
{color:red}*TODO: Mettre une copie en exemple d'un descripteur JBI du SE*{color}
{code:lang=xml}<?xml version="1.0" encoding="UTF-8"?>
<jbi
version="1.0"
xmlns='http://java.sun.com/xml/ns/jbi'
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-5"
xmlns:xslt="http://petals.ow2.org/components/activity/version-1">
<component type="service-engine">
<identification>
<name>petals-se-activity</name>
<description>An Activity Service Engine</description>
</identification>
<component-class-name description="Activity Component class">org.ow2.petals.se.activity.ActivitySe</component-class-name>
<component-class-path><path-element/></component-class-path>
<bootstrap-class-name>org.ow2.petals.component.framework.DefaultBootstrap</bootstrap-class-name>
<bootstrap-class-path><path-element/></bootstrap-class-path>
<petalsCDK:acceptor-pool-size>3</petalsCDK:acceptor-pool-size>
<petalsCDK:processor-pool-size>10</petalsCDK:processor-pool-size>
<petalsCDK:processor-max-pool-size>50</petalsCDK:processor-max-pool-size>
<petalsCDK:properties-file></petalsCDK:properties-file>
<petalsCDK:jbi-listener-class-name>org.ow2.petals.se.activity.ActivityJBIListener</petalsCDK:jbi-listener-class-name>
</component>
</jbi>{code}
h2. CDK parameters
The component configuration includes the configuration of the CDK. The following parameters correspond to the CDK configuration.
{include:0 CDK Component Configuration Table 5.4.0}
{include:0 CDK Parameter scope}
{include:0 CDK Component Interceptor configuration}
h2. Component specific parameters
These parameters are extracted from parameters available for Activity 5.1.3:
* database parameters. Your are responsible to provide this database according to your needs. And especially, you must assume that the database is highly available to have a SE Activity highly available.
h3. Database parameters
{center}{*}Configuration of the component, Specific parameter part, Database*{center}
{table-plus}
|| {color:#333333}Parameter{color} || {color:#333333}Description{color} || {color:#333333}Default{color} || {color:#333333}Required{color} || Scope ||
| jdbc-url | URL of the database. The default database is an in-memory database | {center}jdbc:h2:mem:activiti;DB_CLOSE_DELAY=1000{center} | {center}Yes{center} | {center}Installation{center} |
| jdbc-driver | JDBC driver. Except for the default JDBC driver, it *must* be provided as shared-library. | {center}org.h2.Driver{center} | {center}Yes{center} | {center}Installation{center} |
| jdbc-username | Username used for the database connection. | {center}sa{center} | {center}Yes{center} | {center}Installation{center} |
| jdbc-password | Passwrd used for the database connection. | {center}""{center} | {center}Yes{center} | {center}Installation{center} |
| jdbc-max-active-connections | The number of idle connections that the database connection pool at maximum at any time can contain. | {center}10{center} | {center}No{center} | {center}Runtime{center} |
| jdbc-max-idle-connections | The number of active connections that the database connection pool at maximum at any time can contain. | {center}-{center} | {center}No{center} | {center}Runtime{center} |
| jdbc-max-checkout-time | The amount of time in milliseconds a connection can be 'checked out' from the connection pool before it is forcefully returned. | {center}20000 (20 seconds){center} | {center}No{center} | {center}Runtime{center} |
| jdbc-max-wait-time | This is a low level setting that gives the pool a chance to print a log status and re-attempt the acquisition of a connection in the case that it’s taking unusually long (to avoid failing silently forever if the pool is misconfigured). | {center}20000 (20 seconds){center} | {center}No{center} | {center}Runtime{center} |
h1. Logging
To enable traces of the Activity engine, you add in the logging configuration file of Petals ESB the following logger with the right level: {{xxxx}}
h1. Monitoring the component
{warning}In this documentation, the term "Allocated threads" must be understood as "Active threads", see [PETALSDISTRIB-37|https://jira.petalslink.com/browse/PETALSDISTRIB-37]. This naming error will be fixed in the next version.{warning}
h2. Using metrics
Several probes providing metrics are included in the component, and are available through the JMX MBean '{{org.ow2.petals:type=custom,name=monitoring_*<component-id>*}}', where {{*<component-id>*}} is the unique JBI identifier of the component.
h3. Common metrics
{include:0 CDK Component Monitoring Metrics 5.4.0}
h3. Dedicated metrics
No dedicated metric is available.
h2. Receiving alerts
Several alerts are notified by the component through notification of the JMX MBean '{{org.ow2.petals:type=custom,name=monitoring_*<component-id>*}}', where {{*<component-id>*}} is the unique JBI identifier of the component.
{tip}To integrate these alerts with Nagios, see [petalsesbsnapshot:Receiving Petals ESB defects in Nagios].{tip}
h3. Common alerts
{include:0 CDK Component Monitoring Alerts 5.4.0}
h3. Dedicated alerts
No dedicated alert is available.