The Community OpenORB - ConcurrencyControlService

Jerome Daniel

Marina Daniel

Michael Rumpf

Table of Contents

1. Overview
2. Compilation
3. Installation
4. Configuration
5. Deployment
How launch the OpenORB PSS examples?
A quick overview of the PSDL
The PSDL Compiler
The PSDL Compiler Ant Task
6. Frequently Asked Questions
A. Appendix


This document provides all information on how to download, install, run and test the OpenORB PersistentStateService.

Chapter 1. Overview

The OpenORB Persistent State Service (PSS) is a fully compliant implementation of the Persistent State Service specified by O.M.G. With the PSS, you always use the same API to manipulate persistent data for any kind of datastore.

The Persistent State Service requires a specific description language to describe the persistent structures. That language called PSDL (Persistent State Description Language) is a supset of the CORBA IDL. A PSDL description is compiled to automatically generate data, structures and API required by the PSS implementation. The generation is bound to a datastorage type.

A persistent data described with PSDL is called a storage type. These data are stored into an entity called a storage home (a storage home can be viewed as a table in database). Several Java classes are generated for storage types and storage homes. These API are portable and independant of the real datastore used to store the persistent data.

The connector is the entity that makes the link between the API (storage type and storage home) and the datastore.

OpenORB PSS provides two connectors (the link between the API and the datastore) :

  • a file connector: this connector can be used to store persistent data into a file.
  • a database connector: this connector uses JDBC to store persistent data into a database.
  • a memory connector ! as the connector can be selected in the application, by using the same API you are able to provide persistent or transient data !

The OpenORB implementation of PSS provides several high valuable features :

  • a PSDL compiler
  • a file connector with basic session, transactional session and session pool
  • a database connector with basic session, transactional session and session pool
  • a memory connector with basic session only.

To use the Persistent State Service, you need the OpenORB distribution and the OTS distribution.

Chapter 2. Compilation

The Persistent State Service distribution contains an Ant script. If you use the build.bat (for windows) or (for unix) all dependencies and required classpath are directly used.

Thus, to compile the OpenORB Persistent State Service, we advise you to enter the following command from the command line : build or sh You will find the openorb_pss-{version}.jar file in the dist directory.

Chapter 3. Installation

Chapter 4. Configuration

This pss module defines properties used by the Persistent State Service, a first subset of these properties are used with the File connector:

  • PSS.File.DataStore.Directory: specifies the directory where the file is created to store persistent data. The specified directory must be previously created before running the application that uses the PSS.
  • PSS.File.DataStore.Name: the file name
  • PSS.File.FlushTime: each connector maintains a cache to store data during a short period of time. A flush time is set to specify the time between each cache flush. This property is used to specify this time in seconds.
  • PSS.File.Transaction.IsolationLevel: specifies the isolation level for transactions.

This module also defines a property which is used with database:

  • PSS.Database.Transaction.IsolationLevel: this properties sets the isolation level for databases.
You have to customize the previous properties to use the PSS. However, if you plan to only use the File connector, it is not required to customize the Database properties.

Databases don't use the same SQL data type to specify binary objects. Some databases use 'binary' and some other one 'blob'. For example, Sybase uses 'binary' and Oracle 'blob'. By default, the OpenORB Database connector is using the 'binary' data type. If your database uses 'blob', you have to add a property in the profile :

  • PSS.Database.sql_type: for blob, just put blob .

A Server application that uses PSS has to start with a profile that includes the previous module pss.

The PSS is only used on the Server side by the application that want to provide persistent data. Thus, it is not required to start the client application with the pss profile (excepted if this client application also manages persistent data !!).

Then, you start your server application thanks to the following command line: java myServerThatUsesPSS -ORBProfile=pss

The OpenORB Persistent State Service can also use the OpenORB Transaction Service to provide transaction session when writing a persistent data (in this case, only the File and Database connectors could be used).

If you want to use the Transaction Service in addition to the PSS, you have to define a profile that imports both transaction service and persistent state service modules ! For example :

			<profile name="transactionalpss" extends="default" >
			<import name="transaction" />
			<import name="pss" />
			</profile >
If you define the previous profile, be sure that the transaction module is imported before the pss module.

To complete the configuration, we have to replace the embedded configuration by the new one. The way to do that depends on the distribution that you are currently using: source code or pre built distribution. The following paragraphs describes how to proceed for each distribution kind.

In the source code distribution an Ant target is provided to replace the embedded configuration file. From the command line: build config The new configuration file must be available in the src/config directory. Moreover, the Jar file where the configuration will be output must be available in the dist directory. In the pre built distribution the config directory contains a script named setConfig ( setConfig.bat for Windows and for Unix ). We have just to start this script to replace the embedded configuration file. The new configuration file must be available in the config directory. Moreover, the Jar file where the configuration will be output must be available in the lib directory.

Chapter 5. Deployment

How launch the OpenORB PSS examples?

If you have built the Persistent State Service with the build or sh command, the Persistent State Service examples are already built.

Otherwise, use the following command to build the PSS examples: build examples You will find the several jar files in the dist/examples directory, one for each example.

To launch the examples, you have to specify that you use the PSS profile with the flag -ORBProfile=persistent

For each example, set the classpath with the corresponding jar file and the openorb_pss-{version}.jar and check whether you have configured the OpenORB.xml file properly.

For example in Basic Session:

  • launch the server with: java Server -ORBProfile=pss
  • launch the client with: java Client

For examples in Transactional Session (except for Memory Persistence which does not support transactional sessions):

  • launch the OTS.
  • launch the server with: java Server -ORBProfile=transactionalpss
  • launch the client with: java Client -ORBProfile=ots

A quick overview of the PSDL

The PSDL (Persistent State Description Language) is a new description language to describe persistent data.

The PSDL is an extension of IDL. It means that you can use all IDL descriptions with PSDL.

There are two parts into a PSDL description:

  • an abstract description part
  • a concrete description part

The abstract description part is very important, because this is the part that provides portability! In this part, you describe persistent data and their home:

  • abstract storage type
  • and abstract storage home

The abstract storage type defines local operations and states (persistent states).

For persistent state, the following syntax must be used: state state_type state_name; Example: state string name

Any kind of IDL type is valid for state type. The state access may be limited by the readonly key word. Example : readonly state float price; Local operations example: void print();

To describe an abstract storage type, you have to use a specific key word 'abstract storagetype'

			abstract storagetype Person
				state string name
				state string address

				void print();

Abstract storage types support multiple inheritances. They are managed by abstract storage homes. An abstract storage home contains:

  • local operations
  • keys
  • factories

Keys are additional structures to provide an easy way to find a storage type. Here is how to declare a key: key key_name ( states names ); The key member names must be a state name of the managed storage type.

A factory description provides a way to create new persistent data. Here is how to declare factories: factory factory_name ( states names );

An abstract storage home is declared by:

            abstract storagehome PersonHome of Person
				key name;
                factory create ( name, address, age );

Abstract storage homes support multiple inheritance. The second part of a PSDL description is a for concrete descriptions. There are two types of concrete descriptions:

  • concrete storage type
  • and concrete storage home

A storage type implements one or several abstract storage types.

            storagetype PersonBase implements Person
			{ }
A storage home implements one or several abstract storage homes.
			storagehome PersonHomeBase of PersonBase implements PersonHome
			{ }

To develop portable applications and multi connector applications, it's better to use only abstract storage type and home to define states, local operations, keys and factories. This is the reason why, in the previous example the storage type and storage home content is empty!

A good way to understand PSDL is to study the examples provided with the OpenORB Persistent State Service distribution.

The PSDL Compiler

The OpenORB Persistent State Service provides a PSDL compiler. To start the compiler, enter the following command name: java org.openorb.pss.compiler.PsdlCompiler By default, the compiler generates file for the memory connector (in order to use the PSS API to develop transient applications). In addition to the PSDL option flags, all standard OpenORB IDL flag are available!

The PSDL Compiler Ant Task

OpenORB provides an Ant task that eases the use of OpenORB PSDL compiler. The Ant task can be easily included in your projects by using the taskdef tag. The task does additionnal uptodate checks and only compiles idl files which are more recent than the target Java files. This is done using a cache (in a file called psdl2java.cache by default) which is updated every time the compiler is run.

             <project name="myproject">
               <taskdef resource="">

You only need to reference the openorb_tools-<version>.jar and openorb_pss-<version>.jar in the classpath of your build. The source files are set using a nested FileSet task which means that it possible to specify a whole tree of files to be compiled. It is possible to refine the set of files that are being compiled. This can be done with the includes, includesfile, excludes, and excludesfile attributes. With the includes or includesfile attribute, you specify the files you want to have included. The exclude or excludesfile attribute is used to specify the files you want to have excluded. In both cases, the list of files can be specified by either the filename, relative to the directory(s) specified in the srcdir attribute or nested <src> element(s), or by using wildcard patterns. See the section on Ant Manual,directory-based tasks, for information on how the inclusion/exclusion of files works, and how to write wildcard patterns.

srcdirLocation of the idlfiles files.Yes, unless nested <src> elements are present.
destdirLocation to store the generated java files.generated will be used if nothingspeficied.No
includesComma- or space-separated list of files (may bespecified using wildcard patterns) that must be included; all .idl files are included whenomitted.No
includesfileThe name of a file that contains a list of files toinclude (may be specified using wildcard patterns).No
excludesComma- or space-separated list of files (may bespecified using wildcard patterns) that must beexcluded; no files (except default excludes) are excluded when omitted.No
excludesfileThe name of a file that contains a list of files toexclude (may be specified using wildcard patterns).No
includepathThe path where other included IDL files can be found.This is a path structure and should contain comma- orspace-separated list of directories. An additionnal resource protocol for loading from JAR files can be used (prepend to directory name, e.g. resource:/org/openorb/idl/) if includeorbidl is set to true (by default).No
quietsuppress any outputNo
exportGenerate a Java class for each Service Type that exports an offer; defaults to yes.No
databasepersistenceSelect Database persistence; defaults to no (memory persistence).No
packagePackage name for the generated code.No
persistencetypeSelect persistence type; possible values are memory (default), file and database.No
generateapiGenerate the standard API from PSDL; defaults to yes.No
generatewrapperGenerate wrapper from PSDL; defaults to yes.No
externalwrapperSet the name of an external wrapper for file generation.No
verboseShows debug output; defaults to no.No
jdk14codeGenerates classes that use JDK1.4 features. The generated classes will not compile on previous versions;defaults to noNo
generateallGenerate mapping for included files; defaults tono. Be careful when using this option with the uptodatechecks as the cache is not notified of the included idl files.No
uptodatechecksIndicates if the compiler is doing uptodate checks on idl files and target java files; defaults to yes.No
cachefileIndicates where to place the compiler cache file; defaults to psdl2java.cache.No


<psdl2java destdir="${gensrc.dir}/main"
       includes="Naming.psdl" />

Chapter 6. Frequently Asked Questions


6.1. ?



Appendix A. Appendix