Skip navigation.
Downloads | Product Documentation | Support

Application Developer's Guide

# Invoking Queries in JSP Clients

This chapter describes how to invoke BEA Liquid Data for WebLogic 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 Tag Library Development.

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 section 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
- Making the Tag Library Accessible to a Web Application
- 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.

## Making the Tag Library Accessible to a Web Application

In order to use the Liquid Data tag library in a web application, you must do the following:

- Copy the LDS-taglib.jar File to the WEB-INF/lib Directory
- Add the <taglib> Entry to the web.xml File

### Copy the LDS-taglib.jar File to the WEB-INF/lib Directory

Each web application that uses the Liquid Data tag library must have a copy of the `LDS-taglib.jar` file in the application_context`/WEB-INF/lib` directory. The `LDS-taglib.jar` file is installed with Liquid Data as the following file:

>     bea_home/liquiddata/server/lib/LDS-taglib.jar

### Add the <taglib> Entry to the web.xml File

You must add the following entry to the `web.xml` file for each web application that uses the Liquid Data tag library:

>     <taglib>
>         <taglib-uri>LDSTLD</taglib-uri>
>         <taglib-location>/WEB-INF/lib/LDS-taglib.jar</taglib-location>
>     </taglib>

## 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 4-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.
`username` | Specifies the WebLogic user name for the query request. If you do not specify a `username`, the query is sent as the `guest` user.
`password` | Specifies the password for the `username` attribute.

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

>     <lds:query name="MyStoredQuery" server="t3://222.222.22:7001" username="ldsystem" password="ldsecurity">

### 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 4-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: Add the Tag Library to your Web Application
- Step 2: Reference the Liquid Data Tag Library
- Step 3: Connect to the Liquid Data Server
- Step 4: Specify Query Parameters
- Step 5: Execute the Query
- Step 6: Process the Query Results

## Step 1: Add the Tag Library to your Web Application

You must add the `LDS-taglib.jar` file to the `WEB-INF/lib` directory of your web application and must update the `web.xml` file for the web application. For details, see Making the Tag Library Accessible to a Web Application on page 4-2.

## Step 2: 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 3: 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 4-1 Non-Local JSP Client Connecting to Liquid Data Server

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

>     ...

>     <lds:query ... server="t3://222.222.22:7001" username="ldsystem" password="ldsecurity">

>     ...

>     </lds:query>

## Step 4: 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 4-3.

Listing 4-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 5: Execute the Query

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

When executing a query, its fully qualified name must be used. When the physical location of the query is:

>     repository/stored_queries/dir1/dir2/SQ1.xq

The query is qualified as:

>     dir1.dir1.SQ1

For example, if the query is located at:

>     LDrepository/stored_queries/inventory/widgetsales.xq

the query would be qualified as:

>     inventory.widgetsales

### 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 4-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 4-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 6: 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.

Typically, you perform some kind of post-processing to the query results for display purposes. JSP clients can apply an XSL transform to the XML query result in order to convert it to a presentable format. You can perform the transformation 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 4-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>

You can also use the JSP tag library provided with WebLogic server to perform the XSLT transformation. For details on this tag library, see:

>     http://download.oracle.com/docs/cd/E13222_01/wls/docs81/xml/xml_apps.html

The following sample code uses the WebLogic JSP tag library to perform the XSLT transformation.

Listing 4-6 Using the WebLogic Server XSLT JSP Tag Library for an XSL Transform

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

>     <x:xslt media="http">
>       <x:xml>
>         <lds:query name="viewSample" server="t3://localhost:7001"
>               username="ldsystem" password="ldsystem" >
>         </lds:query>
>       </x:xml>
>       <x:stylesheet media="http"  uri="http.xsl"/>
>     </x:xslt>