struts-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From craig...@apache.org
Subject svn commit: r369184 - in /struts/shale/trunk: core-library/src/java/org/apache/shale/view/faces/CallbacksFactory.java tiger/nbproject/project.xml xdocs/features-tiger-extensions.xml xdocs/using.xml
Date Sun, 15 Jan 2006 07:26:00 GMT
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>&lt;managed-bean-name&gt;</code>
+        and <code>&lt;managed-bean-scope&gt;</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
+    &#64;Bean(name="mybean" scope=Scope.SESSION)
+    public class MyBeanClass { // No required superclass or interface
+
+        // Name a property that will be initialized via expression
+        &#64;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;
+
+    &#64;View public class MyBean { // No required superclass or interface
+
+        // Name your init() method whatever you want
+        &#64;Init public void myInit() { ... }
+
+        // Same with the prerender() method
+        &#64;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: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org


Mime
View raw message