struts-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject cvs commit: jakarta-struts/src/share/org/apache/struts/util package.html
Date Tue, 22 Apr 2003 01:59:38 GMT
dgraham     2003/04/21 18:59:38

  Modified:    src/share/org/apache/struts/util package.html
  Fixed package description for PR# 18315.  Thanks for the patch!
  Revision  Changes    Path
  1.9       +20 -428   jakarta-struts/src/share/org/apache/struts/util/package.html
  Index: package.html
  RCS file: /home/cvs/jakarta-struts/src/share/org/apache/struts/util/package.html,v
  retrieving revision 1.8
  retrieving revision 1.9
  diff -u -r1.8 -r1.9
  --- package.html	26 Jun 2002 22:28:05 -0000	1.8
  +++ package.html	22 Apr 2003 01:59:38 -0000	1.9
  @@ -9,9 +9,8 @@
   <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.Beans">[Beans]</a>
  +<a href="#doc.Utilities">[Servlet Utilities]</a>
   <a href="#doc.Messages">[Message Resources]</a>
  @@ -27,17 +26,10 @@
   suitable for general Java application programming.  The following families
   are included:</p>
  -<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.Beans">Beans</a> - A small set of utility beans useful
  +    encapsulating form elements.</li>
  +<li><a href="#doc.Utilities">Servlet Utilities</a> - A set of classes
  +    for working with servlet-related classes.</li>
   <li><a href="#doc.Messages">Message Resources</a> - A family of classes
       features access to internationalized message strings based on a message
       key coupled with a <code>java.util.Locale</code> object representing a
  @@ -47,426 +39,26 @@
   <a name="doc.Beans"></a>
  -<h3>Beans and Properties</h3>
  -<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=''>
  -    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> 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=''>
  -    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>
  -        &lt;logic:iterate id="product" name="receivedForm" property="receivedList"&gt;
  -              &lt;bean:write name="product" property="description" /&gt;
  -              &lt;bean:write name="product" property="value" /&gt;
  -        &lt;/logic:iterate&gt;
  -    </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
  -<a name="doc.Collections"></a>
  -<h3>Collection Classes</h3>
  -<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> The <code>ImageButtonBean</code> is a simple JavaBean to encapsulate
  +    request parameters sent for an HTML input element of type image. The 
  +    <code>LabelValueBean</code> is a simple JavaBean to represent label-value

  +    pairs, especially useful for html option elements.
  -<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>&lt;action&gt;</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
  -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
  -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>
  -<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
  -in the following manner:</p>
  -<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>
  -<p>As you can see, modification operations are <strong>much</strong>
  -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>
  -<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>
  -<a name="doc.JDBC"></a>
  -<h3>JDBC Connection Pool</h3>
  -<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>
  -<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>
  -<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=""></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>
  -    GenericDataSource dataSource =
  -      new GenericDataSource();
  -<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>
  -    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");
  +<a name="doc.Utilities"></a>
  +<h3>Servlet Utilities</h3>
  -<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> The <code>RequestUtils</code> is a general purpose utility methods

  +    related to processing a servlet request. The <code>ResponseUtils</code>
  +    is a general purpose utility methods related to generating a servlet 
  +    response. The <code>ServletContextWriter</code> is a PrintWriter 
  +    implementation that uses the logging facilities of a 
  +    <code>javax.servlet.ServletContext</code> to output its results.
  -    try {
  -    } catch (SQLException e) {
  -        ... deal with exception ...
  -    }
  -<p>When you are completely through with the connection pool, you can gracefully
  -close all of the currently open database connections by executing</p>
  -    try {
  -        dataSource.close();
  -    } catch (SQLException e) {
  -        ... deal with exception ...
  -    }
  -<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>
  -<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>
  -<p>An example code sequence that performs this procedure might look like
  -    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 = != 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;
  -        }
  -    }
  -<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>
  -    &lt;data-sources&gt;
  -      &lt;data-source&gt;
  -        &lt;set-property property="autoCommit"
  -                      value="false"/&gt;
  -        &lt;set-property property="description"
  -                      value="Example Data Source Configuration"/&gt;
  -        &lt;set-property property="driverClass"
  -                      value="org.postgresql.Driver"/&gt;
  -        &lt;set-property property="maxCount"
  -                      value="4"/&gt;
  -        &lt;set-property property="minCount"
  -                      value="2"/&gt;
  -        &lt;set-property property="password"
  -                      value="mypassword"/&gt;
  -        &lt;set-property property="url"
  -                      value="jdbc:postgresql://localhost/mydatabase"/&gt;
  -        &lt;set-property property="user"
  -                      value="myusername"/&gt;
  -      &lt;/data-source&gt;
  -    &lt;/data-sources&gt;
  -<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>
  -    DataSource dataSource = (DataSource)
  -      servlet.getServletContext().getAttribute(Action.DATA_SOURCE_KEY);
  -    conn = dataSource.getConnection();
  -    ... perform required functions as in the previous example ...
  -    conn.close();

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

View raw message