struts-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r209961 - in /struts/core/trunk/doc/shale: features.xml index.xml project.xml
Date Sat, 09 Jul 2005 18:09:37 GMT
Author: craigmcc
Date: Sat Jul  9 11:09:36 2005
New Revision: 209961

Documentation updates for the Shale website

* Flesh out the "background" section

* Document the required and optional dependencies

* Add a feature description for JNDI integration


Modified: struts/core/trunk/doc/shale/features.xml
--- struts/core/trunk/doc/shale/features.xml (original)
+++ struts/core/trunk/doc/shale/features.xml Sat Jul  9 11:09:36 2005
@@ -417,6 +417,127 @@
+    <section name="Shale JNDI Integration"    href="jndi">
+      <subsection name="JNDI Introduction"    href="jndi-introduction">
+        <p>The <em>Java Naming and Directory Interface</em> (JNDI) API
+        commonly used in a Java2 Enterprise Edition (J2EE) (recently renamed
+        to Java Enterprise Edition (Java EE)) to acquire references to
+        resources that are declared in either:</p>
+        <ul>
+        <li>The deployment descriptor (<code>web.xml</code>) provided with
+            the application.</li>
+        <li>The customized configuration settings applied when the application
+            is depoyed to a particular instance of a particular application
+            server.</li>
+        </ul>
+        <p>As an example of the usefulness of this technique, consider an
+        application that requires a JDBC data source (i.e. a connection pool).
+        Consider also that the development environment contains two instances
+        of the database (development and staging), in addition to the production
+        instance.  If your application can define just a <em>reference</em>
+        to the data source, then the same web application archive (WAR) can
+        be deployed, unchanged, to <strong>any</strong> of these instances.
+        The hookup to a particular database instance is performed through
+        deployment configuration, rather than modifying property settings in
+        the WAR for each environment.</p>
+      </subsection>
+      <subsection name="Services Provided" href="jndi-services">
+        <p>Shale includes custom instances of the <code>VariableResolver</code>
+        and <code>PropertyResolver</code> APIs, from JavaServer Faces, that
+        allow value binding and method binding expressions to navigate through
+        the JNDI <code>InitialContext</code> (and subcontexts) that are provided
+        to each web application by the application server.  Such expressions can
+        be used to configure the values for properties of a JSF component, in
+        the usual way.  In addition, expressions can be evaluated programatically
+        in your event handling code -- providing an easier to use mechanism for
+        acquiring such resources.</p>
+        <p>For example, assume you have a data source (i.e. instance of
+        <code>javax.sql.DataSoruce</code>) with a resource reference name
+        of <code>jdbc/CustomerDB</code> defined in your deployment descriptor.
+        You can programmatically gain access to this data source by evaluating
+        the following expression:</p>
+        <blockquote><code>#{jndi['jdbc/CustomerDB']}</code></blockquote>
+      </subsection>
+      <subsection name="Using JNDI Integration" href="jndi-using">
+        <p>Two examples of using the JNDI integration capabilities are
+        presented -- one using a value binding to a JSF component property,
+        and one using programmatic access to acquire a resource.</p>
+        <p><strong>(1) Binding to JSF Component Property</strong></p>
+        <p>JNDI supports the concept of <em>environment entries</em> that
+        be declared in the deployment descriptor, and optionally modified by
+        the deployment configuration when the application is instaled in a
+        particular environment.  Let's assume that you have a boolean
+        environment entry to define whether your application is running in
+        debug mode or not, declared in <code>web.xml</code> like this:</p>
+        <blockquote><pre>
+  &lt;description&gt;Flag indicating whether we run in debug mode.&lt;/description&gt;
+  &lt;env-entry-name&gt;debugMode&lt;/env-entry-name&gt;
+  &lt;env-entry-value&gt;false&lt;/env-entry-value&gt;
+  &lt;env-entry-type&gt;java.lang.Boolean&lt;env-entry-type&gt;
+        <p>Now, assume you have a status message that you only want to have
+        displayed when debug mode is enabled.  You can bind the
+        <code>rendered</code> property of the component to this environment
+        entry value:</p>
+        <blockquote><pre>
+&lt;h:outputText ... rendered="#{jndi.debugMode}" .../&gt;
+        <p><strong>(2) Programmatic Resource Access</strong></p>
+        <p>Assume you have a data source reference (discussed in the introduction)
+        defined in your <code>web.xml</code> like this:</p>
+        <blockquote><pre>
+  &lt;description&gt;Customer Database&lt;/description&gt;
+  &lt;res-ref-name&gt;jdbc/CustomerDB&lt;/res-ref-name&gt;
+  &lt;res-type&gt;javax.sql.DataSource&lt;/res-type&gt;
+  &lt;res-auth&gt;Container&lt;/res-auth&gt;
+        <p>You can acquire a <code>java.sql.Connection</code> from this
+        source with code like the following (note that the convenience base
+        class <code>BaseViewController</code> contains a <code>getBean()</code>
+        method that substantially reduces the amount of code needed):</p>
+        <blockquote><pre>
+FacesContext context = FacesContext.getCurrentInstance();
+ValueBinding vb =
+  context.getApplication().createValueBinding("#{jndi['jdbc/CustomerDB'].connection}");
+Connection conn = (Connection) vb.getValue(context);
+        <p>This works by first retrieving the JNDI-configured data source
+        instance, and then calling its <code>getConnection()</code> method.
+        After you are through with the connection, return it to the pool
+        by calling the connection's <code>close()</code> method.</p>
+      </subsection>
+    </section>
     <section name="Shale Spring Integration"  href="spring">
       <p>FIXME - Describe Spring integration feature.</p>

Modified: struts/core/trunk/doc/shale/index.xml
--- struts/core/trunk/doc/shale/index.xml (original)
+++ struts/core/trunk/doc/shale/index.xml Sat Jul  9 11:09:36 2005
@@ -51,13 +51,92 @@
         in terms of its continued popularity, that this is a good
         strategic approach.</p>
+        <p>But, it is also time to harvest many of the great ideas that have
+        matured in the last several years.  It is time to base a web tier
+        framework on top of the new standard API in this space (JavaServer Faces),
+        and eliminate the need to implement redundant features, instead of just
+        treating JSF as a UI component technology.  It is time to answer the
+        question "if we knew then what we know now, what would Struts have
+        looked like?"</p>
+        <p>Thus, Shale is a proposal for a modern web application framework,
+        fundamentaly based on JavaServer Faces, and focused on improving
+        ease of use for developers adopting JSF as a foundational technology
+        in their own development environments.  At the same time, the
+        architecture of Shale is a set of fine grained services (and service
+        options) that can be combined as needed to meet particular application
+        requirements, rather than a monolithic request processor that is hard
+        to customize and extend.  In addition, integration links for other
+        frameworks and framework components are provided, to ease development
+        when combinations of technologies are required.</p>
+        <blockquote><em>EDITOR'S NOTE:  Why "Shale"?  As others have pointed
+        the cultural rules of engagement at Apache encourage both evolution
+        and revolution in software designs.  Revolutions are typically assigned
+        code names while they are under discussion, gaining access to the
+        branding of the overall project once they are accepted (or, going off
+        on their own if they are not).  Other proposals for Struts 2.x have
+        talked about tearing down the walls inside the framework, and those
+        are Good Things.  Shale's architecture, on the other hand, is based
+        on the principle that we should fundamentally divide the notion of a
+        web application framework into solid individual layers, much as we
+        see geologically in shale deposits around our volcanoes and coastlines.
+        Each layer of the framework should focus on the specific requirements
+        that are relevant to that layer -- and use of one layer should not
+        necessarily require the use of all the rest (although it's certainly
+        reasonable for synergies to exist if all the layers are chosen :-).
+        Hence, "shale".</em></blockquote>
       <subsection name="Foundations"    href="background-foundations">
-        <p>FIXME - describe foundational technologies.</p>
+        <p>Shale is based on (and requires a runtime environment that
+        supports) the following foundation technologies:</p>
+        <ul>
+        <li>Java Runtime Environment (JRE) 1.4 or later.</li>
+        <li>Servlet API 2.4 or later. (*)</li>
+        <li>JavaServer Pages 2.0 or later. (*)</li>
+        <li>JavaServer Faces 1.1 or later.</li>
+        <li>JSP Standard Tag Library (JSTL) 1.1 or later.</li>
+        <li>Apache Commons BeanUtils 1.7 or later.</li>
+        <li>Apache Commons Chain 1.0 or later.</li>
+        <li>Apache Commons Digester 1.7 or later.</li>
+        <li>Apache Commons Logging 1.0.4 or later.</li>
+        </ul>
+        <p>(*) Although the sample applications shipped with Shale are
+        configured for these Servlet and JSP versions, at the time of this
+        writing Shale itself does not rely on them; you can successfully
+        run Shale based applications on a Servlet 2.3 / JSP 1.2 platform
+        by using the appropriate syntax in deployment descriptors and JSP
+        pages, and substituting a JSTL 1.0 library for the JSTL 1.1 library
+        listed above.  This is <strong>not</strong> a committed feature for
+        a 1.0 release, unless discussion on the development and user mailing
+        lists indicates that it is important to a significant number of
+        users.</p>
+        <p>Various optional Shale components have dependencies on the following
+        additional runtime technologies:</p>
+        <ul>
+        <li>Apache Commons Validator 1.1.4 or later.</li>
+        <li>Spring Framework 1.2.2 or later.</li>
+        <li>Struts Tiles (Stand Alone) - currently in Struts Sandbox.</li>
+        </ul>
+        <p>If you wish to work on Shale itself, you will require the following
+        additional resources:</p>
+        <ul>
+        <li>Java Development Kit (JDK) 1.4 or later.</li>
+        <li>Apache Ant 1.6.3 or later.</li>
+        <li>FindBugs (SourceForge Project) 0.8.6 or later (optional).</li>
+        <li>JUnit 3.8.1 or later.</li>
+        </ul>

Modified: struts/core/trunk/doc/shale/project.xml
--- struts/core/trunk/doc/shale/project.xml (original)
+++ struts/core/trunk/doc/shale/project.xml Sat Jul  9 11:09:36 2005
@@ -19,6 +19,7 @@
         <item name="Application Manager" href="features.html#application"/>
         <item name="Validation"         href="features.html#validation"/>
         <item name="Remoting"           href="features.html#remoting"/>
+        <item name="JNDI Integration"   href="features.html#jndi"/>
         <item name="Spring Integration" href="features.html#spring"/>
         <item name="Reusable Views"     href="features.html#clay"/>
         <item name="Test Framework"     href="features.html#test"/>

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message