
Copyright (C) The Apache Software Foundation. All rights reserved.

A new version of the PSS service has been implemented under the Apache
Avalon Apps Enterprise subproject.  This document contains an overview 
of the changes impleemeted under that release relative to the OpenORB
PSS relase.

The Apache PSS is available via CVS:

  jakarta-avalon-apps/enterprise/orb    - an extended ORB based on OpenORB
  jakarta-avalon-apps/enterprise/ots    - local copies of the OpenORB ORS package
  jakarta-avalon-apps/enterprise/pss    - the PSS service


======================================================================
copy of the Appache PSS service readme
======================================================================

Apache PSS Service

Description

This is an implementation of the OMG PSS (Persistent State Service) based 
on the specification defined under the OMG document number ptc/01-12-02.pdf.  
The implementation is derived from the object model published under the 
OpenORB Community Project 1.2.1 PSS version (a fork of the original Exolab 
open-source project). Due recognition is hereby given to Exolab. Rights 
related to revisions and enhancements copyright Apache Software Foundation.

Assumptions

  The ANT version used to build this module is 1.4.1.
  The ant library and optional.jar file can be downloaded from the 
  following location: 

  http://cvs.apache.org/viewcvs/jakarta-avalon/tools/lib/

Dependencies

  The PSS implementation is dependent on the 1.2.2 CVS version of OpenORB
  (as at 28-FEB-02) from the Community OpenORB Project.  Changes to OpenORB 
  1.2.2 have been made to some utility classes enabling improvements in compiler  
  javadoc management - specifically, the replication of javadoc utility functions
  under the IDLtoJava compiler class to static functions under the 
  org.openorb.compiler.idl.util.tools class.  PSS is also dependent on 
  the Community OpenORB OTS service 1.2.1.

  Dependent OTS and ORB libraries are available in the following packages:

     enterprise/tools
     enterprise/orb
     enterprise/ots

Build Instructions

  Make sure you have checked-out the enterprise packages tools, orb and ots
  before building pss.  After the pss package is checked-out, execute the 
  following from the enterprise/pss directory:

  $ ant help // for a overview of build targets
  $ ant all // to build the compiler, PSS runtime, javadoc and test compilation

Distribution Directory

  Following completion of a build, the distribution directory will 
  contains the following files:

  LICENSE.HTML, license and due credits
  psdl-2.x.y.jar, the PSDL compiler
  pss-2.x.y.jar, the PSS runtime

Changes introduced in the PSS 2.0 implementation (FEB 2002)

  1. Package names for implementation classes have been changed from 
     "org.openorb.pss" to "org.apache.pss" - this change
     reflects the divergence from the classic OpenORB implementation 
     enabling the potential for more rigorous implementation enhancements
     concerning logging, configuration and error management consistent with 
     the Apache Avalon patterns and interfaces. 
  2. Upgrading of the implementation to the final adopted and available 
     specification (FTF results as detailed under the ptc/01-12-01.pdf
     report and summarised under the revised specification ptd/01-12-02.pdf.
  3. The source base for this PSS implementation is a result of the 
     decompilation of the OpenORB PSS binaries (resulting in elimination 
     of redundant code and generation of consistent code layout and 
     structure), reformatting of generated sources to be compliant with
     the established project coding conventions, and enhancement to the 
     code base concerning generation of javadoc comments in generated code.
  4. Documentation of license dependencies, due credits and declaimers. 
  5. Substantial enhancements to the javadoc generation capability, 
     creation of documentation for all packages, documentation of all 
     classes, detailed documentation included in a new edition of the 
     CosPersistentState.idl IDL source.
  6. Separation of compiler from PSS runtime distributions.
  7. Elimination of bugs in the file connector that result in 
     non-availability of persistent data following a server restart.
  8. Extensive introduction of exception handling across all connectors
     and the propagation of errors through cascading exceptions.
  9. Introduction of Apache LogKit as a fallback logging mechanism if 
     the interceptor is not provided with an logger during initialization.
 10. Introduction of defaults configuration using Avalon Configurable
     interfaces and related implementations.

Version and Status

  Published version 2.0.1
  Status: BETA - please note that the beta status is attributed in 
  order to reflect a higher expected change cycle that may impact 
  binary compatibility.  This is required to facilitate sufficient 
  freedom to enable introduction of architectural and implementation 
  enhancements.

Migration Notes.

  Replace any occurrences of the string "org.openorb.pss"
  with "org.apache.pss" (including the reference in the PSS module 
  implementation class in the OpenORB.xml file.  Recompile all 
  PSDL sources using the PSDL compiler class 
  org.apache.pss.compiler.PsdlCompiler.

  The FTF adopted recommendations eliminate the CatalogRepository and 
  CatalogRepositoryHelper classes.  This effects the approach used to 
  resolve an inital reference related to PSS.  The initial specification
  required the supply of a CatalogRepository in response to an initial 
  reference against the string "PSS".  The revised specification treats the
  initial reference argument as a qualified argument composed of "PSS:" +
  "<vendor-identifier>:" + "<vendor-specific-value>".  Under the Apache PSS
  implementation the following three initial reference arguments are 
  supported:

    "PSS:APACHE:file"
    "PSS:APACHE:database"
    "PSS:APACHE:memory"

  The value returned from any of these initial reference arguments will
  be a PSS Connector instance.  Users should narrow the returned value 
  using the org.omg.CosPersistenceHelper.narrow() operation (refer to the
  JavaDoc - org.apache.pss.Initializer for code sample).
