9.3 How JSTL Locates Data Sources

Three JSTL SQL actions access a database: <sql:query>, <sql:update>, and <sql:transaction>. Those actions use a data source to access a database, so they all have an optional dataSource attribute that specifies that data source. When you use those actions, JSTL locates a data source with this algorithm:

Locate a value:

If the dataSource attribute was specified for <sql:query>, <sql:update>, or <sql:transaction>, JSTL uses that attribute's value to access the data source, so go to step 3; otherwise , go to step 2.
If the SQL_DATA_SOURCE configuration setting exists, JSTL uses that setting's value to access the data source. Go to step 3.

Evaluate the value:
If step 1 or 2 yields no value or null , JSTL throws an exception.
If step 1 or 2 yields a data source, JSTL uses it; if not, go to step 5.
If step 1 or 2 yields a string, go to step 6.

Access the data source:
JSTL assumes that the string obtained from step 1 or 2 is a JNDI relative path , and tries to access that JNDI resource.
If step 6 failed, JSTL uses the string to create a JDBC connection.
If steps 6 and 7 failed, JSTL throws an exception.

Let's take a closer look at how the preceding steps work:

Locate a value:

You can specify a data source with the dataSource attribute for <sql:query>, <sql:update>, or <sql:transaction>; for example, you can execute a database query like this:

 <sql:query var='customers'  dataSource='${myDataSource}'  >     SELECT * FROM CUSTOMERS </sql:query>

In the preceding code fragment, the scoped variable myDataSource can reference either a string or an instance of javax.sql.DataSource . If that attribute references an instance of javax.sql.DataSource , that data source is used by the query; if it references a string, JSTL interprets the string as either a JNDI resource or JDBC parameters.

You can also specify a string for the dataSource attribute directly, like this:

 <sql:query var='customers'  dataSource='aJNDIResourceOrJDBCParameters'  >    SELECT * FROM CUSTOMERS </sql:query>

You don't have to specify the dataSource attribute for <sql:query>, <sql:update>, or <sql:transaction>; for example, you can execute a database query like this:

 <sql:query var='customers'>     SELECT * FROM CUSTOMERS </sql:query>

If you omit the dataSource attribute, JSTL assumes that the value of the SQL_DATA_SOURCE configuration setting, if it exists, represents a data source. If the SQL_DATA_SOURCE , configuration setting does not exist and you don't specify the dataSource attribute, the <sql:query>, <sql:update>, and <sql:transaction> actions will throw an exception.

You can specify a value for the SQL_DATA_SOURCE configuration setting in the deployment descriptor, with a business component, or with the <sql:setDataSource> action. See "Creating Data Sources" on page 365 for more information about setting the SQL_DATA_SOURCE configuration setting.

Evaluate the value:

The value that you specify for a data source can be a string or an instance of javax.sql.DataSource . If it's the latter, JSTL uses it as is; if it's the former, continue to the next step.

Access the Data Source:

If you specify a data source as a string, JSTL first assumes that the string is a relative path to a JNDI resource and tries to retrieve that resource from the JSP container's JNDI naming context. If the JNDI lookup fails, then <sql:query>, <sql:update>, and <sql:transaction> assume that the string represents JDBC parameters and try to create a JDBC connection.

If you specify a data source as a string and that string is not a valid JNDI relative path and does not represent valid JDBC parameters, then <sql:query>, <sql:update>, and <sql:transaction> will throw an exception.

Summary:

You can specify a data source as:

an instance of javax.sql.DataSource
a string representing a JNDI relative path that points to a data source
a string representing a JDBC URL and, optionally , a driver, user name , and password

You can specify a data source with:

<sql:query>, <sql:update>, <sql:transaction>, and <sql:setDataSource>
the SQL_DATA_SOURCE configuration setting ^[5]

^[5] If you use <sql:setDataSource> without the var attribute, the specified data source is stored in the SQL_DATA_SOURCE configuration setting.

This section discussed how JSTL locates a data source; how you create a data source and make it available to JSTL is the topic of the next section.