Orchestra User Guide

Nova Orchestra is the name of new version of Orchestra.

“Nova” technology is based on the “Process Virtual Machine” conceptual model for processes. The Process Virtual Machine defines a generic process engine enabling support for multiple process languages (such BPEL, XPDL…).

On top of that, it leads to a pluggable and embeddable design of process engines that gives modeling freedom to the business analyst. Additionally, it enables the developer to leverage process technology embedded in a Java application.

For more information about the Process Virtual Machine, check Nova Orchestra FAQs on the Orchestra web site.

Nova Orchestra is a Web Service Orchestration engine that provides BPEL 2.0 support. Business Process Execution Language (BPEL) is an XML language created by the Oasis Consortium. More information and the specifications can be found on Oasis web site

Nova Orchestra provides partial BPEL 2.0 support. Hereafter, you can find the list of the activities supported :

This version provides Web Service support using the Axis 1.4 framework.

Nova Orchestra is shipped with a complete test suite and a few examples.

Nova Orchestra is persistable. This means that all the data concerning your processes definition and intances execution can be stored in a Database using hibernates. The following database systems have been successfully tested :

Nova Orchestra comes out with an innovative architecture based on a generic and extensible engine, called "The Process Virtual Machine" and a powerful injection technology allowing services pluggability.

This new version of Orchestra is aimed at showing the power of its very innovative architecture by providing support for all the basic activities defined in the BPEL standard. As stated in the previous section, this version provides the possibility to persist the processes definition and execution. Future versions will continue to improve the standard coverage as well as other functionalities like other services. Check the roadmap for more information.

This version does not support the following features :

For the new version, Nova Orchestra does not ship a graphical designer. Nova Orchestra engine has been tested with processes created using the Eclipse BPEL designer. Download and installation instruction are available on the project web site.

This version of Nova Orchestra provides an new Web 2.0 administration console. This console will be improved in following releases to add monitoring capabilities.

A 1GHz processor is recommended, with a minimum of 512 Mb of RAM. Windows users can avoid swap file adjustments and get improved performance by using 1Gb or more of RAM

Unzip the orchestra-axis distribution package.

>unzip orchestra-4.0.RC.zip

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

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

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

>cd orchestra-4.0.RC
>ant install

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

	Important
	if your network is based on a proxy, please change the file conf/conf.properties. Set in this file the proxy host, port and non proxy hosts. Then run ant configure under the installation directory.

The default configuration of Nova Orchestra uses the Database persistence service and the HSQL Database. Nova Orchestra has also been tested with the Postgres database system. To change to postgres, you need to put the corresponding JDBC driver in the directory catalina_base/webapps/orchestra/WEB-INF/lib to modify the hibernate.properties file : uncomment the corresponding lines :

# Hibernate configuration

# For using Orchestra with HSQL 
# hibernate.dialect                      org.hibernate.dialect.HSQLDialect
# hibernate.connection.driver_class      org.hsqldb.jdbcDriver
# hibernate.connection.url               jdbc:hsqldb: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

hibernate.dialect                      org.hibernate.dialect.HSQLDialect
hibernate.connection.driver_class      org.hsqldb.jdbcDriver
hibernate.connection.url               jdbc:hsqldb: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

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

README
build.xml
install.xml
licence.txt
catalina_base/
catalina_home/
conf/
doc/
examples/
lib/

Let's present those items :

The Process Virtual Machine technology includes a services container allowing the injection of services and objets that will be leveraged during the process definition and execution. Objects and services used by the Orchestra engine are defined through a XML file. A dedicated parser and a wiring framework are in charge of creating those objects. Service invoker, publisher, persistence and timers are examples of pluggable services.

This services container (aka IoC container) can be configured through a configuration file. A default configuration file is included in the package under the /conf directory (environment.xml).

Services in Nova Orchestra is all about pluggability. To allow that, each service has been thought in terms of an interface with different possible implementations. In the following lines you will find a description of main services supported in Nova Orchestra.

The PVM includes a framework to allow the injection of services and objects that will be leveraged during the process definition and execution. Objects and services required in Orchestra are defined through an XML file. A dedicated parser and wiring framework in the PVM is in charge of creating those objects.

A default environment file (environment.xml) is provided in the installed package.

Currently, following objects are required for the execution environment :

Example of implementation classes for these objects are embedded into the Orchestra jar and defined into the environment.xml file.

<job-executor threads='1' auto-start='false' />

<environment-definition>

  <application>
    <hibernate-session-factory table-prefix='NOVA_'>
      <properties resource='hibernate.properties' />
      <mapping resource='hibernate.definition.hbm.xml' />
      <mapping resource='hibernate.execution.hbm.xml' />
      <mapping resource='hibernate.job.hbm.xml' />
      <mapping resource='hibernate.queries.hbm.xml' />
      <mapping resource='hibernate.type.hbm.xml' />
      <mapping resource='hibernate.wire.hbm.xml' />
      <mapping resource='bpel.activities.hbm.xml' />
      <mapping resource='bpel.elements.hbm.xml' />
      <mapping resource='bpel.execution.hbm.xml' />
      <mapping resource='bpel.runtime.hbm.xml' />
      <mapping resource='bpel.services.hbm.xml' />
      <mapping resource='bpel.queries.hbm.xml' />
      <mapping resource='bpel.util.hbm.xml' />
      <mapping resource='bpel.wsdl.hbm.xml' />
      <mapping resource='bpel.lang.hbm.xml' />
      <cache-configuration resource='pvm.definition.cache.xml' usage='read-write' />
      <cache-configuration resource='bpel.cache.xml' usage='read-write' />
    </hibernate-session-factory>
    <standard-command-service>
      <retry-interceptor />
      <environment-interceptor />
      <transaction-interceptor />
    </standard-command-service>
    <job-executor threads='1' auto-start='false' />
    <repository class='org.ow2.orchestra.execution.services.db.DbRepository' />
    <publisher class='org.ow2.orchestra.axis.AxisPublisher' />
    <invoker class='org.ow2.orchestra.axis.AxisInvoker' />
  </application>

  <block>
    <timer-session />
    <standard-transaction />
    <job-session />
    <hibernate-session />
    <hibernate-bpel-persistence-service />
  </block>

</environment-definition>

Nova Orchestra is a webapp that can be deployed on Tomcat. So starting Nova Orchestra in fact starts Tomcat with the correct environment. This can be performed from the installation directory with the following command line :

>cd orchestra-4.0.RC
>ant start

Starting Orchestra will not be done in background. This means that the console starting Orchestra will be dedicated to the traces from Orchestra. To perform further actions, new consoles need to be opened.

To stop Nova Orchestra, type the following command line :

>cd orchestra-4.0.RC
>ant stop

Once Nova Orchestra is started, it is then possible to deploy a new process on the engine :

>ant deploy -Dbpel=<process>.bpel -Dwsdl=<process>.wsdl -Dextwsdl=<wsdl1,wsdl2>

Nova Orchestra also provides the possibility to use an archive to deploy a process. This archive should be a zip file with the extension .bar. Here is the command line to deploy such an archive :

>ant deploy -Dbar=<process>.bar

Warning : The archive should be a zip file structured as described bellow :

/bar.properties
/<process>.bpel
/<process>.wsdl
/<files>.wsdl

The bar.properties file should have the following structure :

bpel=<process>.bpel
wsdl=<process>.wsdl
extwsdl=<file1>.wsdl,<file2>.wsdl,...

To undeploy a process, use the following command line :

>ant undeploy -Dprocess=<process_name>

Warning : the process name should be fully qualified. This means that it needs to contain to namespace. For instance :

{http://orchestra.ow2.org/weather}weather

Nova Orchestra provides a set of other commands that can be usefull

The Nova Orchestra package contains two examples of BPEL processes:

A build.xml file is provided for each of those samples. Those ant scripts provide the same targets to deploy, launch and undeploy the sample. Go to the desired example and use the command lines :

>ant deploy
>ant launch
>ant undeploy

Nova Orchestra is delivered with a test suite to check if your installation is correct. There are 3 differents tests available :

A command is also provided to launch those 3 test suites at once :

>ant test-all

The results of the tests are available under the directory testresults.

It is possible to activate the logs. To do so, the file logging.properties under the directory $CATALINA_BASE/webapps/orchestra/WEB-INF/classes can be edited. Here is the content of that file :

handlers= java.util.logging.ConsoleHandler
.level= SEVERE
java.util.logging.ConsoleHandler.level = FINEST
java.util.logging.ConsoleHandler.formatter = org.jbpm.util.JbpmFormatter

# For example, set the com.xyz.foo logger to only log SEVERE messages:
# com.xyz.foo.level = SEVERE

#org.jbpm.pvm.level=INFO
#org.ow2.orchestra.level=FINEST
#org.jbpm.pvm.Execution.level=FINEST
#org.jbpm.wire.level=FINEST

Uncomment the last lines to activate the logs.