Java Solaris Communities Partners My Sun Sun Store

United States Worldwide

Research Home
»	Spotlight Articles
»	Projects
»	Publications
»	People
»	Awards
»	Events
»	Downloads
»	Internships
»	Contrarian Minds
»	About Sun Labs

Converting to PJama 1.x

There are three changes that you need to be aware of when converting from PJama 0.x to PJama 1.x,

Several of the command line options have changed or removed. In particular, options that would be appropriate for any implementation of OPJ are now specified without the -X prefix, in keeping with standard options for the virtual machine.
The way that the persistent store is specified has changed. In PJama 0.x the actual pathname of the (single) file representing the persistent store was provided on the command line with the -Xstore argument. In PJama 1.x, stores can span several files, and so a configuration file that provides the locations (and other information) must be created and passed on the command line. Although the -store keyword is still accepted, the argument is treated as a configuration file. A new alias -config is now recommended as a replacement. Standard sample configuration files are provided with the release - see here for details.
PJama 1.x supports the new API defined in the OPJ specification. Help on converting to this API is provided below.

Converting to the New OPJ API

We strongly recommend that you convert your applications to use the new API. In this section we explain how to transform programs written using the old API. The old API is still supported and, with a couple of exceptions, works as before, but it is deprecated and will be removed in the next major release.

In general, the new API is substantially simpler, and results in a reduction of boilerplate code.

Persistent Store

In the old API, the persistent store was explicitly represented by the PJStore interface and the PJStoreImpl class. In the new API, the persistent store is implicit and the relevant features of PJStore have been moved into the OPRuntime class. In particular, the PJStore.stabilizeAll method has been replaced by OPRuntime.checkpoint.

`Persistent Store Creation`

Applications no longer create persistent stores explicitly through the API. Persistent stores are created implicitly if necessary when the "-store" argument is specifed as a command line argument to the OPJ Virtual Machine. This means that an application can be written with the assumption that the store exists, which is one less special case for the programmer to deal with.

Persistent Roots

The way that persistent roots are specified has changed significantly in the new API. The change was motivated by the focus in the OPJ specification on persistent computation where it is expected that non-persistent objects are the exception rather than the rule. In general, if an object is (persistence) reachable when a checkpoint occurs, then it will (must) be made persistent to maintain the semantics of the computation correctly. This approach is strongly tied to using (persistent) threads as the roots of reachability. However, since our current prototype still does not support persistent threads, it continues to be necessary to establish explicit roots of persistence. To maximize the persistence independence of source code, we have also provided some convenience options to the OPJ Virtual Machine that handle root registration.

In the old API, persistent roots were created by the newPRoot method of PJStore, and were registered under a user-provided name. Choosing this name could be a problem, since the root names had to kept unique. One general solution was to prefix the name with the fully qualified name of the class that the root was associated with. An equivalent approach is to exploit the naming mechanisms of the Java language directly, by using static variables as roots, since these are guaranteed to be unique. Accordingly, the new API simply provides a set (actually a java.util.Set) in the variable OPRuntime.roots, with the expectation that instances of java.lang.Class will added to this set, and that static variables in such classes will acts as roots. The following class demonstrates the new API and, at the same time, shows how the previous style of API can still be supported if required.

package com.acme.util;

import java.util.Hashtable;

import org.opj.OPRuntime;

public class NamedRoots {

  static { OPRuntime.roots.add(com.acme.util.NamedRoots.class); }

  private static Hashtable table;

  public void setPRoot(String name, Object root) {

    table.put(name, root);

  public Object getPRoot(String name) {

    return table.get(name);

In the old API, many applications detected the first run of the application by testing for the absence of a persistent root. This idiom can still be supported by testing instead for a null value in the static variable that denotes the root. For example, using the old API, one might write this:

PJStore pjs = PJStoreImpl.getStore();

Object myRoot = pjs.getPRoot("myRoot")

if (myRoot == null) {

  myRoot = ... // create root object

  pjs.newPRoot"(myRoot". myRoot);

In the new API, the above would be replaced by:

static Object myRoot;

static { OPRuntime.roots.add(Main.class); }

if (myRoot == null) {

  myRoot = ... // create root object, the assignment establishes persistence reachability

Note that the new API code will work regardless of whether the application is running with a persistent store, whereas the old code will fail in the getStore call. Of course, without a persistent store, the myRoot variable will always be null.

Implicit Root Registration

The OPJ Virtual Machine provides two convenience options that avoid having to explicitly register classes as roots in the source code, which can, in many circumstances, allow an application to be executed under OPJ without any source changes. The basic option is "-classroot classname". This option causes the class "classname", which must be a fully qualified name, to be loaded, initialized, if this has not been done in a previous run, and added to the root set, immediately prior to the invocation of the main class. For example, the NamedRoots class, defined above, could be modified to remove the call to OPRuntime.roots.add and instead this could be achieved by adding "-classroot com.acme.util.NamedRoots" to the command line.

The second option. "-mainroot", is simply a special case of the first, and is equivalent to "-classroot mainclass".

Action Handlers

The old PJActionHandler API works as before, but we encourage you to convert to the new event listener API in OPRuntime. This API follows the conventions of the standard Java event model.

Using the Old API

If you currently use opjcs to create your stores, you can continue to do so. Otherwise, you must convert your code as the PJStoreImpl(name) constructor is not supported.

There is one other situation where the old API does not work as expected. In the run of an application in which the store is (implicitly) created, the PJStoreImpl.getStore method throws an NoStoreException exception. The easiest way to finesse this is to use opjcs to create an empty store and then run the application.

Last changed: Dec 7th 1999

Questions and comments to forest-info@sunlabs.com