| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Frameset//EN""http://www.w3.org/TR/REC-html40/frameset.dtd"> |
| <!--NewPage--> |
| <HTML> |
| <HEAD> |
| <!-- Generated by javadoc on Fri Jun 15 16:53:35 PDT 2001 --> |
| <TITLE> |
| Apache Struts API Documentation: Package org.apache.struts.util |
| </TITLE> |
| <LINK REL ="stylesheet" TYPE="text/css" HREF="../../../../stylesheet.css" TITLE="Style"> |
| </HEAD> |
| <BODY BGCOLOR="white"> |
| |
| <!-- ========== START OF NAVBAR ========== --> |
| <A NAME="navbar_top"><!-- --></A> |
| <TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0"> |
| <TR> |
| <TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> |
| <A NAME="navbar_top_firstrow"><!-- --></A> |
| <TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3"> |
| <TR ALIGN="center" VALIGN="top"> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A> </TD> |
| <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> <FONT CLASS="NavBarFont1Rev"><B>Package</B></FONT> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <FONT CLASS="NavBarFont1">Class</FONT> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD> |
| </TR> |
| </TABLE> |
| </TD> |
| <TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM> |
| </EM> |
| </TD> |
| </TR> |
| |
| <TR> |
| <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> |
| <A HREF="../../../../org/apache/struts/upload/package-summary.html"><B>PREV PACKAGE</B></A> |
| NEXT PACKAGE</FONT></TD> |
| <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> |
| <A HREF="../../../../index.html" TARGET="_top"><B>FRAMES</B></A> |
| <A HREF="package-summary.html" TARGET="_top"><B>NO FRAMES</B></A></FONT></TD> |
| </TR> |
| </TABLE> |
| <!-- =========== END OF NAVBAR =========== --> |
| |
| <HR> |
| <H2> |
| Package org.apache.struts.util |
| </H2> |
| The Utilities package provides a variety of families of classes, |
| to solve problems that are commonly encountered in building web applications. |
| <P> |
| <B>See: </B> |
| <BR> |
| <A HREF="#package_description"><B>Description</B></A> |
| <P> |
| |
| <TABLE BORDER="1" CELLPADDING="3" CELLSPACING="0" WIDTH="100%"> |
| <TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor"> |
| <TD COLSPAN=2><FONT SIZE="+2"> |
| <B>Class Summary</B></FONT></TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="ArrayStack.html">ArrayStack</A></B></TD> |
| <TD>Implementation of the <code>java.util.Stack</code> API that is based on |
| an <code>ArrayList</code> rather than a <code>Vector</code>.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="BeanUtils.html">BeanUtils</A></B></TD> |
| <TD><B>Deprecated.</B> <I>At some point after Struts 1.0 final, will be replaced by |
| an equivalent class in the Jakarta Commons Beanutils package.</I></TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="ConvertUtils.html">ConvertUtils</A></B></TD> |
| <TD><B>Deprecated.</B> <I>At some point after Struts 1.0 final, will be replaced by |
| an equivalent class in the Jakarta Commons Beanutils package.</I></TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="ErrorMessages.html">ErrorMessages</A></B></TD> |
| <TD><B>Deprecated.</B> <I>Use org.apache.struts.action.ActionErrors instead</I></TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="FastArrayList.html">FastArrayList</A></B></TD> |
| <TD><B>Deprecated.</B> <I>At some point after Struts 1.0 final, will be replaced by |
| an equivalent class in the Jakarta Commons Collections package.</I></TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="FastHashMap.html">FastHashMap</A></B></TD> |
| <TD><B>Deprecated.</B> <I>At some point after Struts 1.0 final, will be replaced by |
| an equivalent class in the Jakarta Commons Collections package.</I></TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="FastTreeMap.html">FastTreeMap</A></B></TD> |
| <TD><B>Deprecated.</B> <I>At some point after Struts 1.0 final, will be replaced by |
| an equivalent class in the Jakarta Commons Collections package.</I></TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="GenericConnection.html">GenericConnection</A></B></TD> |
| <TD>Generic wrapper implementation of a <strong>Connection</strong> that |
| works with <code>GenericDataSource</code> to wrap connections for any |
| JDBC driver.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="GenericDataSource.html">GenericDataSource</A></B></TD> |
| <TD>Generic data source implementation of the <code>DataSource</code> |
| interface.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="IteratorAdapter.html">IteratorAdapter</A></B></TD> |
| <TD>Utility method for converting Enumeration to an Iterator |
| class.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="MessageResources.html">MessageResources</A></B></TD> |
| <TD>General purpose abstract class that describes an API for retrieving |
| Locale-sensitive messages from underlying resource locations of an |
| unspecified design, and optionally utilizing the <code>MessageFormat</code> |
| class to produce internationalized messages with parametric replacement.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="MessageResourcesFactory.html">MessageResourcesFactory</A></B></TD> |
| <TD>Factory for <code>MessageResources</code> instances.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="PropertyMessageResources.html">PropertyMessageResources</A></B></TD> |
| <TD>Concrete subclass of <code>MessageResources</code> that reads message keys |
| and corresponding strings from named property resources in the same manner |
| that <code>java.util.PropertyResourceBundle</code> does.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="PropertyMessageResourcesFactory.html">PropertyMessageResourcesFactory</A></B></TD> |
| <TD>Factory for <code>PropertyMessageResources</code> instances.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="PropertyUtils.html">PropertyUtils</A></B></TD> |
| <TD><B>Deprecated.</B> <I>At some point after Struts 1.0 final, will be replaced by |
| an equivalent class in the Jakarta Commons Beanutils package.</I></TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="RequestUtils.html">RequestUtils</A></B></TD> |
| <TD>General purpose utility methods related to processing a servlet request |
| in the Struts controller framework.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="ResponseUtils.html">ResponseUtils</A></B></TD> |
| <TD>General purpose utility methods related to generating a servlet response |
| in the Struts controller framework.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="ServletContextWriter.html">ServletContextWriter</A></B></TD> |
| <TD>A PrintWriter implementation that uses the logging facilities of a |
| <code>javax.servlet.ServletContext</code> to output its results.</TD> |
| </TR> |
| </TABLE> |
| |
| |
| <P> |
| <A NAME="package_description"><!-- --></A><H2> |
| Package org.apache.struts.util Description |
| </H2> |
| |
| <P> |
| The Utilities package provides a variety of families of classes, |
| to solve problems that are commonly encountered in building web applications. |
| <br><br> |
| <a name="doc.Description"></a> |
| <div align="center"> |
| <a href="#doc.Intro">[Introduction]</a> |
| <a href="#doc.Beans">[Beans and Properties]</a> |
| <a href="#doc.Collections">[Collection Classes]</a> |
| <a href="#doc.JDBC">[JDBC Connection Pool]</a> |
| <a href="#doc.Messages">[Message Resources]</a> |
| </div> |
| |
| <hr> |
| |
| <a name="doc.Intro"></a> |
| <h3>Introduction</h3> |
| |
| <p>The Struts Utilities Package offers several families |
| of classes that assist in solving commonly encountered problems when building |
| web applications. Most of the classes in this package do not rely on the |
| controller servlet framework, or the custom tag libraries, so they are also |
| suitable for general Java application programming. The following families |
| are included:</p> |
| <ul> |
| <li><a href="#doc.Beans">Beans and Properties</a> - A family of utility |
| classes for manipulating JavaBeans, as well as getting and setting |
| properties, without hard coding the names or data types of the |
| property getter and setter methods.</li> |
| <li><a href="#doc.Collections">Collection Classes</a> - A family of specialized |
| classes supporting the Collections API, designed for use in multithread |
| environments where the vast majority of accesses are read only.</li> |
| <li><a href="#doc.JDBC">JDBC Connection Pool</a> - A very simple connection |
| pool that can be utilized in web applications or other environments that |
| need to share a limited number of JDBC Connections across a much larger |
| number of active users.</li> |
| <li><a href="#doc.Messages">Message Resources</a> - A family of classes that |
| features access to internationalized message strings based on a message |
| key coupled with a <code>java.util.Locale</code> object representing a |
| particular user's preferred language.</li> |
| </ul> |
| |
| <hr> |
| |
| <a name="doc.Beans"></a> |
| <h3>Beans and Properties</h3> |
| |
| <p>FIXME</p> <p>FIXME some parts of this might me moved to Taglibs</p> |
| <p> The <code>BeanUtils</code> and <code>PropertyUtils</code> utilities are |
| used through out struts including the <code>IteratorTag, WriteTag</code>. |
| Much of these utilities rely on and make use of Java reflection, to manipulate |
| <a href='http://developer.java.sun.com/developer/onlineTraining/Beans/beans02/'> |
| Java beans </a>. Creating a <b>valid</b> Java bean is essential ! |
| Briefly referring to the example class <code>ProductBean</code> |
| below would follow these rules : |
| <ul> |
| <li> The class <b>must</b> a null constructor, or no constructor </li> |
| <li> It's class declaration <b>must</b> be public </li> |
| <li> The name for the property say 'value' would have a 'get' method of getValue()</li> |
| <li> The 'get' and 'set' methods to be visible <b>must</b> be public.</li> |
| <li> If desired the 'is' prefix can be used in place if 'get' for a boolean.</li> |
| <li> Other requirements can be found |
| <a href='http://developer.java.sun.com/developer/onlineTraining/Beans/beans02/'> |
| here</a>. |
| </ul> |
| <pre> |
| public class ProductBean() { |
| private String value; |
| public String getvalue() (return this.value} |
| public void setvalue(String value) (this.value = value} |
| } |
| </pre> |
| </p> |
| <p> Observing these conventions will avoid unnecessary errors and save time.</p> |
| |
| <p> |
| This makes it possible to create a JSP page such as: |
| <pre> |
| <logic:iterate id="product" name="receivedForm" property="receivedList"> |
| <bean:write name="product" property="description" /> |
| <bean:write name="product" property="value" /> |
| </logic:iterate> |
| </pre> |
| In this case receiveForm is an ActionForm, with a definition such as |
| <pre> |
| public class ReceivedForm extends ActionForm { |
| private ProductList productList; |
| public void setReceivedList(Enumeration enum) { |
| productList = new ProductList(enum,Limits.ARRAY_SIZE_MIN); |
| } |
| /** |
| * Defined so java.bean reflection will see getReceivedList |
| * as a getter for receivedList |
| */ |
| public void setReceivedList(ProductList productlist) { |
| |
| } |
| |
| /** |
| * Returns an Array list of ProductBeans. |
| */ |
| public ProductList getReceivedList() { |
| return productList; |
| }; |
| } //ReceiveForm |
| </pre> |
| <hr> |
| |
| <a name="doc.Collections"></a> |
| <h3>Collection Classes</h3> |
| |
| <h5>Background</h5> |
| |
| <p>Version 1.2 of the Java 2 Standard Edition (J2SE) introduced a powerful |
| set of collection classes that are generally useful in Java programming, based |
| on the fundamental interfaces <code>java.util.Collection</code>, |
| <code>java.util.List</code>, <code>java.util.Map</code>, and |
| <code>java.util.Set</code>. Compared to the collection classes available in |
| JDK 1.1 (principally <code>java.util.Hashtable</code> and |
| <code>java.util.Vector</code>), the new classes offer much richer functionality |
| as well as the opportunity to improve performance.</p> |
| |
| <p>The performance increase potential comes from the fact that none of the |
| methods used to access the new collection classes are <code>synchronized</code> |
| as were the methods of <code>Hashtable</code> and <code>Vector</code>. In a |
| single thread application, this means that method calls can execute much more |
| quickly because synchronization is never necessary. In a multiple thread |
| environment, though, it is up to the developer to ensure that any method calls |
| made while another thread is modifying the collection must be synchronized. |
| </p> |
| |
| <p>There are many cases in multithreaded server environments (such as a web |
| application) where data structures are initialized at application startup |
| time, and are then predominantly accessed in a read-only manner. An example |
| of this is the Struts controller application, which initializes its collection |
| of <code>ActionMapping</code> instances (each corresponding to an |
| <code><action></code> element in the <code>struts-config.xml</code> |
| file) at startup time. However, it is legal for an application to dynamically |
| change the set of available mappings while the application is running -- so, |
| to be safe, it would normally be necessary to synchronize access to such |
| collections, even though 99% of those accesses are read only and would not |
| otherwise require synchronization.</p> |
| |
| <p>To deal with such scenarios, the Struts utility package includes a series |
| of specialized collection classes designed to operate in a multithread |
| environment where the large majority of accesses are read only, without |
| requiring synchronization on every operation, but still protecting against |
| the possibility of runtime modifications to the underlying collection.</p> |
| |
| <h5>Theory of Operation</h5> |
| |
| <p>Each of the available collection classes operates in one of two modes: |
| <em>fast</em> or <em>slow</em>. When first created, the collection operates |
| in <em>slow</em> mode, which is appropriate for initially populating the |
| contents of the collection. Once the initial population is complete, switch |
| to <em>fast</em> mode by calling <code>setFast(true)</code> for maximum |
| performance when most accesses are read-only.</p> |
| |
| <p>When operating in <em>slow</em> mode, all methods that access this |
| collection, even read-only methods, are synchronized - resulting in impacts on |
| performance similar to that always performed by the <code>Hashtable</code> and |
| <code>Vector</code> classes. This mode is appropriate when you are |
| initializing the content of the collection, or when you need to perform a large |
| series of updates.</p> |
| |
| <p>Using <em>fast</em> mode, on the other hand, causes method calls to operate |
| in the following manner:</p> |
| <ul> |
| <li>Method calls that access information from the collection, but do not |
| modify it, are executed <strong>without</strong> synchronization.</li> |
| <li>Method calls that modify the structure of a collection do so by |
| synchronizing, cloning the existing collection instance, modifying the |
| cloned instance, and then replacing the current collection instance.</li> |
| </ul> |
| |
| <p>As you can see, modification operations are <strong>much</strong> more |
| expensive when operating in <em>fast</em> mode, but doing things in this way |
| allows read only operations, which should be the vast majority, to operate at |
| maximum speed.</p> |
| |
| <p>If your collection will <strong>never</strong> be accessed in a multithread |
| environment, you should use one of the standard collection classes instead, |
| without synchronization, for maximum performance.</p> |
| |
| <h5>Available Collection Classes</h5> |
| |
| <p>The following collection classes, with the ability to operate in either |
| <em>fast</em> or <em>slow</em> mode, are included:</p> |
| <ul> |
| <li><a href="FastArrayList.html">org.apache.struts.util.FastArrayList</a> - |
| Similar in functionality to <code>java.util.ArrayList</code>.</li> |
| <li><a href="FastHashMap.html">org.apache.struts.util.FastHashMap</a> - |
| Similar in functionality to <code>java.util.HashMap</code>.</li> |
| <li><a href="FastTreeMap.html">org.apache.struts.util.FastTreeMap</a> - |
| Similar in functionality to <code>java.util.TreeMap</code>.</li> |
| </ul> |
| |
| |
| <a name="doc.JDBC"></a> |
| <h3>JDBC Connection Pool</h3> |
| |
| <h5>Background</h5> |
| |
| <p>A large number of web applications require interaction with a relational |
| database to access or update persistently stored information. In a typical |
| client-server application, each concurrent user opens their own database |
| connection at program initialization, and uses this connection throughout |
| the period of time the application is open.</p> |
| |
| <p>While this approach can work well in an environment where the number of |
| active users is reasonably fixed, it does not scale well to a web application |
| where the number of simultaneous users could be very large. In addition, open |
| database connections (even when not actively used) do impose some overhead |
| costs, and most web application users (at a given instant) are reviewing the |
| contents of a previously generated page (or typing in their next set of input |
| information), rather than actively accessing the database.</p> |
| |
| <p>To deal with this situation, several basic strategies are possible:</p> |
| <ol> |
| <li>Open a connection on each request, do whatever processing is required, |
| and then close the connection.</li> |
| <li>Open a connection for each user, and store it in the user's session.</li> |
| <li>Share a "pool" of open connections between all of the application's |
| current users.</li> |
| </ol> |
| |
| <p>The first strategy has the virtue of simplicity - you merely need to open |
| a database connection any time you need one, perform the appropriate data |
| accesses and updates, and close the connection. However, it suffers from a |
| major disadvantage: on most databases, establishing a connection can be very |
| time consuming (often requiring multiple seconds of clock time), in order to |
| perform a database transaction that might take milliseconds.</p> |
| |
| <p>Opening a connection per user, as the second strategy suggests, is similar |
| to the approach taken with client-server applications described earlier. As |
| long as the number of simultaneous users can be controlled at a manageable |
| number (such as with many intranet-based applications), this approach is |
| feasible. However, it becomes unmanageable when the number of users can climb |
| rapidly to very large numbers (as is typical of many Internet-hosted public |
| applications), and still requires more overhead than a strategy that would |
| share a smaller number of connections.</p> |
| |
| <p>Connection pooling is an implementation of the third strategy. It is based |
| on the assumption that most users of a web application will be interacting |
| locally with the last page that was sent to their browser. The number of users |
| actually performing a request at any given time is usually a very small |
| percentage of the total number of active users, and during request processing |
| is the only time that a database connection is required.</p> |
| |
| <p>Struts provides a simple connection pool class called |
| <code>org.apache.struts.util.GenericDataSource</code>. It allows you to |
| configure a set of connections (with identical connection parameters) to a |
| particular database, using a particular JDBC driver, and then share those |
| connections among a number of simultaneously operating threads (such as the |
| various request threads that are concurrently active in a servlet container). |
| The <code>GenericDataSource</code> class implements the |
| <code>javax.sql.DataSource</code> interface from the Java Database Connectivity |
| (version 2.0) Standard Extension API, so any programs you use to access it |
| should reference this interface, rather than the class name directly. |
| That way, you can migrate to a more advanced connection pool implementation |
| later, with little or no impact on your application.</p> |
| |
| <p>For more information about the JDBC 2.0 Standard Extension API, you can |
| download the spec (and the corresponding API classes), from |
| <a href="http://java.sun.com/products/jdbc">http://java.sun.com/products/jdbc</a>. You can also find pointers to a substantial amount of other information |
| about available JDBC drivers, programming tutorials, and so on, at this |
| web address.</p> |
| |
| <h5>Initializing and Finalizing the Connection Pool</h5> |
| |
| <p>The following instructions show you how to configure the connection pool |
| class and use it, from any Java application. As you will see below, the Struts |
| controller servlet offers you convenient mechanisms to configure one or more |
| connection pools, and make them available to Action classes and JSP pages by |
| storing the connection pool instances as servlet context attributes (in JSP |
| terms, application-scope beans).</p> |
| |
| <p>To configure a <code>GenericDataSource</code> instance, you must first |
| create one:</p> |
| <pre> |
| GenericDataSource dataSource = |
| new GenericDataSource(); |
| </pre> |
| |
| <p>Next, you must set the appropriate properties, by calling the corresponding |
| JavaBeans property setter methods provided by this class. (See the Javadoc |
| API for the <a href="GenericDataSource.html">GenericDataSource</a> class for |
| more details on the available properties). An example of configuring the |
| connection pool object to a Postgres database might look like this:</p> |
| <pre> |
| dataSource.setAutoCommit(false); |
| dataSource.setDescription("My Database Connection Pool"); |
| dataSource.setDriverClass("org.postgresql.Driver"); |
| dataSource.setMaxCount(4); |
| dataSource.setMinCount(1); |
| dataSource.setPassword("mypassword"); |
| dataSource.setUrl("jdbc:postgresql://localhost/mydatabase"); |
| dataSource.setUser("myusername"); |
| </pre> |
| |
| <p>Finally, you must <code>open()</code> the connection pool. This will |
| establish the initial connections to the database (based on the value you have |
| configured for the <code>minCount</code> property). As you use connections |
| from the pool in multiple threads, additional connections (up to the number |
| you specify with the <code>maxCount</code> property) will be created as needed. |
| </p> |
| <pre> |
| try { |
| dataSource.open(); |
| } catch (SQLException e) { |
| ... deal with exception ... |
| } |
| </pre> |
| |
| <p>When you are completely through with the connection pool, you can gracefully |
| close all of the currently open database connections by executing</p> |
| <pre> |
| try { |
| dataSource.close(); |
| } catch (SQLException e) { |
| ... deal with exception ... |
| } |
| </pre> |
| |
| <h5>Using the Generic Connection Pool</h5> |
| |
| <p>To access the database from within an application class, you must follow a |
| simple four-step procedure each time you need a connection:</p> |
| <ol> |
| <li>Acquire a connection from the connection pool.</li> |
| <li>Perform the database operations required by your application.</li> |
| <li>Cause the last database transaction to be committed or rolled back |
| (commits are required on many databases to ensure that the database |
| operations you just performed are permanently stored or not).</li> |
| <li>"Close" the connection, which returns it to the connection pool for |
| reuse later.</li> |
| </ol> |
| |
| <p>An example code sequence that performs this procedure might look like |
| this:</p> |
| <pre> |
| DataSource dataSource = ... acquire reference to dataSource ... |
| Connection conn = null; |
| PreparedStatement stmt = null; |
| ResultSet rs = null; |
| try { |
| conn = dataSource.getConnection(); |
| stmt = conn.prepareStatement("SELECT cust_id, name FROM customers" + |
| " WHERE (last_purchase_date >= ?)" + |
| " ORDER BY name"); |
| stmt.setDate(1, lastPurchaseDate); |
| rs = stmt.executeQuery(); |
| while ((row = rs.next()) != null) { |
| ... process this row ... |
| } |
| rs.close(); |
| rs = null; |
| stmt.close(); |
| stmt = null; |
| conn.commit(); |
| conn.close(); |
| conn = null; |
| } catch (SQLException e) { |
| if (rs != null) { |
| try { |
| rs.close(); |
| } catch (SQLException f) { |
| ; |
| } |
| rs = null; |
| } |
| if (stmt != null) { |
| try { |
| stmt.close(); |
| } catch (SQLException f) { |
| ; |
| } |
| stmt = null; |
| } |
| if (conn != null) { |
| try { |
| conn.rollback(); |
| } catch (SQLException f) { |
| ... deal with exception ... |
| } |
| } |
| ... deal with exception ... |
| } finally { |
| if (conn != null) { |
| try { |
| conn.close(); |
| } catch (SQLException f) { |
| ... deal with exception ... |
| } |
| conn = null; |
| } |
| } |
| </pre> |
| |
| <p>One aspect of the above code example that might surprise developers who |
| have previously used JDBC connections individually is the idea of calling |
| close() on the Connection. Normally, this call will sever the Connection's |
| underlying link to the database, and render that Connection unuseable for |
| any further operations. However, when used in a connection pool environment, |
| the actual Connection you receive by calling <code>getConnection()</code> |
| is a customized "wrapper" around a real JDBC Connection instance. Calling |
| <code>close()</code> on this wrapper simply causes this connection to be |
| returned to the pool.</p> |
| |
| <p>What would happen if your application failed to return a connection to the |
| pool when it was through? As you might expect, that particular connection |
| becomes "lost" to the server, and can never again be used (even though it |
| remains connected to the database throughout the life of the connection pool |
| itself). If this happens repeatedly, you will eventually exhaust the pool |
| of available connections, and application processing will stop.</p> |
| |
| <p>To avoid this problem, your application logic must ensure that it |
| <strong>ALWAYS</strong> returns allocated connections to the pool, no matter |
| what problems might happen in the interim. The Java language provides one |
| convenient mechanism to achieve this - using a <code>finally</code> block, |
| as in the code example above. This is not the only way to ensure that a |
| connection is always returned, but it is very convenient.</p> |
| |
| <h5>Using Connection Pools with the Struts Controller Servlet</h5> |
| |
| <p>If your application is running underneath the Struts controller servlet |
| (<code>org.apache.struts.action.ActionServlet</code>), you can take advantage |
| of the servlet's ability to preconfigure one or more connection pools for you, |
| based on information included in the <code>struts-config.xml</code> file. |
| Simply include a section that looks like this:</p> |
| <pre> |
| <data-sources> |
| <data-source> |
| <set-property property="autoCommit" |
| value="false"/> |
| <set-property property="description" |
| value="Example Data Source Configuration"/> |
| <set-property property="driverClass" |
| value="org.postgresql.Driver"/> |
| <set-property property="maxCount" |
| value="4"/> |
| <set-property property="minCount" |
| value="2"/> |
| <set-property property="password" |
| value="mypassword"/> |
| <set-property property="url" |
| value="jdbc:postgresql://localhost/mydatabase"/> |
| <set-property property="user" |
| value="myusername"/> |
| </data-source> |
| </data-sources> |
| </pre> |
| |
| <p>After being initialized, the connection pools will be stored as servlet |
| context attributes under the bean name specified by the <code>key</code> |
| attribute. If you did not specify a <code>key</code>, the default key is the |
| value of the string constant <code>Action.DATA_SOURCE_KEY</code>. Thus, you |
| can access and utilize a connection, from within an <code>Action</code> class, |
| like this (for the default data source):</p> |
| <pre> |
| DataSource dataSource = (DataSource) |
| servlet.getServletContext().getAttribute(Action.DATA_SOURCE_KEY); |
| conn = dataSource.getConnection(); |
| ... perform required functions as in the previous example ... |
| conn.close(); |
| </pre> |
| |
| <hr> |
| |
| <a name="doc.Messages"></a> |
| <h3>Message Resources</h3> |
| |
| <h5>Background</h5> |
| |
| <p>Modern applications often include the requirement to support multiple |
| languages, for users who prefer to interact in a language other than the |
| default language configured on the server platform. In addition, sentences |
| often need to be constructed, with dynamic content whose placement in the |
| message depends on the standard sentence structure in that particular |
| language.</p> |
| |
| <p>The standard Java platform includes a family of classes |
| (<code>java.util.ResourceBundle</code>) designed to support looking up message |
| strings based on a standard "key". The resource bundle classes automatically |
| access a Java class (or properties file) that is named with a naming |
| convention that includes the Locale to which messages in that class (or file) |
| pertain. However, this selection is based only on the default Locale of the |
| server platform, and cannot be adjusted on a per-user basis as required for an |
| internationalized web application.</p> |
| |
| <p>Struts includes a family of classes |
| (<code>org.apache.struts.util.MessageResources</code>) that extends the basic |
| approach to looking up message strings by key, allowing you to optionally |
| specify a Locale along with the key. In this way, you can build applications |
| that let your users select which Locale they wish to operate within, and then |
| look up messages in that language - using the same message keys no matter what |
| language is selected.</p> |
| |
| <p>In addition to supporting dynamic selection of a Locale for message lookup, |
| the <code>MessageResources</code> family of classes optionally allow you to |
| specify up to four parameter replacement objects, which are used to replace the |
| parameter placeholders "{0}" through "{3}" in the retrieved message. This |
| replacement uses the facilities of the standard Java |
| <code>java.text.MessageFormat</code> class, which supports many extended |
| formatting capabilities as well.</p> |
| |
| <p>For more information about internationalized messages, consult the following |
| resources in your Java Development Kit documentation bundle:</p> |
| <ul> |
| <li><em>Internationalization Info</em> - General information on Java's standard |
| support for internationalized applications can be found at |
| <code><$JAVA_HOME/docs/guide/internat/index.html></code>. |
| The "Internationalization Overview" section includes useful information |
| about Locales, localized resources, message formatting, and other |
| relevant topics.</li> |
| <li><em>Internationalization Tutorial</em> - The Java Language Tutorial has a |
| comprehensive trail covering internationalization, available at: |
| <a href="http://java.sun.com/docs/books/tutorial/i18n/index.html"> |
| http://java.sun.com/docs/books/tutorial/i18n/index.html</a>.</li> |
| <li><em>Javadoc APIs</em> - You will want to consult the Javadoc API |
| documentation for the following standard Java classes: |
| <ul> |
| <li><code>java.text.MessageFormat</code> |
| <li><code>java.util.ResourceBundle</code> |
| <li><code>java.util.PropertyResourceBundle</code> |
| <li><code>java.util.Properties</code> - See the documentation for the |
| <code>load()</code> method for the valid syntax of properties files |
| that you prepare.</li> |
| </ul></li> |
| </ul> |
| |
| <h5>Using the Standard MessageResources Implementation</h5> |
| |
| <p>The standard <code>MessageResources</code> implementation provided by the |
| Struts library uses Java properties files to initialize message strings, in a |
| manner very similar to that supported by the |
| <code>java.util.PropertyResourceBundle</code> class. The following steps are |
| required to use these facilities in your Java application.</p> |
| |
| <p>First, prepare a Java properties file for each language (or Locale) in which |
| you wish to support your messages. The filenames you use must conform to the |
| naming convention for property resource bundles, as described in the |
| documentation referenced above. Be sure you use the same message keys in each |
| file to identify the same message.</p> |
| |
| <p>For example, you might prepare files in French, Spanish, and English that |
| contain language-specific versions of the word "Hello". The French file would |
| be named <code>Messages_fr.properties</code> and contain the following:</p> |
| <pre> |
| hi=Bonjour |
| </pre> |
| <p>while the Spanish and English files would be named |
| <code>Messages_es.properties</code> and <code>Messages_en.properties</code> |
| respectively. The corresponding message string definitions would say |
| <code>hi=Hola</code> and <code>hi=Hello</code> in these files.</p> |
| |
| <p>Second, place these properties files into the class path for your |
| application, exactly as you would with class files themselves. The name |
| actually used to load resources will look like a fully qualified Java class |
| name (with appropriate package prefixes), so the file should be nested inside |
| a directory structure that matches the packaging (either in an unpacked |
| directory, or within a JAR file, as appropriate). For example, assume you |
| place directory "foo" on your classpath, and stored the above properties files |
| in directory "foo/com/mycompany/mypackage". (If you were using a JAR file like |
| "foo.jar" instead, the files would be in directory "com/mycompany/mypackage" |
| within the JAR file). |
| |
| <p>Third, initialize a <code>MessageResources</code> object that corresponds |
| to the set of properties files for a particular name, within a particular |
| package. The easiest way to do this is to initialize a variable in your main |
| application class, like this:</p> |
| <pre> |
| public static MessageResources messages = |
| MessageResources.getMessageResources("com.mycompany.mypackage.Messages"); |
| </pre> |
| |
| <p>Note that the "com.mycompany.mypackage" part of the name matches the package |
| directory into which you placed your properties files, and "Messages" is the |
| filename prefix for the particular family of properties files supported by this |
| <code>MessageResources</code> instance. Depending on your development process, |
| you might find it convenient to store all message strings for an entire |
| application in a single properties file family, or to have several families - |
| in Struts, for example, there is a family of properties files for each Java |
| package.</p> |
| |
| <p>To access a message string with a particular Locale, execute a statement |
| like this:</p> |
| <pre> |
| Locale locale = ... select the locale to be used ... |
| String message = messages.getMessage(locale, "hi"); |
| </pre> |
| |
| <p>In this case, the variable <code>message</code> will contain the message |
| string corresponding to the key "hi", in the language that corresponds to the |
| locale that was selected.</p> |
| |
| <p>For an example of message formatting with replaceable parameters, assume |
| that the message strings looked like this, instead (only the English version |
| is shown - corresponding changes would be made in the other files):</p> |
| <pre> |
| hi=Hello {0} |
| </pre> |
| |
| <p>Now, you can personalize the retrieved message like this:</p> |
| <pre> |
| Locale locale = ... select the locale to be used ... |
| String name = "Joe"; |
| String message = messages.getMessage(locale, "hi", name); |
| </pre> |
| |
| <p>and the marker "{0}" will have been replaced by the specified name (Joe), |
| no matter which language is in use. See the JavaDoc API documentation for the |
| <code>java.text.MessageFormat</code> class for more advanced uses of the |
| parameter replacement mechanism.</p> |
| |
| <h5>Developing Your Own MessageResources Implementation</h5> |
| |
| <p>In the above example, we were using the default |
| <code>MessageResources</code> implementation supplied by Struts, which uses |
| property files to store the message strings. It is also possible to create |
| customized mechanisms to retrieve messages (such as loading them on demand |
| from a database). The steps required are as follows:</p> |
| <ul> |
| <li>Create a customized subclass of |
| <code>org.apache.struts.util.MessageResources</code> that implements |
| message lookup operations as you require.</li> |
| <li>Create a customized subclass of |
| <code>org.apache.struts.util.MessageResourcesFactory</code> that will |
| create an instance of your custom <code>MessageResources</code> class |
| when the <code>createResources</code> method is called. Note that the |
| "config" argument to this method can be used to select families of |
| messages in any manner appropriate to your needs - you are not required |
| to emulate the "fully qualified Java class name" approach that is used |
| by the standard <code>PropertyMessageResourcesFactory</code> class.</li> |
| <li>Tell the <code>MessageResourcesFactory</code> class the name of the |
| customized <code>MessageResourcesFactory</code> implementation to use |
| when creating new factory instances.</li> |
| <li>Create a new factory instance.</li> |
| <li>Ask the new factory instance to create a <code>MessageResources</code> |
| instance for you.</li> |
| </ul> |
| |
| <p>A code example that illustrates this technique is:</p> |
| <pre> |
| MessageResourcesFactory.setFactoryClass("com.mycompany.mypkg.MyFactory"); |
| MessageResourcesFactory factory = MessageResourcesFactory.createFactory(); |
| MessageResources resources = |
| factory.createResources("configuration information"); |
| </pre> |
| |
| <p>Once you have created your custom MessageResources instance, you utilize it |
| to access message strings (with or without parameter replacement objects), |
| exactly as we illustrated with the standard implementation in the previous |
| section.</p> |
| |
| <h5>Using MessageResources With Struts</h5> |
| |
| <p>If your application uses the Struts controller servlet, you can optionally |
| configure Struts to load an application-specific message resources instance for |
| you, and make it available as a servlet context attribute (in JSP terms, an |
| application-scope bean). This mechanism is managed by setting the following |
| servlet initialization parameters in the web application deployment descriptor: |
| </p> |
| <ul> |
| <li><strong>application</strong> - The configuration string that will be |
| passed to the <code>createResources()</code> method of the message |
| resources factory, in order to identify the family of resources to be |
| supported. If you use the standard message resources factory, this must |
| be the base fully qualified name of the property resources files used |
| to contain these messages, as illustrated above.</li> |
| <li><strong>factory</strong> - Fully qualified Java class name of the |
| <code>MessageResourcesFactory</code> to be used. By default, the standard |
| implementation provided by Struts |
| (<code>org.apache.struts.util.PropertyMessageResourcesFactory</code>) |
| will be used.</li> |
| </ul> |
| |
| <p>Struts provides several JSP custom tags that assume the existence of a |
| <code>java.util.Locale</code> attribute in the user's session, under the key |
| named by the constant string value of <code>Action.LOCALE_KEY</code>. Your own |
| application logic can set this attribute at any time, or you can ask Struts to |
| set it automatically (if not already set) based on the |
| <code>Accept-Language</code> HTTP header included with the request. There are |
| two mechanisms by which you request Struts to perform this service:</p> |
| <ul> |
| <li>To have this service performed on every request submitted to the controller |
| servlet, set the servlet initialization parameter <code>locale</code> to |
| the value <code>true</code> in the application deployment descriptor.</li> |
| <li>To have this service performed by a JSP page when it is accessed directly |
| by a user, utilize a <code><form:html ... locale="true" ... /></code> |
| tag at the top of each page.</li> |
| </ul> |
| <P> |
| <HR> |
| |
| <!-- ========== START OF NAVBAR ========== --> |
| <A NAME="navbar_bottom"><!-- --></A> |
| <TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0"> |
| <TR> |
| <TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> |
| <A NAME="navbar_bottom_firstrow"><!-- --></A> |
| <TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3"> |
| <TR ALIGN="center" VALIGN="top"> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A> </TD> |
| <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> <FONT CLASS="NavBarFont1Rev"><B>Package</B></FONT> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <FONT CLASS="NavBarFont1">Class</FONT> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD> |
| </TR> |
| </TABLE> |
| </TD> |
| <TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM> |
| </EM> |
| </TD> |
| </TR> |
| |
| <TR> |
| <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> |
| <A HREF="../../../../org/apache/struts/upload/package-summary.html"><B>PREV PACKAGE</B></A> |
| NEXT PACKAGE</FONT></TD> |
| <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> |
| <A HREF="../../../../index.html" TARGET="_top"><B>FRAMES</B></A> |
| <A HREF="package-summary.html" TARGET="_top"><B>NO FRAMES</B></A></FONT></TD> |
| </TR> |
| </TABLE> |
| <!-- =========== END OF NAVBAR =========== --> |
| |
| <HR> |
| Copyright © 2000-2001 - Apache Software Foundation |
| </BODY> |
| </HTML> |