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 WebLogic^TM Query API. It contains the following sections:

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.

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 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.

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.

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.

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

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

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.

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.

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:

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.

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.

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.

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.

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.

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.