Application Developer's Guide
For more information about EJB clients, see EJB Development.
INITIAL_CONTEXT_FACTORYshould be set to
PROVIDER_URLshould reflect the location (URI) of the application server hosting the Liquid Data Server (for example,
A local client, i.e. a client that resides on the application server that hosts the Liquid Data Server, may bypass these steps by using the settings in the default context obtained by invoking the empty initial context constructor (i.e. by calling
At this stage, the client may also optionally authenticate itself by passing its security context to the corresponding JNDI environment properties
SECURITY_CREDENTIALS. Alternatively, the client may use the query execution API as an anonymous (default) user.
Once the JNDI context is set up, the client may use the JNDI names of the remote home interfaces of the stateless query execution session bean in order to perform a lookup and obtain remote references to the EJBHome objects.
The JNDI name for the remote interface of the query execution SSB is
com.bea.ldi.server.QueryHome. The home interface may finally be used to obtain references to the
EJBObject object (
com.bea.ldi.server.Query) of the session bean.
Parameterized queries need to be configured before they are executed. Parameterized queries require the client to specify the values of the query parameters. Query parameters allow for dynamic binding of parts of an XQuery query to values specified at runtime. The presence of a parameter in an XQuery query is manifested through the use of the following notation:
pname is a unique name across the query assigned to the parameter. In general, parameters may be used in those places inside a query where a constant could be used. For a list of valid parameter types, see Parameterized Queries.
The value of a parameter can be overwritten and reused in a new query execution by setting it to a new value. Using anything other than a String for a parameter name, or setting a parameter value of an invalid type, results in a
Once the reference to the
EJBObject of the query execution session bean has been obtained and the query has been configured by setting any query parameters or attributes, the query is ready to be executed.
As an example, assuming that the client has obtained a reference to a
Query object, as shown in the following code listing, and the String variable
queryString has been loaded with the contents of an ad hoc XQuery query, the following excerpt shows how to obtain the query result.
If the query is parameterized, once the query parameters have been set, they should be passed in the execution call, that is, the
execute(queryString) call should be replaced with the calls
execute(queryString, qp) and
executeStored(queryName, qp) in the case of ad hoc and stored queries respectively. The
qp in the previous calls is assumed to be loaded with the query parameters.
Note that all execution calls are remote and therefore they may throw a
RemoteException, which should be handled by the client. Note also, that once the query result has been retrieved, the client may release resources by removing the
EJBObject. If the query is parameterized, the client may use the
Query reference to execute the same query multiple times, possibly setting different values for the query parameters each time, before removing the
EJBObject. In any case, other server-side resources related to query execution (for example, database cursors) are automatically released once a query has been executed.
Further processing of the query result at the client side may take various forms ranging from merely extracting, or printing out the XML string to using the DOM representation of the result in order to drill into specific subsets of it.
The result is fully materialized on the server in the form of an unformatted XML string, which is transmitted to the client. The client may then extract the XML content of the query result as a String using
toXML() method. Alternatively, the client may use the
getDocument() call in order to obtain the DOM representation of the result, provided that a JAXP-compliant parser is available in the client environment. In either case, the client is free to process the result using any XML processor (for example, using an XSLT processor to convert the result to a presentable format like HTML).