BSOA Orchestra Frequently Asked Questions (FAQs)

Table of Contents

 

Chapter 1.             Database Issues 1

1.1   Clean a Database – When. 1

1.2   Clean a Database - How.. 2

1.3   Clean a Database - Which. 2

1.4   Remove All Data from a Database. 3

1.5   Open the HSQL Database. 3

1.6   ant initBsoaDb. 5

1.7   Clean a database Vs Undeploy all Web Services 5

1.8   Restore a Deleted Database. 6

Chapter 2.             Memory Issues 7

2.1   outOfMemoryError When Deploying a Process 7

2.2   Out-of-memory Error from Orchestra Console. 7

Chapter 3.             Configuration Issues 9

3.1   Determine if Orchestra Is Running. 9

3.2   Determining Orchestra Configuration Ports 10

Chapter 4.             Performance Issues 11

4.1   Keep Performance Levels Consistent after Database Updates 11

4.2   Improve Orchestra Performance. 11

 

List of Figures

 

Figure 1‑1.    GUI Interface for Accessing the HSQL Database. 4

Figure 1‑2.    Example Query Display in HSQL Database Manager 4

 


Preface

 

This document provides answers to frequently asked questions (FAQs) about BSOA Orchestra.  The questions are grouped into the following categories:

·           Database Issues (Chapter 1)

·           Memory Issues (Chapter 2)

·           Configurations Issues (Chapter 3)

·           Performance Issues (Chapter 4)


 


Chapter 1.      Database Issues

 

This chapter provides answers to the following questions regarding database issues:

·           When would one want to do a “clean database”? (Section 1.1)

·           How do I clean my database? (Section 1.2)

·           Which database is being cleaned? (Section 1.3)

·           How do I remove all the data from my database? (Section 1.4)

·           How do I open the HSQL database? (Section 1.5)

·           What does ant initBsoaDb do? (Section 1.6)

·           Is cleaning a database the same thing as undeploying all web services? (Section 1.7)

·           Can I save the database data prior to deleting it, and then restore it later?
(Section 1.8)

 

1.1                       Clean a Database – When

QUESTION :

When would one want to do a “clean database”?

ANSWER :

It might be desirable to perform a “clean database” under one of the following circumstances:

1.        To obtain testing or performance measurements, to restore the database to its initial state with no information about deployed applications or BPEL process state.

2.        To recover from an inconsistent state of the database, either with respect to its own internal consistency, or with respect to the state of BPEL engine processes.

 


1.2                       Clean a Database - How

QUESTION :

How do I clean my database?

ANSWER :

Clean the database using the following procedure:

1.        First, remove all the data in the database.

2.        Refer to Section 1.4 for information about removing the data from a database.

3.        Launch bsoap start (if it has not already been launched).

4.        In your installation directory, run: ant initBsoaDb

 

To find out what ant initBsoaDb does, refer to Section 1.6.

 

1.3                       Clean a Database - Which

QUESTION :

Which database is being cleaned?

ANSWER :

The database being referred to is the persistence mechanism that Orchestra uses to hold information such as process state, user authentication information, etc.  In a default installation, this is the HSQL database provided with Orchestra.  See Section 1.6 for more information.

 

1.4                       Remove All Data from a Database

QUESTION :

How do I remove all the data from my database?

ANSWER :

All data can be removed from the database in one of the following ways:

·           If using the default HSQL database, this can be done by removing the "work" directory under %JONAS_BASE%.

To open the HSQL database refer to Section 1.5, “How Do I Open the HSQL Database?”

·           If using a database such as PostgreSQL, this can be done by doing a "drop database".

·           All data can also be removed by deleting all rows from the Orchestra tables within the database.

Refer to the database properties file (e.g. HSQL1.properties) for the name of the database being used.

 

1.5                       Open the HSQL Database

QUESTION :

How do I open the HSQL database?

ANSWER :

The HSQL database can be accessed using a GUI interface by first starting Orchestra (bsoap start), then issuing the following command at a command prompt (Windows):

  java  -classpath  %BPEL_HOME%/lib/ext/jdbcDrivers/hsqldb.jar
                    org.hsqldb.util.DatabaseManager

The parameters for opening the database are shown below, where the URL was obtained from the file HSQL1.properties which resides under %JONAS_BASE%\conf.

 


Figure 11.    GUI Interface for Accessing the HSQL Database

The following Figure is an example query that shows the results of having deployed the "assign" sample and "college" demo.

(The display has been scrolled to the right to see the "name" column.)

 

Figure 12.    Example Query Display in HSQL Database Manager

 


1.6                       ant initBsoaDb

QUESTION :

What does ant initBsoaDb do?

ANSWER :

It adds rows of information related to security checks (e.g., user names and passwords) to the database table.  This puts the database into its minimally useful state after removing all data from the database.

Using initBsoaDb by itself will not remove any data, removing all data from the database must be done first.

Orchestra must be running prior to using the initBsoaDb command (use "bsoap start").

 

1.7                       Clean a database Vs Undeploy all Web Services

QUESTION :

Is cleaning a database the same thing as undeploying all web services?

ANSWER :

No, an undeploy involves performing all of the following actions, in this order:

-          undeploy the BPEL processes

-          undeploy the web services

-          clean the database

 

It is recommended that the undeploy actions be performed before doing a “clean database”.

The jiapAdmin console can do an UNDEPLOY of a single web service. (There is no BSOAP UNDEPLOY.  However, there is a BSOAP CLEAN that will delete a process model.)

 


1.8                       Restore a Deleted Database

QUESTION :

Can I save the database data prior to deleting it, and then restore it later?

ANSWER :

Yes, but this operation is potentially dangerous and not recommended.  This is because the state of the database can get out of sync with the state of the file system files generated during deployment (e.g., the Java Implementation, Stub, and message class files).

For example, to save data for the HSQL database, the directory can be copied to another location, the original version deleted, and then the data can be copied back at a later time.

Note:

A re-deploy can be used to ensure that generated files get "cleaned out" and recreated.

 


Chapter 2.      Memory Issues

 

This chapter provides answers to the following questions regarding memory issues:

·           Why do I get an outOfMemoryError when I try to deploy a process? (Section 2.1)

·           Why do I get an out of memory error from the Orchestra console trying to use a web browser to access Orchestra endpoints like the College Demo? (Section 2.2)

 

2.1                       outOfMemoryError When Deploying a Process

QUESTION :

Why do I get an outOfMemoryError when I try to deploy a process?

ANSWER :

An environment variable must be configured to allocate memory to the application.

For Example:

      JAVA_OPTS='-Xms512m -Xmx512m'

 

2.2                       Out-of-memory Error from Orchestra Console

QUESTION :

Why do I get an out of memory error from the Orchestra console trying to use a web browser to access Orchestra endpoints like the College Demo?

ANSWER :

If you get an error like the following:

Exception in thread "HSQLDB Connection @aa6635" java.lang.OutOfMemoryError: Java heap space

It may because you used the port number of the database instead of the Tomcat port number.  For the default installation port numbers, this would be:

http://localhost:9001

instead of:

http://localhost:9000

 


Chapter 3.      Configuration Issues

 

This chapter provides answers to the following questions regarding configuration issues:

·           How can I determine if Orchestra is running? (Section 3.1)

·           How can I determine which ports were used to configure Orchestra? (Section 3.2)

 

3.1                       Determine if Orchestra Is Running

QUESTION :

How can I determine if Orchestra is running?

ANSWER :

Use the following command:

Bsoap status

This should return one of the following messages:

JOnAS server BPEL is running.

JOnAS server BPEL unreachable

 


3.2                       Determining Orchestra Configuration Ports

QUESTION :

How can I determine which ports were used to configure Orchestra?

ANSWER :

There are four port numbers that were specified at installation or configuration time.  They are for the database port, the Tomcat port, the JRMP port, and the a3server port.  The current values for these ports are stored in properties and xml files under $JONAS_BASE/conf.

The database port can be found in jonas.properties. Search for the setting:

jonas.service.db.port

The Tomcat port can be found in server.xml. Search for the setting:

<Connector port=

The JRMP port can be found in carol.properties. Search for the setting:

carol.jrmp.url

The a3server port can be found in a3servers.xml. Search for the setting:

<service class="org.objectweb.joram.mom.proxies.tcp.TcpProxyService" args=

 


Chapter 4.      Performance Issues

 

This chapter provides answers to the following questions regarding performance issues:

·           How do I keep performance levels consistent with PostgreSQL or Oracle after many updates have been done to the database? (Section 4.1)

·           How can I improve Orchestra performance? (Section 4.2)

 

4.1                       Keep Performance Levels Consistent after Database Updates

QUESTION :

How do I keep performance levels consistent with PostgreSQL or Oracle after many updates have been done to the database?

ANSWER :

These two databases use Multi-version Concurrency Control (MVCC), which results in the accumulation of "dead tuples" from previous versions of data rows after update transactions have committed (MVCC makes a copy of the row being updated, rather than locking it).

With PostgreSQL, to remove only the dead tuples, instead of doing a complete removal of all data, the VACUUM command can be used.

 

4.2                       Improve Orchestra Performance

QUESTION :

How can I improve Orchestra performance?

ANSWER :

There are several things that can be done.

1.      Change Orchestra to run in memory mode instead of using a database for persistence (see Section 2.4 on Setup in the BSOA Orchestra Process Console User's Guide).  This can result in a three-fold increase in performance, but with the drawback that it is not possible to recover from a failure.

2.      See the section on Orchestra Tuning in the BSOA Orchestra Overview & Examples document, which lists several possibilities for tuning.