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.
A release of Shale includes several primary categories of materials:
shale-core.jar- Core framework functionality
shale-clay.jar- Clay plug-in
shale-designtime.jar- Optional design time integration with Sun Java Studio Creator 2
shale-remoting.jar- Standalone library for components and applications that wish to support asynchronous callbacks, such as AJAX requests.
shale-spring.jar- Optional integration layer with adapters for the Spring Framework
shale-test.jar- Unit test framework
shale-tiger.jar- Optional core extensions that are available if you are using Java SE 5 ("Tiger")
shale-tiles.jar- Optional integration layer with the standalone version of Tiles, currently under development as part of the Apache Struts project.
tiles-core.jar- For convenience, a copy of the Standalone Tiles distribution is included here, to avoid the requirement to extract it from the sample applications.
shale-blank.war- Very simple "starter" application that includes all of the configuration files and libraries that a typical Shale application will require.
shale-mailreader.war- Canonical Struts 1.x example application, converted to use JavaServer Faces and Shale facilities.
shale-sql-browser.war- Simple implementation of an SQL browsing application that illustrates dynamic changes to the JSF component tree.
shale-usecases.warOmnibus example application that illustrates the use of most Shale features.
shale-dependencies.tar.gz- For convenience, this is a snapshot of all the dependencies that would normally be downloaded by executing the download-dependencies target in the top level build script. Unpack this into the top-level directory of the framework distribution (it will create a lib subdirectory).
shale-dependencies.tar.gz- A starting point source directory structure for a Shale based application that will use Ant as the build tool. This is based on the source code of the Shale Blank Starter Application example, but separated out for the convenience of those who need only this feature. To create a new project:
shale-starterdirectory that is created to the desired name of your project directory.
README.txtdirectory of the new project to customize the default settings.
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 (
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
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:
shale-blank.war- Starter application that incudes the configuration files and libraries needed by most applications.
shale-mailreader.war- Conversion of the canonical Struts 1.x example "mail reader" application.
shale-sql-browser.war- Simple "SQL browser" application that illustrates dynamic component tree manipulation.
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
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.
 View file example in Use Cases is useless.
 Static members accessed in a non-static way.
 NullPointerException when Clay Jsfid parameter of Clay component has null value.
 Clay HTML parser has problem with the <a> tag.
 Fix issues with filter mapping in the Clay Plug-In.
 Clay initialization parameter names should be fully qualified.
 Remoting doesn't work with RI build.
 Clay symbol replacement in CreateComponentCommand.
 Symbol for action attribute on components does not get evaluated.
 Rendered attribute does not affect children.
 Clay not handling binding attribute correctly.
 ValidatorScript does not find validators in facets.
 LoadBundle basename property is not set.
 shale-mailreader-20060316.war could not be started. (r386550)
 The shale-blank application includes extra jars in WEB-INF/lib (r386897)
 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)
 Realphabetize imports and remove redundant ones.
 Default validator configuration should include rules.
 Name and location of validation rule file(s) should be configurable.
 Add spring like syntax for loading clay configs from classpath.
 Refactor ShaleViewHandler and ShalePhaseListener.
 Clay enhancement - reusable clay components.
 Add additional convenience accessors in AbstractFacesBean.
[-----] Allow configuration of a comma delimited list of validation
rules files under the init param
[-----] Include the default
validator-rules.xml file so that
users do not have to include a copy in
[-----] Add support for specifying validator parameters using nested
[-----] Improve functionality of
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
[-----] 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)
 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.
 Additional improvements to the HTML parser will be addressed in a subsequent release.
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.
 IFrames are a specific use case related to multiple simultaneous dialogs, so this issue will be addressed at the same time as 35066.
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.
 Dialog synchronization is not maintained when browser navigation buttons are used.
 RFE to add documentation (on the web site) for the Tiles and Remoting features, to be addressed in a subsequent release.
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
 Shale's Commons Validator integration ignores the immediate attribute when using client side validation.
 ShalePhaseListener executes ViewController.prerender twice. This will be resolved as part of a general exception handling strategy. See Bug 38186.
 Range validator doesn't check dependencies.
 RFE for a general exception handling strategy that fulfills ViewController contracts, and offers application developers some choices in how exceptions are handled.
 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).
 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.
 RFE for a phase listener to invoke a dialog without clicking on a button/link
 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.
 RFE for a "Dialog Aware" button panel component which would automatically generate next and previous buttons, disabling them as appropriate.
 Example applications that use dialogs may have problems when the session state is saved and then restored.
 RFE to support fine grained security on navigation.
 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.