Application Developer's Guide
|
 |
 |
|
|
 |
 |
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:
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.
This section introduces the Liquid Data tag library. It contains the following sections:
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.
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.
In order to use the Liquid Data tag library in a web application, you must do the following:
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
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>
The Liquid Data tag library contains the following tags:
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.
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">
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.
The following example specifies the name of a publisher in the param tag.
<lds:param name="publisher" value="<%=\"Morgan Kaufmann Publishers\"%>"/>
This section describes the process of executing queries from JSP clients. It contains the following steps:
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.
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.
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>
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.
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
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>
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>
Any exception that is thrown during query execution should be handled using standard JSP error handling techniques.
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>
|
|
|