2009/05/20 - Apache Shale has been retired.

For more information, please explore the Attic.

Apache Shale (Version 1.0.2) Release Notes

1.0 Introduction

Welcome to the Apache Shale Framework. Shale is a next generation framework for building web applications using Java technology, and builds upon the framework and component APIs provided by JavaServer Faces.

This is the second milestone release of Shale, released to encourage experimentation and gather feedback on usage issues and requested features. This should be treated as an "alpha" quality release. However, many of the APIs in Shale are reasonably stable -- for details, see Shale API Target Audiences and Stability Ratings.

2.0 What Is Included

A release of Shale includes several primary categories of materials:

In addition to the standard Shale release distribution, the following examples and resources are available:

3.0 Changes From Previous Releases

3.1 New Features

Creator Design Time Support - Shale now includes the beginnings of design time support for importing Shale into Sun Java Studio Creator, a graphical IDE for building web applications based on JavaServer Faces. This support is not yet complete, or ready for use.

Shale Remoting - The previous functionality for supporting "remoting" application (in package org.apache.shale.remote) has been substantially revised and expanded in a new package (org.apache.shale.remoting). In addition, this support has been packaged in a separate JAR file (shale-remoting.jar) that has zero dependencies on the rest of Shale. See the package description for this package in the Javadocs for more information.

Shale Tiger Extensions - If you are running your servlet container on a Java SE 5 ("Tiger") or later JDK, you may use this optional library to reduce the need for configuring application metadata in faces-config.xml files, or having to implement a particular interface to receive View Controller services. See the feature description on the Shale website for more information.

New Sample Applications - New sample applications to illustrate the use of Shale features:

Test Framework Base Class for HTMLUNIT Tests - The test framework now includes a base class for building system integration tests of web based applications. It uses HTMLUNIT (from SourceForge) to simulate the client of the webapp, and then exposes the DOM of the retrieved page to examination by JUnit style test methods.

Test Framework New Mock Objects - The test framework now offers mock objects for ResponseWriter, ResponseStream, and Principal objects.

Shale Clay plugin - The Clay plugin has made several improvements with the help of the community. The most significant improvement is with the HTML template option. Several fixes were applied to in the template parser and to the nested template inclusion. The symbols feature became more stable and a example demonstrating symbols was added to the usecases project. The example features the usage of symbols to create generic tiles like page layouts. In addition, an example of using full XML views was added to the symbols example. The full XML views allow the page entry point to be defined in a XML document conforming to the Clay DTD similar to tiles definitions. These page definitions can be centrality located in a single XML document or defined for each view. The Clay documentation also underwent improvements. A new introduction and story on using HTML views was added. The composition options and reuse features were expanded on.

3.2 Bugfix Issues

[36884] View file example in Use Cases is useless.

[37364] Static members accessed in a non-static way.

[37796] NullPointerException when Clay Jsfid parameter of Clay component has null value.

[37821] Clay HTML parser has problem with the <a> tag.

[37867] Fix issues with filter mapping in the Clay Plug-In.

[38058] Clay initialization parameter names should be fully qualified.

[38157] Clay <TH> bug.

[38190] Remoting doesn't work with RI build.

[38314] Clay symbol replacement in CreateComponentCommand.

[38492] Symbol for action attribute on components does not get evaluated.

[38493] Rendered attribute does not affect children.

[38542] Clay not handling binding attribute correctly.

[38593] ValidatorScript does not find validators in facets.

[38784] LoadBundle basename property is not set.

[39015] shale-mailreader-20060316.war could not be started. (r386550)

[38972] The shale-blank application includes extra jars in WEB-INF/lib (r386897)

[39028] SQL Browser app includes extra jars in WEB-INF/lib. Exclude the unnecessary jars, and retrieve derby.jar from ibiblio in the download-dependencies task. (r386921)

[-----] Fix two Clay configuration parsing bugs.

[-----] The "styleClass" attribute was duplicated in the Clay base configuration file resulting in an invalid "bindingType".

[-----] Fix two Java 1.4 API compatibility issues. (r386527, r386402)

[-----] Fix issues with links and JavaScript in the Use Cases example application. (r386127, r386123)

3.3 Request For Enhancement Issues

[37504] Realphabetize imports and remove redundant ones.

[38042] Default validator configuration should include rules.

[38044] Name and location of validation rule file(s) should be configurable.

[38168] Add spring like syntax for loading clay configs from classpath.

[38185] Refactor ShaleViewHandler and ShalePhaseListener.

[38482] Clay enhancement - reusable clay components.

[38510] Add additional convenience accessors in AbstractFacesBean.

[-----] Allow configuration of a comma delimited list of validation rules files under the init param org.apache.shale.validator.VALIDATOR_RULES.

[-----] Include the default validator-rules.xml file so that users do not have to include a copy in /WEB-INF.

[-----] Add support for specifying validator parameters using nested s:validatorVar tags.

[-----] Improve functionality of LoadBundle and Messages such that the "map" property is not required in value binding expressions.

[-----] Add JSF-friendly helper methods to access bean properties; first step towards removing core dependency on Commons Beanutils.

[-----] Add JSF-friendly helper methods to perform type conversions; second step towards removing core dependency on Commons Beanutils.

[-----] Flesh out operation of many test framework methods that formerly threw UnsupportedOperationException.

[-----] Add the "description" element to describe the element it is nested in to elements in the Clay DTD.

[-----] Add Cargo integration to the Use Cases example application. (r386541)

[-----] Change the Maven groupId for Shale to org.apache.struts.shale. (r385723, r385724, r385727)

4.0 Known Issues In This Release

[35066] The Dialog feature has known problems with attempting to have multiple simultaneously active dialogs in a single session (most commonly due to using frames or multiple windows), and dealing with back buttons. These issues will be addressed in a subsequent release.

[35839] Additional improvements to the HTML parser will be addressed in a subsequent release.

[37024] The Shale contribution to addressing this issue is to ensure that META-INF/clay-config.xml resources from JAR files loaded as part of the application are automatically loaded. This will be addressed in a subsequent release. The actual configuration resources for a given component library such as Tomahawk, however, should be provided by the component library itself rather than by Shale.

[37120] IFrames are a specific use case related to multiple simultaneous dialogs, so this issue will be addressed at the same time as 35066.

[37361] There is a bug in the MyFaces implementation of validation that causes the Use Cases example app to fail, where it works with the RI. The corresponding MyFaces issue is here. Leaving this bug open (with state REMIND) as a reminder to flag this issue in Shale release notes until it is resolved in a subsequent MyFaces release.

[37571] Dialog synchronization is not maintained when browser navigation buttons are used.

[37643] RFE to add documentation (on the web site) for the Tiles and Remoting features, to be addressed in a subsequent release.

[37707] Several classes that need to be serializable (because they could be stored in session scope) are not currently. In addition, two classes inherit an implements Serializable declaration from their superclass, but are not themselves able to be serialized. This does not cause a problem using the classes in Shale, because such instances are never stored into session scope, but will be flagged by code audits that check for this scenario.

[37932] Shale's Commons Validator integration ignores the immediate attribute when using client side validation.

[38000] ShalePhaseListener executes ViewController.prerender twice. This will be resolved as part of a general exception handling strategy. See Bug 38186.

[38079] Range validator doesn't check dependencies.

[38186] RFE for a general exception handling strategy that fulfills ViewController contracts, and offers application developers some choices in how exceptions are handled.

[38187] RFE for ViewController to support init/destroy callbacks into objects that are inserted into, or removed from, any of the servlet API scopes (request, session, application).

[38189] RFE to extend the capability of the servlet event callbacks to work with classes that mark init and destroy methods with annotations, not just those that implement a specific interface.

[38298] RFE for a phase listener to invoke a dialog without clicking on a button/link

[38627] RFE to make the HtmlUnit dependency optional, or modify the build so that it is automatically downloaded. Currently the build fails if you do not have the htmlunit.home property defined.

[38809] RFE for a "Dialog Aware" button panel component which would automatically generate next and previous buttons, disabling them as appropriate.

[38825] Example applications that use dialogs may have problems when the session state is saved and then restored.

[38849] RFE to support fine grained security on navigation.

[38970] When run in GlassFish, the Clay examples from usecases demo output Sun's state field marker. To be addressed when Clay support for JSF 1.2 is considered.