Author: craigmcc
Date: Mon Nov 21 11:22:14 2005
New Revision: 347957
URL: http://svn.apache.org/viewcvs?rev=347957&view=rev
Log:
Promote information on external dependencies, configuring your app for Shale,
acquiring distributions, and building Shale from source into web site pages,
rather than being buried in the release notes. This will make the information
much more accessible, as well as allowing search engines to index it (once the
website is next updated, of course).
Added:
struts/shale/trunk/xdocs/building.xml (with props)
struts/shale/trunk/xdocs/using.xml (with props)
Modified:
struts/shale/trunk/docs/release-notes-1.0.0.html
struts/shale/trunk/xdocs/navigation.xml
Modified: struts/shale/trunk/docs/release-notes-1.0.0.html
URL:
http://svn.apache.org/viewcvs/struts/shale/trunk/docs/release-notes-1.0.0.html?rev=347957&r1=347956&r2=347957&view=diff
==============================================================================
--- struts/shale/trunk/docs/release-notes-1.0.0.html (original)
+++ struts/shale/trunk/docs/release-notes-1.0.0.html Mon Nov 21 11:22:14 2005
@@ -34,11 +34,8 @@
<ul>
<li><a href="#Introduction">Introduction</a></li>
<li><a href="#Included">What Is Included</a></li>
- <li><a href="#External">External Dependencies</a></li>
- <li><a href="#Using">Using Shale In Your Applications</a></li>
<li><a href="#Changes">Changes From Previous Releases</a></li>
<li><a href="#Known">Known Issues In This Release</a></li>
- <li><a href="#Building">Building Shale From Source</a></li>
</ul>
<a name="Introduction"></a>
@@ -92,393 +89,19 @@
</ul>
</ul>
- <a name="External"></a>
- <h3>3.0 External Dependencies</h3>
-
- <p>The following table describes runtime external dependencies of the Shale
- distribution libraries listed in the previous section.</p>
-
- <table border="1">
- <thead>
- <tr>
- <th>Shale Library</th>
- <th>External Library</th>
- <th>Version</th>
- <th>Notes</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>shale-core.jar</code></td>
- <td>JavaServer Faces Implementation</td>
- <td align="center">1.1</td>
- <td align="center"><a href="#[1]">[1]</a></td>
- </tr>
- <tr>
- <td><code>shale-core.jar</code></td>
- <td><a href="http://jakarta.apache.org/commons/beanutils/";>Commons
BeanUtils</a></td>
- <td align="center">1.7</td>
- <td align="center"> </td>
- </tr>
- <tr>
- <td><code>shale-core.jar</code></td>
- <td><a href="http://jakarta.apache.org/commons/chain/";>Commons
Chain</a></td>
- <td align="center">1.0</td>
- <td align="center"> </td>
- </tr>
- <tr>
- <td><code>shale-core.jar</code></td>
- <td><a href="http://jakarta.apache.org/commons/digester/";>Commons
Digester</a></td>
- <td align="center">1.7</td>
- <td align="center"> </td>
- </tr>
- <tr>
- <td><code>shale-core.jar</code></td>
- <td><a href="http://jakarta.apache.org/commons/logging/";>Commons
Logging</a></td>
- <td align="center">1.0.4</td>
- <td align="center"> </td>
- </tr>
- <tr>
- <td><code>shale-core.jar</code></td>
- <td><a href="http://jakarta.apache.org/commons/validator/";>Commons
Validator</a></td>
- <td align="center">1.0</td>
- <td align="center"> </td>
- </tr>
- <tr>
- <td><code>shale-clay.jar</code></td>
- <td>(No additional external dependencies)</td>
- <td align="center">---</td>
- <td align="center"> </td>
- </tr>
- <tr>
- <td><code>shale-spring.jar</code></td>
- <td><a href="http://springframework.org/";>Spring Framework</a></td>
- <td align="center">1.2.2</td>
- <td align="center"><a href="#[2]">[2]</a></td>
- </tr>
- <tr>
- <td><code>shale-test.jar</code></td>
- <td>(No additional external dependencies)</td>
- <td align="center">---</td>
- <td align="center"> </td>
- </tr>
- <tr>
- <td><code>shale-tiles.jar</code></td>
- <td><a
href="http://cvs.apache.org/builds/struts/nightly/sandbox/tiles-core/";>
- Standalone Tiles</a></td>
- <td align="center">Nightly</td>
- <td align="center"><a href="#[3]">[3]</a></td>
- </tr>
- </tbody>
- </table>
-
- <ol>
- <li><a name="[1]"></a>Shale has been tested with the
- <a href="https://javaserverfaces.dev.java.net/";>
- JavaServer Faces Reference Implementation</a> (Version 1.1_01) and
- with <a href="http://myfaces.apache.org/";>Apache MyFaces</a>
- (Version 1.0.9). Be sure to read the release documentation of
- each implementation to acquire the dependencies of that package.</li>
- <li><a name="[2]"></a>Spring ships with either an all-in-one JAR file
- (<code>spring.jar</code>) or a set of smaller JAR files containing
- only portions of the framework. If you do not use the all-in-one
- file, you will need to use <code>spring-beans.jar</code>,
- <code>spring-context.jar</code>, <code>spring-core.jar</code>, and
- <code>spring-web.jar</code>.</li>
- <li><a name="[3]"></a>Standalone Tiles is a (work in progress) extraction
- of the Tiles Framework out of Struts, removing Struts dependencies,
- and doing some refactoring. To date there have been no formal releases
- of this library; the link above points to the nightly builds.</li>
- </ol>
-
- <a name="Using"></a>
- <h3>4.0 Using Shale In Your Applications</h3>
-
- <p>Shale based applications should run on any server that implements the
- Servlet 2.4 and JavaServer Pages 2.0 APIs. The following steps are
- required to assemble a Shale based application that may be deployed and
- executed.
-
- <h4>4.1 Add Required Libraries</h4>
-
- <p>If your server does not already provide an implementation of JavaServer
- Faces, you must include such an implementation (plus all of its dependent
- JARs) in the <code>/WEB-INF/lib</code> directory.</p>
-
- <p>All Shale based applications will require <code>shale-core.jar</code>
- (and its dependencies, as described above). If you wish to utilize the
- features provided in the optional Shale components
(<code>shale-clay.jar</code>,
- <code>shale-spring.jar</code>, and/or <code>shale-tiles.jar</code>),
include
- those JARs (and ther external dependencies) as well.</p>
-
- <p>The <code>shale-test.jar</code> contains base classes for
- <a href="http://junit.org";>JUnit</a> based unit tests for your application
- classes. As such, it is useful only at application build time, and should
- never be included in a runtime web application archive.</p>
-
- <h4>4.2 Configure <code>/WEB-INF/web.xml</code> Resource</h4>
-
- <p>Create a <code>/WEB-INF/web.xml</code> resource that conforms to the
- rules defined in the Servlet 2.4 Specification. You can use the one in
- the Use Cases example as a guide. Include the following elements (at
- appropriate places) as needed.</p>
-
- <p>Configure whether you want JavaServer Faces to save component state
- on the client side or the server side. This lets you choose between the
- tradeoffs of extra network traffic versus extra server memory usage,
- without affecting your application code.</p>
-
- <pre>
- <context-param>
- <param-name>javax.faces.STATE_SAVING_METHOD</param-name>
- <param-value>server</param-value>
- </context-param>
- </pre>
-
- <p>If you have defined JavaServer Faces configuration resources in addition
- to, or instead of, the default one (<code>/WEB-INF/faces-config.xml</code>,
- list them here. You may specify more than one resource by separating the
- paths with a comma (',') character.</p>
-
- <pre>
- <context-param>
- <param-name>javax.faces.CONFIG_FILES</param-name>
- <param-value>/WEB-INF/faces-config.xml</param-value>
- </context-param>
- </pre>
-
- <p>If you have defined your own Command Chain commands (to customize the
- behavior of the standard chains, or to implement mappings for remote
- commands), tell Commons Chain where your configuration resource is.
- You can specify more than one resource by separating the paths with a
- comma (',') characters.</p>
-
- <pre>
- <context-param>
-
<param-name>org.apache.commons.chain.CONFIG_WEB_RESOURCE</param-name>
- <param-value>/WEB-INF/chain-config.xml</param-value>
- </context-param>
- </pre>
-
- <p>If you have defined your own Shale Dialog configuration resources
- in addition to (or instead of) the standard path
- (<code>/WEB-INF/dialog-config.xml</code>), specify the path here. You may
- specify more than one resource by separating the paths with a
- comma (',') character.</p>
-
- <pre>
- <context-param>
-
<param-name>org.apache.shale.dialog.CONFIGURATION</param-name>
- <param-value>/WEB-INF/dialog-config.xml</param-value>
- </context-param>
- </pre>
-
- <p>If you are using the optional integration with Spring, you must specify
- that path to the configuration resource for the ApplicationContext.
- You can specify more than one resource by separating them with
whitespace.</p>
-
- <pre>
- <context-param>
- <param-name>contextConfigLocation</param-name>
- <param-value>/WEB-INF/applicationContext.xml</param-value>
- </context-param>
- </pre>
-
- <p>If you are using the Clay plugin, you must specify the path to the
- configuration resource defining your Clay component definitions. You can
- specify more than one resource by separating them with comma (',')
- characters.</p>
-
- <pre>
- <context-param>
- <param-name>clay-config-files</param-name>
- <param-value>/WEB-INF/clay-config.xml</param-value>
- </context-param>
- </pre>
-
- <p>If you are using the Tapestry-like views feature of the Clay plugin,
- you may override the default resource extension (.clay) used to identify
- pages containing component references.</p>
-
- <pre>
- <context-param>
- <param-name>clay-template-suffix</param-name>
- <param-value>.clay</param-value>
- </context-param>
- </pre>
-
- <p>Configure the standard Shale application controller filter, and map it
- to the requests you want it to apply to. At a minimum, you will want to
- map this filter to the same pattern that <code>FacesServlet</code> is
- mapped to (see below); however, the simplest approach is to use the
- <code>/*</code> pattern to map the filter to all incoming requests.</p>
-
- <pre>
- <filter>
- <filter-name>shale</filter-name>
- <filter-class>
- org.apache.shale.faces.ShaleApplicationFilter
- </filter-class>
- </filter>
- </pre>
-
- <pre>
- <filter-mapping>
- <filter-name>shale</filter-name>
- <url-pattern>/*</url-pattern>
- </filter-mapping>
- </pre>
-
- <p>Configure the Commons Chain configuration listener, so that command
- chains definitions specified by the application, and those defined
- internally by Shale, will be loaded at application startup time.</p>
-
- <pre>
- <listener>
- <listener-class>
- org.apache.commons.chain.web.ChainListener
- </listener-class>
- </listener>
- </pre>
-
- <p>If you are using the Clay plugin, configure the Clay configuration
- listener, so that component definitions specified by the application
- as well as those specified internally by Shale, will be loaded at
- application startup time.</p>
-
- <pre>
- <listener>
- <listener-class>
- org.apache.shale.clay.config.ClayConfigureListener
- </listener-class>
- </listener>
- </pre>
-
- <p>If you are using the Spring integration feature, configure the Spring
- configuration listener so that the application context will be configured
- at application startup time.</p>
-
- <pre>
- <listener>
- <listener-class>
- org.springframework.web.context.ContextLoaderListener
- </listener-class>
- </listener>
- </pre>
-
- <p>Configure the standard JavaServer Faces processing servlet and mapping.
- You may use either prefix or extension mapping, and the JSF runtime will
- automatically adapt. The example below shows the most common default:</p>
-
- <pre>
- <servlet>
- <servlet-name>faces</servlet-name>
-
<servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
- </servlet>
- </pre>
-
- <pre>
- <servlet-mapping>
- <servlet-name>faces</servlet-name>
- <url-pattern>*.faces</url-pattern>
- </servlet-mapping>
- </pre>
-
- <p>If you are using the Tapestry-like views feature of the Clay plug-in,
- map the standard JavaServer Faces servlet to the same extension you
- specified for the <code>clay-template-suffix</code> context init
parameter.</p>
-
- <pre>
- <servlet-mapping>
- <servlet-name>faces</servlet-name>
- <url-pattern>*.html</url-pattern>
- </servlet-mapping>
- </pre>
-
- <p>Optionally, configure the "welcome file(s)" for your application.</p>
-
- <pre>
- <welcome-file-list>
- <welcome-file>index.jsp</welcome-file>
- </welcome-file-list>
- </pre>
-
- <h4>4.3 Runtime Assertion Checking</h4>
-
- <p>Shale leverages the <code>assert</code> capability of JDK 1.4 (or later)
- Java Virtual Machine (JVM) runtime environments to support a large number
- of runtime assertion tests, to ensure that functional assumptions are
- satisfied. By default, the runtime JVM of your container will disable
- checking such assertions (so that they incur no production runtime
- hit on performance). During development, however, you will want to
- make sure that the <code>-Denableassertions</code> (or, if you only want
- Shale assertions enabled, use
<code>-Denableassertions:org.apache.shale...</code>
- instead) command line argument is passed to the startup script for the
- servlet container used by your development tool. The details of
configuring
- this command line option are, of necessity, tool specific.</p:
-
<a name="Changes"></a>
- <h3>5.0 Changes From Previous Releases</h3>
+ <h3>3.0 Changes From Previous Releases</h3>
<p>This is the first milestone release of Shale, so there is no formal
list of changes from the previous release.</p>
<a name="Known"></a>
- <h3>6.0 Known Issues In This Release</h3>
-
- <p>FIXME</p>
-
- <a name="Building"></a>
- <h3>7.0 Building Shale From Source</h3>
-
- <p>The Shale distribution includes all of the source code for Shale,
- plus build scripts to reconstruct the release from scratch. In order
- to build Shale, you must perform the following steps:</p>
- <ul>
- <li>Acquire a copy of a <a href="http://java.sun.com/j2se/";>Java
- Development Kit</a> (Version 1.4 or later), and install it according
- to the provided documentation.</li>
- <li>Acquire a copy of <a href="http://ant.apache.org/";>Apache Ant</a>
- (version 1.6.3 or later), and install it according to the
- provided documentation.</li>
- <li>If you wish to build Shale against the JavaServer Faces reference
- implementation, <a href="http://java.sun.com/j2ee/javaserverfaces/";>
- acquire a copy</a> (Version 1.1_01) and install it according to
- the provided documentation.</li>
- <li>Acquire a Shale distribution (nightly build or release), and unpack
- it into a convenient directory.</li>
- <li>In the top-level directory of the unpacked Shale distribution, copy
- the file <code>build.properties.sample</code> to
<code>build.properties</code>,
- and customize the property values it contains. Pay particular
attention
- to the following values:
- <ul>
- <li><code>jsfri.dir</code> - If you downloaded and installed the
- JavaServer Faces Reference implementation, set this property
- to the fully qualified pathname of the directory into which
- you installed the distribution.
- <li><code>jsf.home</code> - If you are using MyFaces, comment out
- the default value and uncomment the following line.</li>
- <li><code>jsf-api.jar</code> - IF you are using MyFaces, comment out
- the default value and uncomment the following line.</li>
- <li><code>jsf-impl.jar</code> - If you are using MyFaces, comment out
- the default value and uncomment the following line.</li>
- </ul></li>
- <li>In the top-level directory of the unpacked Shale distribution, execute
- the following Ant commands to set up external dependencies:
- <ul>
- <li><code>ant download-dependencies</code> - to download freely
available
- external dependencies.</li>
- <li><code>ant copy-jsf-ri</code> - if you are using the JSF RI, load
- the appropriate artifacts.</li>
- </ul></li>
- <li>In the top-level directory of the unpacked Shale distribution, execute
- the command <code>ant clean release</code> to completely rebuild the
- entire distribution from source.</li>
- <li>In addition, each of the major source subdirectories has a properly
- configured <code>build.xml</code> file, so you can rebuild just that
- subdirectory if desired.</li>
- </ul>
+ <h3>4.0 Known Issues In This Release</h3>
+ <p>The <em>Dialog</em> feature has known problems with attempting to have
+ multiple simultaneously active dialogs in a single session (most commonly
+ due to using frames or multiple windoes), and dealing with back buttons.
+ These issues will be addressed in a subsequent release.</p>
</body>
Added: struts/shale/trunk/xdocs/building.xml
URL:
http://svn.apache.org/viewcvs/struts/shale/trunk/xdocs/building.xml?rev=347957&view=auto
==============================================================================
--- struts/shale/trunk/xdocs/building.xml (added)
+++ struts/shale/trunk/xdocs/building.xml Mon Nov 21 11:22:14 2005
@@ -0,0 +1,95 @@
+<?xml version="1.0"?>
+<document>
+
+ <properties>
+ <title>Acquiring and Building Shale</title>
+ </properties>
+
+ <body>
+
+ <a name="building"/>
+ <section name="Acquiring and Building Shale">
+
+ <a name="building-introduction"/>
+ <subsection name="Introduction">
+
+ <p>This page documents how to <a href="#building-acquiring">Acquire
+ a copy of the source code</a> and <a href="#building-building">Build
+ the framework from source</a>.</p>
+
+ </subsection>
+
+ <a name="building-acquiring"/>
+ <subsection name="Acquiring Shale">
+
+ <p>The easiest way to acquire the source code for Shale is to download
+ one of the
+ <a href="http://cvs.apache.org/builds/struts/nightly/struts-shale/";>
+ Nightly Build</a> or release distributions, which contain both the
+ source code and the binary libraries. Alternatively, you can check out
+ the source code from the Struts Subversion repository using the
+ URLs specified
+ <a
href="http://struts.apache.org/acquiring.html#Source_Code";>here</a>.</p>
+
+ </subsection>
+
+ <a name="building-building"/>
+ <subsection name="Building Shale From Source">
+
+ <p>Once you have <a href="#building-acquiring">acquired</a> the
+ source code for Shale, as described above, you can proceed to set
+ up a development environment with which to build it. Follow these
+ steps to continue:</p>
+
+ <ul>
+ <li>Acquire a copy of a <a href="http://java.sun.com/j2se/";>Java
+ Development Kit</a> (Version 1.4 or later), and install it
according
+ to the provided documentation.</li>
+ <li>Acquire a copy of <a href="http://ant.apache.org/";>Apache Ant</a>
+ (version 1.6.3 or later), and install it according to the
+ provided documentation.</li>
+ <li>If you wish to build Shale against the JavaServer Faces reference
+ implementation, <a
href="http://java.sun.com/j2ee/javaserverfaces/";>
+ acquire a copy</a> (Version 1.1_01) and install it according to
+ the provided documentation.</li>
+ <li>In the top-level directory of the unpacked Shale distribution, copy
+ the file <code>build.properties.sample</code> to
+ <code>build.properties</code>, and customize the property values
+ it contains. Pay particular attention
+ to the following values:
+ <ul>
+ <li><code>jsfri.dir</code> - If you downloaded and installed the
+ JavaServer Faces Reference implementation, set this property
+ to the fully qualified pathname of the directory into which
+ you installed the distribution.</li>
+ <li><code>jsf.home</code> - If you are using MyFaces, comment out
+ the default value and uncomment the following line.</li>
+ <li><code>jsf-api.jar</code> - IF you are using MyFaces, comment
out
+ the default value and uncomment the following line.</li>
+ <li><code>jsf-impl.jar</code> - If you are using MyFaces,
+ comment out the default value and uncomment the following
+ line.</li>
+ </ul></li>
+ <li>In the top-level directory of the unpacked Shale distribution,
+ execute the following Ant commands to set up external dependencies:
+ <ul>
+ <li><code>ant download-dependencies</code> - to download freely
+ available external dependencies.</li>
+ <li><code>ant copy-jsf-ri</code> - if you are using the JSF RI,
load
+ the appropriate artifacts.</li>
+ </ul></li>
+ <li>In the top-level directory of the unpacked Shale distribution,
+ execute the command <code>ant clean release</code> to completely
+ rebuild the entire distribution from source.</li>
+ <li>In addition, each of the major source subdirectories has a properly
+ configured <code>build.xml</code> file, so you can rebuild just
that
+ subdirectory if desired.</li>
+ </ul>
+
+ </subsection>
+
+ </section>
+
+ </body>
+
+</document>
Propchange: struts/shale/trunk/xdocs/building.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: struts/shale/trunk/xdocs/building.xml
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
Modified: struts/shale/trunk/xdocs/navigation.xml
URL:
http://svn.apache.org/viewcvs/struts/shale/trunk/xdocs/navigation.xml?rev=347957&r1=347956&r2=347957&view=diff
==============================================================================
--- struts/shale/trunk/xdocs/navigation.xml (original)
+++ struts/shale/trunk/xdocs/navigation.xml Mon Nov 21 11:22:14 2005
@@ -11,6 +11,8 @@
<item name="Download" href="index.html#Shale_Download"/>
<item name="Documentation" href="index.html#Shale_Documentation"/>
<item name="Issue Tracking"
href="index.html#Shale_Issue_Tracking"/>
+ <item name="Using Shale" href="using.html"/>
+ <item name="Building Shale" href="building.html"/>
</menu>
<menu name="Features">
Added: struts/shale/trunk/xdocs/using.xml
URL:
http://svn.apache.org/viewcvs/struts/shale/trunk/xdocs/using.xml?rev=347957&view=auto
==============================================================================
--- struts/shale/trunk/xdocs/using.xml (added)
+++ struts/shale/trunk/xdocs/using.xml Mon Nov 21 11:22:14 2005
@@ -0,0 +1,372 @@
+<?xml version="1.0"?>
+<document>
+
+ <properties>
+ <title>Using Shale In Web Applications</title>
+ </properties>
+
+ <body>
+
+ <section name="Using Shale In Web Applications">
+ <a name="using"/>
+
+ <a name="using-introduction"/>
+ <subsection name="Introduction">
+
+ <p>This page documents the use of Shale in your web applicatons,
+ including <a href="#using-dependencies">external dependencies</a>
+ and detailed instructions on <a href="#using-configuring">configuring
+ your application</a>. A future milestone of Shale will
+ likely include a "shale-blank" example application with all of the
+ basics set up for you, ready to be customized for your own use.</p>
+
+ </subsection>
+
+ <a name="using-dependencies"/>
+ <subsection name="External Dependencies">
+
+ <p>The following table describes runtime external dependencies of the
+ Shale libraries included in the distribution.</p>
+
+ <table border="1">
+ <thead>
+ <tr>
+ <th>Shale Library</th>
+ <th>External Library</th>
+ <th>Version</th>
+ <th>Notes</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><code>shale-core.jar</code></td>
+ <td>JavaServer Faces Implementation</td>
+ <td align="center">1.1</td>
+ <td align="center"><a href="#[1]">[1]</a></td>
+ </tr>
+ <tr>
+ <td><code>shale-core.jar</code></td>
+ <td><a
href="http://jakarta.apache.org/commons/beanutils/";>Commons BeanUtils</a></td>
+ <td align="center">1.7</td>
+ <td align="center">---</td>
+ </tr>
+ <tr>
+ <td><code>shale-core.jar</code></td>
+ <td><a href="http://jakarta.apache.org/commons/chain/";>Commons
Chain</a></td>
+ <td align="center">1.0</td>
+ <td align="center">---</td>
+ </tr>
+ <tr>
+ <td><code>shale-core.jar</code></td>
+ <td><a
href="http://jakarta.apache.org/commons/digester/";>Commons Digester</a></td>
+ <td align="center">1.7</td>
+ <td align="center">---</td>
+ </tr>
+ <tr>
+ <td><code>shale-core.jar</code></td>
+ <td><a href="http://jakarta.apache.org/commons/logging/";>Commons
Logging</a></td>
+ <td align="center">1.0.4</td>
+ <td align="center">---</td>
+ </tr>
+ <tr>
+ <td><code>shale-core.jar</code></td>
+ <td><a
href="http://jakarta.apache.org/commons/validator/";>Commons Validator</a></td>
+ <td align="center">1.2.0</td>
+ <td align="center">---</td>
+ </tr>
+ <tr>
+ <td><code>shale-clay.jar</code></td>
+ <td>(No additional external dependencies)</td>
+ <td align="center">---</td>
+ <td align="center">---</td>
+ </tr>
+ <tr>
+ <td><code>shale-spring.jar</code></td>
+ <td><a href="http://springframework.org/";>Spring
Framework</a></td>
+ <td align="center">1.2.2</td>
+ <td align="center"><a href="#[2]">[2]</a></td>
+ </tr>
+ <tr>
+ <td><code>shale-test.jar</code></td>
+ <td>(No additional external dependencies)</td>
+ <td align="center">---</td>
+ <td align="center">---</td>
+ </tr>
+ <tr>
+ <td><code>shale-tiles.jar</code></td>
+ <td><a
href="http://cvs.apache.org/builds/struts/nightly/sandbox/tiles-core/";>
+ Standalone Tiles</a></td>
+ <td align="center">Nightly</td>
+ <td align="center"><a href="#[3]">[3]</a></td>
+ </tr>
+ </tbody>
+ </table>
+
+ <ol>
+ <li><a name="[1]"></a>Shale has been tested with the
+ <a href="https://javaserverfaces.dev.java.net/";>
+ JavaServer Faces Reference Implementation</a> (Version 1.1_01) and
+ with <a href="http://myfaces.apache.org/";>Apache MyFaces</a>
+ (Version 1.1.1). Be sure to read the release documentation of
+ each implementation to acquire the dependencies of that
+ package.</li>
+ <li><a name="[2]"></a>Spring ships with either an all-in-one JAR file
+ (<code>spring.jar</code>) or a set of smaller JAR files containing
+ only portions of the framework. If you do not use the all-in-one
+ file, you will need to use <code>spring-beans.jar</code>,
+ <code>spring-context.jar</code>, <code>spring-core.jar</code>, and
+ <code>spring-web.jar</code>.</li>
+ <li><a name="[3]"></a>Standalone Tiles is a (work in progress)
+ extraction of the Tiles Framework out of Struts, removing Struts
+ dependencies, and doing some refactoring. To date there have been
+ no formal releases of this library; the link above points to the
+ nightly builds.</li>
+ </ol>
+
+ </subsection>
+
+ <a name="using-configuring"/>
+ <subsection name="Configuring Your Application For Shale">
+
+ <p>Shale based applications should run on any server that implements
the
+ Servlet 2.4 and JavaServer Pages 2.0 APIs. The following steps are
+ required to assemble a Shale based application that may be deployed and
+ executed.</p>
+
+ <h4>(A) Add Required Libraries</h4>
+
+ <p>If your server does not already provide an implementation of
+ JavaServer Faces, you must include such an implementation (plus all
+ of its dependent JARs) in the <code>/WEB-INF/lib</code> directory.</p>
+
+ <p>All Shale based applications will require
<code>shale-core.jar</code>
+ (and its dependencies, as described above). If you wish to utilize the
+ features provided in the optional Shale components
+ (<code>shale-clay.jar</code>, <code>shale-spring.jar</code>, and/or
+ <code>shale-tiles.jar</code>), include those JARs (and ther external
+ dependencies) as well.</p>
+
+ <p>The <code>shale-test.jar</code> contains base classes for
+ <a href="http://junit.org";>JUnit</a> based unit tests for your
+ application classes. As such, it is useful only at application
+ build time, and should never be included in a runtime web
+ application archive.</p>
+
+ <h4>(B) Configure <code>/WEB-INF/web.xml</code> Resource</h4>
+
+ <p>Create a <code>/WEB-INF/web.xml</code> resource that conforms to the
+ rules defined in the Servlet 2.4 Specification. You can use the one in
+ the Use Cases example as a guide. Include the following elements (at
+ appropriate places) as needed.</p>
+
+ <p>Configure whether you want JavaServer Faces to save component state
+ on the client side or the server side. This lets you choose between
the
+ tradeoffs of extra network traffic versus extra server memory usage,
+ without affecting your application code.</p>
+
+<source>
+ <context-param>
+ <param-name>javax.faces.STATE_SAVING_METHOD</param-name>
+ <param-value>server</param-value>
+ </context-param>
+</source>
+
+ <p>If you have defined JavaServer Faces configuration resources in
+ addition to, or instead of, the default one
+ (<code>/WEB-INF/faces-config.xml</code>), list them here.
+ You may specify more than one resource by separating the
+ paths with a comma (',') character. Note that the default
+ configuration resource will be processed, if it is present,
+ whether or not it is explicity listed here.</p>
+
+<source>
+ <context-param>
+ <param-name>javax.faces.CONFIG_FILES</param-name>
+
<param-value>/WEB-INF/managed-beans.xml,/WEB-INF/navigation.xml</param-value>
+ </context-param>
+</source>
+
+ <p>If you have defined your own Command Chain commands (to customize
the
+ behavior of the standard chains, or to implement mappings for remote
+ commands), tell Commons Chain where your configuration resource is.
+ You can specify more than one resource by separating the paths with a
+ comma (',') characters.</p>
+
+<source>
+ <context-param>
+
<param-name>org.apache.commons.chain.CONFIG_WEB_RESOURCE</param-name>
+ <param-value>/WEB-INF/chain-config.xml</param-value>
+ </context-param>
+</source>
+
+ <p>If you have defined your own Shale Dialog configuration resources
+ in addition to (or instead of) the standard path
+ (<code>/WEB-INF/dialog-config.xml</code>), specify the path here.
+ You may specify more than one resource by separating the paths with a
+ comma (',') character.</p>
+
+<source>
+ <context-param>
+
<param-name>org.apache.shale.dialog.CONFIGURATION</param-name>
+ <param-value>/WEB-INF/dialog-config.xml</param-value>
+ </context-param>
+</source>
+
+ <p>If you are using the optional integration with Spring, you must
+ specify that path to the configuration resource for the
+ <code>ApplicationContext</code>. You can specify more than one
+ resource by separating them with whitespace.</p>
+
+<source>
+ <context-param>
+ <param-name>contextConfigLocation</param-name>
+ <param-value>/WEB-INF/applicationContext.xml</param-value>
+ </context-param>
+</source>
+
+ <p>If you are using the Clay plugin, you must specify the path to the
+ configuration resource defining your Clay component definitions. You
+ can specify more than one resource by separating them with comma (',')
+ characters.</p>
+
+<source>
+ <context-param>
+ <param-name>clay-config-files</param-name>
+ <param-value>/WEB-INF/clay-config.xml</param-value>
+ </context-param>
+</source>
+
+ <p>If you are using the Tapestry-like views feature of the Clay plugin,
+ you may override the default resource extension (.clay) used to
identify
+ pages containing component references.</p>
+
+<source>
+ <context-param>
+ <param-name>clay-template-suffix</param-name>
+ <param-value>.clay</param-value>
+ </context-param>
+</source>
+
+ <p>Configure the standard Shale application controller filter, and map
+ it to the requests you want it to apply to. At a minimum, you will
+ want to map this filter to the same pattern that
+ <code>FacesServlet</code> is mapped to (see below); however, the
+ simplest approach is to use the <code>/*</code> pattern to map
+ the filter to all incoming requests.</p>
+
+<source>
+ <filter>
+ <filter-name>shale</filter-name>
+ <filter-class>
+ org.apache.shale.faces.ShaleApplicationFilter
+ </filter-class>
+ </filter>
+</source>
+
+<source>
+ <filter-mapping>
+ <filter-name>shale</filter-name>
+ <url-pattern>/*</url-pattern>
+ </filter-mapping>
+</source>
+
+ <p>Configure the Commons Chain configuration listener, so that command
+ chains definitions specified by the application, and those defined
+ internally by Shale, will be loaded at application startup time.</p>
+
+<source>
+ <listener>
+ <listener-class>
+ org.apache.commons.chain.web.ChainListener
+ </listener-class>
+ </listener>
+</source>
+
+ <p>If you are using the Clay plugin, configure the Clay configuration
+ listener, so that component definitions specified by the application
+ as well as those specified internally by Shale, will be loaded at
+ application startup time.</p>
+
+<source>
+ <listener>
+ <listener-class>
+ org.apache.shale.clay.config.ClayConfigureListener
+ </listener-class>
+ </listener>
+</source>
+
+ <p>If you are using the Spring integration feature, configure the
+ Spring configuration listener so that the application context will
+ be configured at application startup time.</p>
+
+<source>
+ <listener>
+ <listener-class>
+ org.springframework.web.context.ContextLoaderListener
+ </listener-class>
+ </listener>
+</source>
+
+ <p>Configure the standard JavaServer Faces processing servlet and
+ mapping. You may use either prefix or extension mapping, and the
+ JSF runtime will automatically adapt. The example below shows the
+ most common default:</p>
+
+<source>
+ <servlet>
+ <servlet-name>faces</servlet-name>
+
<servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
+ </servlet>
+</source>
+
+<source>
+ <servlet-mapping>
+ <servlet-name>faces</servlet-name>
+ <url-pattern>*.faces</url-pattern>
+ </servlet-mapping>
+</source>
+
+ <p>If you are using the Tapestry-like views feature of the Clay
+ plug-in, map the standard JavaServer Faces servlet to the same
+ extension you specified for the <code>clay-template-suffix</code>
+ context init parameter.</p>
+
+<source>
+ <servlet-mapping>
+ <servlet-name>faces</servlet-name>
+ <url-pattern>*.html</url-pattern>
+ </servlet-mapping>
+</source>
+
+ <p>Optionally, configure the "welcome file(s)" for your
application.</p>
+
+<source>
+ <welcome-file-list>
+ <welcome-file>index.jsp</welcome-file>
+ </welcome-file-list>
+</source>
+
+ <h4>(C) Runtime Assertion Checking</h4>
+
+ <p>Shale leverages the <code>assert</code> capability of JDK 1.4
+ (or later) Java Virtual Machine (JVM) runtime environments to
+ support a large number of runtime assertion tests, to ensure that
+ functional assumptions are satisfied. By default, the runtime JVM
+ of your container will disable checking such assertions (so that
+ they incur no production runtime hit on performance). During
+ development, however, you will want to make sure that the
+ <code>-Denableassertions</code> (or, if you only want Shale
+ assertions enabled, use
+ <code>-Denableassertions:org.apache.shale...</code> instead)
+ command line argument is passed to the startup script for the
+ servlet container used by your development tool. The details
+ of configuring this command line option are, of necessity,
+ tool specific.</p>
+
+ </subsection>
+
+ </section>
+
+ </body>
+
+</document>
Propchange: struts/shale/trunk/xdocs/using.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: struts/shale/trunk/xdocs/using.xml
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
