Red Hat Web Application Framework 6.0 Release Notes

Table of Contents
1. Release Notes

1. Release Notes

These are the release notes for Red Hat Web Application Framework 6.0. They contain an overview of Red Hat WAF 6.0, an installation reference, a list of known issues, and an enumeration of significant changes since WAF 5.2.x.


1.1. Overview

The Web Application Framework is written in Java™ and provides a set of APIs for data storage, retrieval, and presentation. For more information, visit

An overview of the Red Hat WAF architecture can be found at

For information about the Red Hat Applications community, see You may also want to subscribe to the

1.2. Requirements

Red Hat WAF 6.0 requires a Java environment running 1.3.0 or 1.3.1. Please note that IBM JVM build 1.3.1 cxia32131-20020302 has a bug where BigDecimal hashcode values are generated inconsistently (IBM defect 51972), which will make for errors that are highly difficult to track down. This bug is fixed in SR2 and later versions of the IBM JVM. For performance and scalability reasons, Red Hat strongly recommends IBM JVM 1.3.1 SR4 or later on Red Hat Enterprise Linux.

Red Hat WAF 6.0 requires an RDBMS, either Oracle8i™ database, Oracle9i™ database, or PostgreSQL 7.3.3 or later. For optimum performance and stability, we strongly recommend Oracle9i version or PostgreSQL 7.3.3 - Red Hat Edition. The Standard Edition of Oracle database does not support online rebuilds of interMedia™ indices; users will need to either use Lucene for search or do offline rebuilds. Red Hat WAF 6.0 has been fully tested on Oracle8i, Oracle9i, Oracle9i, and PostgreSQL 7.3.3 - Red Hat Edition.

Red Hat WAF 6.0 requires a servlet container with support for Servlet 2.2 and JSP 1.1. Red Hat WAF 6.0 has been tested on Tomcat 4.0.6, Resin™ 2.1.4, and Resin 2.1.8.

1.3. What's New

Red Hat WAF 6.0 is a major release that features an overhauled persistence engine, a diff-based versioning system (as opposed to the old copy-based versioning scheme), and numerous new features and bug fixes.

Specific improvements in 6.0 include:

Diff-based versioning

The versioning service has been rewritten and now is based on storing differences instead of copies. This approach allows for increased functionality and scalability. The new system uses a more efficient approach to storage that reduces the amount of space required for versioning by 50%. The versioning service now is implemented at the data layer; VersionedACSObject is now deprecated. For details on how to use the new versioning service, see the Red Hat Web Application Framework Developer Guide.

New Persistence Engine

The persistence engine has been re-architected for greater extensibility and performance. New features include improved debuggability, transparent query caching, and APIs that expose the persistent event stream to other systems (notably, versioning).

Other Persistence Changes

It is no longer necessary to explicitly call save(). Changes are written to the database as necessary in order to maintain a consistent view of data. This has a number of implications:

  • Queries now automatically write changes to the database before executing. This means the old caveats about not seeing changes to data until save was called are no longer true.

  • Because of this autosave behavior, objects may be saved before save is called. This can result in database constraint violations for constraints that are not described in PDL. Specifically, if a property is required in the physical schema, but not required in PDL, then persistence may attempt to create the object on disk before it has all the necessary information, resulting in a not null constraint violation.

  • Objects can no longer be created and then thrown away. Previously it was possible to create data objects and then throw them away without calling save. Now, at the end of the transaction, persistence will attempt to save all outstanding changes to the database, including objects that have not had save called on them. Code that depends on the old behavior will either result in an error if there are any partially specified objects i.e., newly created objects that are missing required properties, or will result in extraneous data being created on disk.

  • The order in which data is saved is now automatically determined by persistence. This means if you do explicitly call save() or if persistence is required to write changes to the database it will automatically infer the correct order to execute SQL based on the constraints in the logical model. If your physical model has foreign keys that persistence doesn't know about, then it is possible for foreign key violations to occur when writing data.

Persistence now stores all in-memory data in a single data store associated with the session. All queries read data into the session data store. Previously each query executed would result in a new data object with a new copy of the data. This could result in data aliasing, i.e., situations where one copy of a data object had different data from another. This is no longer possible.

Single object retrieves are now cached. Previously Session.retrieve(OID) would hit the database and always return a new copy of a data object. Now persistence will only hit the database if that object isn't already in the session data store.

It is now legal when filtering or sorting to reference paths that have not been aggressively loaded.

Queries can be dynamically extended to retrieve more data via the new DataQuery.addPath(String) method. This is just like adding an aggressive load, but only effects a single invocation of the query.

The Session.flushAll() method has been added in order to allow all outstanding changes to be written to the database. The method will throw an error if there are any partially specified objects. This can be useful in tests where it is desirable to simulate some of the effects of committing the transaction without actually doing so.

PDL now supports SQL numeric sql data types with precision and scale specified.

Disconnected data objects now always return disconnected data objects when navigating through 0..1 or 1..1 associations.

1..1 constraints are rigorously enforced. Previously, violations of 1..1 constraints were allowed in many cases.

For data objects, only id properties can be accessed or modified until all of the id properties are set.

The "" is automatically converted to null for storage in the database. This makes PostgreSQL look like Oracle database with regard to empty strings and nulls.

The DataHandler API has been removed.

The WRAP_QUERIES option in PDL and setNoView() method for data queries are no longer supported. They were unsafe to use as filtering and ordering was not guaranteed to operate correctly without the view wrapping.

Link attributes can no longer be accessed with just the link attribute name passed to get(). The link attribute name must be prepended with link. This change eliminates the possibility of name conflicts between link attributes and attributes of the type being retrieved.

For SQL specified in PDL, the retrieve event is no longer used by default. Instead, the retrieve all event is used with appropriate filters applied for id properties.

When mapping columns to query properties, table prefixes are ignored. This means columns accessed by the query must be aliased to unique names.

UniqueConstraintExceptions are sometimes detected in Java and thus can occur earlier than before.

In PDL, the super keyword is deprecated. Instead, the default behavior is to include the super type event.

In persistence, clear events no longer exist. Instead, the persistence implementation of clear uses repeated remove events.

Many of the public accessors to mapping and physical metadata have been removed from the metadata classes in the com.arsdigita.persistence.metadata package.

com.arsdigita.persistence.TransactionListenerImpl has been renamed to com.arsdigita.persistence.AbstractTransactionListener in accordance with Java naming standards.

Multi-JVM Lucene search

The Lucene search service introduced in 5.2 now supports multiple JVMs.

PostgreSQL 7.3.x support

WAF now requires PostgreSQL 7.3.3 or later. The Red Hat edition of PostgreSQL 7.3.3 that is shipped with Red Hat Enterprise Linux is recommended for general use, as these packages have been specifically tuned to work with WAF, although the community packages will work without modification.

Screenname login support

Login with screennames is now supported. This option is configurable in enterprise.init.

Revamped Stylesheet system

The stylesheet system has a new set of classes for loading, resolving, caching, and applying XSL files that supplant the Stylesheet and BasePresentationManager classes with a more flexible and robust API.

MimeTypes in WAF

The MimeType system has been moved from the CMS into WAF so that other applications can take advantage of the system without depending on the CMS.

Improved support for WAF developers

  • Revamped assertion framework. The Assert class has been made to better avoid running assertion logic when assertions are disabled, and the new alternative static methods are shorter and more convenient.

  • The Tracer class, part of the com.arsdigita.util package, adds support for tracing the execution of complex traversal logic by tracking method entry and method exit. The class logs the output with appropriate indentation and the elapsed time of each method body.

  • Developer support now has a more open API to facilitate use by alternative user interfaces, provides a link to download SQL statements directly for debugging, and checks for read permission by the site-wide administrator.

  • A simple user interface for viewing the versioning log is now available. Set the debugInterfaceOn parameter to true to activate the UI, which is mounted as an independent servlet served via /versioning/.

  • The persistence engine can now output profiling data as XML.

Workflow notifications:

The workflow engine now has the ability to send email notifications at specific points (e.g., state changes) throughout the workflow cycle.

Dispatcher enhancements:

Support in the dispatcher for virtual hosting. In addition, the dispatcher now has an InternalPrefixerServlet that allows arbitrary prefixes to be added to web.xml. For more information, see the Javadoc.

New Developer Guide:

Due to the number of extensive changes in 6.0, the developer guide for Red Hat WAF has been reorganized and rewritten. A significant amount of new content has been added, while out-of-date content has been removed or updated.

Bug fixes

Numerous bug fixes to all aspects of WAF. All bug fixes available in WAF 5.2.x errata series as of August 15, 2003 have been merged into this release. See the WAF 5.2.x release notes for details of specific fixes.

The Section 1.7 Upgrading has technical details on how each of these systems have changed, if applicable.

1.4. License

Red Hat Web Application Framework 6.0 is copyrighted 1999-2003 by Red Hat Inc. It is released under the CCMPL 1.0. The text of the CCMPL 1.0 can be found at

The CCMPL is based on the OSI-approved IBM Public License Version 1.0 ( The IBM Public License is a true open source license that requires open-sourcing of any modifications or other "derivative works."

1.5. Installation

The most recent installation documentation is available at

1.6. Documentation

Documentation for Red Hat WAF, including installation guide, Javadoc, developer guide, and engineering standards, can be found at

1.7. Upgrading


Upgrading is a one-way, irreversible process. Thoroughly test the upgrade on a backup copy of your database before upgrading your production system.

This section contains upgrading information specific to this version of WAF. For detailed upgrading instructions, see the appropriate section of the Red Hat Web Application Framework Installation Guide.

Data Model


From a shell, change the working directory to sql/upgrade. Then, use SQL*Plus to load the necessary upgrade script(s). To upgrade from 5.2.1 to 6.0, type:

cd /var/www/ccm-core/dist/WEB-INF/sql/core/upgrade/
sqlplus scott/tiger < oracle-se-5.2.1-6.0.sql

Red Hat WAF 6.0 now requires version 7.3.3 or later of PostgreSQL. This includes the upgrade scripts. Therefore, the first step in upgrading your PostgreSQL data model is to upgrade your PostgreSQL installation to 7.3.3 or later.

The following URLs document the PostgreSQL installation upgrade process:

We recommend that you use the --blobs and --format=c flags for the pg_dump[all] command. Also, do not run createlang on your new database as this is done automatically by pg_restore.

Once you have upgraded to PostgreSQL 7.3.3, go to a shell and change the working directory to sql/upgrade. Then, use psql to load the necessary upgrade script(s). To upgrade from 5.2.1 to 6.0, type:

cd /var/www/ccm-core/dist/WEB-INF/sql/core/upgrade/
psql -d postgres < postgres-5.2.1-6.0.sql

save() is now declared final. Overriding this method in the past caused subtle bugs that were difficult to find; use beforeSave() and afterSave() instead.

The fundamental changes in the versioning system preclude an automatic upgrade of previously versioned objects. The upgrade scripts preserve this data in the database, but this data is not accessible through the user interface. The new versioning system maintains significantly more metadata about changes than the previous versioning system; regenerating this metadata based on the old versioning log would be laborious and error-prone.

Significant changes to enterprise.init have been made. We recommend you use the development RPMs and script to insure the correctness of your enterprise.init. There are many, many additional configuration options in enterprise.init that need to be double-checked and configured correctly. Existing enterprise.init files will need to be updated to work with 6.0.

1.8. Known Issues

No known issues.

1.9. Bug Reporting

Please file bug reports in the Red Hat Web Application Framework section of

Last modified: $DateTime: 2003/08/21 11:30:59 $