WebLogic Server 6.0 Code Examples, BEA Systems, Inc.

Package examples.jsp.tagext.sql

The SQL example is a comprehensive use of the tag extension library to make a JDBC query from a JSP page.

See:
          Description

Class Summary
ConnectionTag Creates a JDBC connection.
QueryExtraInfo Assigns the name given by the id attribute
QueryTag Executes the SQL statement.
ResultsTag This class defines a custom JSP tag that enumerates through the contents of the current session.
 

Package examples.jsp.tagext.sql Description

The SQL example is a comprehensive use of the tag extension library to make a JDBC query from a JSP page.

The SQL example introduces the following tag extension library concepts:

          Instructions for Building and Running the Example

Additional Resources for examples.jsp.tagext.sql
query.jsp This is the JSP page that runs this example.
sqltags.tld The tag library descriptor (tld) for this example.
 

The JSP page opens a connection to the JDBC connection pool "demoPool" defined in the WebLogic Server Administration Console, makes a query on the "emp" database, iterates through the results, and displays them in a table.

The example uses the following tags:

<sql:connection>
This tag takes a required attribute poolName that identifies the name of a JDBC connection pool to obtain a connection from. The pool must be setup in the WebLogic Server Administration Console.

<sql:query>
A <query> tag must be nested within a <connection> tag. It uses the connection of the surrounding tag to make a query to a database and stores the result in a scripting variable named by the id attribute that represents a JDBC ResultSet.

<sql:results>
The <results> tag iterates through a JDBC ResultSet named by the tag attribute fromQuery. This should correspond to a ResultSet from a surrounding <query> tag.

The tags make efficient use of nested tag bodies to clarify when to close JDBC resources. When the closing </connection> tag is reached, the connection is closed, returning the resource to the connection pool. When the </query> tag is reached, the JDBC ResultSet is closed.

The tag handlers for this example are implemented by the Java classes located under the WEB-INF/classes directory of the examplesWebApp, under the package name examples.jsp.tagext.sql. Each new tag is declared in the sqltags.tld Tag Library Descriptor file, also located in the WEB-INF directory of the examplesWebApp.

Using the findAncestorWithClass() Method

The <query> tag uses the inherited findAncestorWithClass() method of the TagSupport class to search for a surrounding scope tag handler of the <connection> tag (ConnectionTag). This allows us to implicitly infer which JDBC connection the SQL query should use. The following code searches for the surrounding <connection> tag class:
      try {
        ConnectionTag connTag = (ConnectionTag)
             findAncestorWithClass(this, 
                     Class.forName("examples.jsp.tagext.sql.ConnectionTag"));
        if (connTag != null) {
          conn = connTag.getConnection();
        }
      } catch(ClassNotFoundException cnfe) {
        throw new JspException("Query tag connection attribute not set "+
                               "AND not nested within connection tag");
      }

Naming Scripting Variables with "id"

A JSP page might want to make multiple queries on the same page and combine the results, so we have used the id attribute to demonstrate how a tag can define a dynamically-named scripting variable. The same approach might be used for the <connection> tag, where multiple connections to different resources that are created by different <sql:connection> tags could be combined at the same scope. We omitted the use named scripting variables in the <sql:connection> tag for simplicity, and to show that you can use the findAncestorWithClass() method as an alternative.

Every TagSupport class implicitly has an instance variable called id and a setTagId() method that is invoked to initialize the id attribute value. This works in much the same way as regular tag attributes, except that the id attribute is implicitly supported. The setTagId() method does not follow the same JavaBean naming convention, but is invoked since it is a special case.

The id attribute can be used to dynamically name a new scripting variable, since it is passed to the ExtraTagInfo class method getVariableInfo() method in the TagData parameter. Any tag attribute can be used to name a scripting variable since all of the tag attributes are available through the TagData.getAttributes() method. The id attribute is more convenient since its value can be retrieved via the TagData.getId() method. The following code declares the new scripting variable in the QueryExtraInfo Java class:

  public VariableInfo[] getVariableInfo(TagData data) {
    return new VariableInfo[] {
        // We assign the name given by the 'id' attribute to this variable name
        new VariableInfo(data.getId(), 
                         "java.sql.ResultSet",
                         true,
                         VariableInfo.NESTED) };
  }
Here, the getId() method is called to declare the name of the scripting variable dynamically.

In the doStartTag() method of the QueryTag class, the ResultSet from the JDBC query is assigned to the scripting variable named by the id attribute:

  pageContext.setAttribute(id, results);

Later in the tag handler for the <sql:results> tag (ResultsTag), we access the ResultSet scripting variable named by the fromQuery attribute. The name of the scripting variable is first initialized via the setFromQuery() method, which is invoked by the JSP engine. In the doStartTag(), we retrieve the named scripting variable from the page context with the following code:

  results = (ResultSet)pageContext.getAttribute(rName);
where rName is the instance variable where we stored the string value of the fromQuery attribute.

Note that tag attributes can only hold String values, but these String values can be used to look up named scripting variables. Scripting variables can be of any Java type, where you define the full package name of the type in the ExtraTagInfo class where they are declared.

Using request-time attribute values

The JSP page uses a scriptlet variable to specify the JDBC query made by the <sql:query> tag. To enable this property in the tag, we must declare the attribute as capable of using a request-time value in the tag library descriptor, shown here in bold:

  <attribute>
    <name>sql</name>
    <required>true</required>
    <rtexprvalue>true</rtexprvalue>
  </attribute>
In the JSP page, the request-time value must be a quoted JSP expression.

Instructions for Package examples.jsp.tagext.sql

Build the Example

  1. Open a new command shell.

  2. Set up this development shell as described in Setting up Your Environment for Building and Running the Examples.

  3. In this development shell, switch to the samples/examples/jsp/tagext/sql directory of your WebLogic Server distribution.

  4. Compile the Java classes used in this example using the following command line:
      $ javac -d %EX_WEBAPP_CLASSES% *.java

  5. In your WebLogic Server installation, copy
    samples/examples/jsp/tagext/sql/query.jsp
    to
    config/examples/applications/examplesWebApp/query.jsp

  6. In your WebLogic Server installation, copy
    samples/examples/jsp/tagext/sql/sqltags.tld
    to
    config/examples/applications/examplesWebApp/WEB-INF/sqltags.tld

  7. Start WebLogic Server with the examples configuration.

Configure the Server

  1. Make sure that the examplesWebApp is deployed on your server.

  2. Make sure that the connection pool "demoPool" is deployed on the "myserver" target in the WebLogic Server Administration Console.

Run the Example

Use a web browser to load the following URL:
http://localhost:7001/examplesWebApp/query.jsp

There's More...

For more information on WebLogic JSP see Programming WebLogic JSP.

For more information on WebLogic JSP Tag Libraries see Programming WebLogic JSP Tag Libraries.

Copyright © 2000 BEA Systems, Inc. All rights reserved.



Documentation is available at
http://e-docs.bea.com/wls/docs60

Copyright © 2000 BEA Systems, Inc. All Rights Reserved.