Author: rahul
Date: Wed Oct 25 15:10:45 2006
New Revision: 467786
URL: http://svn.apache.org/viewvc?view=rev&rev=467786
Log:
Beginnings of a site for the shale-core module. Includes a blurb for the index
page and the features-* JNDI content.
SHALE-306
Added:
shale/framework/trunk/shale-core/src/site/xdoc/index.xml (with props)
shale/framework/trunk/shale-core/src/site/xdoc/jndi-integration.xml (with
props)
Added: shale/framework/trunk/shale-core/src/site/xdoc/index.xml
URL:
http://svn.apache.org/viewvc/shale/framework/trunk/shale-core/src/site/xdoc/index.xml?view=auto&rev=467786
==============================================================================
--- shale/framework/trunk/shale-core/src/site/xdoc/index.xml (added)
+++ shale/framework/trunk/shale-core/src/site/xdoc/index.xml Wed Oct 25
15:10:45 2006
@@ -0,0 +1,62 @@
+<?xml version="1.0"?>
+<document>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to you under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+ <properties>
+ <title>Shale Core</title>
+ </properties>
+
+ <body>
+
+ <section name="Shale Core">
+ <a name="core"/>
+
+ <p>Shale includes a core library providing useful additions and
+ utilies for JSF applications.</p>
+
+ <a name="core-services"/>
+ <subsection name="Services Provided">
+
+ <ul>
+
+ <li><a href="jndi-integration.html">JNDI Integration</a> - 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.</li>
+
+ <li><a href="tagreference.html">Shale Core Taglib</a> -
+ A tag library that provides a <s:token> tag that that
+ renders a transaction token (hidden) input field, and then
+ validates it on a subsequent form submit.</li>
+
+ <li><a
href="apidocs/org/apache/shale/util/package-summary.html">Utility classes</a>
+ - A set of helper classes spanning topics such as
+ internationalization, access to JSF converters and utilities for
+ JSF tags and JavaBeans properties.</li>
+
+ </ul>
+
+ </subsection>
+
+ </section>
+
+ </body>
+
+</document>
Propchange: shale/framework/trunk/shale-core/src/site/xdoc/index.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: shale/framework/trunk/shale-core/src/site/xdoc/index.xml
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
Added: shale/framework/trunk/shale-core/src/site/xdoc/jndi-integration.xml
URL:
http://svn.apache.org/viewvc/shale/framework/trunk/shale-core/src/site/xdoc/jndi-integration.xml?view=auto&rev=467786
==============================================================================
--- shale/framework/trunk/shale-core/src/site/xdoc/jndi-integration.xml (added)
+++ shale/framework/trunk/shale-core/src/site/xdoc/jndi-integration.xml Wed Oct
25 15:10:45 2006
@@ -0,0 +1,151 @@
+<?xml version="1.0"?>
+<document>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to you under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+ <properties>
+ <title>Shale JNDI Integration</title>
+ </properties>
+
+ <body>
+
+ <section name="Shale JNDI Integration">
+ <a name="jndi"/>
+
+ <a name="jndi-introduction"/>
+ <subsection name="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>
+
+ <a name="jndi-services"/>
+ <subsection name="Services Provided">
+
+ <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>
+
+ <a name="jndi-using"/>
+ <subsection name="Using JNDI Integration">
+
+ <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 installed 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>
+
+<source>
+<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>
+</source>
+
+ <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>
+
+<source>
+<h:outputText ... rendered="#{jndi.debugMode}" .../>
+</source>
+
+ <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>
+
+<source>
+<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>
+</source>
+
+ <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>
+
+<source>
+FacesContext context = FacesContext.getCurrentInstance();
+ValueBinding vb =
+
context.getApplication().createValueBinding("#{jndi['jdbc/CustomerDB'].connection}");
+Connection conn = (Connection) vb.getValue(context);
+</source>
+
+ <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>
+
+ </body>
+
+</document>
Propchange: shale/framework/trunk/shale-core/src/site/xdoc/jndi-integration.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: shale/framework/trunk/shale-core/src/site/xdoc/jndi-integration.xml
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
