Skip navigation.
Downloads | Product Documentation | Support

Building Queries and Data Views

#

# Using Complex Parameter Types in Queries

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:

- Understanding Complex Parameter Types
- Creating a Complex Parameter Type
- Complex Parameter Type Query Samples

# Understanding Complex Parameter Types

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:

- An XML schema that models the type of the user-defined variable as a CPT.
- A complex parameter type definition that you configure through the Liquid Data node of the WebLogic Administration Console (see "Configuring Access to Complex Parameter Types" in the Liquid Data Administration Guide).
- A runtime source that provides XML data conforming to the XML schema mentioned above.

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:

- Setting Complex Parameter Types and Invoking Queries in EJB Clients in the Application Developer's Guide.
- Liquid Data 8.1 API Reference (Javadoc).

There is also a Liquid Data EJB API sample in the directory:

>     <WL_HOME>/samples/<liquiddata>/ejbAPI

## A CPT Use Case

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.

Use Case

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:

- products database
- sales discount schedule (from sales management software)
- a partner commission structure (from a spreadsheet maintained by the regional sales organization)

However, some data only becomes available when the order is received including:

- customer identification
- item
- quantity
- salesperson

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.

## Understanding CPT Schema and Data

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

### Sample CPT Schema

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"

Declares a namespace `cocpt` associated with the URI.

>     xmlns:xsd="http://www.w3.org/2001/XMLSchema"

Declares a namespace `xsd` to the standard XML schema URI.

>     <xsd:element name="CustOrder">

Declares `CustOrder` as the schema root element.

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.

### Sample XML Data Stream

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"

Defines urn:schemas-bea-com:ld-cocpt as the namespace aliased to `cocpt` and `CustOrder` as the complex data type:

>     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

Declares the standard XML schema instance URI.

>     xsi:schemaLocation="urn:schemas-bea-com:ld-cocpt coCptSample2.xsd"

Identifies the schema location to resolve the name space declaration. Note that Liquid Data automatically looks in the repository `schema` directory for the specified file. Otherwise a full path name to `coCptSample2.xsd` is needed.

## Notes on Hand-Crafting CPT XQueries

There are two issues to remember when hand crafting an XQuery that accesses a Complex Parameter Type:

- Unique Namespace
- XQuery of type element Declaration

### Unique Namespace

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.

### XQuery of type element Declaration

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.

# Creating a Complex Parameter Type

This section describes the steps needed to create and run a complex parameter type.

Step 1. Create a CPT Schema

Step 2. Create Your Runtime Source

Step 3. Define Your CPT in the Administration Console

Step 4. Build Your Query

Step 5. Run Your Query

### Step 1. Create a CPT Schema

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.

### Step 2. Create Your Runtime Source

Create an instance of your runtime source. The runtime source needs to be in XML.

### Step 3. Define Your CPT in the Administration Console

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.

### Step 4. Build Your Query

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.

### Step 5. Run Your Query

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 th`e` 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

# Complex Parameter Type Query Samples

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:

- <WL_HOME>/samples/<liquiddata>/buildQuery/db-cpt
- <WL_HOME>/samples/<liquiddata>/buildQuery/db-cptco

Also see the Liquid Data Samples page for information on other available query samples.