Orchestra User Guide

Orchestra web service implementation based on Axis 1.4 offers basic web service capabilities.

Orchestra web service implementation based on CXF offers advanced web service capabilities.

CXF implementation adds support for:

Unzip the orchestra-tomcat distribution package.

>unzip orchestra-tomcat-4.6.0.zip

A new directory orchestra-tomcat-4.6.0 will be created. It contains an ant file to install and start Orchestra.

3.2.1.1. Basic installation

Remark : Orchestra runs in Apache Tomcat servlet container. Tomcat 6.0.26 is delivered with the Orchestra Package.

To install Orchestra, go to orchestra directory and launch the install by running ant:

>cd orchestra-tomcat-4.6.0
>ant install

The install script installs Tomcat and Orchestra. The default installation activates the persistence using the H2 Database.

	Important
	if your network is based on a proxy, please specify the proxy settings in your JAVA_OPTS environment property. The system properties to specify are described in the java documentation.

			catalina.home=${orchestra.dir}/tomcat
			catalina.base=${catalina.home}
		  

>ant install

The default configuration of Orchestra uses the Database persistence service and the H2 Database. Orchestra has also been tested with Oracle, MySQL and Postgres database system. To change to mysql, postgres or Oracle, you need to put the corresponding JDBC driver in the directory $CATALINA_BASE/lib and modify the hibernate.properties file (see Section 4.3.4.1, “Database Access Configuration”)

Hereafter is detailled the structure of Orchestra installation. The installation directory contains the following structure :

        	README
  			build.xml
  			install.xml
        common.xml
  			Licence.txt
  			tomcat/
  			conf/
  			doc/
  			examples/
  			lib/
        resources/
  		

Let's present those items :

Unzip the orchestra-felix distribution package.

>unzip orchestra-felix-4.6.0.zip

A new directory orchestra-felix-4.6.0 will be created. It contains an ant file to install and start Orchestra.

Remark : Orchestra runs in Apache Felix OGSI platform. Felix 2.0.2 is delivered with the Orchestra Package.

There is no specific installation step for running Orchestra :

>cd orchestra-felix-4.6.0

The default configuration activates the persistence using the H2 Database.

	Important
	if your network is based on a proxy, please specify the proxy settings in your JAVA_OPTS environment property. The system properties to specify are described in the java documentation.

The default configuration of Orchestra uses the Database persistence service and the H2 Database. Orchestra has also been tested with Oracle, MySQL and Postgres database system. To change to mysql, postgres or Oracle, you need to install the corresponding JDBC driver bundle in the OSGI platform and modify the hibernate.properties file (see Section 4.3.4.1, “Database Access Configuration”)

Hereafter is detailled the structure of Orchestra installation. The installation directory contains the following structure :

        	README
  			build.xml
  			Licence.txt
  			bundle/
        felix/
  			conf/
  			doc/
  			examples/
  			lib/
        resources/
  		

Let's present those items :

The default environment.xml file created during the installation of Orchestra is set to use the database implementation of the persistence service. This file also sets the configuration of hibernate. Here is the environment.xml file generated :

<environment-definition>                                                                       
  <environment-factory>                                                                        
    <properties name="orchestra-properties" resource="orchestra.properties"/>                  
    <hibernate-configuration name="hibernate-configuration:core">                              
      <properties resource="hibernate.properties"/>                                            
      <mappings resource="hibernate/bpel.core.mappings.xml"/>                                  
      <mappings resource="hibernate/bpel.monitoring.mappings.xml"/>                            
      <cache-configuration resource="hibernate/bpel.cache.definition.xml" usage="nonstrict-read-write"/>
    </hibernate-configuration>
    <hibernate-session-factory configuration="hibernate-configuration:core" init="eager" name="hibernate-session-factory:core"/>
    <command-service>
      <orchestra-retry-interceptor delay-factor="2" retries="10"/>
      <environment-interceptor/>
      <standard-transaction-interceptor/>
    </command-service>
    <invoke-executor threads="10"/>
    <job-executor auto-start="false" lock="180000" threads="10"/>
    <hibernate-configuration name="hibernate-configuration:history">
      <properties resource="hibernate-history.properties"/>
      <mappings resource="hibernate/bpel.monitoring.mappings.xml"/>
      <mapping resource="hibernate/bpel.util.hbm.xml"/>
    </hibernate-configuration>
    <hibernate-session-factory configuration="hibernate-configuration:history" init="eager" name="hibernate-session-factory:history"/>
    <dead-job-handler class="org.ow2.orchestra.services.handlers.impl.ExitInstanceDeadJobHandler"/>
    <repository class="org.ow2.orchestra.services.impl.DbRepository"/>
    <publisher class="org.ow2.orchestra.cxf.CxfPublisher"/>
    <invoker class="org.ow2.orchestra.cxf.CxfInvoker" name="serviceInvoker"/>
  </environment-factory>
  <environment>
    <hibernate-session factory="hibernate-session-factory:core" name="hibernate-session:core"/>
    <runtime-db-session name="runtime-session:core" session="hibernate-session:core"/>
    <transaction/>
    <timer-session retries="10"/>
    <message-session retries="10" use-fair-scheduling="false"/>
    <job-db-session session="hibernate-session:core"/>
    <journal class="org.ow2.orchestra.persistence.db.DbJournal" name="journal">
      <arg>
        <ref object="querier-session:core"/>
      </arg>
    </journal>
    <querier-db-session name="querier-session:core" session="hibernate-session:core"/>
    <history class="org.ow2.orchestra.persistence.db.DbHistory" name="history">
      <arg>
        <ref object="querier-session:history"/>
      </arg>
    </history>
    <hibernate-session factory="hibernate-session-factory:history" name="hibernate-session:history"/>
    <querier-db-session name="querier-session:history" session="hibernate-session:history"/>
    <chainer name="recorder">
      <recorder class="org.ow2.orchestra.persistence.log.LoggerRecorder"/>
      <ref object="journal"/>
    </chainer>
    <chainer name="archiver">
      <archiver class="org.ow2.orchestra.persistence.log.LoggerArchiver"/>
      <ref object="history"/>
    </chainer>
    <queryApi name="queryList">
      <ref object="journal"/>
      <ref object="history"/>
    </queryApi>
    <chainer name="finished-instance-handler">
      <finished-instance-handler class="org.ow2.orchestra.services.handlers.impl.DeleteFinishedInstanceHandler"/>
      <finished-instance-handler class="org.ow2.orchestra.services.handlers.impl.ArchiveFinishedInstanceHandler"/>
    </chainer>
    <chainer name="undeployed-process-handler">
      <undeployed-process-handler class="org.ow2.orchestra.services.handlers.impl.ArchiveUndeployedProcessHandler"/>
    </chainer>
  </environment>
</environment-definition>

Currently, following objects implementations can be injected in the environment:

* Note 1: As explained before persistence objects are provided as default implementations in the environment. Notice that in a persistence configuration additional resources are required, i.e for hibernate persistence you can specify mappings, cache configuration...

* Note 2: The environment is divided in two different contexts: environment-factory and environment. Objects declared inside the environment-factory context are created once and reused while objects declared inside the environment context are created for each operation.

The publisher service sets the way the services proposed by the BPEL processes will be published. The default implementation of this service uses the Axis Web Service Container.

The invoker service sets the way the BPEL processes will call external services. The default implementation of this service uses the SAAJ implementation.

The repository service sets the way the data will be handled by the engine. Orchestra proposes one implementation managing data in the database.

Persistence is one of key technical services injected into the services container. This service, as well as other major services in Orchestra, is based on a service interface. That means that multiple persistence implementations can be plugged on top.

The Persistence service interface is responsible to save and load objects from a relational database. By default, a persistence implementation based on the Hibernate ORM framework is provided (JPA and JCR to come).

The Process Virtual Machine core definition and execution elements (processes, nodes, transitions, events, actions, variables and executions) as well as the BPEL extension ones (activities, conditions, variables...) are persisted through this service. Process Virtual Machine core elements are also cached by leveraging the default persistence service implementation (Hibernate based). Processes and instances are stored through this persistence service. Repository is the term used in Orchestra to store those entities.

This service is only used if the repository service is set to database.

  # Hibernate configuration
  
  # For using Orchestra with H2 
  # hibernate.dialect                      org.hibernate.dialect.H2Dialect
  # hibernate.connection.driver_class      org.h2.Driver
  # hibernate.connection.url               jdbc:h2:file:db_orchestra
  # hibernate.connection.username          sa
  # hibernate.connection.password
  
  # For using Orchestra with postgreSQL  
  # hibernate.dialect                      org.hibernate.dialect.PostgreSQLDialect
  # hibernate.connection.driver_class      org.postgresql.Driver
  # hibernate.connection.url               jdbc:postgresql://server:port/db
  # hibernate.connection.username          user
  # hibernate.connection.password          pass
  
  # For using Orchestra with MySQL  
  # hibernate.dialect                      org.hibernate.dialect.MySQL5InnoDBDialect
  # hibernate.connection.driver_class      com.mysql.jdbc.Driver
  # hibernate.connection.url               jdbc:mysql://server:port/db
  # hibernate.connection.username          user
  # hibernate.connection.password          pass
  
  hibernate.dialect                      org.hibernate.dialect.H2Dialect
  hibernate.connection.driver_class      org.h2.Driver
  hibernate.connection.url               jdbc:h2:file:db_orchestra
  hibernate.connection.username          sa
  hibernate.connection.password
  
  hibernate.hbm2ddl.auto                 update
  hibernate.cache.use_second_level_cache true
  hibernate.cache.provider_class         org.hibernate.cache.HashtableCacheProvider
  hibernate.show_sql                     false
  hibernate.format_sql                   false
  hibernate.use_sql_comments             false
  hibernate.bytecode.use_reflection_optimizer true
            

This module concerns the way in which the process data is stored during the process execution and archived when the execution is completed. This is indeed a crucial module in a process solution.

Orchestra unifies journal data et history data as the underlying essence of both is to handle process data. For that to be done, we created the concept of process record. A record is a minimal set of attributes describing a process entity execution. That means that each process entity related to the execution has its own associated record.

Those records are recorded during the process execution and stored depending on the persistence service implementation (db, xml...). The Orchestra API will retrieve record data from the records storage and sent them back to the users (meaning that records also acts as value objects in Orchestra APIs).

As soon as a process instance is finished, a typical scenario would be (by default) to move instance related process data from the production environment to a history one. While the physical device and the data structure could changed from one process engine deployment to another (XML, BI database...), the internal format could remain the same (records). This is exactly what is happening in Orchestra, when archiving data the engine just move execution records from the production to the history environment without data transformation in between.

Journal and history data are persisted in different database. Change hibernate.properties [hibernate-history.properties] file in conf directory to modify the journal [history] database

The querier is an API tool for getting process records corresponding to different criteria. It can get records from journal, from history or both. This possibility is defined in the environment. Several parameters will allow us to obtain this information by various criteria: their state (running or after delivery) or ID. Depending on the circumstances this request will return a record, a set of records or an empty table.

The command service manages the environments and the transactions in Orchestra. Each process or api method is executed by the command service.

Its definition in the environment is the following :

<command-service>
  <orchestra-retry-interceptor delay-factor="2" delay="100" max-delay="10000" retries="10"/>
  <environment-interceptor/>
  <standard-transaction-interceptor/>
</command-service>

The retries (optional) attribute can be used to define how many times commands will be tried before propagating the exception. This attribute is ignored for jobs (see Section 4.3.8, “Asynchronous Executions (Jobs)”).

The delay, max-delay, delay-factor (optional) attributes can be used to define the sleep time between each retry. The sleep time for the n^th attempt is given by

sleep = min($max-delay, $delay * $delay-factor * random(1, $delay-factor)n)

delay and max-delay values are in milliseconds.

To optimize the execution, Orchestra splits the execution in small steps. A job represents a step of an execution. It can be executed in parallel with other jobs. Jobs are grouped in two sets: messages, which can be executed immediately, and timers, whose executions are scheduled at a precise date.

Timers are used for the BPEL statements "wait" and "onAlarm".

Messages are used for the BPEL statements "receive", "onEvent", "onMessage" and "invoke".

Orchestra uses the PVM Job executor framework to handle jobs. Jobs are created using either the timer session service or the message session service. The job executor then fetches the job from the database and perform the instructions contained in the job.

<timer-session retries="5"/>

<message-session retries="5" use-fair-scheduling="false"/>

<invoke-executor threads='10' />

FIH are executed after the instance finished. Orchestra provides following implementations in the package org.ow2.orchestra.services.handlers.impl:

UPH are executed after the process is undeployed. Orchestra provides following implementations in the package org.ow2.orchestra.services.handlers.impl :

Orchestra can run in a clustered environment.

In a clustered environment, all Orchestra nodes share the same database.

When a process is deployed in Orchestra, the process web services are deployed on each node of the cluster. An instance of the process can execute on any node of the cluster.

	Important
	In a clustered environment, reply activities are not supported. The web services exported by Orchestra are only one-way web services.

In this version, Orchestra cluster configuration is done by declaring the cluster nodes in the environment.xml file.

To declare a cluster, add these lines to the environment-factory part of the configuration file:

<static-cluster>
  <jmx-server serviceUrl="..." objectName="..." />
  <jmx-server serviceUrl="..." objectName="..." />
</static-cluster>

Each jmx-server element describes an Orchestra node. The serviceUrl and objectName attributes are the parameters to use to connect to the JMX interface of the node. These values are configured for each node in the orchestra.properties file.

Available attributes:

Orchestra uses Camel Spring language to describe routes. To define the Camel routes deployed with a process, add a camel-context.xml file in your BAR archive. Orchestra will deploy and start the routes with the process. If your camel-context.xml uses external Java classes, you can add them too to the BAR archive.

Example of camel-context.xml file:

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="
       http://www.springframework.org/schema/beans 
        http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
       http://camel.apache.org/schema/spring 
        http://camel.apache.org/schema/spring/camel-spring.xsd">
  <camelContext xmlns="http://camel.apache.org/schema/spring" autoStartup="false">
    <route>
      <from uri="file:///inputDir" />
      <to uri="direct:hello"/>
    </route>
  </camelContext>
</beans>

In the WSDL file of the service you want to invoke or expose in the camel context,

Example of WSDL Service configured to use Camel:

<wsdl:binding name="helloworldPTSOAPBinding" type="tns:helloworldPT">
  <soap:binding style="document" transport="http://cxf.apache.org/transports/camel"/>
  <wsdl:operation name="submit">
    <soap:operation soapAction="http://orchestra.ow2.org/helloworld/submit"/>
    <wsdl:input>
      <soap:body use="literal" />
    </wsdl:input>
    <wsdl:output>
      <soap:body use="literal"/>
    </wsdl:output>
  </wsdl:operation>
</wsdl:binding>

<wsdl:service name="helloworldService">
  <wsdl:port name="helloworldPort" binding="tns:helloworldPTSOAPBinding">
    <soap:address location="camel://direct:hello"/>
  </wsdl:port>
</wsdl:service>

A process has three states:

A process can change state from:

Process lifecycle.

To deploy a new version of a process, just deploy a new process with the same name and namespace as an already deployed process. The version is automatically incremented.

Only one version of a process can be active. If multiple versions are deployed:

There are some restrictions when changing the process web services between process versions.

If a web service is shared by two versions of a process (same endpoint address), it must have the same WSDL definition (same portType, same binding...) in the two versions.

A new version of a process can add/remove web services (if receive activities are added, removed), as long as they use a separate portType.

A web service cannot be shared by two different processes (processes with different names).

Actually, four different APIs are available in Orchestra :

You can find detailled information about APIs in the javadocs. APIs are included in a Maven module. To include this module you have to add following Maven dependency :

<dependency>
  <groupId>org.ow2.orchestra</groupId>
  <artifactId>orchestra-api</artifactId>
  <version>4.6.0</version>
</dependency>
        

If you do not want / can't use Maven, you can create a Maven module which depends only on this dependency and create an assembly. Then copy created jar to your project.

Hereafter you will find an example on how to access to the QueryRuntimeAPI from your client application:

 org.ow2.orchestra.facade.QuerierRuntimeAPI querierRuntimeAPI = 
                org.ow2.orchestra.facade.AccessorUtil.getQueryRuntimeAPI(String, String);
        

The method getQueryRuntimeAPI takes two arguments of type String. The first argument is the URL of the JMX service. The second is the name of the object JMX. In case we use the default configuration, two constants can be used which are: AccessorUtil.SERVICE_URL and AccessorUtil.OBJECT_NAME.

For a detailed insight on Orchestra APIs, please take a look to the Orchestra javadoc APIs (available under /javadoc directory)

Similar methods exists to access to the QueryDefinitionAPI, ManagementAPI and InstanceManagementAPI.