You are viewing a plain text version of this content. The canonical link for it is here.
Posted to taglibs-dev@jakarta.apache.org by pi...@apache.org on 2001/12/12 21:12:35 UTC
cvs commit: jakarta-taglibs/standard/examples/web index.html
pierred 01/12/12 12:12:35
Modified: standard/doc/conf web.xml
standard/doc/web GettingStarted.html Overview.html
index.html
standard/examples/web index.html
Added: standard/doc/web DB_FunctionalDescription_1_EA3.html
I18N_FunctionalDescription_6_EA3.html
Log:
Doc update for EA3
Revision Changes Path
1.2 +1 -1 jakarta-taglibs/standard/doc/conf/web.xml
Index: web.xml
===================================================================
RCS file: /home/cvs/jakarta-taglibs/standard/doc/conf/web.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- web.xml 2001/11/21 07:34:07 1.1
+++ web.xml 2001/12/12 20:12:35 1.2
@@ -7,7 +7,7 @@
<web-app>
<description>
- Documentation for the 'standard' tag library (JSTL EA2)
+ Documentation for the 'standard' tag library (JSTL EA3)
</description>
</web-app>
1.3 +75 -93 jakarta-taglibs/standard/doc/web/GettingStarted.html
Index: GettingStarted.html
===================================================================
RCS file: /home/cvs/jakarta-taglibs/standard/doc/web/GettingStarted.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- GettingStarted.html 2001/11/27 19:39:41 1.2
+++ GettingStarted.html 2001/12/12 20:12:35 1.3
@@ -5,7 +5,7 @@
</head>
<body bgcolor="#FFFFFF">
-<h1>Getting started with JSTL (EA2)</h1>
+<h1>Getting started with JSTL (EA3)</h1>
<p>This document describes how to get up and running quickly with JSTL's
second early-access release. It can be useful to page authors and tag
@@ -24,13 +24,13 @@
<hr />
<h2>Introduction</h2>
-<a name="#1.1" />
+<a name="#1.1" /></a>
<h3>What is JSTL? Where does it come from?</h3>
<p>JSTL is the JSP(tm) Standard Tag Library. It is an effort of the Java
Community Process (JCP) and comes out of the JSR-052 expert group.</p>
-<a name="#1.2" />
+<a name="#1.2" /></a>
<h3>What does JSTL do?</h3>
<p>JSTL encapsulates, as simple tags, core functionality common to many
@@ -61,16 +61,19 @@
finalized: mail us at <a href="mailto:jsr052-comments@sun.com">
jsr052-comments@sun.com</a> if you have any comments.</p>
+<h3>What has changed since EA2?</h3>
+<p>Please see the <a href="ReleaseNotes_EA3.html">Release Notes</a> document for
+ information on JSTL RI changes.</p>
<h3>What has changed since EA1?</h3>
-<p>Please see the <a href="ReleaseNotes.html">Release Notes</a> document
-for information on JSTL RI changes.</p>
+<p>Please see the <a href="ReleaseNotes.html">Release Notes</a> document for information
+ on JSTL RI changes.</p>
+<p> </p>
<hr />
-<h2><a name="#2" />Getting started quickly</h2>
+<h2><a name="#2" /></a>Getting started quickly</h2>
-<p>JSTL EA2 uses features provided only by the JSP 1.2 standard draft, so
-it requires a JSP 1.2 container. We recommend you test JSTL with Tomcat
-4.0.</p>
+<p>JSTL EA3 uses features provided only by the JSP 1.2 standard draft, so it requires
+ a JSP 1.2 container. We recommend you test JSTL with Tomcat 4.0.</p>
<p>To install Tomcat, follow the instructions at <a
href="http://jakarta.apache.org/tomcat">http://jakarta.apache.org/tomcat</a>.
@@ -105,10 +108,10 @@
<h3>Expression languages</h3>
-<p>Half of JSTL's tag libraries -- the recommended ones -- rely on an
-expression language. To facilitate experimentation and feedback, the
-JSTL RI currently lets you switch between a number of different languages.
-For EA2, the ECMAScript language is the default.</p>
+<p>Half of JSTL's tag libraries -- the recommended ones -- rely on an expression
+ language. To facilitate experimentation and feedback, the JSTL RI currently
+ lets you switch between a number of different languages. Since EA2, the ECMAScript
+ language has been set as the default.</p>
<p>The expression language for a web application is configured by
setting the servlet context parameter
@@ -126,11 +129,11 @@
<tt>web.xml</tt> file that comes with the <tt>jstl-examples</tt>
application.)</p>
-<p>In JSTL EA2, you can also mix different expression languages on the
-same page using the <tt><expressionLanguage></tt> tag. This tag's
-<tt>evaluator</tt> attribute points to the class containing the
-expression-evaluation logic you wish to use. See the Functional
-Description of expression-language support for more information.</p>
+<p>In JSTL EA, you can also mix different expression languages on the same page
+ using the <tt><expressionLanguage></tt> tag. This tag's <tt>evaluator</tt>
+ attribute points to the class containing the expression-evaluation logic you
+ wish to use. See the Functional Description of expression-language support for
+ more information.</p>
<p>The attributes in tags for the EL version of the library do not accept
rtexprvalues. Instead, you specify literal expressions that the tags
@@ -139,85 +142,64 @@
<pre>
<c:forEach items="<b>$page:myItems</b>" />
</pre>
-
-<i><b>Important:</b> The expression-language support included with JSTL
-JSTL EA2 should be considered even more experimental than the rest of the
-package. You should not assume that either the "pluggability" mechanism
-or the prepackaged languages themselves will remain in JSTL's final
-version, or even in the next EA releases.</i>
-
-<h3>Topics covered in JSTL EA2</h3>
-
-<p>As we mentioned above, JSTL EA2 includes core tags to support
-iteration, conditionals, and expression-language support. For more
-information on precisely how these tags work, you should read the
-"Functional Description" documents provided as part of this distribution.
-Here, we just offer a quick roadmap of each feature in order to help
-orient you.</p>
-
-<dl>
-<dt><b>Iteration</b></dt>
-
-<dd>The core iteration tag is <forEach>, which iterates over most
-collections and similar objects you'd think to iterate over.
-<forTokens> lets you iterate over tokens in a <tt>String</tt>
-object; it lets you specify the <tt>String</tt> and the delimiters.</dd>
-
-<dt><b>Conditionals</b></dt>
-
-<dd>JSTL EA2 supports a simple conditional <if> tag along with
-a collection of tags -- <choose>, <when>, and <otherwise>
--- that support mutually exclusive conditionals. These latter three
-tags let you implement a typical <tt>if/else if/else if/else</tt>
-structure.</dd>
-
-<dt>
-<b>Expression languages</b></dt>
-
-<dd>We described the EL support in JSTL EA2 above. In addition to
-<expressionLanguage>, JSTL EA2 provides a few other tags to
-facilitate use of expression language. <expr> prints out the value
-of a particular expression in the current EL, similar to the way that the
-scriptlet expression (<%= ... %=>) syntax prints out the value of a
-expression in the scripting language (typically Java). <set> lets
-you set a scoped attribute (e.g., a value in the request, page, session,
-or application scopes) with the value of an expression.</dd>
-
-<dt>
-<b>Text inclusion</b></dt>
-
-<dd>JSP supports the <tt>jsp:include</tt> tag, but this standard action is
-limited in that it only supports relative URLs. JSTL EA2 introduces the
-<tt>c:import</tt> tag, which lets you retrieve absolute URLs. For
-instance, you can use <tt>c:import</tt> to retrieve information from the
-web using HTTP URLs, or from a file server using an FTP URL. The tag also
-has some advanced support for performance optimizations, avoiding
-unnecessary buffering of data that's retrieved.</dd>
-
-<dt>
-<b>I18N-capable text formatting</b></dt>
-
-<dd>Formatting data is one of the key tasks in many JSP pages. JSTL
-introduces tags to support data formatting and parsing. These tags
-rely on convenient machinery to support internationalized applications.
-</dd>
-
-<dt>
-<b>XML manipulation</b></dt>
-
-<dd>You can't look anywhere these days without seeing XML, and JSTL
-gives you convenient support for manipulating it from your JSP pages.
-Parse documents, use XPath to select content, and perform XSLT transformations
-from within your JSP pages.</dd>
-
+<i><b>Important:</b> The expression-language support included with JSTL EA should
+be considered even more experimental than the rest of the package. You should
+not assume that either the "pluggability" mechanism or the prepackaged languages
+themselves will remain in JSTL's final version, or even in the next EA releases.</i>
+<h3>Topics covered in JSTL EA3</h3>
+
+<p>As we mentioned above, JSTL EA3 includes core tags to support iteration, conditionals,
+ and expression-language support. For more information on precisely how these
+ tags work, you should read the "Functional Description" documents provided as
+ part of this distribution. Here, we just offer a quick roadmap of each feature
+ in order to help orient you.</p>
+
+<dl>
+ <dt><b>Iteration</b></dt>
+ <dd>The core iteration tag is <forEach>, which iterates over most collections
+ and similar objects you'd think to iterate over. <forTokens> lets you
+ iterate over tokens in a <tt>String</tt> object; it lets you specify the <tt>String</tt>
+ and the delimiters.</dd>
+ <dt><b>Conditionals</b></dt>
+ <dd>JSTL supports a simple conditional <if> tag along with a collection
+ of tags -- <choose>, <when>, and <otherwise> -- that support
+ mutually exclusive conditionals. These latter three tags let you implement
+ a typical <tt>if/else if/else if/else</tt> structure.</dd>
+ <dt> <b>Expression languages</b></dt>
+ <dd>We described the EL support in JSTL above. In addition to <expressionLanguage>,
+ JSTL provides a few other tags to facilitate use of expression language. <expr>
+ prints out the value of a particular expression in the current EL, similar
+ to the way that the scriptlet expression (<%= ... %=>) syntax prints
+ out the value of a expression in the scripting language (typically Java).
+ <set> lets you set a scoped attribute (e.g., a value in the request,
+ page, session, or application scopes) with the value of an expression.</dd>
+ <dt> <b>Text inclusion</b></dt>
+ <dd>JSP supports the <tt>jsp:include</tt> tag, but this standard action is limited
+ in that it only supports relative URLs. JSTL introduces the <tt>c:import</tt>
+ tag, which lets you retrieve absolute URLs. For instance, you can use <tt>c:import</tt>
+ to retrieve information from the web using HTTP URLs, or from a file server
+ using an FTP URL. The tag also has some advanced support for performance optimizations,
+ avoiding unnecessary buffering of data that's retrieved.</dd>
+ <dt> <b>I18N-capable text formatting</b></dt>
+ <dd>Formatting data is one of the key tasks in many JSP pages. JSTL introduces
+ tags to support data formatting and parsing. These tags rely on convenient
+ machinery to support internationalized applications. </dd>
+ <dt> <b>XML manipulation</b></dt>
+ <dd>You can't look anywhere these days without seeing XML, and JSTL gives you
+ convenient support for manipulating it from your JSP pages. Parse documents,
+ use XPath to select content, and perform XSLT transformations from within
+ your JSP pages.</dd>
+ <dt><b>Database access</b></dt>
+ <dd>Easily access relational databases using the SQL actions.</dd>
+ <dt> </dt>
</dl>
<h3>For tag developers...</h3>
-<p>Developers of custom tags should also read the "Functional
-Descriptions" provided for each topic addressed by JSTL EA2. JSTL EA2
-provides some abstract classes that assist with rapid development of tags
-and promote integration of custom tags with JSTL's tag set.</p>
+<p>Developers of custom tags should also read the "Functional Descriptions" provided
+ for each topic addressed by JSTL EA. JSTL EA provides some abstract classes
+ that assist with rapid development of tags and promote integration of custom
+ tags with JSTL's tag set.</p>
<p>For instance, custom tags can use JSTL's expression-language
mechanism. As another example, extending
1.4 +136 -6 jakarta-taglibs/standard/doc/web/Overview.html
Index: Overview.html
===================================================================
RCS file: /home/cvs/jakarta-taglibs/standard/doc/web/Overview.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- Overview.html 2001/11/26 22:51:30 1.3
+++ Overview.html 2001/12/12 20:12:35 1.4
@@ -7,7 +7,7 @@
<body bgcolor="#FFFFFF" text="#000000">
<h1>Overview</h1>
<p>This document provides a high level overview of the JSP™ Standard Tag
- Library (JSTL) as it stands for EA2 (Early Access release 2). If you have a
+ Library (JSTL) as it stands for EA3 (Early Access release 3). If you have a
strong opinion on the topic — positive (you really like it), or constructive
(we messed up some parts and you have some constructive comments for improvements)
— we'll be happy to hear from you at <a href="mailto:jsr052-comments@sun.com">jsr052-comments@sun.com</a>.
@@ -73,12 +73,12 @@
<td><font face="Courier New, Courier, mono"><fmt:<i>tagname</i> ...></font></td>
</tr>
<tr>
- <td>Database access</td>
- <td>http://java.sun.com/jstl/ea/db</td>
+ <td>Database access (SQL)</td>
+ <td>http://java.sun.com/jstl/ea/sql</td>
<td>
- <div align="center"><font face="Courier New, Courier, mono">db</font></div>
+ <div align="center"><font face="Courier New, Courier, mono">sql</font></div>
</td>
- <td><font face="Courier New, Courier, mono"><db:<i>tagname</i> ...></font></td>
+ <td><font face="Courier New, Courier, mono"><sql:<i>tagname</i> ...></font></td>
</tr>
</table>
</div>
@@ -152,7 +152,7 @@
of a tag; i.e. tags with lots of attributes that can do just about anything.
Rather, we privilege a larger number of tags with well focused behavior.</p>
<hr noshade>
-<h2>JSTL EA2— Quick Reference</h2>
+<h2>JSTL EA3— Quick Reference</h2>
<h2>Core Actions</h2>
<table width="100%" border="1" cellpadding="5">
<tr bgcolor="#000099">
@@ -663,6 +663,136 @@
is given) in its localized form</font>
</td>
<td width="392"><tt><fmt:exception bundle="$errorMessages"/></tt></td>
+ </tr>
+</table>
+<h2>SQL actions</h2>
+<table border="1" cellpadding="5">
+ <tr>
+ <td colspan="2" bgcolor="#000099"><b><font color="#FFFFFF" size="+1">SQL Actions</font></b></td>
+ </tr>
+ <tr bgcolor="#FFFF66">
+ <td><b>Action</b></td>
+ <td><b>Sample usage</b></td>
+ </tr>
+ <tr>
+ <td>
+ <p><code><b><sql:query></b></code></p>
+ <p><code><sql:query var=<i>"varName"</i> <br>
+ sql="<i>sqlQuery</i>"<br>
+ [dataSource=<i>dataSourceSpec</i>]<br>
+ [maxRows="<i>maxRows</i>"]<br>
+ [startRow="<i>startRow</i>"]/></code></p>
+ <p><code><sql:query var=<i>"varName"<br>
+ </i> [sql="<i>sqlQuery</i>"]<br>
+ [dataSource=<i>dataSourceSpec</i>]<br>
+ [maxRows="<i>maxRows</i>"]<br>
+ [startRow="<i>startRow</i>"]/>
+ </code><code><br>
+ ... optional query statement ...<br>
+ ... optional <sql:param> actions ...<br>
+ </sql:query></code></p>
+ <p>General purpose action for performing SQL queries on a database and gettting
+ back a single result set containing rows of data.</p>
+ </td>
+ <td>
+ <p><code><sql:query var="customers"<br>
+
+ dataSource="$dataSource"<i>><br>
+ </i> SELECT * FROM employees<br>
+ WHERE country = 'China'<br>
+ ORDER BY lastname<br>
+ </sql:query><i> </i></code></p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <p><code><b><sql:update></b></code></p>
+ <p><code><sql:update var=<i>"varName"</i> <br>
+ sql="<i>sqlUpdate</i>"<br>
+ [dataSource=<i>dataSourceSpec</i>]/></code></p>
+ <p><code><sql:update var=<i>"varName"<br>
+ </i></code><code> [sql="<i>sqlUpdate</i>"]<br>
+ [dataSource=<i>dataSourceSpec</i>]><br>
+ ... optional query statement ...<br>
+ ... optional <sql:param> actions ...<br>
+ </sql:update></code></p>
+ <p>General purpose action for "updates"; i.e. statements that
+ update the database (insert, update, delete) and return nothing or a single
+ integer. </p>
+ </td>
+ <td>
+ <p><code><sql:update><br>
+ UPDATE account <br>
+ SET BALANCE = ?<br>
+ WHERE accountNo = ?<br>
+ </code><code> <sql:param<br>
+ value="$balance"><br>
+ <sql:param<br>
+ value="$accountNo"><br>
+ </sql:update></code></p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <p><code><b><sql:transaction><br>
+ </b></code><br>
+ <code><sql:transaction <br>
+ [dataSource=<i>dataSourceSpec</i>] <br>
+ [transactionIsolation=<i>"transactionIsolationLevel"</i>]><br>
+ ... <sql:query> and <sql:update> statements ...<br>
+ </sql:transaction> </code></p>
+ </td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td>
+ <p><code><b><sql:driver><br>
+ </b></code><br>
+ <code><sql:driver var=<i>"varName"</i><br>
+ [driver="<i>driverClassName</i>"]
+ <br>
+ [jdbcUrl="<i>jdbcUrl</i>"]<br>
+ [userName="<i>userName</i>"]
+ /></code><br>
+ </p>
+ <p>Facilitates the setup of a DataSource object around a JDBC driver for
+ prototype/simple applications. </p>
+ </td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td>
+ <p><code><b><sql:param><br>
+ </b></code> </p>
+ <p><code><sql:param value=<i>"parameterValue"</i>/></code></p>
+ <p><code><sql:param><br>
+ ... parameter value ...<br>
+ </sql:param></code><br>
+ </p>
+ <p>Subtag of SQLExecutionTag actions such as <sql:query> and <sql:update>
+ to set the values of parameter markers ('?') specified in the SQL statement.</p>
+ </td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td>
+ <p><code><b><sql:query> result related interfaces<br>
+ </b></code> </p>
+ <p><code>public interface Result<br>
+ </code><code> </code><code>public interface ResultMetaData<br>
+ </code><code>public interface Row</code><code><br>
+ public interface ColumnMetaData</code><code><br>
+ public </code><code>interface Column</code></p>
+ </td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td>
+ <p><code><b>interface SQLExecutionTag</b></code> </p>
+ <p>Identifies a tag handler that can accept parameter values from nested
+ tag handlers.</p>
+ </td>
+ <td> </td>
</tr>
</table>
<h2>Tag Library Validators</h2>
1.5 +8 -6 jakarta-taglibs/standard/doc/web/index.html
Index: index.html
===================================================================
RCS file: /home/cvs/jakarta-taglibs/standard/doc/web/index.html,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- index.html 2001/11/29 17:32:43 1.4
+++ index.html 2001/12/12 20:12:35 1.5
@@ -7,9 +7,9 @@
<body bgcolor="#FFFFFF">
<h1>RI for the JSP™ Standard Tag Library (JSTL)</h1>
-<h2>Release: Early Access 2 (EA2)</h2>
+<h2>Release: Early Access 3 (EA3)</h2>
-<p>Thanks for downloading the JSTL EA2 release. We hope you find the tags, documents,
+<p>Thanks for downloading the JSTL EA3 release. We hope you find the tags, documents,
and examples here of interest. We're curious to hear your feedback on this release,
which represents work in progress toward a standard JSP Tag Library. Please
contact us at</p>
@@ -28,8 +28,8 @@
you get started with this release.</li>
<li><a href="Overview.html">Overview</a>: An overview of JSTL's design philosophy
and current syntax.</li>
- <li><a href="ReleaseNotes.html">Release Notes</a>: Changes since EA1, and
- other historical information.</li>
+ <li><a href="ReleaseNotes.html">Release Notes</a>: Changes since EA1, and other
+ historical information.</li>
<li>Functional descriptions: Technical guides representing the design considerations
and functionality of JSTL's tag set. Note that these are not formal specifications,
just technical overviews of functionality and intent.
@@ -49,7 +49,7 @@
</ul>
</li>
<li><a href="IOT_Import_FunctionalDescription_5_EA2.html">Import tags</a></li>
- <li>XML tags
+ <li>XML tags
<ul>
<li><a href="XML_Core_FunctionalDescription_2_EA2.html">core</a></li>
<li><a href="XML_ControlFlow_FunctionalDescription_1_EA2.html">control
@@ -57,7 +57,9 @@
<li><a href="XML_Transformation_FunctionalDescription_3_EA2.html">transformation</a></li>
</ul>
</li>
- <li><a href="I18N_FunctionalDescription_5_EA2.html">I18N & Formatting
+ <li><a href="I18N_FunctionalDescription_6_EA3.html">I18N & Formatting
+ tags</a></li>
+ <li><a href="DB_FunctionalDescription_1_EA3.html">SQL (database access)
tags</a></li>
</ul>
</li>
1.1 jakarta-taglibs/standard/doc/web/DB_FunctionalDescription_1_EA3.html
Index: DB_FunctionalDescription_1_EA3.html
===================================================================
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="GENERATOR" content="Mozilla/4.76 [en] (Windows NT 5.0; U) [Netscape]">
<title>Database Tags -- Functional Description</title>
<style media="screen" type="text/css"><!--
.fixme { color: red }
--></style>
</head>
<body bgcolor="#FFFFFF">
<h3>
<hr width="100%" noshade>
</h3>
<h2> SQL Actions — Functional Description <br>
</h2>
<h2><tt><sql:query><br>
<sql:update><br>
<sql:transaction><br>
<sql:param><br>
<sql:driver><br>
</tt></h2>
<h2><tt>interface SQLExecutionTag<br>
interface Result<br>
interface Row<br>
interface ResultMetaData<br>
interface ColumnMetaData<br>
interface Column</tt></h2>
<hr width="100%" noshade>
<h3>1. Introduction</h3>
<p>Many dynamic web applications need to access relational databases for the dynamic
aspects of their presentation layer. While it can be argued that database operations
should be handled in the business logic of a web application designed with an
MVC architecture, the fact of the matter is that real world applications will
sometimes require this capability within the JSP pages for various reasons (e.g.
prototyping/testing, small scale/simple applications, lack of developer resources,
etc).</p>
<p>With JSTL, we do not want to force a unique way to design web applications.
Our goal is to provide the right set of common tools needed by page authors
to be successful in their projects. A set of database tags has been clearly
identified as one of these required common tools</p>
<hr width="100%" noshade>
<h3>2. Overview<br>
</h3>
<p>The JSTL database actions allow a page author to </p>
<ul>
<li>perform database queries (select)</li>
<li>easily access query results</li>
<li>perform database updates (insert, update, delete)</li>
<li>group database operations within transactions</li>
</ul>
<p><b>DataSource</b></p>
<p>Database actions operate on a DataSource. A DataSource is an object associated
with the database to be accessed. It provides a factory for Connection objects.
With the JSTL database tagset, a DataSource can be specified either as a javax.sql.DataSource
object, or as a path to a JNDI resource (in containers that support it; i.e.
J2EE containers, or others that support this specific mechanism for referencing
resources.)</p>
<p>There are many ways by which a page author can get access to a DataSource,
namely: </p>
<blockquote>
<p>1. Transparent collaboration (implicit scoped attribute)</p>
<p>Initialization code in the application logic (e.g. application event listener,
initialization servlet) can be used to set the default DataSource associated
with a web application via the scoped attribute "javax.servlet.JSTL.DataSource".
With this approach, an application with a single database makes the DataSource
that is being used by the database actions totally transparent to the page
author</p>
<p>2. Explicit collaboration via application logic</p>
<p>The controller code in an MVC-based application sets a JSP scoped attribute
representing the DataSource. The attribute's name and scope are communicated
to the page author who uses that information in the "dataSource"
attribute of the database actions. For example:</p>
<blockquote>
<p><code><sql:query dataSource="$dataSource" ...></code></p>
</blockquote>
<p>3. Explicit collaboration via <sql:driver> action</p>
<p>If a DataSource cannot be set within the application logic (prototype/simple
project with no developer at hand), the <sql:driver> action can be used
as a simplified alternative for the creation of a DataSource object wrapped
around a JDBC driver. For example:</p>
<blockquote>
<p><code><sql:driver var="dataSource" <br>
driver="org.gjt.mm.mysql.Driver" <br>
url="//localHost/myDB"></code><br>
<code><sql:query dataSource="$dataSource" .../></code>
</p>
</blockquote>
</blockquote>
<p><b>Querying a database</b></p>
<p>The most common usage of the database actions is to query a database and display
the results. In the example below, customers from China are selected from the
"customers" table of the database, they are ordered by last name,
and finally displayed in an HTML table.</p>
<blockquote>
<p><code><sql:query var="customers" dataSource="$dataSource"<i>><br>
</i> SELECT * FROM customers<br>
WHERE country = 'China'<br>
ORDER BY lastname<br>
</sql:query><i> </i></code></p>
</blockquote>
<blockquote>
<p><code><font color="#666666"><table></font><i><br>
</i><jc:forEach var="row" items="$customers.rows"><br>
<font color="#666666"><tr> </font><br>
<font color="#666666"><td></font><jc:expr
value="$row.lastName"/><font color="#666666"></td></font><br>
<font color="#666666"><td></font><jc:expr
value="$row.firstName"/><font color="#666666"></td></font><br>
<font color="#666666"><td></font><jc:expr
value="$row.address"/><font color="#666666"></td></font>
<br>
<font color="#666666"></tr> </font><br>
</jc:forEach><br>
<font color="#666666"></table></font> </code></p>
</blockquote>
<p><b>Updating a database</b></p>
<p>It is possible to update a database via the <sql:update> action. Updates
to the database can be grouped within a <sql:transaction> action to ensure
database integrity. For example, the following code transfers money between
two accounts.</p>
<blockquote>
<p><code><sql:transaction dataSource="$dataSource"><br>
<sql:update> <br>
UPDATE account <br>
SET Balance = Balance - ?<br>
WHERE accountNo = ?<br>
</code><code> <sql:param value="$transferAmount"><br>
<sql:param value="$accountFrom"><br>
</sql:update><br>
<sql:update> <br>
UPDATE account <br>
SET Balance = Balance + ?<br>
WHERE accountNo = ?<br>
</code><code> <sql:param value="$transferAmount"><br>
<sql:param value="$accountTo"><br>
</sql:update><br>
</sql:transaction> </code></p>
</blockquote>
<p><b>SQL Statement Parameters</b></p>
<p>The JSTL database tagset also supports SQL statements that take parameters
to supply values to be used in place of question mark placeholders (as seen
in example above). This support is extensible via interface SQLExecutionTag
so that custom "parameter" tags can be developed to easily set the
value of statement parameters from any kind of input data.</p>
<hr width="100%" noshade>
<h3>3. Actions</h3>
<h3>3.1 <sql:query></h3>
<h4>Synopsis</h4>
<p><sql:query> is the general purpose action for performing SQL queries
on a database and gettting back a single result set containing rows of data.</p>
<p>This action may or not have a body. If the action has no body, it is of the
form:</p>
<blockquote>
<p><code><sql:query var=<i>"varName"</i> sql="<i>sqlQuery</i>"
[dataSource=<i>dataSourceSpec</i>]<br>
[maxRows="<i>maxRows</i>"]
[startRow="<i>startRow</i>"] </code><code>/></code></p>
</blockquote>
<p>If the action has a body, it is of the form:</p>
<blockquote>
<p><code><sql:query var=<i>"varName"</i> [sql="<i>sqlQuery</i>"]
[dataSource=<i>dataSourceSpec</i>]><br>
[maxRows="<i>maxRows</i>"]
[startRow="<i>startRow</i>"</code><code>]><br>
</code><code> ... optional query statement ...<br>
</code><code> ... optional <sql:param> actions ...<br>
</sql:query></code></p>
<p>In the "body" form, the SQL query statement can be specified either
via attribute "sql" or within the tag's body.</p>
</blockquote>
<p><code>dataSourceSpec ::= javax.sql.DataSource object | "jndiPathToDataSource"</code><br>
</p>
<h4>Details</h4>
<p>The results of the query are exposed via an object that implements the Result
interface (see section 4.1) in the attribute named by "var".</p>
<p>For example:</p>
<blockquote>
<p><code><sql:query var="customers" dataSource="$dataSource"<i>><br>
</i> SELECT * FROM employees<br>
WHERE country = 'China'<br>
ORDER BY lastname<br>
</sql:query><i> </i></code></p>
</blockquote>
<p>If the query produces no results, then an <i>empty</i> (i.e. size is 0) Result
object is returned.</p>
<p>The SQL query statement can be specified either via attribute "sql"
or within the tag's body (mutually exclusive). Optional parameter markers (?)
can be specified in the query statement as supported by JDBC. The values of
these parameters are set via subtag <sql:param>. <sql:query> implements
interface SQLExecutionTag (see section 4.2) to make this extensible to custom
tags. </p>
<p>The set of rows stored within the Result data structure can be limited by attribute
"maxRows". If unspecified, all rows resulting from the query are stored.
Attribute "startRow" can be used to specify the starting row for the
results. For example, if set at 10, this means that the first 9 rows will be
skipped before the rows returned by the query are stored in the Result data
structure (up to maxRows if applicable).</p>
<p>These two attributes protect against "runaway queries", allow efficient
access to the top rows of large result sets, and also provide a poor-man's way
of paging through a large set of results by bumping the startRow up by maxRows
on each page.<br>
<br>
It is also possible to configure a default "maxRows" value that applies
by default to all <sql:query> actions. This is done via context parameter
"javax.servlet.jsp.jstl.sql.maxRows". This global value for maxRows
can be turned off by giving the maxRows attribute of an <sql:query> action
the value -1.</p>
<p>The tag retrieves and releases a Connection using the following algorithm:
</p>
<ol>
<li>If the optional "dataSource" attribute is provided, then a connection
is retrieved through getConnection() against this DataSource, and released
by the tag handler before the tag completes its processing (result set is
cached in the Result object). If the 'dataSource' attribute's value resolves
to a String, after rtexpr/EL evaluation, this String is used as a JNDI path
to a DataSource in containers that support it (i.e., J2EE containers, or others
that support this specific mechanism for referencing resources.)</li>
<li>If "dataSource" is not present, but we are the child tag of a
<sql:transaction> tag, retrieve a Connection from our parent and do
nothing to release it. The connection is managed by the parent.</li>
<li>If neither (1) nor (2), then look for a DataSource named by scoped attribute
"javax.servlet.JSTL.DataSource". Handling of the connection is
then as described in 1.</li>
</ol>
<p>It is illegal for <sql:query> to specify a DataSource when nested within
<sql:transaction> (throws JspTagException).</p>
<h3>3.2 <sql:update></h3>
<h4>Synopsis</h4>
<p><sql:update> executes an SQL INSERT, UPDATE or DELETE statement. In addition,
SQL statements that return nothing, such as SQL DDL statements, can be executed.</p>
<p>This action may or not have a body. If the action has no body, it is of the
form:</p>
<blockquote>
<p><code><sql:update sql="<i>sqlUpdate</i>" <br>
[var=<i>"varName"</i>]
<br>
[dataSource=<i>dataSourceSpec</i>]/></code></p>
</blockquote>
<p>If the action has a body, it is of the form:</p>
<blockquote>
<p><code><sql:update var=<i>"varName"<br>
</i></code><code>[sql="<i>sqlUpdate</i>"]
<br>
[dataSource=<i>dataSourceSpec</i>]><br>
... optional update statement ...<br>
... optional <sql:param> actions ...<br>
</sql:query></code></p>
<p>The SQL update statement can be specified either via attribute "sql"
or within the tag's body.</p>
</blockquote>
<p><code>dataSourceSpec ::= javax.sql.DataSource object | <br>
"<i>jndiPathToDataSource</i>"</code><br>
</p>
<h4>Details</h4>
<p>The result of the database update is optionally exposed in the attribute named
by "var". This result is a java.lang.Integer object that tells how
many rows were affected by the statement. The value 0 is returned if no rows
were affected by INSERT, DELETE, or UPDATE, as well as for DDL statements that
return nothing (e.g. CREATE TABLE). This is the same behavior as Statement.executeUpdate()
in JDBC.</p>
<p>For example:
<blockquote>
<p><code><sql:update><br>
UPDATE account <br>
SET BALANCE = ?<br>
WHERE accountNo = ?<br>
</code><code> <sql:param value="$balance"><br>
<sql:param value="$accountNo"><br>
</sql:update></code></p>
</blockquote>
<p>The tag acts identically to <sql:query> with respect to connection management,
the "sql" and "dataSource" attributes, PreparedStatement
lifecycle, etc.</p>
<h3>3.3 <sql:transaction></h3>
<h4>Synopsis</h4>
<p><sql:transaction> serves to establish a transaction context for its <sql:query>
and <sql:update> subtags. </p>
<p><code><sql:transaction [dataSource=<i>dataSourceSpec</i>] <br>
[transactionIsolation=<i>"transactionIsolationLevel"</i>]><br>
... <sql:query> and <sql:update> statements ...<br>
</sql:transaction> </code></p>
<p><code>dataSourceSpec ::= javax.sql.DataSource object | "jndiPathToDataSource"<br>
transactionIsolationLevel ::= "none" | "read_committed"
| "read_uncommitted" | <br>
"repeatable_read"
| "serializable"</code><br>
</p>
<p>The transaction isolation levels are the same as the ones supported in JDBC
by java.sql.Connection.<br>
</p>
<h4>Details</h4>
Behavior is defined as follows:
<ul>
<li>in doStartTag(), call Connection.getTransactionIsolation().
<ul>
<li>If this equals TRANSACTION_NONE
<ul>
<li>fail by throwing an exception.</li>
</ul>
</li>
<li>If this does not equal TRANSACTION_NONE
<ul>
<li>call Connection.setAutoCommit(false).</li>
</ul>
</li>
</ul>
</li>
<li>If the "transactionIsolation" attribute is specified
<ul>
<li>save current transaction isolation level and set the specified one for
the connection.</li>
</ul>
</li>
<li>in doEndTag(), call Connection.commit()</li>
<li>in doCatch(), call Connection.rollback()</li>
<li>in doFinally()
<ul>
<li>restore the transaction isolation level via Connection.setTransactionIsolation(),
if one was saved </li>
<li>reset auto commit: Connection.setAutoCommit(true)</li>
<li>close the connection</li>
</ul>
</li>
</ul>
<p>Throughout the transaction, any SQLException that occurs is simply propagated.</p>
<p>The same connection-management scheme as <sql:query> is used to acquire
a Connection, except that the parent isn't checked for DataSource (<sql:transaction>
tags cannot be nested as a means of propagating a Connection). It is iIllegal
for nested <sql:query> and <sql:update> subtags to specify a DataSource.</p>
<p>The behavior of the <sql:transaction> action is undefined if it executes
in the context of a larger JTA user transaction.</p>
<h3>3.4 <sql:driver></h3>
<h4>Synopsis</h4>
<p><sql:driver> facilitates the wrapping of a DataSource object around a
JDBC driver for prototype/simple applications.</p>
<p><code><sql:driver var=<i>"varName"</i><br>
[driver="<i>driverClassName</i>"]
<br>
[url="<i>jdbcUrl</i>"]<br>
[user="<i>userName</i>"]
/></code></p>
<h4>Details<br>
</h4>
<p>The <sql:driver> action is <b> only intended for prototyping and simple
applications</b>. An application's business logic (e.g. via a life cycle event
listener or controller servlet) should normally be used to create a DataSource
and make it available to the rest of the application.</p>
<p>Four configuration parameters can be specified to create a DataSource object
wrapped around a JDBC driver manager:</p>
<ol>
<li>JDBC driver class name -- used to access a database of a specific type</li>
<li> JDBC URL to the database -- used to locate a specific database</li>
<li> user name -- identifies the user accessing the database</li>
<li> password -- the user's password</li>
</ol>
<p>All parameters, except for "password", can be specified via an action
attribute or a context init parameter (see below). Action attributes take precedence
over context init parameters. The password configuration parameter can only
be specified via a context init parameter to prevent situations where sensitive
information would be hard coded in a JSP page.</p>
<p>The context init parameters are:</p>
<ul>
<li>javax.servlet.jstl.sql.driver.driver</li>
<li> javax.servlet.jstl.sql.driver.url</li>
<li> javax.servlet.jstl.sql.driver.user</li>
<li> javax.servlet.jstl.sql.driver.password</li>
</ul>
<p>For example, assuming a prototype web application whose database is accessible
by anyone without any password:</p>
<blockquote>
<p><code><sql:driver var="dataSource" <br>
driver="org.gjt.mm.mysql.Driver"
<br>
url="//localhost/appDB"/></code></p>
</blockquote>
<h3>3.5 <sql:param></h3>
<h4>Synopsis</h4>
<p><sql:param> is used as a subtag of SQLExecutionTag actions such as <sql:query>
and <sql:update> to set the values of parameter markers ('?') specified
in the SQL statement.</p>
<p>This action may or not have a body. If the action has no body, it is of the
form:</p>
<blockquote>
<p><code><sql:param value=<i>"parameterValue"</i>/></code></p>
</blockquote>
<p>If the action has a body, it is of the form:</p>
<blockquote>
<p><code><sql:param><br>
... parameter value ...<br>
</sql:param></code></p>
</blockquote>
<h4>Details<br>
</h4>
<p> If tag body is used, it is first run through String.trim().</p>
<p>With the value specified, <sql:param> locates its nearest SQLExecutionTag
ancestor and calls SQLExecutionTag.addSQLParameter(value). The mapping from
Java object types to SQL types is handled according to the JDBC specification
(see method java.sql.PreparedStatement.setObject()).</p>
<hr width="100%" noshade>
<h3>4. Interfaces</h3>
<h3>4.1 <sql:query> result related interfaces</h3>
<blockquote>
<p><code>public interface Result { <br>
public Row[] getRows(); </code><code><br>
</code><code> public ResultMetaData getmetaData(); </code><code><br>
public int getSize(); // number of rows in the Result<br>
public boolean isLimitedByMaxRows();</code><code><br>
}</code><code> </code><code> </code></p>
<p> <code>public interface ResultMetaData {<br>
public ColumnMetaData get(String name);<br>
public ColumnMetaData get(int index);<br>
public ColumnMetaData[] getColumns();<br>
// @@@ non-column meta data here as well<br>
}</code></p>
<p><code> public interface Row {<br>
public Column get(String name);<br>
public Column get(int index); <br>
public Column[] getColumns();<br>
}</code></p>
<p><code> public interface ColumnMetaData {<br>
public String getName();<br>
public int getType();<br>
public String getTypeName();<br>
... all other relevant <br>
... java.sql.ResultSetMetaData information<br>
} </code></p>
<p><code> public interface Column extends ColumnMetaData {<br>
public Object getValue();<br>
public String toString();</code><br>
} </p>
</blockquote>
<p>One key incentive for defining new interfaces representing the result of a
query is to allow simpler access to result data via the Expression Language.
Here are some sample use cases:</p>
<p>Use case 1: iteration (probably most common use case)</p>
<blockquote>
<p><code><c:forEach var="row" items="$result.rows"><br>
Price is: <c:expr value="$row.get('price')"/></code><code><br>
Quantity is: <c:expr value="$row.columns[3]"/><br>
</c:forEach></code></p>
</blockquote>
<p>[Note: <code>$row.get('price')</code> could be replaced by <code>$row.price</code>
if EL supports the mapping <code>$a.prop -> a.get("prop")</code>]<br>
<br>
Use case 2: direct access from $result </p>
<blockquote>
<p><code>Price is: $result.rows[24].price<br>
Price is: $result.rows[24].columns[3] </code></p>
</blockquote>
<p><br>
Use case 3: Putting it all together:</p>
<blockquote>
<p><code><table><br>
<!-- header --><br>
<tr><br>
<!-- for each column in the result --><br>
<c:forEach var="metaData" items="$result.metaData.columns"><br>
<!-- Column Name --><br>
<th>$metaData.name</th><br>
</c:forEach><br>
</tr><br>
<!-- for each row in the result --><br>
<c:forEach var="row" items="$result.rows"><br>
<tr><br>
<!-- for each column in the row --><br>
<c:forEach var="column" items="$row.columns"><br>
<td><c:expr value="$column"/></td><br>
</c:forEach><br>
</tr><br>
</c:forEach><br>
</table></code></p>
</blockquote>
<p>
<h3>4.2 Interface SQLExecutionTag</h3>
<p>The SQLExecutionTag interface identifies a tag handler that can accept parameter
values from nested tag handlers.</p>
<blockquote>
<p><code>public interface SQLExecutionTag {<br>
public void addSQLParameter(Object value) throws SQLException;<br>
}</code></p>
</blockquote>
<p>This interface is implemented by both <sql:query> and <sql:update>.
Action <sql:param> invokes method addSQLParameter() of the SQLExecutionTag
interface to set parameter values. </p>
<p>The parameter's index and semantic interpretation are both the responsibility
of the tag handler; a typical implementation will keep an internal index and
increment it once for each call. </p>
<p>This interface is public to allow for custom actions that can facilitate the
setting of statement parameters. For example, let's assume an end-user enters
a date in three separate fields: year, month, and day. If the database table
has a single column for the complete date, one could develop a <foo:dateParam>
action to set the corresponding parameter as follows:</p>
<blockquote>
<p> <code><foo:dateParam year="$year" month="$month"
day="$day" /></code></p>
</blockquote>
<p>Please note that the JSTL internationalization tags support the parsing of
string representations of dates and numbers into their associated data type
(java.util.Date and java.lang.Number respectively). For example:</p>
<blockquote>
<p> <code><fmt:parseDate var="myDate" value="$param:someDate
/><br>
<sql:param value="$myDate" /></code></p>
</blockquote>
<p></p>
<hr width="100%" noshade>
<p></p>
<h3>5. Summary</h3>
<table border="1" cellpadding="5">
<tr>
<td colspan="2" bgcolor="#000099"><b><font color="#FFFFFF" size="+1">SQL Actions</font></b></td>
</tr>
<tr bgcolor="#FFFF66">
<td><b>Action</b></td>
<td><b>Sample usage</b></td>
</tr>
<tr>
<td>
<p><code><b><sql:query></b></code></p>
<p><code><sql:query var=<i>"varName"</i> <br>
sql="<i>sqlQuery</i>"<br>
[dataSource=<i>dataSourceSpec</i>]<br>
[maxRows="<i>maxRows</i>"]<br>
[startRow="<i>startRow</i>"]/></code></p>
<p><code><sql:query var=<i>"varName"<br>
</i> [sql="<i>sqlQuery</i>"]<br>
[dataSource=<i>dataSourceSpec</i>]<br>
[maxRows="<i>maxRows</i>"]<br>
[startRow="<i>startRow</i>"]/>
</code><code><br>
... optional query statement ...<br>
... optional <sql:param> actions ...<br>
</sql:query></code></p>
<p>General purpose action for performing SQL queries on a database and gettting
back a single result set containing rows of data.</p>
</td>
<td>
<p><code><sql:query var="customers"<br>
dataSource="$dataSource"<i>><br>
</i> SELECT * FROM employees<br>
WHERE country = 'China'<br>
ORDER BY lastname<br>
</sql:query><i> </i></code></p>
</td>
</tr>
<tr>
<td>
<p><code><b><sql:update></b></code></p>
<p><code><sql:update var=<i>"varName"</i> <br>
sql="<i>sqlUpdate</i>"<br>
[dataSource=<i>dataSourceSpec</i>]/></code></p>
<p><code><sql:update var=<i>"varName"<br>
</i></code><code> [sql="<i>sqlUpdate</i>"]<br>
[dataSource=<i>dataSourceSpec</i>]><br>
... optional query statement ...<br>
... optional <sql:param> actions ...<br>
</sql:update></code></p>
<p>General purpose action for "updates"; i.e. statements that
update the database (insert, update, delete) and return nothing or a single
integer. </p>
</td>
<td>
<p><code><sql:update><br>
UPDATE account <br>
SET BALANCE = ?<br>
WHERE accountNo = ?<br>
</code><code> <sql:param<br>
value="$balance"><br>
<sql:param<br>
value="$accountNo"><br>
</sql:update></code></p>
</td>
</tr>
<tr>
<td>
<p><code><b><sql:transaction><br>
</b></code><br>
<code><sql:transaction <br>
[dataSource=<i>dataSourceSpec</i>] <br>
[transactionIsolation=<i>"transactionIsolationLevel"</i>]><br>
... <sql:query> and <sql:update> statements ...<br>
</sql:transaction> </code></p>
</td>
<td> </td>
</tr>
<tr>
<td>
<p><code><b><sql:driver><br>
</b></code><br>
<code><sql:driver var=<i>"varName"</i><br>
[driver="<i>driverClassName</i>"]
<br>
[jdbcUrl="<i>jdbcUrl</i>"]<br>
[userName="<i>userName</i>"]
/></code><br>
</p>
<p>Facilitates the setup of a DataSource object around a JDBC driver for
prototype/simple applications. </p>
</td>
<td> </td>
</tr>
<tr>
<td>
<p><code><b><sql:param><br>
</b></code> </p>
<p><code><sql:param value=<i>"parameterValue"</i>/></code></p>
<p><code><sql:param><br>
... parameter value ...<br>
</sql:param></code><br>
</p>
<p>Subtag of SQLExecutionTag actions such as <sql:query> and <sql:update>
to set the values of parameter markers ('?') specified in the SQL statement.</p>
</td>
<td> </td>
</tr>
<tr>
<td>
<p><code><b><sql:query> result related interfaces<br>
</b></code> </p>
<p><code>public interface Result<br>
</code><code> </code><code>public interface ResultMetaData<br>
</code><code>public interface Row</code><code><br>
public interface ColumnMetaData</code><code><br>
public </code><code>interface Column</code></p>
</td>
<td> </td>
</tr>
<tr>
<td>
<p><code><b>interface SQLExecutionTag</b></code> </p>
<p>Identifies a tag handler that can accept parameter values from nested
tag handlers.</p>
</td>
<td> </td>
</tr>
</table>
</body>
</html>
1.1 jakarta-taglibs/standard/doc/web/I18N_FunctionalDescription_6_EA3.html
Index: I18N_FunctionalDescription_6_EA3.html
===================================================================
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="GENERATOR" content="Mozilla/4.76C-CCK-MCD Netscape [en] (X11; U; SunOS 5.7 sun4u) [Netscape]">
<title>I18N -- Functional Description</title>
<style media="screen" type="text/css"><!--
.fixme { color: red }
--></style>
</head>
<body bgcolor="#FFFFFF">
<h3>
<hr width="100%" noshade></h3>
<h2> I18N-Capable Formatting Tags: Functional Description</h2>
<h2>
<tt><fmt:locale><br>
<fmt:timeZone><br>
<fmt:bundle><br>
<fmt:message><br>
<fmt:messageFormat><br>
<fmt:messageArg><br>
<fmt:formatNumber><br>
<fmt:parseNumber><br>
<fmt:formatDate><br>
<fmt:parseDate><br>
<fmt:exception><br>
<fmt:requestEncoding></tt></h2>
<hr width="100%" noshade>
<h3>
1. Introduction</h3>
With the explosion of application development based on web technologies,
and the deployment of such applications on the Internet, applications must
be able to adapt to the languages and formatting conventions of their clients.
This means that page authors must be able to tailor any locale-specific
page content according to the conventions of the client's language and
cultural formatting conventions. For example, the number <tt>345987.246
</tt>should
be formatted as <tt>345 987,246 </tt>for French, <tt>345.987,246
</tt>for
German, and <tt>345,987.246</tt><i> </i>for clients<i> </i>in the U.S.
<p>The process of designing an application (or page content) so that it
can be adapted to various languages and regions without requiring any engineering
changes is known as <i>internationalization</i>, or I18N for short. Once
a web application has been internationalized, it can be adapted for a number
of regions or languages by adding locale-specific components and translating
text. This process is known as <i>localization</i>.
<p>There are two approaches to internationalizing a web application:
<ul>
<li>
Provide a version of the JSP in each of the target locales and have a controller
servlet dispatch the request to the appropriate page (depending on the
requested locale). This approach is useful if large amounts of data on
a page or an entire web application need to be internationalized.</li>
<li>
Isolate any locale-sensitive data on a page (such as error messages, string
literals, or button labels) into resource bundles, and access the data
via I18N tags, so that the corresponding translated message is fetched
automatically and inserted into the page.</li>
</ul>
This proposal supports both approaches. It defines two sets of<font size=+0>
tags: I18N tags, whose purpose is to assist page authors with creating
internationalized page content that can be localized into any locale available
in the JSP container (this addresses the second approach), and formatting
tags, which allow various data elements such as numbers, currencies, dates
and times to be formatted and parsed in a locale-sensitive or customized
manner (this may be used in either approach).</font>
<h3>
2. Locale selection</h3>
JSTL supports both browser- and application-based locales, which are discussed
in more detail.
<h4>
2.1 Browser-based locales</h4>
By default, browser-sensing capabilities for locales are enabled. This
means that the client determines (via its browser settings) which locale
to use, and allows page authors to cater to the language preferences of
their clients. For example, a shopping application may want to greet its
customers in their language, and it may even want to label its GUI components
in that language (for example, a cancel button would be labelled
<tt>Cancel</tt>
for English and <tt>Abbrechen</tt> for German speaking customers).
<p>Any action that requires a locale first calls the <tt>getLocales()</tt>
method on the incoming request, which provides a list, in order of preference,
of the locales that the client wants to use. This list is processed differently
depending on whether the action is an I18N or a formatting tag.
<h5>
2.1.1 Resource bundle locale</h5>
Any I18N actions that acquire a resource bundle based on its base name
(that is, the <tt><bundle></tt> action which (always) takes a <tt>basename</tt>
attribute and the <tt><message></tt> action which may use the default
resource bundle base name defined by the <tt>javax.servlet.jsp.jstl.i18n.basename
</tt>attribute)
determine the best matching locale by comparing the list of client locales
against the list of available locales for the resource bundle in question,
as follows:
<p>For each of the client's preferred locales (in order of preference),
the action checks if there is a matching locale for the resource bundle
in question, by passing the resource bundle's base name and the client's
requested locale to the <tt>java.util.ResourceBundle.getBundle()</tt> method.
The returned locale may either match both the country and language of the
requested locale (exact match), only its language, or neither. If there
is an exact match, it is used, and no further client locales are checked
(an exact match may exist only if the client's preferred locale specifies
a country). Otherwise, the first match on language is used. If no such
match exists, the fallback locale is used by searching the <tt>javax.servlet.jsp.jstl.i18n.fallbackLocale</tt>
attribute in the page, request, session (if valid), and application scope(s)
(in this order) (see Section 16: <i>Configuration parameters</i>). If this
attribute does not exist, the default locale of the JSP container's Java
runtime is used.
<p>For example, if the client's preferred locales were <tt>ja</tt>, <tt>en-UK</tt>,
<tt>en-US</tt>,
<tt>en-CA</tt>,
and f<tt>r </tt>(in this order), and the available ones (for the resource
bundle in question) <tt>en</tt> and
<tt>fr</tt>, the best match would be
<tt>en</tt>;
if the available ones were
<tt>en</tt>,
<tt>en-US</tt>, and
<tt>fr</tt>,
then the best match would be <tt>en-US</tt>.
<p> The behavior is implementation-defined if the set of available
resource bundles changes during execution of the page. Implementations
may thus cache the best matching locale for a given resource bundle when
one is found.
<h5>
2.1.2 Formatting locale</h5>
This is the locale used by the <tt><formatNumber></tt>, <tt><parseNumber></tt>,
<tt><formatDate></tt>,
and <tt><parseDate></tt> formatting actions.
<p>If the formatting action is enclosed within a <tt><bundle> </tt>action,
the locale of the parent bundle is used as the formatting locale.
<p>Otherwise, if the <tt>javax.servlet.jsp.jstl.i18n.basenam</tt>e attribute
is set, the best matching locale for that base name is determined (according
to the algorithm described in Section 2.1.1) and used as the formatting
locale.
<p>Otherwise, the formatting action checks, for each of the client's preferred
locales (in order of preference), if there is a matching locale available.
The <tt><formatNumber>
</tt>and<tt> <parseNumber></tt>, and the <tt><formatDate>
</tt>and
<tt><parseDate>
</tt>actions
determine the available locales by calling <tt>java.text.NumberFormat.getAvailableLocales()</tt>
and <tt>java.text.DateFormat.getAvailableLocales()</tt>, respectively.
If there is an exact match (that is, a client's preferred locale specifies
a country and matches both the language and country of an available locale),
it is used, and no further client locales are checked. Otherwise, the first
match on language is used. If no such match exists, the default locale
of the JSP container's Java runtime is used. Once the best matching locale
has been determined, it is cached, so that any subsequent formatting actions
on the same page do not have to determine it again.
<h4>
2.2. Application-based locales</h4>
The browser-sensing capabilities for locales can be disabled by setting
the <tt>javax.servlet.jsp.jstl.i18n.locale</tt> (scoped) attribute. This
attribute may be set directly by application code for any of the JSP scopes.
For example, an application might let its users pick their preferred locale
and then set the <tt>javax.servlet.jsp.jstl.i18n.locale
</tt>attribute
accordingly. Alternatively, the <tt><locale> </tt>action may be used
to set the <tt>javax.servlet.jsp.jstl.i18n.locale </tt>attribute with page
scope only. This may be useful in the case where a client's preferred locale
is retrieved from a database (using the JSTL database tags)and installed
on the page using the <tt><locale></tt> tag.
<p>The <tt>javax.servlet.jsp.jstl.i18n.locale</tt> attribute is searched
in the page, request, session (if valid), and application scope(s) (in
this order).
<h3>
3. Response encoding</h3>
Every action that is responsible for establishing a locale passes that
locale to the <tt>setLocale()</tt> method of the <tt>javax.servlet.ServletResponse</tt>.
<p>More specifically, the response's <tt>setLocale()</tt> method is always
called by the <tt><locale></tt> action. In addition, it is called by
the following actions in the absence of the <tt>javax.servlet.jsp.jstl.i18n.locale</tt>
attribute:
<br>
<li>
Any <tt><bundle></tt> action.</li>
<li>
A <tt><message></tt> action that uses the default resource bundle base
name (defined by the <tt>javax.servlet.jsp.jstl.i18n.basename</tt> attribute).</li>
<li>
A <tt><formatNumber></tt> or <tt><formatDate></tt> action that is
not enclosed within a <tt><bundle> </tt>action.</li>
<p><br>After an action has called <tt>ServletResponse.setLocale()</tt>,
it determines the character encoding associated with the locale (by calling
<tt>ServletResponse.getCharacterEncoding()</tt>) and stores it in the <tt>javax.servlet.jsp.jstl.i18n.request.charset</tt>
session attribute. This attribute may be used by the <tt><requestEncoding></tt>
action in a page invoked by a form included in the response to set the
request charset to the same as the response charset. This makes it possible
for the container to decode the form parameter values properly, since browsers
typically encode form field values using the response's charset.
<h3>
4. Time zone</h3>
The <tt>javax.servlet.jsp.jstl.i18n.timeZone </tt>JSP attribute specifies
the time zone in which any time information formatted using the <tt><formatDate></tt>
action is represented. This allows any time information on a page to be
tailored to the preferred time zone of its clients, which is useful if
the server hosting the page containing the time information and its clients
reside in different time zones. Page authors could be advised to always
use the "long" time format which includes the time zone, but that would
still require clients to convert the formatted time into their own time
zone.
<p>The <tt>javax.servlet.jsp.jstl.i18n.timeZone</tt> attribute may be set
directly by application code for any of the JSP scopes. For example, an
application might let its users pick their preferred time zone and then
set the <tt>javax.servlet.jsp.jstl.i18n.timeZone
</tt>attribute accordingly.
Alternatively, the <tt><timeZone></tt> action may be used to set the
<tt>javax.servlet.jsp.jstl.i18n.timeZone</tt>
attribute for the current page context. This may be useful in the case
where a client's preferred time zone is retrieved from a database (using
the JSTL database tags) and imported into the page using the <tt><timeZone></tt>
tag.
<p>The <tt>javax.servlet.jsp.jstl.i18n.timeZone </tt>attribute is searched
in the page, request, session (if valid), and application scope(s) (in
this order). If not found, the JSP container's time zone is used.
<h3>
5. <locale></h3>
The <tt><locale></tt> action is used to set or override the JSP attribute
<tt>javax.servlet.jsp.jstl.i18n.locale</tt>
with the locale specified by the <tt>value</tt> attribute in the scope
given by the <tt>scope</tt> attribute (default: "page").
<p>The locale specified by the <tt>value</tt> attribute must contain a
two-letter (lower-case) language code (as defined by ISO-639), and may
contain a two-letter (upper-case) country code (as defined by ISO-3166)<tt>.
</tt>Language
and country codes must be separated by hyphen ('-') or underscore ('_').
<p>Optionally, a (vendor- or browser-specific) variant may be specified
using the <tt>variant</tt> attribute. See the <tt>java.util.Locale</tt>
javadocs for more information on variants.
<p>Example:
<p><tt> <fmt:locale value="en-US" variant="UNIX"/></tt>
<p>By using this action, the browser-sensing capabilities for locales described
in Section 2 of this functional description are disabled. This means that
if this action is being used, it should be declared at the beginning of
a page, before any other I18N-capable formatting tags. Otherwise, a different
locale might be used up to the position in the page where the <tt><locale></tt>
action is specified.
<h3>
6. <timeZone></h3>
The <tt><timeZone></tt> action establishes the time zone (specified
via the <tt>value</tt> attribute) to be used by any nested <tt><formatDate></tt>
actions:
<p><tt> <fmt:timeZone value="America/Los_Angeles"></tt>
<br><tt> <fmt:formatDate type="time"/></tt>
<br><tt> </fmt:timeZone></tt>
<p>The time zone may be specified as either an abbreviation (such as "PST"),
a full name (such as "America/Los_Angeles"), or a custom format (such as
"GMT-8:00). See
<tt>java.util.TimeZone.getTimeZone()
</tt>for more details
on the supported time zone formats.
<p>The <tt>var</tt> attribute may be used to expose the time zone as a
JSP-scoped attribute of type <tt>java.util.TimeZone
</tt>(with visibility
<tt>AT_END</tt>),
so that it can be referenced by any subsequent
<tt><formatDate></tt>
actions that are not nested inside a <tt><timeZone></tt> action and
take a <tt>timeZone</tt> attribute:
<p><tt> <fmt:timeZone value="America/Los_Angeles"
var="losAngelesTimeZone"/></tt>
<br><tt> <fmt:formatDate type="time" timeZone="$losAngelesTimeZone"/></tt>
<p>An empty <tt><timeZone></tt> action that is specified without the
<tt>var</tt>
attribute can be used to set or override the
<tt>javax.servlet.jsp.jstl.i18n.timeZone</tt>
attribute in the scope given by the <tt>scope</tt> attribute (default:
"page"), thereby making its time zone the (new) default in that scope:
<p><tt> <fmt:timeZone value="America/Los_Angeles"/></tt>
<br><tt> <fmt:formatDate type="time"/></tt>
<h3>
7. <bundle></h3>
The <tt><bundle> </tt>action loads the resource bundle whose base name
is specified via the <tt>basename</tt> attribute:
<p> <tt> <fmt:bundle basename="com.acme.labels.ButtonLabels"></tt>
<br><tt> <user-of-bundle/></tt>
<br><tt> </fmt:bundle></tt>
<p>The resource bundle's locale is determined according to Section 2 of
this functional description.
<p>The <tt>var</tt> attribute may be used to expose the resource bundle
as a JSP-scoped attribute of type <tt>java.util.ResourceBundle
</tt>(with
visibility <tt>AT_END</tt>), so that it can be referenced by any subsequent
<tt><message></tt>
actions that take a <tt>bundle</tt> attribute:
<p><tt> <fmt:bundle basename="com.acme.labels.ButtonLabels"
var="buttonLabels"/></tt>
<br><tt> <fmt:message key="Submit" bundle="$buttonLabels"/></tt>
<p>Exposing a resource bundle via the <tt>var</tt> attribute is useful
if the bundle needs to be accessed multiple times.
<p>An empty <tt><bundle></tt> action that is specified without the <tt>var</tt>
attribute can be used to set or override the <tt>javax.servlet.jsp.jstl.i18n.basename</tt>
attribute in the scope given by the <tt>scope</tt> attribute (default:
"page"), thereby making its base name the (new) default in that scope:
<p><tt> <fmt:bundle basename="com.acme.labels.ButtonLabels"/></tt>
<br><tt> <fmt:message key="Submit"/></tt>
<p>The <tt>prefix</tt> attribute is provided as a convenience for very
long key names: Its value is prepended to any message key (see the <tt><message></tt>
action) that is to be looked up in the resource bundle that was loaded
by this action.
<h3>
8. <message></h3>
The <tt><message></tt> action retrieves the localized message corresponding
to the message key specified by the
<tt>key</tt> attribute.
<p>The resource bundle in which to look up the message key may be given
by the <tt>bundle</tt> attribute. If this attribute is missing, and the
<tt><message>
</tt>action
is nested inside a <tt><bundle></tt> tag, the resource bundle to use
is taken from the enclosing <tt><bundle></tt> tag. Otherwise, the resource
bundle with the default base name given by the
<tt>javax.servlet.jsp.jstl.i18n.basename
</tt>attribute
is used, which is searched in the page, request, session (if valid),
and application scope(s) (in this order).
<p>The <tt><message></tt> action outputs its result to the current
<tt>JspWriter</tt>
object, unless the <tt>var</tt> attribute is specified, in which case the
result is stored in the named JSP attribute.
<p>Example:
<p> <tt><fmt:message key="Welcome"/>
<%-- Key is looked up in default bundle --%></tt>
<br><tt> <fmt:bundle basename="Errors" var="errorBundle"/></tt>
<br><tt> <fmt:bundle basename="Greetings"></tt>
<br><tt> <fmt:message key="Welcome"/>
<%-- Key is looked up in parent <bundle> tag --%></tt>
<br><tt> <fmt:message key="WrongPassword"
bundle="$errorBundle"/> <%-- Key is looked up in errorBundle --%></tt>
<br><tt> </fmt:bundle></tt>
<p>If the given key is not found in the resource bundle, or a resource
bundle with the given base name does not exist, a message is logged to
the servlet context, and an error message of the form <tt>"???<key>???"</tt>
(where
<tt><key></tt> is the name of the undefined key) is output to
the current <tt>JspWriter
</tt>object.
<p>If the message corresponding to the given key is <i>compound</i>, that
is, contains one or more variables, it can be supplied with argument values
for these variables by using the <tt>messageArgs</tt> attribute or one
or more <tt><messageArg></tt> subtags (one for each argument value).
This procedure is referred to as
<i>parametric replacement.</i> If the
message is compound, but no <tt>messageArgs</tt> attribute or <tt><messageArg></tt>
subtags are given, the message is left unmodified. Specifying a <tt><message></tt>
tag with both a <tt>messageArgs</tt> attribute and one or more <tt><messageArg></tt>
subtags causes a translation error.
<p>If the parent <tt><bundle></tt> action specifies a <tt>prefix</tt>
attribute, its value is prepended to any key names to be looked up in that
bundle. For example, using the <tt>prefix</tt> attribute, the key names
in:
<p><tt> <fmt:bundle basename="Labels"></tt>
<br><tt> <fmt:message key="com.acme.labels.firstName"/></tt>
<br><tt> <fmt:message key="com.acme.labels.lastName"/></tt>
<br><tt> </fmt:bundle></tt>
<p>may be abbreviated to:
<p><tt> <fmt:bundle basename="Labels" prefix="com.acme.labels."></tt>
<br><tt> <fmt:message key="firstName"/></tt>
<br><tt> <fmt:message key="lastName"/></tt>
<br><tt> </fmt:bundle></tt>
<h3>
9. <messageFormat></h3>
The <tt><messageFormat> </tt>action performs parametric replacement
on the pattern string specified via the <tt>value</tt> attribute, using
the runtime's default locale.
<p>The argument values for parametric replacement must be supplied via
<tt><messageArg></tt>
subtags. Each <tt><messageArg></tt> subtag replaces one parameter in
the pattern. Parametric replacement takes place in the order of the
<tt><messageArg></tt>
subtags. If no <tt><messageArg></tt> subtag is given, the specified
pattern is left unmodified.
<p>The result is output to the current <tt>JspWriter</tt> object, unless
the <tt>var</tt> attribute is given, in which case it is stored in the
named JSP attribute.
<p>The <tt><messageFormat></tt> action is useful if a pattern needs
to be supplied from sources other than resource bundles, or if a pattern
extracted from a resource bundle needs to be used multiple times.
<p>For example, when displaying a list of products, the same internationalized
message (pattern) would be used to display the price, but rather than looking
up the same pattern for every single product, the pattern could be looked
up once (using the <tt><message></tt> action) and then passed in to
the <tt><messageFormat></tt> action for each product, as follows:
<p><tt> <fmt:bundle basename="..." var="i18n"/></tt>
<br><tt> <fmt:message key="store.product.price" bundle="$i18n"
var="priceMsg"/></tt>
<br><tt> <c:forEach ...></tt>
<br><tt> ... <fmt:messageFormat value="$priceMsg">...</fmt:messageFormat></tt>
<br><tt> </c:forEach></tt>
<p>instead of the less efficient alternative:
<p><tt> <fmt:bundle basename="..." var="i18n"/></tt>
<br><tt> <c:forEach ...></tt>
<br><tt> ... <fmt:message key="store.product.price"
bundle="$i18n">...</fmt:message></tt>
<br><tt> </c:forEach></tt>
<h3>
10. <messageArg></h3>
The <tt><messageArg></tt> action provides one argument (for parametric
replacement) to the compound message or pattern in its parent
<tt><message></tt>
or <tt><messageFormat></tt> action, respectively.
<p>One <tt><messageArg> </tt>action must be specified for each variable
in the compound message or pattern. Parametric replacement takes place
in the order of the <tt><messageArg></tt> tags.
<p>The argument value can be specified either via the <tt>value</tt> attribute:
<pre> <fmt:message key="Welcome">
<fmt:messageArg value="$dateArg"/>
</fmt:message></pre>
or inline via the tag's body content:
<p><tt> <fmt:message key="Welcome"></tt>
<br><tt> <fmt:messageArg></tt>
<br><tt> <acme:doIt .../></tt>
<br><tt> </fmt:messageArg></tt>
<br><tt> </fmt:message></tt>
<h3>
11. <formatNumber></h3>
The <tt><formatNumber></tt> action allows the formatting of numbers,
currencies, and percentages, using predefined or customized formatting
styles.
<p>Depending on the value of the <tt>type</tt> attribute, which must be
one of "number", "currency", or "percent" (default: "number"), the numeric
value specified by the <tt>value</tt> attribute is formatted as a number,
currency, or percentage, respectively, using the default formatting pattern
for numbers (currencies, percentages) of the page's locale, which is determined
according to Section 2 of this functional description.
<p>The result is output to the current
<tt>JspWriter</tt> object, unless
the <tt>var</tt> attribute is given, in which case it is stored (as a string)
in the named JSP attribute.
<p>Example: The output of
<p><tt> <fmt:formatNumber value="9876543.21" type="currency"/></tt>
<p>varies with the page's locale (given in parentheses), as follows:
<p><tt> 9 876 543,21 F (fr_FR)</tt>
<br><tt> 9.876.543,21 DM (de_DE)</tt>
<br><tt> $9,876,543.21 (en_US)</tt>
<p>When formatting the given value as a number, the predefined formatting
pattern of the page's locale can be overridden by using the <tt>pattern</tt>
attribute, allowing page authors to control the display of leading and
trailing zeros, prefixes and suffixes, grouping (thousands) separators,
and the decimal separator of the formatted number. The given pattern string
must follow the <a href="http://java.sun.com/docs/books/tutorial/i18n/format/numberpattern.html">Number
Format Pattern Syntax </a> specified in the tutorial trail on internationalization
at <tt>java.sun.com</tt>.
<p>For example, a pattern of ".000" will cause any numeric value formatted
with it to be represented with 3 fraction digits, adding trailing zeros
if necessary, so that
<p><tt> <fmt:formatNumber value="12.3" pattern=".000"/></tt>
<p>will output "12.300".
<p>Likewise, a pattern of "#,#00.0#" specifies that any numeric value formatted
with it will be represented with a minimum of 2 integer digits, 1 fraction
digit, and a maximum of 2 fraction digits, with every 3 integer digits
grouped. Applied to "123456.7891", as in:
<p><tt> <fmt:formatNumber value="123456.7891" pattern="#,#00.0#"/></tt>
<p>the formatted output will be "123,456.79" (note that rounding is handled
automatically).
<p>The <tt>value</tt> and <tt>pattern</tt> attributes accept both string
literals and EL values.
<p>If the input to the <tt>value</tt> attribute is a string literal, it
is first parsed into an instance of <tt>java.lang.Number
</tt>according
to the default pattern of the locale specified by the <tt>parseLocale</tt>
attribute. In the absence of this attribute, the English (<tt>en</tt>)
locale is used. If the numeric string uses a pattern different from the
parsing locale's default, it must be parsed using the
<tt><parseNumber></tt>
action.
<p>The <tt>type</tt> attribute accepts (case-insensitive) literals only,
causing an error at translation-time validation if the specified literal
is illegal.
<p>The <tt>pattern</tt> attribute may be used only when formatting numbers
(that is, if the <tt>type</tt> attribute is missing or is equal to "number").
Using it with a <tt>type</tt> attribute equal to "currency" or "percent"
causes a translation-time error.
<h3>
12. <parseNumber></h3>
The <tt><parseNumber></tt> action is used for parsing numbers, currencies,
and percentages.
<p>Depending on the value of the <tt>type</tt> attribute, which must be
one of "number", "currency", or "percent" (default: "number"), the string
specified via the <tt>value</tt> attribute is parsed as a number, currency,
or percentage, respectively, using the default formatting pattern for numbers
(currencies, percentages) of the locale specified by the <tt>parseLocale</tt>
attribute. If the <tt>parseLocale</tt> attribute is missing, the page's
locale is used, which is determined according to Section 2 of this functional
description.
<p>If the number specified via the <tt>value</tt> attribute uses a format
different from the page locale's default, the pattern required to parse
it may be specified using the <tt>pattern</tt> attribute.
<p>If the <tt>var</tt> attribute is given, the parsing result (of type
<tt>java.lang.Number</tt>)
is stored in the named JSP attribute. Otherwise, it is output to
the current <tt>JspWriter</tt> object using <tt>java.lang.Number.toString()</tt>.
<p>The <tt>value</tt> and <tt>pattern</tt> attributes accept both literals
and EL values, whereas the <tt>type</tt> attribute accepts (case-insensitive)
literals only, causing an error at translation-time validation if the specified
literal is illegal.
<p>The <tt>pattern</tt> attribute may be used only when parsing numbers
(that is, if the <tt>type</tt> attribute is missing or equals "number").
Using it with a <tt>type</tt> attribute equal to "currency" or "percent"
causes a translation-time error.
<h3>
13. <formatDate></h3>
The <tt><formatDate</tt>> action allows the formatting of dates and
times using predefined or customized formatting styles.
<p>Depending on the value of the <tt>type</tt> attribute, which must be
one of "time", "date", or "both" (default: "date"), only the time, the
date, or both the time and date components of the date specified via the
<tt>value</tt>
attribute are formatted, using one of the predefined formatting styles
for dates (specified via the <tt>dateStyle</tt> attribute) and times (specified
via the <tt>timeStyle</tt> attribute) of the page's locale, which is determined
according to Section 2 of this functional description. Legal values
for the
<tt>dateStyle</tt> and <tt>timeStyle</tt> attributes are "default",
"short", "medium ", "long", and "full" (default: "default").
<p>If the <tt>value</tt> attribute is missing, the current date and time
are used.
<p>Any time information is represented in the time zone given by the <tt>timeZone</tt>
attribute. If this attribute is missing, and the <tt><formatDate>
</tt>action
is nested inside a <tt><timeZone></tt> tag, the time zone to use is
taken from the enclosing <tt><timeZone></tt> tag. Otherwise, the default
time zone given by the <tt>javax.servlet.jsp.jstl.i18n.timeZone</tt> attribute
is used, which is searched in the page, request, session (if valid), and
application scope(s) (in this order). If not found, the JSP container's
time zone is used.
<p>The action's result is output to the current <tt>JspWriter</tt> object,
unless the <tt>var</tt> attribute is given, in which case it is stored
(as a string) in the named JSP attribute.
<p>Example: Assuming a current date of Oct 22, 2001 and a current time
of 4:05:53 PM,
<p><tt> <fmt:formatDate timeStyle="long" dateStyle="long"/></tt>
<p>will output
<p><tt> October 22, 2001 4:05:53 PM PDT</tt>
<p>for the U.S. and
<p><tt> 22 octobre 2001 16:05:53 GMT-07:0</tt>
<p>for the French locale.
<p>Page authors may also apply a customized formatting style for their
times and dates by specifying the <tt>pattern</tt> attribute. The specified
formatting pattern must use the <a href="http://java.sun.com/docs/books/tutorial/i18n/format/datepattern.html">Date
Format Pattern Syntax</a> specified in the tutorial trail on internationalization
at <tt>java.sun.com</tt>.
<p>Example: Assuming the same current date and time as in the above example,
the output of
<p><tt> <fmt:formatDate pattern="EEE, MMM d, ''yy"/></tt>
<p>will be
<p><tt> Mon, Oct 22, '01</tt>
<p>for the U.S. locale.
<p>The <tt>value</tt> and <tt>pattern</tt> attributes accept both string
literals and EL values (which must evaluate to objects of type<tt> java.util.Date
</tt>in
the case of the <tt>value</tt> attribute).
<p>If the input to the
<tt>value</tt> attribute is a string literal, it
is first parsed into an instance of <tt>java.util.Date</tt> according to
the default formatting style for dates of the parsing locale specified
by the <tt>parseLocale</tt> attribute, that is, it is parsed in a fashion
equivalent to using a <tt><parseDate></tt> action with <tt>type</tt>
equal to "date" (its default value) and <tt>dateStyle</tt> equal to "default"
(its default value). In the absence of the <tt>parseLocale</tt> attribute,
the English (<tt>en</tt>) locale is used as the parsing locale. If the
string in the <tt>value</tt> attribute uses a formatting style for dates
different from the parsing locale's default, or includes a time component,
it must first be parsed using a
<tt><parseDate></tt> action whose parsing
result can then be supplied to a <tt><formatDate></tt> action for formatting.
<p>The <tt>type</tt>, <tt>timeStyle</tt>, and <tt>dateStyle</tt> attributes
take (case-insensitive) literals only, causing an error at translation-time
validation if the specified literal is illegal.
<h3>
14. <parseDate></h3>
The <tt><parseDate></tt> action is used for parsing date and time strings.
<p>Depending on the value of the <tt>type</tt> attribute, which must be
one of "time", "date", or "both" (default: "date"), the date string given
via the
<tt>value</tt> attribute is expected to contain only a time, a
date, or both a time and date component, respectively. It is parsed according
to one of the predefined formatting styles for dates (specified via the
<tt>dateStyle</tt>
attribute) and times (specified via the <tt>timeStyle</tt> attribute) of
the locale specified by the <tt>parseLocale</tt> attribute. If the <tt>parseLocale</tt>
attribute is missing, the page's locale is used, which is determined according
to Section 2 of this functional description. Legal values for the
<tt>dateStyle</tt>
and <tt>timeStyle</tt> attributes are "default", "short", "medium ", "long",
and "full" (default: "default").
<p>If the given date string uses a different format, the pattern required
to parse it may be specified via the <tt>pattern</tt> attribute.
<p>If the given time information does not specify a time zone, it is interpreted
in the time zone given by the <tt>timeZone</tt> attribute. If this
attribute is missing, and the <tt><parseDate>
</tt>action is nested
inside a <tt><timeZone></tt> tag, the time zone is taken from the enclosing
<tt><timeZone></tt>
tag. Otherwise, the default time zone given by the
<tt>javax.servlet.jsp.jstl.i18n.timeZone</tt>
attribute is used, which is searched in the page, request, session (if
valid), and application scope(s) (in this order). If not found, the JSP
container's time zone is used.
<p>If the <tt>var</tt> attribute is given, the parsing result (of type
<tt>java.util.Date</tt>)
is stored in the named JSP attribute. Otherwise, it is output to the current
<tt>JspWriter</tt>
object using <tt>java.util.Date.toString()</tt>.
<p>The <tt>value</tt> and <tt>pattern</tt> attributes accept both literals
and EL values. The <tt>type,timeStyle</tt>, and <tt>dateStyle</tt> attributes
take (case-insensitive) literals only, causing an error at translation-time
validation if the specified literal is illegal.
<h3>
15. <exception></h3>
The <tt><exception</tt>> action is used to display the exception given
by the <tt>value</tt> attribute in its localized form:
<p><tt> <fmt:exception value="$exception" bundle="$errorMessages"/></tt>
<p>If no <tt>value</tt> attribute is given, and this action is used in
an error page, the exception of the error page is used.
<p>Developers may designate an exception as localizable by having it implement
the <tt>javax.servlet.jsp.jstl.i18n.LocalizableException</tt> interface,
which is defined as follows:
<p><tt> public interface LocalizableException {</tt>
<p><tt> /**</tt>
<br><tt> * Returns the
exception's message key from which the exception's</tt>
<br><tt> * localized message
is derived via a resource bundle lookup.</tt>
<br><tt> */</tt>
<br><tt> public String getMessageKey();</tt>
<p><tt> /**</tt>
<br><tt> * Returns the
arguments for parametric replacement on the exception's</tt>
<br><tt> * localized message.</tt>
<br><tt> */</tt>
<br><tt> public Object[] getMessageArgs();</tt>
<br><tt> }</tt>
<p>If the given exception is not an instance of this interface, the <tt><exception></tt>
action uses its fully qualified class name as the key to look up in the
resource bundle for exception messages.
<p>Otherwise, the <tt><exception></tt> action uses the return value
of the exception's
<tt>getMessageKey()</tt> method as the key . If <tt>getMessageKey</tt>
returns null, the exception's fully qualified class name is used as the
key.
<p>The key is looked up in the resource bundle given by the <tt>bundle</tt>
attribute. If this attribute is missing, and the
<tt><exception> </tt>action
is nested inside a <tt><bundle> </tt>tag, the resource bundle to use
is taken from the enclosing <tt><bundle></tt> tag. Otherwise, the default
resource bundle for exception messages, whose default base name is given
by the <tt>javax.servlet.jsp.jstl.i18n.exception.basename</tt> scoped attribute,
is used. This attribute is searched in the page, request, session (if valid),
and application scope(s) (in this order).
<p>The result of looking up the key in the resource bundle is used as the
localized exception message. If the key is not found in the resource bundle,
or the default resource bundle for exception messages does not exist, the
return value of the exception's
<tt>getLocalizedMessage()</tt> method is
used as the localized exception message. If the exception is an instance
of the <tt>LocalizableException </tt>interface, the return value of the
excpetion's <tt>getMessageArgs()</tt> method is used for parametric replacement
on the localized exception message.
<p>The <tt><exception></tt> action outputs the localized exception message
to the current
<tt>JspWriter</tt> object.
<p>If the <tt>stackTrace</tt> attribute is given with a value of <tt>true</tt>,
the exception's stacktrace is printed out in addition to its localized
exception message.
<h3>
16. <requestEncoding></h3>
The <tt><requestEncoding></tt> action is used to set the request's character
encoding, in order to decode request parameter values with a different
encoding than ISO-8859-1 correctly:
<p> <tt><fmt:requestEncoding value="Shift_JIS" /></tt>
<p>This action is needed because browsers do not follow the HTTP spec by
failing to include a <tt>Content-Type</tt> header in their requests.
<p>This action calls the <tt>setCharacterEncoding()</tt> method on the
servlet request with the character encoding name specified in the <tt>value</tt>
attribute. It must be used before any parameters are retrieved, either
explicitly or through the use of an EL expression.
<p>If the character encoding of the request parameters is not known in
advance (since the locale and thus character encoding of the page that
generated the form collecting the parameter values was determined dynamically),
the <tt>value</tt> attribute must not be specified. In this case, the <tt><requestEncoding></tt> action
first checks if there is a charset defined in the request <tt>Content-Type</tt>
header. If not, it uses the character encoding from the <tt>javax.servlet.jsp.jstl.i18n.request.charset</tt>
attribute, which is searched in the page, request, session (if valid),
and application scope(s) (in this order). If this attribute is not found,
the default character encoding (ISO-8859-1) is used.
<h3>
17. Configuration parameters</h3>
This section discusses I18N- and formatting-related initialization parameters
in a web application's deployment descriptor (DD) file.
<h4>
17.1 javax.servlet.jsp.jstl.i18n.basename</h4>
This parameter specifies the base name of the application's default resource
bundle, which is used if a <tt><message></tt> action does not specify
a <tt>bundle</tt> attribute and is not nested inside a
<tt><bundle>
</tt>action.
<p>Example:
<p><tt> <web-app></tt>
<br><tt> <context-param></tt>
<br><tt> <param-name>javax.servlet.jsp.jstl.i18n.basename</param-name></tt>
<br><tt> <param-value>com.acme.MyResources</param-value></tt>
<br><tt> </context-param></tt>
<br><tt> </web-app></tt>
<h4>
17.2 javax.servlet.jsp.jstl.i18n.exception.basename</h4>
This parameter specifies the base name of the application's default resource
bundle for exception messages, which is used by the <tt><exception></tt>
action.
<p>Example:
<p><tt> <web-app></tt>
<br><tt> <context-param></tt>
<br><tt> <param-name>javax.servlet.jsp.jstl.i18n.exception.basename</param-name></tt>
<br><tt> <param-value>com.acme.MyExceptionResources</param-value></tt>
<br><tt> </context-param></tt>
<br><tt> </web-app></tt>
<h4>
17.3 javax.servlet.jsp.jstl.i18n.fallbackLocale</h4>
This parameter specifies the application's default fallback locale, which
is used if browser-sensing capabilities are enabled, but none of the available
locales for the resource bundle in question match any of the client's preferred
locales.
<p>Example:
<p><tt> <web-app></tt>
<br><tt> <context-param></tt>
<br><tt> <param-name>javax.servlet.jsp.jstl.i18n.fallbackLocale</param-name></tt>
<br><tt> <param-value>fr-CA</param-value></tt>
<br><tt> </context-param></tt>
<br><tt> </web-app></tt>
<h4>
17.4 javax.servlet.jsp.jstl.i18n.timeZone</h4>
This parameter specifies the application's default time zone in which any
times and dates formatted using the <tt><formatDate></tt> action are
represented.
<p>Example:
<p><tt> <web-app></tt>
<br><tt> <context-param></tt>
<br><tt> <param-name>javax.servlet.jsp.jstl.i18n.timeZone</param-name></tt>
<br><tt> <param-value>"America/Los_Angeles"</param-value></tt>
<br><tt> </context-param></tt>
<br><tt> </web-app></tt>
<h3>
18. Developer support</h3>
The locale-determination logic for resource bundles described in Section
2.1.1 is exposed as a general convenience method so it may be used by any
tag handler implementation that needs to produce localized messages. For
example, a tag handler's exception messages may be intended directly for
user consumption on an error page and therefore need to be localized.
<p>The convenience method, named <tt>getLocalizedMessage()</tt> and exposed
by the <tt>org.apache.taglibs.jstl.extra.i18n.Locale</tt> class, looks
up a given message key in the resource bundle with a given base name (or
the default base name), whose locale is determined according to the locale-determination
logic described in Section 2.1.1, and optionally performs parametric replacement
on the result of the lookup before returning it.
<p><tt>getLocalizedMessage()</tt> comes in the following overloaded flavors:
<p> <tt> /**</tt>
<br><tt> * Retrieves the localized message corresponding
to the given key.</tt>
<br><tt> *</tt>
<br><tt> * The given key is looked up in the resource
bundle whose base</tt>
<br><tt> * name is retrieved from the javax.servlet.jsp.jstl.i18n.basename
scoped</tt>
<br><tt> * attribute and whose locale is determined
according to the</tt>
<br><tt> * algorithm described in Section 2.1.1
of the functional description.</tt>
<br><tt> *</tt>
<br><tt> * If the javax.servlet.jsp.jstl.i18n.basename
attribute is not found</tt>
<br><tt> * in any of the scopes, or no resource
bundle with that base name exists,</tt>
<br><tt> * or the given key is undefined in the
resource bundle that was loaded as</tt>
<br><tt> * a result of this call, the string "???<key>???"
is returned,</tt>
<br><tt> * where "<key>" is replaced with the
given key</tt>
<br><tt> *</tt>
<br><tt> * @param pageContext the page in which
the given key must be localized</tt>
<br><tt> * @param key the message key to be looked
up</tt>
<br><tt> *</tt>
<br><tt> * @return the localized message corresponding
to the given key</tt>
<br><tt> */</tt>
<br><tt> public static String getLocalizedMessage(PageContext
pageContext,</tt>
<br><tt>
String key);</tt>
<p><tt> /**</tt>
<br><tt> * Retrieves the localized message corresponding
to the given key.</tt>
<br><tt> *</tt>
<br><tt> * The given key is looked up in the resource
bundle with the given</tt>
<br><tt> * base name whose locale is determined
according to the</tt>
<br><tt> * algorithm described in Section 2.1.1
of the functional description.</tt>
<br><tt> *</tt>
<br><tt> * If no resource bundle with the given
base name exists,</tt>
<br><tt> * or the given key is undefined in the
resource bundle that was loaded as</tt>
<br><tt> * a result of this call, the string "???<key>???"
is returned,</tt>
<br><tt> * where "<key>" is replaced with the
given key</tt>
<br><tt> *</tt>
<br><tt> * @param pageContext the page in which
the given key must be localized</tt>
<br><tt> * @param key the message key to be looked
up</tt>
<br><tt> * @param basename the resource bundle
base name</tt>
<br><tt> *</tt>
<br><tt> * @return the localized message corresponding
to the given key</tt>
<br><tt> */</tt>
<br><tt> public static String getLocalizedMessage(PageContext
pageContext,</tt>
<br><tt>
String key,</tt>
<br><tt>
String basename);</tt>
<p><tt> /**</tt>
<br><tt> * Retrieves the localized message corresponding
to the given key and</tt>
<br><tt> * performs parametric replacement using
the arguments specified in the</tt>
<br><tt> * <tt>args</tt> parameter.</tt>
<br><tt> *</tt>
<br><tt> * The given key is looked up in the resource
bundle whose base</tt>
<br><tt> * name is retrieved from the javax.servlet.jsp.jstl.i18n.basename
scoped</tt>
<br><tt> * attribute and whose locale is determined
according to the</tt>
<br><tt> * algorithm described in Section 2.1.1
of the functional description.</tt>
<br><tt> *</tt>
<br><tt> * Before being returned, the result of
the lookup undergoes parametric</tt>
<br><tt> * replacement, using the arguments specified
in the <tt>args</tt></tt>
<br><tt> * parameter.</tt>
<br><tt> *</tt>
<br><tt> * If the javax.servlet.jsp.jstl.i18n.basename
attribute is not found</tt>
<br><tt> * in any of the scopes, or no resource
bundle with that base name exists,</tt>
<br><tt> * or the given key is undefined in the
resource bundle that was loaded as</tt>
<br><tt> * a result of this call, the string "???<key>???"
is returned,</tt>
<br><tt> * where "<key>" is replaced with the
given key</tt>
<br><tt> *</tt>
<br><tt> * @param pageContext the page in which
the given key must be localized</tt>
<br><tt> * @param key the message key to be looked
up</tt>
<br><tt> * @param args the arguments for parametric
replacement</tt>
<br><tt> *</tt>
<br><tt> * @return the localized message corresponding
to the given key</tt>
<br><tt> */</tt>
<br><tt> public static String getLocalizedMessage(PageContext
pageContext,</tt>
<br><tt>
String key,</tt>
<br><tt>
Object[] args);</tt>
<p><tt> /**</tt>
<br><tt> * Retrieves the localized message corresponding
to the given key.</tt>
<br><tt> *</tt>
<br><tt> * The given key is looked up in the resource
bundle with the given</tt>
<br><tt> * base name whose locale is determined
according to the</tt>
<br><tt> * algorithm described in Section 2.1.1
of the functional description.</tt>
<br><tt> *</tt>
<br><tt> * Before being returned, the result of
the lookup undergoes parametric</tt>
<br><tt> * replacement, using the arguments specified
in the <tt>args</tt></tt>
<br><tt> * parameter.</tt>
<br><tt> *</tt>
<br><tt> * If no resource bundle with the given
base name exists,</tt>
<br><tt> * or the given key is undefined in the
resource bundle that was loaded as</tt>
<br><tt> * a result of this call, the string "???<key>???"
is returned,</tt>
<br><tt> * where "<key>" is replaced with the
given key</tt>
<br><tt> *</tt>
<br><tt> * @param pageContext the page in which
the given key must be localized</tt>
<br><tt> * @param key the message key to be looked
up</tt>
<br><tt> * @param args the arguments for parametric
replacement</tt>
<br><tt> * @param basename the resource bundle
base name</tt>
<br><tt> *</tt>
<br><tt> * @return the localized message corresponding
to the given key</tt>
<br><tt> */</tt>
<br><tt> public static String getLocalizedMessage(PageContext
pageContext,</tt>
<br><tt>
String key,</tt>
<br><tt>
Object[] args,</tt>
<br><tt>
String basename);</tt>
<h3>
19. Summary</h3>
<table BORDER CELLPADDING=5 >
<tr>
<td COLSPAN="2" BGCOLOR="#000099"><b><font color="#FFFFFF"><font size=+1>I18N
Tags</font></font></b></td>
</tr>
<tr BGCOLOR="#FFFF66">
<td WIDTH="318"><b>Element</b></td>
<td WIDTH="420"><b>Sample usage</b></td>
</tr>
<tr>
<td WIDTH="318"><b><tt><locale></tt></b>
<br><tt><font color="#000000"><b>value </b>variant scope</font></tt>
<p>Establishes the locale specified by the <tt>value</tt> attribute for
the variant given by the <tt>variant</tt> attribute.</td>
<td WIDTH="420"><tt><fmt:locale value="en-US" variant="UNIX"/></tt></td>
</tr>
<tr>
<td WIDTH="318"><b><tt><timeZone></tt></b>
<br><tt><font color="#000000"><b>value </b>var scope</font></tt>
<p>Establishes the time zone given by the <tt>value</tt> attribute.</td>
<td WIDTH="420"><tt><fmt:timeZone value="America/Los_Angeles"></tt>
<br><tt> <fmt:formatDate type="time"/></tt>
<br><tt></fmt:timeZone></tt></td>
</tr>
<tr>
<td WIDTH="318"><b><tt><bundle></tt></b>
<br><tt><font color="#000000"><b>basename </b>prefix var scope</font></tt>
<p>Loads the resource bundle whose base name is specified by the <tt>basename</tt>
attribute, and optionally exposes it in the named scoped attribute.</td>
<td WIDTH="420"><tt><fmt:bundle basename="Greetings" var="greetingBundle"/></tt></td>
</tr>
<tr>
<td WIDTH="318"><b><tt><message></tt></b>
<br><tt><font color="#000000"><b>key </b>bundle messageArgs var scope</font></tt>
<p>Fetches the localized message corresponding to the key specified by
the <tt>key</tt> attribute from the resource bundle given by the <tt>bundle</tt>
attribute, and performs parametric replacement on the retrieved message
using the argument values supplied via the <tt>messageArgs</tt> attribute
or <tt><messageArg></tt> subtags.</td>
<td WIDTH="420"><tt><fmt:message key="Welcome" bundle="$greetingBundle"/></tt></td>
</tr>
<tr>
<td WIDTH="318"><b><tt><messageFormat></tt></b>
<br><tt><font color="#000000"><b>value</b> var scope</font></tt>
<p>Performs parametric replacement on the pattern specified by the <tt>value</tt>
attribute using the argument values supplied via <tt><messageArg></tt>
subtags.</td>
<td WIDTH="420"><tt><fmt:messageFormat value="$priceMsg"></tt>
<br><tt> <fmt:messageArg value="$priceArg"/></tt>
<br><tt></fmt:messageFormat></tt></td>
</tr>
<tr>
<td WIDTH="318"><b><tt><messageArg></tt></b>
<br><tt><font color="#000000">value</font></tt>
<p>Supplies the argument specified by the <tt>value</tt> attribute
(if present) or the tag body to its parent <tt><message></tt> action
for parametric replacement.</td>
<td WIDTH="420"><tt><fmt:message key="Welcome" bundle="$greetingBundle"> </tt>
<br><tt> <fmt:messageArg value="$dateArg"/></tt>
<br><tt></fmt:message></tt></td>
</tr>
<tr>
<td WIDTH="318"><b><tt><formatNumber></tt></b>
<br><tt><font color="#000000"><b>value </b>type pattern parseLocale var
scope</font></tt>
<p><font color="#000000">Formats the given numeric value as a number, currency,
or percentage using the locale's predefined or the specified (customized)
formatting pattern.</font></td>
<td WIDTH="420"><tt><fmt:formatNumber value="12345.67" parseLocale="de"
type="currency"/></tt></td>
</tr>
<tr>
<td WIDTH="318"><b><tt><parseNumber></tt></b>
<br><tt><font color="#000000"><b>value </b>type<b> </b>pattern parseLocale
var scope</font></tt>
<p><font color="#000000">Parses the given numeric string using the locale's
default or the specified (customized) formatting pattern.</font></td>
<td WIDTH="420"><tt><fmt:parseNumber value="$num" var="parsed"/></tt></td>
</tr>
<tr>
<td WIDTH="318"><b><tt><formatDate></tt></b>
<br><tt><font color="#000000">value<b> </b>type dateStyle timeStyle pattern
timeZone parseLocale var scope</font></tt>
<p><font color="#000000">Formats the given (or current) date using the
locale's predefined or the specified (customized) formatting pattern.</font></td>
<td WIDTH="420"><tt><fmt:formatDate timeStyle="long" dateStyle="long"/></tt></td>
</tr>
<tr>
<td WIDTH="318"><b><tt><parseDate></tt></b>
<br><tt><font color="#000000"><b>value</b> type dateStyle timeStyle pattern
timeZone parseLocale var scope</font></tt>
<p><font color="#000000">Parses the given date string using the locale's
default or the specified (customized) formatting pattern.</font></td>
<td WIDTH="420"><tt><fmt:parseDate value="May 22, 2001 4:05:53 PM PDT"
var="parsed"/></tt></td>
</tr>
<tr>
<td WIDTH="318"><b><tt><exception></tt></b>
<br><tt><font color="#000000">value bundle stackTrace</font></tt>
<p><font color="#000000">Displays the exception given by the <tt>value</tt>
attribute (or the error page's exception if no <tt>value</tt> attribute
is given) in its localized form.</font></td>
<td WIDTH="420"><tt><fmt:exception bundle="$errorMessages"/></tt></td>
</tr>
<tr>
<td WIDTH="318"><b><tt><requestEncoding></tt></b>
<br><tt><font color="#000000">value</font></tt>
<p><font color="#000000">Sets the request character encoding to the charset
specified by the <tt>value</tt> attribute.</font></td>
<td WIDTH="420"><tt><fmt:requestEncoding value="Shift_JIS"/></tt></td>
</tr>
</table>
</body>
</html>
1.7 +3 -2 jakarta-taglibs/standard/examples/web/index.html
Index: index.html
===================================================================
RCS file: /home/cvs/jakarta-taglibs/standard/examples/web/index.html,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- index.html 2001/11/21 20:55:22 1.6
+++ index.html 2001/12/12 20:12:35 1.7
@@ -38,7 +38,7 @@
Group.</b>
<h3>Documentation</h3>
<p>Documentation on the JSTL tags is available at <a href="http://jakarta.apache.org/taglibs/doc/standard-doc">http://jakarta.apache.org/taglibs/doc/standard-doc</a>.
- It is also available as the standard-doc web application of the JSTL EA2 release.
+ It is also available as the standard-doc web application of the JSTL EA3 release.
<h3>Mailing Lists</h3>
<p>There are three ways to obtain information from or send your comments to the
JSR052 Expert Group:
@@ -64,6 +64,7 @@
<li><a href="import/index.html">Import Tags</a> </li>
<li><a href="format/index.html">I18N & Formatting Tags</a></li>
<li><a href="xml/index.html">XML Tags</a></li>
+ <li><a href="sql/index.html">SQL Tags</a></li>
<li><a href="ecmascript/index.html">EcmaScript Examples</a></li>
<li><a href="misc/index.html">Miscellaneous</a></li>
</ul>
@@ -127,7 +128,7 @@
</ul>
</li>
</ul>
-<!-- #EndEditable -->
+<!-- #EndEditable -->
<hr noshade color="#000099">
<table width="100%" border="0" cellpadding="5">
<tr>
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: cvs commit: jakarta-taglibs/standard/examples/web index.html
Posted by Pierre Delisle <pi...@sun.com>.
Shawn,
I've just committed some updates for EA3 docs.
I don't think anything else needs my attention on that front.
[Please note that I've added a link for the EA3 release notes in GettingStarted.
I assume you'll handle that.]
As soon as Justy commits the SQL examples, I'll do a final review and give you
the ok for our side.
Thanks,
-- Pierre
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>