Configuring Turbine

I l @ ve RuBoard

Instructions on where to get Turbine libraries and how to install them can be found in Appendix C. But before you can use the Turbine facilities themselves , you need to set up your application for Turbine. You also need to create a property file with some specific initialization values for the db pool in it, specifically for the application that you intend to build. Listing 7.2 is an example of what it looks like.

Listing 7.2 /TomCat/webapps/bfg/TurbineResources.properties

 # ------------------------------------------------------------------- # #  S E R V I C E S # # ------------------------------------------------------------------- # Classes for Turbine Services should be defined here. # Format: services.[name].classname=[implementing class] # # To specify properties of a service use the following syntax: # service.[name].[property]=[value] services.PoolBrokerService.classname=org.apache.turbine.services.db.  TurbinePoolBrokerService services.MapBrokerService.classname=org.apache.turbine.services.db.TurbineMapBroker Service

The first few lines of the property file tells Turbine which classes to use for specific services (the db pooling and logging):

 # ------------------------------------------------------------------- # #  D A T A B A S E  S E T T I N G S # # ------------------------------------------------------------------- # These are your database settings.  Look in the # org.apache.turbine.util.db.pool.* packages for more information. # The default driver for Turbine is for MySQL. # # The parameters to connect to the default database.  You MUST # configure these properly. # ------------------------------------------------------------------- database.default.driver=org.gjt.mm.mysql.Driver database.default.url=jdbc:mysql://localhost/BFG database.default.username=bfguser database.default.password=bfg

The first four lines of the database settings tell Turbine what database to connect to when allocating new entries in the pool:

 # The number of database connections to cache per ConnectionPool # instance (specified per database). database.default.maxConnections=50

The maxConnections setting is the maximum number of simultaneous connections to allow to the database. If a connection is requested beyond this limit, Turbine will wait for one to become available. You need to make sure that this is set high enough that, if a database query takes a few seconds, you don't run out of connections in the meantime.

 # The amount of time (in milliseconds) that database connections will be # cached (specified per database). # # Default: one hour = 60 * 60 * 1000 database.default.expiryTime=3600000

The expiryTime is how long an idle connection will be left in the pool before being closed.

 # The amount of time (in milliseconds) a connection request will have to wait # before a time out occurs and an error is thrown. # # Default: ten seconds = 10 * 1000 database.connectionWaitTimeout=10000

The WaitTimeout is how long a request for a connection can wait before an error is thrown. Again, set it high enough that you don't end up without enough time for a long query to finish when you're short on connections.

 # The interval (in milliseconds) between which the PoolBrokerService logs # the status of it's ConnectionPools. # # Default: No logging = 0 = 0 * 1000 database.logInterval=0

logInterval specifies how often the status of the connection pools should be sent to the log. Setting it to means that the connection pools will never be sent.

 # These are the supported JDBC drivers and their associated Turbine # adaptor.  These properties are used by the DBFactory.  You can add # all the drivers you want here. database.adaptor=DBMM database.adaptor.DBMM=org.gjt.mm.mysql.Driver

The adaptor settings set Turbine up to use mysql as the database service to pool.

 # Determines if the quantity column of the IDBroker's id_table should # be increased automatically if requests for ids reaches a high # volume. database.idbroker.cleverquantity=true

The cleverquantity setting can be left unchanged from the value set in the example file provided with Turbine.

Before you can use the Turbine facilities for this application, you need to initialize Turbine by telling it where to find the configuration file that you just created. One way to do this is to have every piece of code that will use the database check to see if Turbine had been initialized, and to initialize Turbine if it has not. This not only involves a lot of unnecessary code, it also slows down the execution a great deal. Instead, you should take advantage of a feature of servlet engines (including Tomcat) that allows you to specify a servlet that will be initialized as part of application startup.

To specify the servlet, you create a class that extends the HttpServlet class. In Listing 7.3, the example is called TurbineInit , and it should reside in the com.bfg.services package.

Listing 7.3 com/bfg/services/TurbineInit.java

 TurbineInit.java package com.bfg.services; import javax.servlet.http.HttpServlet; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; import java.io.PrintWriter; import java.io.IOException; import org.apache.turbine.util.TurbineConfig; public class TurbineInit extends HttpServlet {   public   void init() {       String prefix =  getServletContext().getRealPath("/");       String dir = getInitParameter("turbine-resource-directory");       TurbineConfig tc = new TurbineConfig(dir, "TurbineResources.properties");       tc.init();     }   public   void doGet(HttpServletRequest req, HttpServletResponse res) {   } }

The class overloads two methods . One, the doGet method, is basically a noop but is required by HttpServlet . The init method is called during startup, and it's here that you put the code that initializes Turbine. Upon initialization, you run the call that tells Turbine where to find its configuration file. The path is relative to where Catalina was started, which is the TOMCAT_HOME/bin directory.

Now all you have to do is instruct Tomcat to use this servlet as part of the BFG application. To do this, place a simple web.xml file in the BFG web-inf directory, as shown in Listing 7.4.

Listing 7.4 web.xml

 <?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE web-app     PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"     "http://java.sun.com/j2ee/dtds/web-app_2_3.dtd">     <web-app>   <servlet>     <servlet-name>log4j-init</servlet-name>     <servlet-class>com.bfg.services.Log4jInit</servlet-class>   <servlet>     <servlet-name>turbine-init</servlet-name>     <servlet-class>com.bfg.services.TurbineInit</servlet-class>     <init-param>       <param-name>turbine-resource-directory</param-name>       <param-value>c:/tomcat/webapps/bfg/WEB-INF</param-value>     </init-param>     <load-on-startup>1</load-on-startup>   </servlet>  </web-app>

All that the code in Listing 7.4 does is register TurbineInit as a servlet. You'll need to change the path to the turbine-resource-directory to whatever the absolute bfg WEB-INF directory path is.

You should also add code to your Ant script to automatically copy the web.xml and the TurbineResources.properties files from the source hierarchy. It's always dangerous to have application-specific files that live only in the deployed server; they might be overwritten by a reinstall. Putting them in the source hierarchy and having Ant install them ensures that you don't lose them. The additional lines in the dist section of the script are shown in Listing 7.5.

Listing 7.5 Additions to build.xml

 <mkdir dir="${appdir} /logs"/> . . .      <copy todir="${appdir}">         <fileset dir="." includes="TurbineResources.properties"/>      </copy>      <copy todir="${appdir} /WEB-INF">         <fileset dir="." includes="web.xml"/>      </copy>

I l @ ve RuBoard