Accessing Databases from Web Applications

The Java^TM Web Services Tutorial

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 12, 13, 15, and 16 require a database. For this release we have tested the examples with the PointBase 4.3 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

Install and start the PointBase database server
Populate the example tables
Configure the Web application to reference a data source
Define a data source in Tomcat
Configure Tomcat to map the reference to the data source

Installing and Starting the Database Server

You can download an evaluation copy of the PointBase 4.3 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:
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>
 
Copy <PB_HOME>/lib/pbclient43.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.
In a terminal window, go to <PB_HOME>/tools/server.
Start the PointBase server by typing start_server on UNIX or startserver on Windows.
Populating the Database
In a terminal window, go to <JWSDP_HOME>/docs/tutorial/examples/web.
Execute ant. The default Ant task, create-book-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 Data Source

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, the type of the data 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.

To specify a resource reference in deploytool:

Select the WAR.
Select the Resource Refs tab.
Click Add.
Enter jdbc/BookDB in the Coded Name field.

Defining a Data Source in Tomcat

In order to use a database you must create a data source in Tomcat. The data source contains information about the driver class and URL used to connect to the database and database login parameters. To define a data source in Tomcat, you use admintool (see Configuring Data Sources) as follows:
Start admintool by opening a browser at:
  http://localhost:8080/admin/index.jsp
 
Log in using the user name and password you specified when you installed the Java WSDP.
Select the Data Sources entry under Resources.
Select Available ActionsCreate New Data Source.
Enter pointbase in the JNDI Name field.
Enter jdbc:pointbase:server://localhost/sample in the Data Source URL field.
Enter com.pointbase.jdbc.jdbcUniversalDriver in the JDBC Driver Class field.
Enter public in the User Name and Password fields.
Click the Save button.
Click the Commit button.
Configuring Tomcat to Map the JNDI Name to a Data Source

Since the resource reference declared in the Web application deployment descriptor uses a JNDI name to refer to the data source, you must connect the name to a data source by providing a resource link entry in Tomcat's configuration. Here is the entry used by the application discussed in all the Web technology chapters:
<Context path="/bookstore1"
  docBase="../docs/tutorial/examples/web/bookstore1/build" 
  debug="0">
  <ResourceLink name="jdbc/BookDB" global="pointbase"/>
</Context>
 
Since the resource link is a subentry of the context entry described in Installing Web Applications and Deploying Web Applications, you add this entry to Tomcat's configuration in the same ways that you add the context entry: by passing the name of a configuration file containing the entry to the config attribute of the Ant install task or by copying the configuration file named mywebapp.xml that contains the context entry to <JWSDP_HOME>/webapps.

If you are deploying the application using the Ant deploy task, you must package a configuration file named context.xml containing the context entry in the META-INF directory of the WAR.

If you are deploying the application using deploytool, you make the connection as follows:

Select the WAR.
Select the Resource Refs tab.
Select the data source you defined in Configuring the Web Application to Reference a Data Source.
Click the Import Data Sources button.
Dismiss the confirmation dialog.
Select pointbase from the drop down list.

The examples discussed in chapters 12, 13, 15, and 16 illustrate the last two deployment mechanisms.

Home
TOC
Index

This tutorial contains information on the 1.0 version of the Java Web Services Developer Pack.

All of the material in The Java Web Services Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.