http://xml.apache.org/http://www.apache.org/http://www.w3.org/

Index
License

Install
Install on Solaris8
Install on Win2k

Technologies
Infrastructure
User Guide
Dynamic Content
How it works

XSP Processor
SQL XSP Taglib
FP XSP Taglib
SQL Conn Pool
SQL Processor
LDAP Processor
DCP Processor

XSP WD

Javadocs

Cocoon 2

FAQ
Changes
Todo

Live Sites

Code Repository
Dev Snapshots
Mail Lists
Mail Archive


Required Components

In the /lib directory you'll find the turbine-pool.jar jar package that contains the Turbine Connection Pool binary files (a new addition to Cocoon in version 1.8). While this package may not be the most up-to-date version, it is guaranteed and tested to work properly with Cocoon so, we suggest that you use it.


Installing Turbine Connection Pool
Installing on Apache JServ

On JServ, it is necessary to make sure that the new turbine-pool.jar is visible to Java. This implies adding the following to the servlet engine classpath by adding a line to your jserv.properties file for the connection pool jar package.

wrapper.classpath=[path-to-jar]/[jar-name].jar

Here is an example:

wrapper.classpath=/usr/local/java/cocoon/lib/turbine-pool.jar

Please also read the next section.


Generic Installation for All Servlet Engines

To use the pool, you need to have the appropriate properties defined in your cocoon.properties file. The important ones are listed below. This is an example of creating a default pool for use with Oracle. Currently Turbine supports a wide number of different databases. If your database is not already supported, please subscribe to the mailing list and ask for help or try on your own. It is quite easy to add support for your favorite database.

        # These are your database settings, look in the
        # org.apache.turbine.util.db.pool.* package for more information.
        processor.xsp.pool.database.default.driver=oracle.jdbc.driver.OracleDriver
        processor.xsp.pool.database.default.url=jdbc:oracle:thin:@localhost:1521:ORCL
        processor.xsp.pool.database.default.username=dbUser
        processor.xsp.pool.database.default.password=dbPass
        processor.xsp.pool.database.default.maxConnections=3
        processor.xsp.pool.database.default.expiryTime=3600000
        # These are the supported jdbc-drivers and their adaptors.
        # These properties are used by the DBFactory.
        processor.xsp.pool.database.adaptor=DBWeblogic,DBOracle,DBInstantDB,DBPostgres,DBSybase,DBInformix
        processor.xsp.pool.database.adaptor.DBWeblogic=weblogic.jdbc.pool.Driver
        processor.xsp.pool.database.adaptor.DBOracle=oracle.jdbc.driver.OracleDriver
        processor.xsp.pool.database.adaptor.DBInstantDB=org.enhydra.instantdb.jdbc.idbDriver
        processor.xsp.pool.database.adaptor.DBPostgres=postgresql.Driver
        processor.xsp.pool.database.adaptor.DBInformix=com.informix.jdbc.IfxDriver
        processor.xsp.pool.database.adaptor.DBSybase=com.sybase.jdbc.SybDriver
        # The full path name to a pool log file
        # if not given, commands to log events using org.apache.turbine.util.Log will be ignored.
        # This file must already exist and be writable.
        # Default: none
        #
        processor.xsp.pool.logfile=/opt/apache/var/log/dbPool.log
     

The default is by convention the default connection used by the Turbine Connection Pool. To define a Named connection, add new entries with the word "default" replaced with the name you want. Here is an example for defining a connection to an Oracle database called "helpdesk":

        processor.xsp.pool.database.helpdesk.driver=oracle.jdbc.driver.OracleDriver
        processor.xsp.pool.database.helpdesk.url=jdbc:oracle:thin:@localhost:1521:ORCL
        processor.xsp.pool.database.helpdesk.username=dbUser
        processor.xsp.pool.database.helpdesk.password=dbPass
        processor.xsp.pool.database.helpdesk.maxConnections=3
        processor.xsp.pool.database.helpdesk.expiryTime=3600000
     

The maxConnections setting is the maximum number of connections to cache. The expiryTime setting is for automaticially timing out cached connections to the database. This is to prevent connections from becoming stale. The username and password settings should be obvious. If your database does not support users, then simply leave these items blank. The rest of the settings are database specific and you should read the various connection interfaces javadoc and drivers to find out the appropriate strings to use.



Using Turbine Connection Pool

This section is to describe how you can use the Turbine connection pool in your own code. (At the time of writing, in Cocoon only the SQL taglibs use connection pooling - another good reason to use the SQL taglibs!) To demonstrate this, I'll show an example of how I modified Ricardo Rocha's excellent example XSQL. This is some of the code that he had before:

    import java.sql.*;
    import java.util.*;
    import org.w3c.dom.*;
    import DBConnectionManager;

    public class XSQL {
      static DBConnectionManager manager = DBConnectionManager.getInstance();

      public static Element executeQuery(
        String connectionName,
        String statementId,
        String statementText,
        Document factory
      )
        throws SQLException
      {
        Connection connection = null;

        try {
          connection = manager.getConnection(connectionName);
          Statement statement = connection.createStatement();
          ResultSet resultSet = statement.executeQuery(statementText);
          ResultSetMetaData metaData = resultSet.getMetaData();
          int columnCount = metaData.getColumnCount();

          Element rowSet = factory.createElement("xsql:rowset");
          rowSet.setAttribute("id", statementId);

          for (int i = 0; resultSet.next(); i++) {
            Element row = factory.createElement("xsql:row");
            row.setAttribute("sequence", String.valueOf(i + 1));
            rowSet.appendChild(row);
    
            for (int j = 0; j < columnCount; j++) {
              String value = resultSet.getString(j + 1);

              Element element = factory.createElement(
               metaData.getColumnLabel(j + 1).toLowerCase()
              );
              row.appendChild(element);

              if (value != null) {
                element.appendChild(
                  factory.createTextNode(value)
                );
              }
            }
          }

          resultSet.close();
          statement.close();

          return rowSet;
        } catch (SQLException e) {
          throw(new SQLException(statementText));
        } finally {
          if (connection != null) {
            manager.freeConnection(connectionName, connection);
          }
        }
      }

    }
    

Now this is the code modified to use the Turbine connection pool:

    import java.sql.*;
    import java.util.*;
    import org.w3c.dom.*;
    import DBConnectionManager;

    public class XSQL {
        static DBBroker pool = DBBroker.getInstance();       // <---- Pool code!

        public static Element executeQuery(
        String connectionName,
        String statementId,
        String statementText,
        Document factory
      )
        throws SQLException
      {
        Connection connection = null;
        DBConnection db = null;                              // <---- Pool code!
        try {
          db = pool.getConnection(connectionName);           // <---- Pool code!
          connection = db.getConnection();                   // <---- Pool code!
          Statement statement = connection.createStatement();
          ResultSet resultSet = statement.executeQuery(statementText);
          ResultSetMetaData metaData = resultSet.getMetaData();
          int columnCount = metaData.getColumnCount();

          Element rowSet = factory.createElement("xsql:rowset");
          rowSet.setAttribute("id", statementId);

          for (int i = 0; resultSet.next(); i++) {
            Element row = factory.createElement("xsql:row");
            row.setAttribute("sequence", String.valueOf(i + 1));
            rowSet.appendChild(row);

            for (int j = 0; j &lt; columnCount; j++) {
              String value = resultSet.getString(j + 1);

              Element element = factory.createElement(
                metaData.getColumnLabel(j + 1).toLowerCase()
              );
              row.appendChild(element);

              if (value != null) {
                element.appendChild(
                  factory.createTextNode(value)
                );
              }
            }
          }

          resultSet.close();
          statement.close();

          return rowSet;
        } catch (SQLException e) {
          throw(new SQLException(statementText));
        } finally {
          if (connection != null) {
            pool.releaseConnection(db);                      // <---- Pool code!
          }
        }
      }

    }
    

Please see the getting started documentation at the Turbine homepage for more information about Turbine (a server-side framework which is the home of the connection pool code).



Copyright © 1999-2000 The Apache Software Foundation. All Rights Reserved.