| |||||||||||||||||||||||||||||||
Find this tutorial in: /usr/local/resin/webapps/resin-doc/db/tutorial/jdbc-basic
Try the Tutorial This tutorial describes the standard pattern for using a database in Resin.
Using a JDBC database is a three step process:
JDBC database access is based around the Factory pattern. With JDBC, javax.sql.DataSource is the Factory 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:
In the above example, the <path> is a driver-specific parameter, set using bean-style initialization , i.e. the ConnectionFactory class has a setPath method. com.caucho.db.jca.ConnectionFactoryThe specific driver for this example, com.caucho.db.jca.ConnectionFactory is a simple database intended for examples and testing.
The servlet is configured with a DataSource to access JDBC. Resin allows two styles of configuration: Dependency Injection using bean-style setters and standard servlet <init-param> configuration. The Dependency Injection style is simpler, while the <init-param> style will work on all servlet engines. By creating a separate assemble() method, a servlet can take advantage of Resin's Dependency Injection and still be fully compatible with other servlet engines. 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. Because the DataSource is designed to be thread-safe, it can be used simultaneously by any of the requesting threads.
When the servlet initializes, it checks to see if the DataSource is already configured. If not, the assemble() method configures the DataSource itself using JNDI. The assemble() method performs the Assembler function in the Dependency Injection (Assembly Line) pattern. If you are using Resin's Dependency Injection capability, the assemble() method is not needed. You can eliminate the JNDI code and rely on the setDataSource. You'll need the assemble() method if you're porting your servlet to a different servlet engine. Dependency Injection configurationUsing dependency injection to configure servlets has some advantages over the init-param method:
Enabling the Dependency Injection pattern is trivial: just add a setDataSource method as in the example above.
Standard configuration
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.
|