Invoking Queries in JSP Clients

This topic describes how to invoke BEA Liquid Data for WebLogic^TM queries in JSP client applications using the Liquid Data tag library. It contains the following sections:

• About the Liquid Data Tag Library

• Processing Steps

For more information about JSP clients, see JSP Clients.

Note: The following discussion assumes that you are familiar with the use of custom tag libraries. For more information, see Programming WebLogic JSP Tag Extensions in the WebLogic Server documentation.

 

---

About the Liquid Data Tag Library

This topic introduces the Liquid Data tag library. It contains the following sections:

• Scope of the Liquid Data Tag Library

• Location of the Liquid Data Tag Library

• Tags in the Liquid Data Tag Library

Scope of the Liquid Data Tag Library

The goal of the Liquid Data tag library is to provide simple declarative means for JSP clients to obtain access to the XML results of XQuery queries. Tag library clients need only be concerned with the configuration of parameterized queries. The following section provides detailed information on how to set up query parameters in this case.

Location of the Liquid Data Tag Library

The Java classes and other file resources required by tag library clients are packaged inside LDS-client.jar, LDS-em-client.jar, and LDS-taglib.jar. The tag library descriptor file (taglib.tld) defines the elements and attributes in the Liquid Data tag library. The taglib.tld is stored under META-INF inside the LDS-taglib.jar file.

Tags in the Liquid Data Tag Library

The Liquid Data tag library contains the following tags:

• query Tag

• param Tag

query Tag

The query tag specifies the query to execute and the host machine on which to run the query. The query tag has the following attributes.

Table 3-1 Attributes of the query tag  

Attribute	Description
name	Specifies the name of a stored query from which to retrieve results.
server	Specifies the host machine on which the Liquid Data Server is running. Use only when JSP clients are deployed on different machine from the one hosting the Liquid Data Server.

The following example specifies the stored query on the specified host machine.

<lds:query name="MyStoredQuery" server="t3://222.222.22:7001">

param Tag

The param tag specifies a query parameter as a name-value pair. For each parameter, you specify a separate param tag. The param tag has the following attributes.

Table 3-2 Attributes of the param tag  

Attribute	Description
name	Name of the query parameter.
value	Value of the query parameter.

The following example specifies the name of a publisher in the param tag.

<lds:param name="publisher" value="<%=\"Morgan Kaufmann Publishers\"%>"/>

 

---

Processing Steps

This section describes the process of executing queries from JSP clients. It contains the following steps:

• Step 1: Reference the Liquid Data Tag Library

• Step 2: Connect to the Liquid Data Server

• Step 3: Specify Query Parameters

• Step 4: Execute the Query

• Step 5: Process the Query Results

Step 1: Reference the Liquid Data Tag Library

To use the tags in the Liquid Data tag library, you must reference them in each JSP page. To reference the JSP tags described in Tags in the Liquid Data Tag Library, including the following code near the top of each JSP page:

<%@ taglib uri="LDSTLD" prefix="lds" %>

Note: The default prefix (lds:) is configurable.

Step 2: Connect to the Liquid Data Server

Tag library clients are JSP clients. JSP clients that are deployed on the same application server that hosts Liquid Data Server do not need to take any steps in order to connect to Liquid Data Server, as this case is supported by default.

JSP clients deployed on a server other than the one hosting Liquid Data Server need to specify the location (URL) of the server hosting Liquid Data Server using the server attribute of the query tag, as shown in the following example.

Listing 3-1 Non-Local JSP Client Connecting to Liquid Data Server

<%@ taglib uri="LDSTLD" prefix="lds" %>

...	

<lds:query ... server="t3://222.222.22:7001">

...

</lds:query>

Step 3: Specify Query Parameters

In the Liquid Data tag library, the query tag accepts a nested param tag, which may be used to specify the name and the value of a parameter applied to the XQuery query represented by the query tag. The following excerpt illustrates how to set the parameter for the query shown in Listing  3-3.

Listing 3-2 Setting the Query Parameters

<%@ taglib uri="LDSTLD" prefix="lds" %>

...

<lds:query ... server="t3://222.222.22:7001">

...

      <lds:param name="publisher" 

            value="<%=\"Morgan Kaufmann Publishers\"%>"/>

</lds:query>

The value of the parameter is a JSP expression that is evaluated at run time. Quotes are escaped out. The supported parameter types are the same as those supported for EJB clients. The actual type of the parameter is implied by the Java type of the value specified as the content of the value attribute. So, for example, a value Date.valueOf("2002-03-01") would correspond to a parameter of type java.sql.Date. A query that uses multiple parameters would require the use of as many param elements.

Step 4: Execute the Query

The Liquid Data Server Tag Library supports both ad hoc and stored queries.

Executing Stored Queries

Stored queries are specified by having their name being passed as the value of the name attribute of the query tag, as shown in the following example of a parameterized, stored query.

Listing 3-3 Sample Stored Query

<%@ taglib uri="LDSTLD" prefix="lds" %>

...	

<lds:query name="MyStoredQuery" server="t3://222.222.22:7001">

      <lds:param name="publisher" 

            value="<%=\"Morgan Kaufmann Publishers\"%>"/>

</lds:query>

Executing Ad Hoc Queries

Ad hoc queries should have their content directly embedded inside the query element, as shown in the following example.

Listing 3-4 Sample Ad Hoc Query

<%@ taglib uri="LDSTLD" prefix="lds" %>

...

<lds:query server="t3://222.222.22:7001">

      <lds:param name="publisher" 

            value="<%=\"Morgan Kaufmann Publishers\"%>"/>

      <root>

      { 

      for $b in document("bib")//book,

            $pub in $b/publisher

            where $pub = $#publisher 

            return

                  <result>

                        {$b/title}

                        {$b/author}

                  </result>

            }

      </root>

</lds:query>

Handling Exceptions

Any exception that is thrown during query execution should be handled using standard JSP error handling techniques.

Step 5: Process the Query Results

Query execution results in the unformatted XML content of the query result becoming available to the JSP client for further processing.

A typical post-processing step followed by JSP clients at this point would be to apply an XSL transform to the query result XML content in order to convert it to a presentable format. This can normally be conveniently accomplished by enclosing the query tag with another custom tag that performs the XSL transformation. For example, the following listing uses the x:transform tag described in the JavaServer Pages Standard Tag Library 1.0 Specification, which is published by the Sun Microsystems, Inc. at the following URL:

http://java.sun.com/products/jsp/jstl/index.html

Listing 3-5 Applying an XSL Transform to the Query Result

<%@ taglib uri="LDSTLD" prefix="lds" %>

<%@ taglib uri="X" prefix="x" %>

...

<x:transform  xsltUrl="url-to-xsl-script">

      <lds:query server="t3://222.222.22:7001">

            <lds:param name="publisher" 

                  value="<%=\"Morgan Kaufmann Publishers\"%>"/>

            <root>

                  for $b in document("bib")//book,

                  $pub in $b/publisher

                  where $pub = $#publisher 

                  return

                        <result>

                              {$b/title}

                              {$b/author}

                        </result>

                  }

            </root>

      </lds:query>

</x:transform>