This tutorial describes the standard pattern for using a database in Resin.
Using a JDBC database is a three step process:
DataSource
from the global JNDI
resource map.
Connection
from the DataSource
to execute the SQL.
JDBC database access is based around the Factory pattern.
With JDBC, javax.sql.DataSource
is the Factory object
and java.sql.Connection
is the factory's generated object.
The <database> configures the DataSource
and stores it
in the JNDI resource map. The servlet will retrieve the
DataSource
and use it as a factory to obtain
Connection
objects, the main workhorse for using databases.
In Resin 3.0, the <database> tag configures the database pool and driver and saves the connection factory (DataSource) in JNDI. JNDI is just a global lookup tree available to all classes, making it straightforward to separate resource configuration from the application code.
The <driver> tag configures the database driver. The database vendor will make the driver classes available and describe the configuration variables. The thirdparty database page describes several important database configurations.
The <type> tag is the most important driver configuration item. It specifies the main Java driver class. For many drivers, you will have a choice of different drivers following different internal JDBC APIs. If you have a choice, you should try the drivers in the following order, after checking your database vendor's recommendations:
The <url> specifies the location of the database. Each database driver will have a unique URL formal. In this case, the <url> specifies a directory for the database files. Other databases may specify a host and port.
The specific driver for this example,
com.caucho.db.jca.ConnectionFactory
is a simple database
intended for examples and testing.
The servlet needs to locate the DataSource
to
use JDBC. The servlet needs to lookup the database pool's DataSource
using JNDI. In the configuration above, the name "jdbc/basic" is
shorthand for "java:comp/env/jdbc/basic". "java:comp/env" is a
context containing configured resources. For example,
"java:comp/env/jdbc/basic" is a JDBC resource in that context.
Because the servlet only needs to look up the
DataSource
once, it will generally look it up in the
init()
method and store it as an instance variable.
The DataSource
is thread-safe, so it
can be used simultaneously by any of the requesting threads.
The servlet checks see if the DataSource is
already configured. If not, the assemble()
method
configures the DataSource itself using JNDI.
The most important pattern when using JDBC is the
following try/finally block. All database access should follow this pattern.
Because connections are pooled, it's vital to close the connection no
matter what kind of exceptions may be thrown So the
conn.close()
must be in a finally block.
The full example splits the database access into two methods to
clarify the roles. The service
retrieves the output
writer from the servlet response and wraps any checked exceptions
in a ServletException
. Splitting the servlet method
simplifies the doQuery
method, so it can concentrate
on the database access.