Author: craigmcc
Date: Sat Jan 14 23:25:47 2006
New Revision: 369184
URL: http://svn.apache.org/viewcvs?rev=369184&view=rev
Log:
Document the current state of the Shale Tiger Extensions. Also, fix a couple
of typos in other areas.
Modified:
struts/shale/trunk/core-library/src/java/org/apache/shale/view/faces/CallbacksFactory.java
struts/shale/trunk/tiger/nbproject/project.xml
struts/shale/trunk/xdocs/features-tiger-extensions.xml
struts/shale/trunk/xdocs/using.xml
Modified:
struts/shale/trunk/core-library/src/java/org/apache/shale/view/faces/CallbacksFactory.java
URL:
http://svn.apache.org/viewcvs/struts/shale/trunk/core-library/src/java/org/apache/shale/view/faces/CallbacksFactory.java?rev=369184&r1=369183&r2=369184&view=diff
==============================================================================
---
struts/shale/trunk/core-library/src/java/org/apache/shale/view/faces/CallbacksFactory.java
(original)
+++
struts/shale/trunk/core-library/src/java/org/apache/shale/view/faces/CallbacksFactory.java
Sat Jan 14 23:25:47 2006
@@ -60,7 +60,7 @@
ClassLoader cl = getApplicationClassLoader();
Class clazz = null;
try {
- clazz =
cl.loadClass("org.apache.shale.tiger.view.faces.ViewControllerCallbacks");
+ clazz =
cl.loadClass("org.apache.shale.tiger.view.faces.ViewControllerCallbacks2");
} catch (ClassNotFoundException e) {
;
}
Modified: struts/shale/trunk/tiger/nbproject/project.xml
URL:
http://svn.apache.org/viewcvs/struts/shale/trunk/tiger/nbproject/project.xml?rev=369184&r1=369183&r2=369184&view=diff
==============================================================================
--- struts/shale/trunk/tiger/nbproject/project.xml (original)
+++ struts/shale/trunk/tiger/nbproject/project.xml Sat Jan 14 23:25:47 2006
@@ -8,17 +8,17 @@
<properties/>
<folders>
<source-folder>
- <label>src/conf</label>
+ <label>Configuration Files</label>
<type>java</type>
<location>src/conf</location>
</source-folder>
<source-folder>
- <label>src/java</label>
+ <label>Java Sources</label>
<type>java</type>
<location>src/java</location>
</source-folder>
<source-folder>
- <label>src/test</label>
+ <label>Test Sources</label>
<type>java</type>
<location>src/test</location>
</source-folder>
@@ -49,15 +49,15 @@
<view>
<items>
<source-folder style="packages">
- <label>src/conf</label>
+ <label>Configuration Files</label>
<location>src/conf</location>
</source-folder>
<source-folder style="packages">
- <label>src/java</label>
+ <label>Java Sources</label>
<location>src/java</location>
</source-folder>
<source-folder style="packages">
- <label>src/test</label>
+ <label>Test Sources</label>
<location>src/test</location>
</source-folder>
<source-file>
Modified: struts/shale/trunk/xdocs/features-tiger-extensions.xml
URL:
http://svn.apache.org/viewcvs/struts/shale/trunk/xdocs/features-tiger-extensions.xml?rev=369184&r1=369183&r2=369184&view=diff
==============================================================================
--- struts/shale/trunk/xdocs/features-tiger-extensions.xml (original)
+++ struts/shale/trunk/xdocs/features-tiger-extensions.xml Sat Jan 14 23:25:47
2006
@@ -10,7 +10,188 @@
<section name="Shale Tiger Extensions">
<a name="tiger"/>
- <p>FIXME - Describe tiger feature.</p>
+ <a name="tiger-introduction"/>
+ <subsection name="Introduction">
+
+ <p>Are you running your web container on a Java SE 5 (code named
+ "Tiger") or later JVM? If so, you can take advantage of several
+ Shale features that are enabled by this underlying platform:</p>
+ <ul>
+ <li>The ability to declare managed bean configuration
+ with annotations, rather than requiring configuration
+ in a <code>faces-config.xml</code> resource.</li>
+ <li>The ability of a backing bean to receive
+ <a href="features-view-controller.html">View Controller</a>
+ event callbacks to arbitrary methods declared with annotations,
+ rather than requiring the backing bean to implement the
+ <code>ViewController</code> interface and provide methods
+ with the names defined by this interface.</li>
+ </ul>
+
+ <p>These features are enabled automatically if you include
+ <code>shale-tiger.jar</code> in your web application.</p>
+
+ </subsection>
+
+ <a name="tiger-services"/>
+ <subsection name="Services Provided">
+
+ <h4>Annotated Managed Beans</h4>
+
+ <p>In a traditional JavaServer Faces application, managed
+ beans must be declared in a <code>faces-config.xml</code>
+ resource supplied by the application. In many cases, the
+ supplied values are effectively constant -- for example, the
+ name that the managed bean is known by is a dependency for
+ other elements of the application (such as value binding
+ expressions). In such cases, it would be very useful to
+ be able to configure the managed bean name, and the scope
+ this bean should be stored in, directly in the bean source
+ code itself.</p>
+
+ <p>In addition to defining the characteristics of the managed
+ bean itself, you can also use the <code>@Value</code>
+ annotation to establish the initial value to which a
+ field should be set. (You must supply a corresponding public
+ property setter method.) This is not particularly useful
+ for setting literal values, because you can accomplish the
+ same result with a Java initialization expression on the
+ instance variable itself. However, it is very useful when
+ you want to specify an application-specific value binding
+ expression, without requiring the developer to explicitly
+ include the configuration in a <code>faces-config.xml</code>
+ resource.</p>
+
+ <p>In some scenarios, an application developer will still want
+ to override the characteristics that are specified via annotations.
+ For this reason, any configuration information in a
+ <code>faces-config.xml</code> resource, for a particular
+ managed bean name, will <em>override</em> the corresponding
+ settings defined by annotations.</p>
+
+ <h4>Annotated View Controllers</h4>
+
+ <p>The <a href="features-view-controller.html">View Controller</a>
+ feature of Shale provides event callback services for several
+ interesting lifecycle events:</p>
+
+ <ul>
+ <li><code>init</code> - Called when the view corresponding
+ to this class has been created or restored.</li>
+ <li><code>preprocess</code> - Called if this view is the one
+ that will process a form submit.</li>
+ <li><code>prerender</code> - Called immediately before this
+ view will be asked to render itself.</li>
+ <li><code>destroy</code> - Called after rendering, for all
+ instances where <code>init</code> was called.</li>
+ </ul>
+
+ <p>In the standard Shale implementation, this functionality is
+ provided in the traditional way -- the backing bean interested
+ in these callbacks is required to implement the
+ <code>org.apache.shale.view.ViewController</code> interface,
+ with fixed method names for each callback. With the Shale Tiger
+ Extensions, however, this is no longer required (although it is,
+ of course, still supported).</p>
+
+ <p>Instead, you implement a backing bean class with no requirements
+ on extending a particular base class, or implementing a particular
+ interface. Instead, you use the <code>@View</code> annotation on
+ the class itself to say that it is interested in view controller
+ callback events. Then, on any public method that takes no arguments,
+ you use the <code>@Init</code>, <code>@Preprocess</code>,
+ <code>@Prerender</code>, or <code>@Destroy</code> annotations
+ to request callbacks, to that particular method, when the corresponding
+ lifecycle event occurs. You are <strong>NOT</strong> required
+ to use a particular method name for these callbacks. In addition,
+ if your backing bean logic is not interested in one or more of the
+ view controller callbacks, you are <code>NOT</code> required to
+ provide a method that is marked with the corresponding annotaiton.</p>
+
+ </subsection>
+
+ <a name="tiger-using"/>
+ <subsection name="Using The Tiger Extensions">
+
+ <p>To use any of the Shale Tiger Extensions in your application,
+ you <strong>MUST</strong> run your web container on a Java SE 5
+ or later container, and <strong>MUST</strong> include the
+ <code>shale-tiger.jar</code> resource in your web application.</p>
+
+ <h4>Using Annotated Managed Beans</h4>
+
+ <p>To use the <em>Annotated Managed Beans</em> feature, you must
+ use the <code>@Bean</code> annotation on the class itself, and
+ set the managed bean name (required) and scope (optional). These
+ elements correspond to the <code><managed-bean-name></code>
+ and <code><managed-bean-scope></code> elements in a
+ <code>faces-config.xml</code> resource. Then, within the class,
+ you can optionally use the <code>@Value</code> annotation on a
+ field to provide a literal value, or value binding expression,
+ that will provide the initial value for the corresponding property.</p>
+
+ <p>Putting it all together, you might end up with a class that
+ looks like this:</p>
+
+<source>
+ package com.mycompany.mypackage;
+
+ import org.apache.shale.tiger.managed.Bean;
+ import org.apache.shale.tiger.managed.Scope;
+ import org.apache.shale.tiger.managed.Value;
+
+ // Define a managed bean named "mybean" to be put in session scope
+ @Bean(name="mybean" scope=Scope.SESSION)
+ public class MyBeanClass { // No required superclass or interface
+
+ // Name a property that will be initialized via expression
+ @Value("#{otherBean.otherProperty}")
+ private String name = null;
+
+ public String getName() { return this.name; }
+ public void setName(String name) { this.name = name; }
+
+ }
+</source>
+
+ <h4>Using Annotated View Controllers</h4>
+
+ <p>To use the <em>Annotated View Controllers</em> feature,
+ you must use the <code>@View</code> annotation on the class
+ itself. Then, you can use the <code>@Init</code>,
+ <code>@Preprocess</code>, <code>@Prerender</code>, and
+ <code>@Destroy</code> annotations on the methods that you
+ wish to have notified when the corresponding lifecycle trips
+ occur. You need to implement only the callbacks you are
+ interested in (unlike the traditional implementation of an
+ interface, where you must provide implementations for all of
+ the defined method signatures).</p>
+
+ <p>A class that wishes to receive view controller callbacks
+ via these annotations might look like this:</p>
+
+<source>
+ package com.mycompany.mypackage;
+
+ import org.apache.shale.tiger.view.Init;
+ import org.apache.shale.tiger.view.Preprocess;
+ import org.apache.shale.tiger.view.View;
+
+ @View public class MyBean { // No required superclass or interface
+
+ // Name your init() method whatever you want
+ @Init public void myInit() { ... }
+
+ // Same with the prerender() method
+ @Prerender public void justBeforeRendering() { ... }
+
+ // This class is not interested in preprocess or destroy
+ // methods, so they are not defined
+
+ }
+</source>
+
+ </subsection>
</section>
Modified: struts/shale/trunk/xdocs/using.xml
URL:
http://svn.apache.org/viewcvs/struts/shale/trunk/xdocs/using.xml?rev=369184&r1=369183&r2=369184&view=diff
==============================================================================
--- struts/shale/trunk/xdocs/using.xml (original)
+++ struts/shale/trunk/xdocs/using.xml Sat Jan 14 23:25:47 2006
@@ -93,6 +93,13 @@
<td align="center">---</td>
</tr>
<tr>
+ <td><code>shale-tiger.jar</code></td>
+ <td>Java SE</td>
+ <td>5 or later</td>
+ <td><strong>MUST</strong> be running on a Java SE 5
+ (code name "Tiger") or later JDK.</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>
@@ -142,15 +149,21 @@
<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>
+ (<code>shale-clay.jar</code>, <code>shale-spring.jar</code>,
+ <code>shale-tiger.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>
+
+ <p>The <code>shale-tiger.jar</code> contains feature extensions
+ that depend on platform capabilities (most particularly the
+ annotations facility) of Java SE 5 (code named "Tiger"). You
+ must <strong>NOT</strong> include this library if you are running
+ on a JDK 1.4 platform.</p>
<h4>(B) Configure <code>/WEB-INF/web.xml</code> Resource</h4>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
