Building Queries and Data Views
You can use complex parameter types (CPTs) to make one or several streaming data sources available for Liquid Data queries. Such content is variously called runtime source, data stream, real-time data, or in-flight XML. As long as an XML schema can model the runtime source, you can use it with Liquid Data queries. Liquid Data complex parameter types enable the on-the-fly aspect of this query.
The following subjects are discussed in this chapter:
A complex parameter type is a user-defined variable that allows modelling of runtime data as a data source for a Liquid Data query. Complex parameter types (CPTs) are defined through an XML schema. In other words, a CPT is a user-defined variable whose signature is expressed in via an XML schema.
In order to use CPTs, you need:
You can use the Data View Builder to develop and test the query that uses CPT. When testing a complex parameter types using the Data View Builder, you must assign an XML file to the CPT variable.
When you are satisfied with your ability to run your query using a runtime data source, the query can be invoked via a EJB API or via a JSP. For details on invoking queries programmatically and the Liquid Data API see:
There is also a Liquid Data EJB API sample in the directory:
<WL_HOME>/samples/<liquiddata>/ejbAPI
Complex parameter types allow you to access information that may not be available from traditional static data sources. For example, an enterprise frequently needs to bring together highly diverse pieces of information to complete a business activity or analysis.
A corporation typically receives large electronically-transmitted orders for customized computer chips from companies and governments all over the world. Orders are transmitted using an agreed-upon XML schema provided by eWorld. When an order is received, a variety of commissions and bonuses become payable.
Some information about the transaction is readily available from existing data sources such as:
However, some data only becomes available when the order is received including:
When an order arrives, Liquid Data uses information from all these data sources, including the runtime order information. As the order is received as an in-flight XML document, a query is run and an XML report generated that calculates costs and commissions, taking into account both the order and cumulative discount and commission schedules for the buyers, middlemen, and sales people involved in the transaction.
This section describes elements of a sample CPT schema and its XML instance. It uses the DB-CPTCO sample installed with Liquid Data when describing a CPT schema and XML data source. The sample is installed in the following directory:
<WL_HOME>/samples/<liquiddata>/buildQuery/db-cptco
The project file is coCPTSample
.
The CPT schema shown in Listing 9-1 (coCptSample2.xsd
) is from the DB-CPTCO sample. It is located in the Liquid Data repository schemas
directory.
<WL_HOME>/samples/domains/<liquiddata>/ldrepository/schemas
This simple example defines a complex variable type containing four data elements: customer_id
, product_name
, quantity
, and price
. The complex type you design will vary depending on the signature of your runtime source.
Listing 9-1 DB-CPTCO Sample CPT Schema (coCptSample2.xsd
)
<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema targetNamespace="urn:schemas-bea-com:ld-cocpt"
xmlns:cocpt="urn:schemas-bea-com:ld-cocpt"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<xsd:element name="CustOrder">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="CUSTOMER_ORDER" minOccurs="0" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="CUSTOMER_ID" type="xsd:string"/>
<xsd:element name=
"NEW_ORDER_LINE_ITEM"type="cocpt:NEW_ORDER_LINE_ITEMType"
minOccurs="0" maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:complexType name="NEW_ORDER_LINE_ITEMType">
<xsd:sequence>
<xsd:element name="PRODUCT_NAME" type="xsd:string"/>
<xsd:element name="QUANTITY" type="xsd:decimal"/>
<xsd:element name="PRICE" type="xsd:decimal"/>
</xsd:sequence>
</xsd:complexType>
</xsd:schema>
Components of the sample schema shown in Listing 9-1 include:
xmlns:cocpt="urn:schemas-bea-com:ld-cocpt"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
<xsd:element name="CustOrder">
It is the unique combination of namespace and schema root element that defines the portion of a schema used as a complex parameter type.
Note: Only one instance of a CPT (that is, a unique combination of namespace and schema root element) can be available in the Data View Builder. If you try and duplicate a CPT under another alias name, a red mark will appear over the duplicate CPT name to indicate that it is unavailable.
When you are first developing your query, you will likely want to create a sample XML data file to test your query with an EJB client such as the data in the Data View Builder. In the following listing from the DB-CPTCO sample XML data stream, note that the namespace must match that in the DB-CPTCO sample schema.
Listing 9-2 DB-CPTCO Sample XML Data Stream (coCptSample2.xml)
<?xml version="1.0" encoding="UTF-8"?>
<cocpt:CustOrder xmlns:cocpt="urn:schemas-bea-com:ld-cocpt"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:schemas-bea-com:ld-cocpt
coCptSample2.xsd">
<CUSTOMER_ORDER>
<CUSTOMER_ID>CUSTOMER_1</CUSTOMER_ID>
<NEW_ORDER_LINE_ITEM>
<PRODUCT_NAME>RBBC01</PRODUCT_NAME>
<QUANTITY>1000</QUANTITY>
<PRICE>20</PRICE>
</NEW_ORDER_LINE_ITEM>
<NEW_ORDER_LINE_ITEM>
<PRODUCT_NAME>CS2610</PRODUCT_NAME>
<QUANTITY>1000</QUANTITY>
<PRICE>20</PRICE>
</NEW_ORDER_LINE_ITEM>
</CUSTOMER_ORDER>
</cocpt:CustOrder>
The DB-CPTCO sample XML file is located in the Liquid Data repository xml_files
directory.
<WL_HOME>/samples/domains/<liquiddata>/ldrepository/schemas
Components in the sample XML data stream shown in Listing 9-2 include:
cocpt:CustOrder xmlns:cocpt="urn:schemas-bea-com:ld-cocpt"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:schemas-bea-com:ld-cocpt coCptSample2.xsd"
There are two issues to remember when hand crafting an XQuery that accesses a Complex Parameter Type:
The namespace of your Complex Parameter Type must be unique. It is a good design pattern to have a namespace defined in your schema file and specified when you define your Complex Parameter Type to Liquid Data. If a namespace is specified in the Complex Parameter Type definition, all XQueries that access the Complex Parameter Type must specify the namespace. Regardless of whether you use namespaces, uniqueness is required.
When you use a Complex Parameter Type in a query, you need to specify a query parameter with the following declaration.
type element [<namespace>:]<root element>
The namespace is optional, but the specified root element must be unique. For example, consider the following query:
namespace cocpt = "urn:schemas-bea-com:ld-cocpt"
<cocpt:CustOrder>
{
for $CO_CPTSAMPLE.CUSTOMER_ORDER_2 in
($#QParamForCO-CPTSAMPLE of type element cocpt:CustOrder)
/CUSTOMER_ORDER
return
<CUSTOMER_ORDER>
<CUSTOMER_ID>
{xf:data($CO_CPTSAMPLE.CUSTOMER_ORDER_2/CUSTOMER_ID) }
</CUSTOMER_ID>
</CUSTOMER_ORDER>
}
</cocpt:CustOrder>
The alias cocpt
is used in the namespace declaration of this query, and the bold section (which uses the cocpt
alias) defines the XML input stream for the Complex Parameter Type.
This section describes the steps needed to create and run a complex parameter type.
Step 2. Create Your Runtime Source
Step 3. Define Your CPT in the Administration Console
Create a schema that models the runtime source. See the Sample CPT Schema for a small schema example.
Note: In some design situations you may first create a CPT schema and then develop a model for the runtime source. The important point is that there is a tightly coupled relationship between the schema and the runtime data that it models. Both must work together and, once working, the structure of the documents cannot be changed independently.
Create an instance of your runtime source. The runtime source needs to be in XML.
Through the Liquid Data node of the WebLogic Administration Console, define a complex parameter type. for a detailed procedure, see Configuring Access to Complex Parameter Types in the Administration Guide.
Figure 9-1 Creating a Complex Parameter Type in the Administration Console
A valid CPT definition includes an alias identifier and a schema. It is also a good programming practice to provide both a namespace URI and a schema root element name to uniquely identify your CPT.
Create your query either using the Data View Builder or by hand. See Key Concepts of Query Building for information on designing queries in Liquid Data.
Once you have created a CPT schema, have a data sample available, and have defined the CPT in the WebLogic Administration Console, you are ready to use a complex parameter type in a query.
Note: Complex parameter types are not type aware and are always of the type xs:string
in Liquid Data. You need to cast each element appropriately.
The Liquid Data DB-CPT sample cptSample.qpr
uses a CPT to supply a promotion plan name for a given state. The sample is installed in the following directory:
<WL_HOME>/samples/<liquiddata>/buildQuery/db-cptco
When the query runs details of one or more matching promotion plans names are retrieved from a database.
Figure 9-2 shows the DB-CPT project. Notice that there are two complex parameter types available for use. CPTSAMPLE
is the
complex parameter type used in the query.
Figure 9-2 DB-CPT Project (CPTSAMPLE.QPR) with Complex Parameter Types Displayed
To test your query the name of an XML data file that is modeled on the CPT schema must be entered in the Data View Builder (see Figure 9-3). To locate the Liquid Data sample XML file click on the Value field to open the Liquid Data file browser to the following directory:
<WL_HOME>/samples/domains/<liquiddata>/ldrepository/xml_files
Figure 9-3 DB-CPT Project in Test Mode
Figure 9-4 shows the DB-CPT (CPTSAMPLE.QPR
) project when the query is run.
Figure 9-4 DB-CPT Project (CPTSAMPLE.QPR) in Run Mode
For a step by step example of building a query with a CPT, see Example 6: Complex Parameter Type (CPT) in Liquid Data by Example.
There are also two CPT query samples installed with the Liquid Data samples. These samples show how to create a complex parameter type, configure it as a complex parameter type, and then run the query.
Instructions for running the samples can be found under Complex Parameter Type (CPT) Sample Queries in Liquid Data by Example. The examples can be found under:
Also see the Liquid Data Samples page for information on other available query samples.