The JavaTM Web Services Tutorial
Home
TOC
PREV TOP NEXT

Accessing Databases from Web Applications

Data that is shared between Web components and persistent between invocations of a Web application is usually maintained by a database. Web applications use the JDBC 2.0 API to access relational databases. For information on this API, see

http://java.sun.com/docs/books/tutorial/jdbc
 

The Examples

The examples discussed in the chapters 13, 14, 16, and 17 require a database. For this release we have tested the examples with the Pointbase 4.2 database and we provide an Ant build file to create the database tables and populate the database. The remainder of this section describes how to


Note: The last two bullets are discussed further in the document JNDI Resources HOW-TO at <JWSDP_HOME>/docs/tomcat/config/jndi-resources-howto.html. A limitation of the current release of the Java WSDP is that you cannot deploy a database-enabled Web application using the Ant deploy task or deploytool because you cannot map a database reference to a database (see Configuring Tomcat to Map the JNDI Name to a Database) using either of these tools.

Installing and Starting the Database Server

You can download an evaluation copy of the Pointbase 4.2 database from:

http://www.pointbase.com
 

Make sure to choose a platform-specific (UNIX or Windows) installation package. Install the client and server components. After you have downloaded and installed the Pointbase database, do the following:

  1. Add a pb.home property to your build.properties file (discussed in Managing the Examples) that points to your Pointbase install directory. On Windows the syntax of the entry must be
       pb.home=drive:\\<PB_HOME>
     
    
  2. Copy <PB_HOME>/lib/pbclient42.jar to <JWSDP_HOME>/common/lib to make the Pointbase client library available to the example applications. If Tomcat is running, restart it so that it loads the client library.
  3. In a terminal window, go to <PB_HOME>/tools/server.
  4. Start the Pointbase server by typing start_server on UNIX or startserver on Windows.

Populating the Database

  1. In a terminal window, go to <JWSDP_HOME>/docs/tutorial/examples/web.
  2. Execute ant. The default Ant task, create-web-db, uses the Pointbase console tool to execute the SQL statements in books.sql. At the end of the processing, you should see the following output:
    [java] ID	
    [java] ----------	
    [java] 201	
    [java] 202	
    [java] 203	
    [java] 204	
    [java] 205	
    [java] 206	
    [java] 207	
    [java]	
    [java] 7 Rows Selected.	
    [java]	
    [java] SQL>	
    [java]	
    [java] COMMIT;	
    [java] OK
     
    

Configuring the Web Application to Reference a Database

In order to access a database from a Web application, you must declare resource reference in the application's Web application deployment descriptor (see References to Environment Entries, Resource Environment Entries, or Resources). The resource reference declares a JNDI name, jdbc/BookDB, the type of the resource, and the kind of authentication used when the resource is accessed:

<resource-ref>	
   <res-ref-name>jdbc/BookDB</res-ref-name>	
   <res-type>javax.sql.DataSource</res-type>	
   <res-auth>Container</res-auth>	
</resource-ref>
 

The JNDI name is used to create a data source object in the database helper class database.BookDB used by the tutorial examples. The res-auth element specifies that the container will manage logging on to the database.

Configuring Tomcat to Map the JNDI Name to a Database

Since the resource reference declared in the Web application deployment descriptor uses a JNDI name to refer to the database, you must connect the name to an actual database by providing a resource and resource parameters entries in Tomcat's configuration. Here are the entries used by the application discussed in all the Web technology chapters:

<Resource name="jdbc/BookDB" reloadable="true" 	
   auth="Container" type="javax.sql.DataSource"/>	
<ResourceParams name="jdbc/BookDB">	
   <parameter>	
      <name>user</name>	
      <value>public</value>	
   </parameter>	
   <parameter>	
      <name>password</name>	
      <value>public</value>	
   </parameter>	
   <parameter>	
      <name>driverClassName</name>	
      <value>com.pointbase.jdbc.jdbcUniversalDriver</value>	
   </parameter>	
   <parameter>	
      <name>driverName</name>	
      <value>	
         jdbc:pointbase:server://localhost/sample	
      </value>	
   </parameter>	
</ResourceParams>
 

Since the resource and resource parameter entries are subentries of the context entry described in Deploying Web Applications, you add this entry to Tomcat's configuration in the same ways that you can add the context entry.


Note: A limitation of the current release of the Java WSDP is that you cannot deploy a database-enabled Web application using the ant deploy task or deploytool because you cannot add resource or resource parameter entries to Tomcat's configuration using either of these tools.

Home
TOC
PREV TOP NEXT