bea.com | products | dev2dev | support | askBEA
 Download Docs   Site Map   Glossary 
Search

Getting Started

 Previous Next Contents Index View as PDF  

Getting Started with Liquid Data: A Basic Example

These Getting Started steps walk you through a simple example to illustrate the general process of configuring some data sources and constructing a query. This example shows how to build a query similar to the Order Query used in our BEA Liquid Data for WebLogicTM "Avitek Sample." Following through this process using our example query is an easy and fun way to get familiar with how to configure data sources, construct data views, and run the generated queries in Liquid Data.

Please note that this topic is meant to serve as an example only to familiarize you with the most common tasks of configuration and query building—it is not comprehensive or required. For more advanced query examples, see the Query Cookbook in Building Queries and Data Views and the Samples readme files and project files that are installed with Liquid Data. For details on how to set up and manage Liquid Data and configure data sources, see the Liquid Data Administration Guide. For information on building queries and using the Data View Builder, see Building Queries and Data Views.

The following sections are included here:

 


Step 1. Start the Samples Server

If you have not already done so, start the Liquid Data Samples server.

If you have just installed Liquid Data and this the first time running the Samples server after installation, be sure to first populate the Samples database by choosing the following menu option:

Start—>Programs—>BEA WebLogic Platform 7.0—>Liquid Data for WebLogic 1.0—>Liquid Data Samples—>First-Time Samples Configuration

Wait for the Samples setup to complete. Now you are ready to start the server.

BEA_Home/WL_HOME/liquiddata/samples/config/ld_samples/startWeblogic.sh

Note: For more information on setting up and starting the Samples server, see Post-Installation Tasks in Installing Liquid Data. For more information on starting Liquid Data servers in the various preconfigured domains, see Starting and Stopping the Server in the Liquid Data Administration Guide.

 


Step 2. Start the WLS Administration Console

To start the WLS Administration Console for the Liquid Data Samples server running on your local machine, type the following URL in a Web browser address field:

http://localhost:7001/console/

Login to the console by providing the following default username and password for the Samples server.

Table 1-1 User Name and Password for Samples WLS Administration Console

Field

Defaults

Username

system

Password

security


 

The Console Home Page is displayed.

Figure 1-1 Samples WLS Administration Console


 

Note: For more information on using the Administration Console, see starting the Using the WLS Administration Console in the Liquid Data Administration Guide.

 


Step 3. Configure Order Query Data Sources

This section describes how to configure the two data sources used in the Order Query in the Sample:

Configure a Relational Database Data Source Description for the Wireless Data

Configuring a Relational Database Liquid Data source description consists of first creating a JDBC connection pool and JDBC data source, and then configuring the Liquid Data data source using the JDBC configuration you just created. Each of these tasks is described here:

Note: For detailed information on configuring Relational Database data sources in Liquid Data, see Configuring Access to Relational Databases in the Liquid Data Administration Guide.

Create and Deploy the JDBC Connection Pool

  1. In the left pane, expand the Services node.

  2. Expand the JDBC node.

  3. Click on Connection Pools.

    A table of existing connection pools, if any, is shown.

  4. Click the "Configure a new JDBC connection pool" text link to display the JDBC pool General configuration tab.

    Figure 1-2 JDBC Connection Pool General Configuration Tab


     

  5. On the General tab, provide information about the JDBC connection pool you want to create as described in the following table.


     

  6. Click Create.

    The new JDBC connection pool you created is shown in the table.

  7. In the table of connection pools, click on the name of the new JDBC connection pool you just created.

    The Configuration and Monitoring tabs for that pool are displayed.

  8. Click on the Configuration tab.

  9. Click on the Connections tab and set the Maximum Capacity to 10. (This is an optional step, but we suggest setting the Maximum Capacity on the JDBC connection pool to some number greater than 1.)

  10. Click on the Targets tab.

    The name of your Liquid Data server should be listed under Available Servers.

  11. Select the Liquid Data server in Available and click the right arrow button to move the server into the Chosen list.

  12. Click Apply.

Create and Deploy the JDBC Data Source

  1. In the left pane, expand the Services node.

  2. Expand the JDBC node.

  3. Click on Data Sources.

    A table of existing data sources, if any, is shown.

  4. Click the "Configure a new JDBC Data Source connection pool" text link to display the JDBC data source General configuration tab.

    Figure 1-3 JDBC Data Source General Configuration Tab


     

  5. On the General tab, provide information about the JDBC data source you want to create as described in the following table.


     

  6. Click Create.

    The new JDBC data source you created is shown in the table.

  7. In the table of JDBC data sources, click on the name of the new JDBC data source you just created.

    The Configuration and Monitoring tabs for that JDBC data source are displayed.

  8. Click on the Configuration tab.

  9. Click on the Targets tab.

    The name of your Liquid Data server should be listed under Available Servers.

  10. Select the Liquid Data server in Available and click the right arrow button to move the server into the Chosen list.

  11. Click Apply.

Configure the Relational Database Data Source Description

Now you are ready to add a description of your Relational Database data source to the Liquid Data Server registry. To do this:

  1. In the left pane, click the Liquid Data node.

  2. In the right pane, click the Configuration tab.

  3. Click the Data Sources tab.

  4. Click the Relational Databases tab.

  5. Click the "Configure a new Relational Database source description" text link to display Configure tab.

    Figure 1-4 Liquid Data Relational Databases Configuration Tab on the Liquid Data Node


     

  6. Fill in the fields for your data source as described in the following table. (You need only fill in the fields detailed in the following table—leave other fields blank.)


     

  7. Click Create.

You can click on Relational Databases in the breadcrumbs path at the top of the console to see the relational database you added displayed in the summary table.

Configure an XML File Data Source Description for the BroadBand Data

Configuring an XML File data source description in Liquid Data simply consists of configuring it as a resource using the Liquid Data node in the WLS Administration Console:

  1. In the left pane, click the Liquid Data node.

  2. In the right pane, click the Configuration tab.

  3. Click the Data Sources tab.

  4. Click the XML Files tab.

  5. Click the "Configure a new XML data source description" text link to display Configure tab.

    Figure 1-5 XML Configuration Tab on the Liquid Data Node


     

  6. Fill in the fields for your data source as described in the following table.


     

  7. Click Create.

You can click on XML Files in the breadcrumbs path at the top of the console to see the file you added displayed in the summary table.

Note: For detailed information on configuring XML data sources in Liquid Data, see Configuring Access to XML Files in the Liquid Data Administration Guide.

 


Step 4. Start the Data View Builder and Verify the Data Sources You Configured Show Up in Builder Toolbar

To start the Data View Builder and connect to the Samples server, do the following:

  1. Start the Data View Builder.

  2. Connect to the Samples server.

    1. Enter the following address in the Server URI field on the Login window. (No username or password is required here. Leave those fields blank.)
      t3://localhost:7001

    2. Click the Login button.

    The Data View Builder workspace and tools are displayed. You can click on the buttons on the left Navigation panel to view the various types of data sources configured on the Liquid Data server to which your Data View Builder is connected. In this case, we are connected to the Samples server.

    Figure 1-6 Starting the Data View Builder


     

  3. The data sources you just configured on the Samples server should be available in the Data View Builder. To find them, click the buttons on the left for the appropriate data source types:

 


Step 5. Construct the Query

The Data View Builder allows you to construct queries (or data views) by dragging and dropping elements or nodes in source and target schemas for the data sources with which you are working.

You can drag and drop elements among source schemas and use other tools (such as constants and functions) to express the query statement. This is also referred to as defining source conditions.

You can also drag and drop elements from your source schemas to the target schema to shape and define the structure of the query result. This is also referred to as mapping.

As you work in Design mode with the data elements and attributes in source and target schemas using drag-and-drop actions to join or map elements, Data View Builder is generating the XQuery for the query in the background. You can also use the Data View Builder to run the query and view the results in Test Query mode—as a way of testing queries as you build them.

The query you are about to build here is similar to the Order Query featured in the Liquid Data Avitek Sample. Given a customer with orders stored in two data sources ("Wireless" orders in a relational database and "Broadband" orders in an XML file), this query will return the order information for that customer.

To construct our sample Order Query, you need to do the following:

All of the tasks described in this section are accomplished using the Design tab in the Data View Builder. For more information on using the tools and features on the Design tab, see the Design tab in Building Queries and Data Views.

View a Demo

Constructing the "Order Query" Demo... If you are looking at this documentation online, you can click the "Demo" button to see a viewlet demo showing how to build the conditions and create the mappings described in this example. This demo previews the steps described in detail in the following sections.


Open the Data Source Schemas You Need

To open the data sources you need to construct the data view, simply navigate to them on the Builder Toolbar—>Sources tab and double-click on them:

  1. Click the Design tab.

  2. On the Builder Toolbar, click the Sources tab (on the bottom of the left vertical panel).

  3. Open the data source schemas from the Builder toolbar as follows:

    The XML schemas for the each of the data sources are displayed.

Note: You can open multiple data source schemas and move them around on the workspace as needed.

Add a Target Schema from the Server Repository

The target schema we will use for the Order Query is in a file called customerOrderReport.xsd which is available in the Samples server repository.

To add the target schema:

  1. Choose the menu command File—>Set Target Schema.

    This brings up a file browser. Use the file browser to navigate into the server Repository, which includes several schemas available for use.

  2. Choose customerOrderReport.xsd and click Open.

    customerOrderReport.xsd is displayed as the target schema.

Note: You can open only one target schema at a time and it is always docked to the right side of the workspace.

At this point, your Data View Builder workspace contains two data source schemas and a target schemas you plan to work with as shown in the following figure.

Figure 1-7 Data View Builder with Source and Target Schemas


 

Project the Output by Mapping Source to Target Schema

Note: To expand the XML element trees in source and target schemas select the top element, right mouse-click to get the pop-up menu, and choose Expand.

  1. The Order Query target schema includes a CUSTOMER_ORDER format for both Wireless and Broadband. So, we'll start by mapping the CUSTOMER_ORDER elements shown in each data source to the corresponding CUSTOMER_ORDER elements in the target schema as follows:

    In both cases, the sub-elements to map are ORDER_DATE, ORDER_ID, CUSTOMER_ID, SHIP_METHOD and TOTAL_ORDER_AMOUNT.

Note: As you drag and drop elements from source to target, the Mappings tab is automatically displayed in the lower part of the workspace. The mapped elements are highlighted in the schema windows and each mapping is recorded on the Mappings tab showing Source and Target details. If you need to delete a mapping, select it on the Mappings tab by clicking in the Mapping ID field to highlight the row in which the Source/Target mapping is shown and then click the Trashcan icon.

  1. For this example, we use the Wireless data source schema to format the CUSTOMER element in the target schema. So we need to map the CUSTOMER elements shown in the Wireless data source to the CUSTOMER elements in the target.

    To do this, drag and drop the sub-elements contained in the Wireless data source CUSTOMER* into the corresponding sub-elements in the target schema CUSTOMER.

    Note: Note that you do not necessarily need to have a target for every source element. In our example, we create source-to-target mappings for every node that exists in our target CUSTOMER schema.

    Figure 1-10 Mapping Wireless CUSTOMER to Target Schema CUSTOMER


     

    At this point, you have completed the source to target mappings and the target schema is ready.

    The source-to-target mappings you created are shown on the Mappings tab.

    Figure 1-11 Source-to-Target Mappings


     

Define the Source Conditions

The final step in constructing the data view for our example query is to define some source conditions. This is the way in which you actually pose the "question" (query) or filter designed to get at the data in a particular way. In this example, we want to find out which customers (whose customer IDs match a given constant) have orders in both BroadBand and Wireless.

Create a Join Between the CUSTOMER_IDs in CUSTOMER and CUSTOMER_ORDER within Wireless

In the Wireless data source, drag and drop the sub-element CUSTOMER_ID (from CUSTOMER) to CUSTOMER_ID (subelement in CUSTOMER_ORDER) within the same data source schema window.

This creates a join between CUSTOMER and CUSTOMER_ORDER. The syntax of this join is displayed on the first row on Conditions tab:

Note: As you drag and drop elements from source element to source element, the Conditions tab is automatically displayed in the lower part of the workspace. The mapped elements are highlighted in the schema windows and each source condition is recorded on the Conditions tab. If you need to delete a condition, select it on the Conditions tab by clicking in the Condition ID field to highlight the row in which the condition is shown and then click the Trashcan icon.

Create a Join between Wireless CUSTOMER_ID and Broadband CUSTOMER_ID

Drag and drop the Wireless element CUSTOMER/CUSTOMER_ID onto the Broadband data source element CUSTOMER/CUSTOMER_ID.

The syntax of this Join is displayed on the next row on the Conditions tab.

Note: If you ran the query at this point, you would get a query result showing all customers who have orders in both BroadBand and Wireless. In the next step, however, we refine the query a little further.

Use a Function to Retrieve a Customer ID Matching a Given Constant

You can use a function to create filter that matches a given customer.

  1. If the Conditions tab is not already selected in the lower panel, click the Conditions tab.

  2. On the Builder Toolbar (left navigation panel) click the Toolbox tab, then click Functions.

  3. In the Functions panel, expand the Operators list and find the Equals function (eq).

  4. Drag and drop the eq function from the Builder Toolbar into the first empty row in under Conditions on the lower part of the workspace.

    If you have been following along this will be the third row since it's the third source condition you are setting.

    This causes the Functions Editor to open automatically. By dragging the eq function into the conditions you get a "placeholder" equation in the Functions Editor in the form of:

     (anyValue1 - xset:anyValue eq anyValue2- xset:anyValue)

  5. Drag the Wireless CUSTOMER_ID (a sub-element of CUSTOMER) into the left side of the equation (onto the first placeholder, "anyValue1 - xset:anyValue").

  6. On the left navigation panel, click Constants.

  7. In the Constants String field, type CUSTOMER_1. Drag and drop the constants icon (to the right of the field) into the right side of the equation (onto the remaining placeholder, "anyValue2- xset:anyValue" ).

    Figure 1-12 Using a String Constant in a Function


     

Note: Make sure that you have the left navigation panel expanded out far enough to the right to be able to see the arrow icons to the left of the Constants fields.

The syntax of this statement is displayed in the Functions Editor.

Figure 1-13 Equation for a Source Condition Shown in Functions Editor


 

You can close the Functions Editor by clicking the Close button on it.

You have set up all the source conditions. They are reflected on the Conditions tab.

Note: To see the full text of the source conditions statements, you may have to expand the Conditions area by clicking and dragging the left or right borders.

Figure 1-14 Source Conditions


 

 


Step 6. View and Test the Query

Switch to Test View

Now you are ready to switch to the Test tab where you can look at the XQuery syntax of the generated query you just constructed, and then run the query to test it.

Click the Test tab at the top of the workspace.

The Test tab is displayed as shown in the following figure.

Figure 1-15 Test Tab


 

Understanding the Generated XQuery

The Data View Builder generates the following XQuery for the query you constructed with drag-and-drop tools.

Listing 1-1 Generated XQuery for Getting Started Query

{--	Generated by Data View Builder 1.0	--}
<CustomerOrderReport>
{
for $MyWireless_LD_DS.CUSTOMER_1 in document("MyWireless-LD-DS")/db/CUSTOMER
where ($MyWireless_LD_DS.CUSTOMER_1/CUSTOMER_ID eq "CUSTOMER_1")
return
<customerOrder>
<CUSTOMER>
<FIRST_NAME>{ xf:data($MyWireless_LD_DS.CUSTOMER_1/FIRST_NAME) }</FIRST_NAME>
<LAST_NAME>{ xf:data($MyWireless_LD_DS.CUSTOMER_1/LAST_NAME) }</LAST_NAME>
<CUSTOMER_ID>{ xf:data($MyWireless_LD_DS.CUSTOMER_1/CUSTOMER_ID) }</CUSTOMER_ID>
<STATE>{ xf:data($MyWireless_LD_DS.CUSTOMER_1/STATE) }</STATE>
<EMAIL_ADDRESS>{ xf:data($MyWireless_LD_DS.CUSTOMER_1/EMAIL_ADDRESS) }</EMAIL_ADDRESS>
<TELEPHONE_NUMBER>{ cast as xs:long(xf:data($MyWireless_LD_DS.CUSTOMER_1/TELEPHONE_NUMBER)) }</TELEPHONE_NUMBER>
</CUSTOMER>
<wireless_orders>
{
for $MyWireless_LD_DS.CUSTOMER_ORDER_2 in document("MyWireless-LD-DS")/db/CUSTOMER_ORDER
where ($MyWireless_LD_DS.CUSTOMER_1/CUSTOMER_ID eq $MyWireless_LD_DS.CUSTOMER_ORDER_2/CUSTOMER_ID)
return
<CUSTOMER_ORDER>
<ORDER_DATE>{ cast as xs:string(xf:data($MyWireless_LD_DS.CUSTOMER_ORDER_2/ORDER_DATE)) }</ORDER_DATE>
<ORDER_ID>{ xf:data($MyWireless_LD_DS.CUSTOMER_ORDER_2/ORDER_ID) }</ORDER_ID>

<CUSTOMER_ID>{ xf:data($MyWireless_LD_DS.CUSTOMER_ORDER_2/CUSTOMER_ID) }</CUSTOMER_ID>
<SHIP_METHOD>{ xf:data($MyWireless_LD_DS.CUSTOMER_ORDER_2/SHIP_METHOD) }</SHIP_METHOD>
<TOTAL_ORDER_AMOUNT>{ xf:data($MyWireless_LD_DS.CUSTOMER_ORDER_2/TOTAL_ORDER_AMOUNT) }</TOTAL_ORDER_AMOUNT>
</CUSTOMER_ORDER>
}
</wireless_orders>
<broadband_orders>
{
for $MyBroadBand_LD_DS.CUSTOMER_ORDER_3 in document("MyBroadBand-LD-DS")/db/CUSTOMER_ORDER
where ($MyWireless_LD_DS.CUSTOMER_1/CUSTOMER_ID eq $MyBroadBand_LD_DS.CUSTOMER_ORDER_3/CUSTOMER_ID)
return
<CUSTOMER_ORDER>
<ORDER_DATE>{ xf:data($MyBroadBand_LD_DS.CUSTOMER_ORDER_3/ORDER_DATE) }</ORDER_DATE>
<ORDER_ID>{ xf:data($MyBroadBand_LD_DS.CUSTOMER_ORDER_3/ORDER_ID) }</ORDER_ID>
<CUSTOMER_ID>{ xf:data($MyBroadBand_LD_DS.CUSTOMER_ORDER_3/CUSTOMER_ID) }</CUSTOMER_ID>
<SHIP_METHOD>{ xf:data($MyBroadBand_LD_DS.CUSTOMER_ORDER_3/SHIP_METHOD) }</SHIP_METHOD>
<TOTAL_ORDER_AMOUNT>{ cast as xs:decimal(xf:data($MyBroadBand_LD_DS.CUSTOMER_ORDER_3/TOTAL_ORDER_AMOUNT)) }</TOTAL_ORDER_AMOUNT>
</CUSTOMER_ORDER>
}
</broadband_orders>
</customerOrder>
}
</CustomerOrderReport>

Run the Query

When you are ready to run the query, click the Run query button on the toolbar in the upper left.


 

The Liquid Data server process the query and the query result is displayed as shown in the following figure and code listing.

Figure 1-16 Query Result on Test Tab


 

Listing 1-2 XML for the Query Result

<CustomerOrderReport>
<customerOrder>
<CUSTOMER>
<FIRST_NAME>JOHN_1</FIRST_NAME>
<LAST_NAME>KAY_1</LAST_NAME>
<CUSTOMER_ID>CUSTOMER_1</CUSTOMER_ID>
<STATE>TX</STATE>
<EMAIL_ADDRESS>abc@abc.com</EMAIL_ADDRESS>
<TELEPHONE_NUMBER>4081231234</TELEPHONE_NUMBER>
</CUSTOMER>
<wireless_orders>
<CUSTOMER_ORDER>
<ORDER_DATE>2002-03-06-08:00</ORDER_DATE>
<ORDER_ID>ORDER_ID_1_0</ORDER_ID>
<CUSTOMER_ID>CUSTOMER_1</CUSTOMER_ID>
<SHIP_METHOD>AIR</SHIP_METHOD>
<TOTAL_ORDER_AMOUNT>1000</TOTAL_ORDER_AMOUNT>
</CUSTOMER_ORDER>
<CUSTOMER_ORDER>
<ORDER_DATE>2002-03-06-08:00</ORDER_DATE>
<ORDER_ID>ORDER_ID_1_1</ORDER_ID>
<CUSTOMER_ID>CUSTOMER_1</CUSTOMER_ID>
<SHIP_METHOD>AIR</SHIP_METHOD>
<TOTAL_ORDER_AMOUNT>2000</TOTAL_ORDER_AMOUNT>
</CUSTOMER_ORDER>
</wireless_orders>
<broadband_orders>
<CUSTOMER_ORDER>
<ORDER_DATE>2002-04-09</ORDER_DATE>
<ORDER_ID>ORDER_ID_1_0</ORDER_ID>
<CUSTOMER_ID>CUSTOMER_1</CUSTOMER_ID>
<SHIP_METHOD>AIR</SHIP_METHOD>
<TOTAL_ORDER_AMOUNT>1000.00</TOTAL_ORDER_AMOUNT>
</CUSTOMER_ORDER>
<CUSTOMER_ORDER>
<ORDER_DATE>2002-04-09</ORDER_DATE>
<ORDER_ID>ORDER_ID_1_1</ORDER_ID>
<CUSTOMER_ID>CUSTOMER_1</CUSTOMER_ID>
<SHIP_METHOD>AIR</SHIP_METHOD>
<TOTAL_ORDER_AMOUNT>1500.00</TOTAL_ORDER_AMOUNT>
</CUSTOMER_ORDER>
</broadband_orders>
</customerOrder>
</CustomerOrderReport>

Congratulations! You have successfully built and run a query using Liquid Data.

Note: If you want to switch back to the Design mode again, click the Design View tab on the toolbar.

 


Step 7. Save the Project

We suggest you save the project file at this point if you have not done so already.

To save the project for the first time:

  1. Choose the menu option File—>Save Project. The Save dialog is displayed.

  2. Navigate to the directory in which you want to save your project and enter a name for it in the File Name field.

  3. Click Save.

    The file is saved as a Data View Builder project with a .qpr extension.

Note: Saving the project file is not the same as saving a query. For more information on working with and saving projects, see Working with Projects in the Building Queries and Data Views. For information on saving a query as a stored query, see Saving a Query also in Building Queries and Data Views.

 


Next Steps

The process you just completed with these Getting Started steps is a thin slice of the Liquid Data picture meant to help familiarize you with some of the basics. If you are ready to learn more, try the following topics:

 

Back to Top Previous Next