Author: craigmcc
Date: Sat Jul 9 11:09:36 2005
New Revision: 209961
URL: http://svn.apache.org/viewcvs?rev=209961&view=rev
Log:
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/index.xml
struts/core/trunk/doc/shale/project.xml
Modified: struts/core/trunk/doc/shale/features.xml
URL:
http://svn.apache.org/viewcvs/struts/core/trunk/doc/shale/features.xml?rev=209961&r1=209960&r2=209961&view=diff
==============================================================================
--- 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>
+ <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 is
+ 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 can
+ 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>
+<env-entry>
+ <description>Flag indicating whether we run in debug
mode.</description>
+ <env-entry-name>debugMode</env-entry-name>
+ <env-entry-value>false</env-entry-value>
+ <env-entry-type>java.lang.Boolean<env-entry-type>
+</env-entry>
+</pre></blockquote>
+
+ <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>
+<h:outputText ... rendered="#{jndi.debugMode}" .../>
+</pre></blockquote>
+
+ <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>
+<resource-ref>
+ <description>Customer Database</description>
+ <res-ref-name>jdbc/CustomerDB</res-ref-name>
+ <res-type>javax.sql.DataSource</res-type>
+ <res-auth>Container</res-auth>
+</resource-ref>
+</pre></blockquote>
+
+ <p>You can acquire a <code>java.sql.Connection</code> from this data
+ 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);
+</pre></blockquote>
+
+ <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
URL:
http://svn.apache.org/viewcvs/struts/core/trunk/doc/shale/index.xml?rev=209961&r1=209960&r2=209961&view=diff
==============================================================================
--- 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
out,
+ 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>
<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>
+
</subsection>
Modified: struts/core/trunk/doc/shale/project.xml
URL:
http://svn.apache.org/viewcvs/struts/core/trunk/doc/shale/project.xml?rev=209961&r1=209960&r2=209961&view=diff
==============================================================================
--- 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: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
