The connection tag provides a robust way for a JSP page to get a database connection without getting tangled up in the APIs to make that work.
The JSP 1.2 TryCatchFinally interface lets tag library designers create more robust libraries. For example, database connections must always be closed, even when exceptions occur. The TryCatchFinally interface lets a ConnectionTag automatically close the connection when the tag completes.
The connection tag example creates a JSP tag to look up a database data source in the environment using JNDI. From that data source, it creates a new connection and makes it available to the page. When the connection tag completes, it automatically closes the connection.
<%@ taglib prefix="ct" ... %>
The taglib declaration configuresas a tag prefix. Following tags with the prefix , like map to JSP tag implementations, in this case to instances of ConnectionTag.
The taglib uri,, specifies the tag library descriptor file. The tld tells Resin maps tag names to tag classes and specifies tag attributes.
When the ct:connection tag closes, the tag closes the connection. By using the TryCatchFinally interface, the tag can guarantee it will close the connection with an exception.
The new TryCatchFinally interface of JSP 1.2 lets tags handle exceptions gracefully. The ConnectionTag uses the doFinally() method of TryCatchFinally close the connection even when an exception occurs.
Attributes in JSP tags use Bean methods to set values. When Resin evaluates the ct:connection tag, it will call setName with thevalue. In this example, it will call .
The database name, jdbc/hogwarts, matches its configuration in the resin.conf or web.xml as described in the database config page.
Resin calls ConnectionTag's doStartTag method after setting the attributes. Typically a passthrough tag like ConnectionTag will returnso JSP will interpret the contents as normal JSP.
The database is stored using JNDI, the Java Naming and Directory Interface. The lookup() method used in this example is sufficient for 90% of projects.
JNDI provides a global singleton, InitialContext, and namespace, letting applications grab configuration information from any class. JNDI is nice since you don't need to pass around a configuration variable. You can just use InitialContext where you need it.
In the example, the database source is stored in java:comp/env/jdbc/hogwarts. The database form example uses the same JNDI pattern to grab its database.
With Java's database interface, JDBC, applications grab connections from a data source. With Resin, the data source automatically pools database connections.
creates a new Java variable, . ConnectionTag passes the connection to the JSP page by setting the conn attribute in the pageContext. pageContext is a protected variable inherited from the TagSupport class and set by the JSP page before calling any other methods.
Applications must always close connection objects. Failing to close the connection will give the connection pool fits. By using the TryCatchFinally interface and implementing doFinally(), ConnectionTag can make sure the connection is always closed even when exceptions happen.
Because the ct:connection tag creates new variables in the JSP page, the tag library needs to create a tag info class to declare the variables.
The tag info class returns an array of all the variables. This example has a single variable, conn, which has the type java.sql.Connection. The variable is only valid inside the tag, so its scope is VariableInfo.NESTED.
The tag library descriptor (tld) associates the tag name, connection, with the tag class test.ConnectionTag and the tag info class test.ConnectionTagInfo.
The tag has a single attribute, name, which is required.
The database configuration example more fully describes the database configuration.
A resource-ref describes a factory resource. When Resin initializes, it will create the factory and store it in the JNDI context.
res-ref-name gives the JNDI name. The value of res-ref-name is appended to java:comp/env. So this example will produce the full JNDI name of java:comp/env/jdbc/hogwarts.
res-type describes the type of the resource. This example is a JDBC data source, so it uses the name javax.sql.DataSource. An applications could replace res-type with an arbitrary bean names; Resin would instantiate, initialize and bind the bean to the JNDI context.
init-param uses Bean introspection to initialize the new resource. The parameter name is converted to a method name. For example, driver-name maps to setDriverName and url maps to setURL. After creating the new resource, Resin will call all the initializers to configure it.