bea.com | products | dev2dev | support | askBEA

Download Docs | Site Map | Glossary
Search

Building Queries and Data Views

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. 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 Administration Console (see Configuring Access to Complex Parameter Types in the 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 in Invoking Liquid Data Queries Programmatically.

- Invoking Queries in EJB Clients in Invoking Liquid Data Queries Programmatically.

- Liquid Data 1.1 API Reference (Javadoc).

There is also a Liquid Data EJB API sample in:

>     BEA_HOME/weblogic700/liquidata/samples/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

eWorldCo 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:

>     BEA_HOME/weblogic700/liquidata/samples/buildQuery/db-cptco

The project file is coCPTSample.

Sample CPT Schema

The CPT schema shown in Listing 7-1 (coCptSample2.xsd) is from the DB-CPTCO sample. It is located in the LDrepository/schemas directory.

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 7-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 7-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: One 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 7-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 LDRepository/xml_files directory.

Components in the sample XML data stream shown in Listing 7-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.

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