using dependency-injection with jdbc databases

This tutorial describes the standard pattern for using a database in Resin, following the Dependency-Injection/Inversion-of-Control pattern using Java Injection annotations.

Demo

Using a JDBC database is a three step process:

• Configuring the <database> in the resin-web.xml or resin.conf
• Injecting the DataSource to a field with a @com.caucho.config.Name annotation.
• Using a 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. The <database> configures the DataSource and stores it in the CDI registry. The servlet will retrieve the DataSource and use it as a factory to obtain Connection objects, the main workhorse for using databases.

CREATE TABLE jdbc_basic_brooms (
  id INTEGER PRIMARY KEY auto_increment,

  name VARCHAR(128),

  cost INTEGER
);

INSERT INTO jdbc_basic_brooms (name, cost) VALUES ('firebolt', 4000)
INSERT INTO jdbc_basic_brooms (name, cost) VALUES ('nimbus 2001', 500)
INSERT INTO jdbc_basic_brooms (name, cost) VALUES ('nimbus 2000', 300)
INSERT INTO jdbc_basic_brooms (name, cost) VALUES ('cleansweep 7', 150)
INSERT INTO jdbc_basic_brooms (name, cost) VALUES ('cleansweep 5', 100)
INSERT INTO jdbc_basic_brooms (name, cost) VALUES ('shooting star', 50)

In Resin 4.0, the <database> tag configures the database pool and driver and saves the connection factory (DataSource) in the Java Injection manager. Java Injection is an IoC (inversion-of-control) configuration system, 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:

1. JCA - Java Connection Architecture - this is a common driver interface for more than just JDBC. If possible, it's generally the best to choose.
2. ConnectionPoolDataSource - JDBC driver which has extra hooks to help Resin pool the connections.
3. Driver - old-style JDBC driver. Its main benefit is that it's generally always available as a fallback.

<web-app xmlns="http://caucho.com/ns/resin"
   xmlns:example="urn:java:example">
  <database jndi-name="jdbc/basic">

    <example:Demo/>
    
    <driver type="com.caucho.db.jca.ConnectionFactory">
      <url>resin:WEB-INF/db</url>
    </driver>
  </database>
</web-app>

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 servlet is configured with a DataSource to access JDBC. Resin allows two styles of configuration: Dependency Injection using CDI injection and standard servlet <init-param> configuration with JNDI lookups. The Dependency Injection style is simpler, cleaner and makes the application more testable and robust.

package example;

import javax.inject.Inject;

public class BasicServlet extends HttpServlet {
  @Inject @Demo private DataSource _ds;

  ...
}

<servlet servlet-name="my-servlet"
         servlet-class="example.BasicServlet">
</servlet>

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.

Connection conn = _ds.getConnection();
try {
  ...
} finally {
  conn.close();
}

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.

public void service(HttpServletRequest req, HttpServletResponse res)
  throws java.io.IOException, ServletException
{
  PrintWriter out = res.getWriter();

  try {
    doQuery(out);
  } catch (SQLException e) {
    throw new ServletException(e);
  }
}

private void doQuery(PrintWriter out)
  throws IOException, SQLException
{
  Connection conn = _ds.getConnection();

  try {
    String sql = "SELECT name, cost FROM jdbc_basic_brooms ORDER BY cost DESC";
      
    Statement stmt = conn.createStatement();

    ResultSet rs = stmt.executeQuery(sql);

    out.println("<table border='3'>");
      
    while (rs.next()) {
      out.println("<tr><td>" + rs.getString(1));
      out.println("    <td>" + rs.getString(2));
    }

    out.println("</table>");
      
    rs.close();
    stmt.close();
  } finally {
    conn.close();
  }
}

• Database configuration reference
• Sample configurations for several database drivers
• Using Dependency Injection for Databases
• The Dependency Injection (or Assembly Line) pattern.

Demo