bea.com | products | dev2dev | support | askBEA

Download Docs | Site Map | Glossary
Search

Invoking Liquid Data Queries Programmatically

About the Liquid Data Query API

This topic describes concepts that you need to understand in order to invoke queries programmatically using the BEA Liquid Data for WebLogicTM Query API. It contains the following sections:

- About Liquid Data Queries

- Components of the Liquid Data Query API

- Types of Java Clients

For reference information about the Liquid Data Query API, see the Liquid Data Javadoc. For an introduction to the XQuery standard, see "Liquid Data Implements the XQuery Standard" in Liquid Data Concepts in the Product Overview.

About Liquid Data Queries

This section describes the following Liquid Data query concepts:

- Stored Queries

- Ad Hoc Queries

- Parameterized Queries

For more information about Liquid Data queries, see "Key Concepts of Query Building" in Overview and Key Concepts in Building Queries and Data Views.

Stored Queries

Stored queries have been predefined by the personnel (typically data architects) of the organization that operates the Liquid Data Server. Stored queries are assigned a unique name starting with an alphabetic character (A-Z a-z) and reside in the Liquid Data server repository. Clients may execute stored queries by merely specifying their name and parameters, if any. For more information about the server repository, see Managing the Liquid Data Repository in the Liquid Data Administration Guide.

Ad Hoc Queries

An ad hoc query is a query that has not been stored in the Liquid Data repository as a stored query but rather is passed to the Liquid Data server on the fly. Ad hoc queries are defined by the client. In effect, clients need to provide the actual content of ad hoc queries to the server at run time.

Parameterized Queries

Although queries may return results that are of general interest, it is often the case that the content of query results, and therefore also the content of the query, needs to be customized in order to better fit the client's needs. This requirement is commonly addressed through the use of parameterized queries, which are queries that allow for substitution of parts of the query with parameters whose value can be provided (and changed) per query execution.

The Liquid Data Server API provides support for parameterized queries using named parameters. When parameterized queries are used, clients need to provide the value and the type of each named parameter in the query.

Components of the Liquid Data Query API

This topic describes the components of the Liquid Data Query API. It contains the following sections:

- Packages

- Query Execution EJB

- Query Parameters

- Query Attributes

- Query Results

For reference information about the Liquid Data Query API, see the Liquid Data Javadoc.

Packages

The Liquid Data API includes the following packages:

Table 1-1 Packages in the Liquid Data Query API

Package Name | Description
--- | ---
com.bea.ldi.server | Defines the Liquid Data query execution EJBs, including their home and remote interfaces.
com.bea.ldi.server.common | Defines interfaces and classes for query parameters, query results, query result exceptions, and attributes for query evaluation.

Query Execution EJB

The com.bea.ldi.server package defines the following stateless session bean:

>     bea.ldi.server.QueryBean

The com.bea.ldi.server package also defines the home and remote interfaces for this EJB. The query execution EJB, along with the Liquid Data Server, can be deployed in a cluster.

Query Parameters

The com.bea.ldi.server.common.QueryParameters class represents parameters that are specified for parameterized queries prior to query execution. In addition to Java primitive types (byte, float, int, long, short, and double) that you can specify using setxxxx() methods, query parameters can be any of the following types:

- java.lang.Boolean

- java.lang.Byte

- java.lang.Double

- java.lang.Float

- java.lang.Integer

- java.lang.Long

- java.lang.Short

- java.lang.String

- java.math.BigDecimal

- java.math.BigInteger

- java.util.Calendar

- java.sql.Date

- java.sql.Time

- java.sql.Timestamp

The QueryParameters class provides methods for setting parameters based on these types as well as a getParameters() method that collects defined query parameters in a java.util.Map object.

Query Attributes

The com.bea.ldi.server.common.QueryAttributes interface provides a variable (LARGE_DATA) that specifies whether the query is expected to produce a large final result set or large intermediate result sets.

Query Results

The com.bea.ldi.server.common.QueryResult interface represents the results of a query. The QueryResult interface provides methods for retrieving the query results, expressed in XML, as a DOM document (org.w3c.dom.Document), determining whether the query result is empty, printing the query results as XML to a specified device, and deallocating local and server resources.

Types of Java Clients

Any authorized Java client can use Java Naming and Directory Interface (JNDI) to obtain references to the EJBs and use them to issue queries against the Liquid Data Server.

Different types of Java clients include:

- Standalone Java applications

- Java servlets

- Java Server Pages (JSPs)

- Java Beans

- Other EJBs

- Business operations in workflows that execute in the Business Process Management (BPM) component of WebLogic Integration

- WebLogic Portal

- Web Services

Both local and remote clients can access the Liquid Data Query API.

EJB Clients

EJB clients are any applications that invoke queries on the Liquid Data Server using the Liquid Data EJB API. All Java clients can leverage the flexibility and the powerful data integration properties offered by XQuery in order to meet their data access needs. All these types of clients access the EJB remote interfaces directly, therefore they can be collectively characterized as EJB clients. For more information about EJB clients, see Invoking Queries in EJB Clients.

Note: A special kind of EJB client is the Data View Builder itself, which may be used by data architects and developers to build and execute queries.

JSP Clients

In addition to the procedural Liquid Data API, JSP clients, in particular, may use the Liquid Data Server tag library, which provides a declarative way to extend their querying and data access capabilities. The Liquid Data Server tag library is typically deployed within the web application that contains the JSP clients. The declarative nature of the tag library makes it simpler for JSP clients to issue stored or ad hoc, fixed or parameterized, queries. These JSP clients form a second family of API clients, collectively characterized as tag library clients. For more information about JSP clients, see Invoking Queries in JSP Clients.