• Introduction
• What Is Included
• Changes From Previous Releases
• Known Issues In This Release
• Detailed Change Log

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.

To download the binary release artifacts, go here, select an appropriate mirror, download the corresponding zip files, and check the checksums and digital signatures. In addition, the individual JAR files are available in the default Maven 2 repositories, using artifact identifiers described below in Section 2.2.

This is the third milestone release of Shale, released to encourage experimentation and gather feedback on usage issues and requested features. A final vote on quality has yet to take place for this release, but it will likely be voted to be of "beta" quality due to the following issues:

• Outstanding bugs in the Dialog feature implementation.
• Reliance on a snapshot of the unreleased Standalone Tiles package.

However, many of the APIs in Shale are reasonably stable -- for details, see Shale API Target Audiences and Stability Ratings.

The largest change in this release is that Shale has switched over to using Maven 2 as its build tool. In turn, this has affected the content and format of the release artifacts themselves, and also introduces the availability of individual artifacts in publicly available Maven 2 repositories. See the following section for more information.

2.0 What Is Included

2.1 Release Artifacts

Shale is released as a series of zip files, each of which contains the binary deliverables, as well as the corresponding source code. In addition, if you have Maven 2 (version 2.0.4 or later) installed, you can rebuild the contents of each zip, by positioning to the top level directory in a command shell, and typing mvn install from there.

The following release artifacts are available:

• shale-framework-1.0.3.zip - Contains source code, javadocs, and compiled libraries for the standard Shale libraries, plus copies of dependent JAR files that are also required. The following Shale libraries are included:
  • shale-core-1.0.3.jar - Core Shale features (required for any application using Shale except one that only uses Shale Remoting)
  • shale-clay-1.0.3.jar - Clay Plugin (required to use the Clay alternate view handler)
  • shale-remoting-1.0.3.jar - Standalone library supporting static and dynamic resource downloads for AJAX applications and components
  • shale-spring-1.0.3.jar - Library providing lightweight integration with the dependency injection capabilities of the Spring Framework
  • shale-test-1.0.3.jar - Library of mock objects and JUnit test case base classes for building unit tests for JSF-based web applications and components
  • shale-tiger-1.0.3.jar - Optional library providing additional features for applications running on Java SE 5 "Tiger" or later releases
  • shale-tiles-1.0.3.jar - Library providing integration with the Standalone Tiles package from Struts
• mailreader-jpa-1.0.3.zip - Java class library containing Java Persistence Architecture (JPA) entity classes, and a corresponding Persistence Unit configuration, for use by the shale-mailreader-jpa example application.
• Other shale-xxxxx-1.0.3.zip archives - Each of the following archives contains the source code and javadocs for a sample application using Shale, plus a WAR file that can be dropped directly into your servlet container to run the sample. The following sample apps are included in this release:
  • shale-blank-1.0.3.zip - Simple base application that can be used as a starting point for developing your own application that depends on Shale
  • shale-clay-usecases-1.0.3.zip - A simple "Rolodex" application implemented in several ways to show off the capabilities of the Clay Plug-In
  • shale-mailreader-1.0.3.zip - A transcription of the canonical Struts "mail reader" example application, using an XML document to simulate the database.
  • shale-mailreader-jpa-1.0.3.zip - A modernized version of the mail reader example that uses a database to store the data, and JPA entity classes to access it (requires a Java EE 5 application server)
  • shale-sql-browser-1.0.3.zip - Simple SQL browser application that illustrates features from the shale-tiger.jar library, as well as dynamically building a JSF component tree
  • shale-usecases-1.0.3.zip - Contains miniature sets of pages showcasing various features of the Shale Core library

2.2 Maven Repository Artifacts

Beginning with this release, the various JAR files that are included in the framework release artifact have also been published to public Maven 2 repositories. If you are using Maven 2 to build your apps, you need only declare dependencies on the following identifiers (group id, artifact id, and version number), and Maven 2 will automatically download Shale (and its dependencies) for you.

• org.apache.shale:shale-core:1.0.3 - for shale-core-1.0.3.jar
• org.apache.shale:shale-clay:1.0.3 - for shale-clay-1.0.3.jar
• org.apache.shale:shale-remoting:1.0.3 - for shale-remoting-1.0.3.jar
• org.apache.shale:shale-spring:1.0.3 - for shale-spring-1.0.3.jar
• org.apache.shale:shale-test:1.0.3 - for shale-test-1.0.3.jar
• org.apache.shale:shale-tiger:1.0.3 - for shale-tiger-1.0.3.jar
• org.apache.shale:shale-tiles:1.0.3 - for shale-tiles-1.0.3.jar
• org.apache.shale.extras:mailreader-jpa:1.0.3 - for mailreader-jpa-1.0.3.jar

3.0 Changes From Previous Releases

Details on all of the included changes are in Section 5, below. The following sections highlight the most important changes.

3.1 New Features

Maven 2 Based Build Environment - Shale now uses Maven 2 to build its constituent artifacts, and is made available in public Maven 2 repositories to facilitate use in applications that are also built with Maven 2.

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

• shale-clay-usecases - A sample "Rolodex" application implemented in several different ways to illustrate the use of the Clay Plug-In feature of Shale.
• shale-mailreader-jpa - Conversion of the canonical Struts 1.x example "mail reader" application, using a database to store the persistent information, and accessing it using the new Java Persistence Architecture API that is part of the Java EE 5 platform.

3.2 Improvements

Exception Handling Strategy - Exceptions thrown by application event handlers will be accumulated during the request processing lifecycle. By default, control will be forwarded to the error handler page defined by the application, but this behavior can be customized.

Additional View Controller Events - By implementing an appropriate base class, model beans can receive init() and destroy() callbacks for request scope, session scope, or application scope. If you are using the Tiger Extensions library, these features are also available via annotations.

Test Framework Support for Cargo - It is now possible to build unit tests, using the Test Framework, that uses the Cargo Maven plugin to automatically start and stop your servlet container.

Clay Plug-In Improvements - FIXME ... identify the highlights of what has improved.

3.2 Bugfix Issues

View Controller event callbacks - Fixed various bugs where event callbacks were being done twice or not at all.

Token Component - Fixed issues with the Token component that prevented its use when an application returned to the current page with validation errors.

Commons Validator issues - Various problems with the integration of Commons Validator were fixed.

4.0 Known Issues In This Release

Follow this link for a detailed Road Map of upcoming versions of Shale. The following paragraphs highlight only the most important issues.

Dialog Feature - Several outstanding JIRA issues focus on functional problems with the implementation of the Dialog feature. Fixing these problems will be a high priority goal for the next release of Shale, although they might also require some backwards incompatible changes in the current Dialog APIs.

Standalone Tiles - Shale has a dependency on the Standalone Tiles package, currently in the Struts Sandbox and not yet released. This needs to be resolved before a General Availability release of Shale can occur.

5.0 Detailed Change Log

5.1 Bug

• [SHALE-24] - [Shale] No clay component configuration for MyFaces Tomahawk
• [SHALE-30] - ShalePhaseListener executes ViewController.prerender twice after exception
• [SHALE-41] - [shale] Missing binding attribute in clay-config.xml
• [SHALE-177] - s:token tag allows submit after displaying validation error
• [SHALE-180] - [Shale] generates JavaScript for components that are not rendered
• [SHALE-182] - s:token tag doesn't allow sending a form, when any validation error occurs on page
• [SHALE-185] - @Value is too restrictive on naming
• [SHALE-194] - javascript validation function errors in Shale 1.0.3
• [SHALE-195] - strange behaviors in rolodex with clay use case example
• [SHALE-198] - Subview Component not compatible with Tiger Extensions handling of view controllers
• [SHALE-203] - Symbol tag generates ClassCastException
• [SHALE-205] - 20060629 nightly missing org/apache/shale/remoting/Bundle.properties
• [SHALE-206] - convertDateTime component throws exception when using the timeZone attribute
• [SHALE-208] - The clay markup parser was not handling a CDATA block.
• [SHALE-209] - Missing tag validator for the clay component.
• [SHALE-217] - Not possible to pass dynamically information from a beans as a shale method parameter.
• [SHALE-220] - init() lifecycle method called twice
• [SHALE-223] - System integration test TokenTestCase fails against the JSF 1.1 RI
• [SHALE-247] - s:validatorScript produces invalid html markup
• [SHALE-248] - [CommonsValidator] missing trim JavaScript function
• [SHALE-251] - Java 1.5 method java.lang.String.replace(Ljava/lang/CharSequence;Ljava/lang/CharSequence;) used in org.apache.shale.test.mock.MockValueBinding.parse
• [SHALE-252] - @Prerender and @Preprocess annotated callbacks not called
• [SHALE-253] - JNDI access to data sources configured in Tomcat returns null
• [SHALE-254] - Tiger Extensions do not call back to annotated preprocess/prerender methods
• [SHALE-255] - Subview doing processDecode on beginEncode
• [SHALE-256] - Cannot use annotated managed beans unless ShaleApplicationFilter is configured

5.2 Improvement

• [SHALE-125] - [Shale][View] Devise coherent exception handling strategy
• [SHALE-134] - [Shale][Tiger] Implement event callbacks via annotations
• [SHALE-137] - [Shale][View] Event callbacks for servlet lifecycle events
• [SHALE-170] - Clay attributes are not using xml namespaces
• [SHALE-173] - Dialog feature should not hard code "dialog:" prefix on outcome strings
• [SHALE-174] - Implement attribute event support on mock context, request, and session classes
• [SHALE-176] - The Token component doesn't allow to override the message like the validator
• [SHALE-178] - Shale Remoting doesn't support multiple instances of the FacesServlet, for example in the case of AJAX
• [SHALE-181] - Improve the performance of the Clay HTML template processing
• [SHALE-187] - Add the ability for tooling to digest clay component descriptions
• [SHALE-193] - Provide a reusable TestSetup class that starts and stops a servlet container
• [SHALE-199] - MockFacesContext.setCurrentInstance()
• [SHALE-201] - Support 2 pass symbol replacement
• [SHALE-246] - Consistently use managed beans for replaceable functionality components
• [SHALE-249] - Add "throws Exception" to signatures of setUp() and tearDown() in AbstractJsfTestCase

5.3 New Feature

• [SHALE-191] - Consider renaming @Value to @Property
• [SHALE-197] - Allow PhaseListeners to be defined with Annotations
• [SHALE-225] - Example application ilustrating Java Persistence Architecture (JPA) integration
• [SHALE-231] - Publish an XML Catalog for Shale defined DTDs and Schemas
• [SHALE-240] - Easier way to exclude content from the HTML template

5.4 Task

• [SHALE-179] - Convert the Shale build to Maven 2
• [SHALE-189] - Shale Test is incompatible with HtmlUnit 1.8
• [SHALE-207] - Establish Shale as a top-level Apache project
• [SHALE-218] - Change dtd doctype URLs to shale.apache.org
• [SHALE-227] - Restructure the svn repo to establish a 'sandbox' and separate the 'maven' module from the framework
• [SHALE-241] - Release Shale Master POM in preparation for a 1.0.3 release
• [SHALE-242] - Review dependency version numbers
• [SHALE-257] - Clean up 1.0.3 release artifacts per developer review