Skip navigation.
Downloads | Product Documentation | Support

Data Services Developer's Guide

# Liquid Data Projects and Components

BEA Liquid Data for WebLogic® can be added to Workshop in two ways:

- As a new application designed to provide data services
- As a project in an existing application

The basic menus, common behavior, and look-and-feel associated with Workshop all apply to Liquid Data.

Note: Workshop online documentation is available at:

>     http://download.oracle.com/docs/cd/E13226_01/workshop/docs81/index.html

This chapter discusses various Workshop facilities that you will likely use in creating and managing your Liquid Data-based projects. Liquid Data extensions to Workshop are also described from an interface perspective.

The following topics are covered:

- Liquid Data-Enabled BEA WebLogic Projects
- Major Components of a Liquid Data Project

# Liquid Data-Enabled BEA WebLogic Projects

You can create a Workshop application that automatically includes a Liquid Data project. Or you can add Liquid Data projects to any BEA WebLogic application. When an application contains a Liquid Data project it is considered Liquid Data-enabled.

Note: It often makes sense to consolidate Liquid Data queries in a Workshop application dedicated to Liquid Data development. Other applications can then access these queries through the Liquid Data Mediator API or a Liquid Data control. For details see the Liquid Data Client Application Developer's Guide.

### Verifying Your Liquid Data Version Number

To ascertain that Liquid Data is available to your application or to determine the version of Liquid Data that you are using, start your BEA WebLogic Server and access its Administration Console. For example, the Console for the sample domain provided with BEA WebLogic can be accessed from:

>     http://localhost:7001/console

Navigate to the Console —>Versions page (Console being the top menu item) and find the version and creation date for Liquid Data.

## Creating a Liquid Data-enabled Application

To create a Liquid Data-enabled application select File —>New —>Application from the Workshop menu. When the dialog appears, select Liquid Data Application (Figure 2-1).

Figure 2-1 Creating a New Liquid Data Application

You probably will want to change the name of the application from Untitled to something else. Your new application automatically contains an initial Liquid Data project.

Figure 2-2 Application View of a New Liquid Data Application

You can save your application at any time using the File —> Save, Save As, or Save All commands. Save All saves any modified files in your application.

When you initially create a Workshop application such as "myLD", a file called `myLD.work` is created in the root directory of the application. Invoking Workshop with this file also opens your application.

An application can contain any number of Liquid Data or other types of Workshop projects.

## Adding a Liquid Data Project to an Existing BEA WebLogic Application

You can also add one or several Liquid Data projects to any Workshop application.

To do this select File —>New —>Project. When the project creation dialog appears, choose Liquid Data Project.

Figure 2-3 Application Pane of a New Liquid Data Application

# Major Components of a Liquid Data Project

When a new Liquid Data application or project is created, a Liquid Data project folder is also created. This becomes the root directory of your project (see Figure 2-3). Two Java archive (`.jar`) files are added to the application's Libraries folder including `ld-server-app.jar` and the `mediator.jar`, which manages Service Data Objects (SDOs), described in detail in the Client Application Developer's Guide.

Table 2-4 list major Liquid Data file types and their purposes.

Table 2-4 Liquid Data Components, Including File Types

Component | Purpose
--- | ---
Data Services (`.ds`) | Data services are contained in `.ds` files and can be located anywhere in your application. Each data service file is an XQuery document. Note: Since a `.ds` file may contain numerous XQueries as well as other automatically-generated pragma directives, care should be exercised when editing this file directly.
Model Diagrams (`.md`) | Model diagrams provide a graphical representation of the relationships between various data services, which themselves represent the physical and logical data services available to your Liquid Data queries. Model diagrams have the extension `.md` and can be located anywhere in your Liquid Data project.
Metadata information | Metadata information is contained in META-INF folders associated with `.jar` files. The non-editable contents of this Libraries folder contains information on data sources used by data services.
Schemas (`.xsd`) | Data services typically are associated with XML types whose physical representation is an XML schema file. Schema files can be located anywhere in your application. Schemas automatically created by the Metadata Import wizard are placed in a `schemas` directory inside your project. Schema files can be manually created or modified using any text editor as well as though the data service Design View and model diagrams containing the data service. The XML type is repeated for each read function as its return type. The return type precisely describes the shape of the document to be returned by your query. The return type can be modified through the XQuery Editor or directly in source. However, this generally should only be done in conjunction with the Save and Associate Schema command (see Creating a New Data Service and an XQuery Function for additional details).
XFL files (`.xfl`) | XML file libraries can contain utility XQuery functions that can be used in data services and in building data transformations. A typical example would be a routine for converting currencies based on daily exchange rate. Such functions could be used by any data service in your application.

Other files which may appear in Liquid Data projects include Java files containing custom update logic and SDO configuration files such as `sdo.xsdconfig`, which allows XMLBean technology to create SDOs rather than XMLBeans.

## Using the Workshop IDE

Workshop is fully described in on-line and printed documentation. A good place to start is:

>     http://download.oracle.com/docs/cd/E13226_01/workshop/docs81/index.html

Alternatively, Workshop provides complete on-line help.

Figure 2-5 Some WebLogic Workshop Components in a Liquid Data-enabled Project

The following table briefly describes:

- Workshop functionality extensively used by Liquid Data
- Liquid Data extensions to the Workshop user interface

Table 2-6 Summary of Workshop Pane Used by Liquid Data

Service | Purpose
--- | ---
Application pane | Lists the projects and other components in your application.
Files pane | Provides an ordered listing of files used in your application.
Build pane | Provides feedback while the application is being built and reports build success or failure.
Output pane | Shows data sources accessed, execution times, and query statement.
Property Editor | Provides information on properties associated with the currently selected object. Some properties are configurable or editable.

Table 2-7 describes the several Workshop menu commands you will use with Liquid Data projects.

Table 2-7 Summary of Workshop Menu Services Used by Liquid Data

Service | Purpose
--- | ---
File menu | When working with Liquid Data projects you will often use the following File menu options: Save, Save As, Save All. The Save command saves the current file while the Save All command saves all open or modified files in your project. Use the Save All command to make sure that all changes you have made to your application will be persisted. Import commands. Use the Import file browser to add files or libraries to your project. For example, if you have an externally developed schema you can use the Import command and associated file browser to bring a copy of it into your project.

### Property Editor

You can use the Property Editor to view details related to any Liquid Data artifact (see Figure 2-8). For example, in Design View (see Design View) if you click on the general data service, the Property Editor provides details on the entire service. If you click on a relationship represented in a data service, property details on that relationship appear. In many cases, property settings are editable or configurable.

Figure 2-8 Relationship Properties in a Data Service

You can find important properties detailed in conjunction with feature descriptions.

### Finding Text in Files

Workshop provides a comprehensive file search facility with its Find in Files option, available from the Edit menu (Edit —> Find in Files).

Figure 2-9 Workshop File Search Facility

You can use Find in Files to search for references to any Liquid Data artifacts such as particular data sources, use of functions, and so forth.

## Survey of Liquid Data Additions to Workshop

A Liquid Data project adds menu items and views to the basic Workshop environment to support the following functionality:

- Metadata Import
- Data Models
- Data Services

### Metadata Import

Data services are central to creating data models and physical and logical data views that can be used in Liquid Data queries. The first step in creating a data service is to import metadata from physical data sources so that corresponding physical data services can be created.

Figure 2-10 Selecting Metadata Import for a Liquid Data Project

For details related to importing and updating metadata into your Liquid Data project see Obtaining Enterprise Metadata.

### Data Models

It is through the data model interface that you can:

- Establish or modify relationships between data services.
- Edit a data service's return type.
- Create annotations to a model or a data service.

Figure 2-11 Creating a Data Model Diagram From the File Menu

For details on developing and maintaining data models see Modeling Data Services.

### Data Services

Every data service provides a Design View, XQuery Editor View, Source View, Test View, and Query Plan View. Each data service is based around a single XQuery source file. And every data service has an associated XML type.

Data services are composed of read and navigation functions. Read functions must return the XML type of the data service. Navigation functions, return the XML type of their native data service.

Figure 2-12 Sample Data Service

#### Design View

Design View is the central reference point of every data service. It is through Design View that you can:

- Add or modify the XML type.
- Add read functions using the XQuery Editor View.
- Add relationships in the form of navigation functions. These functions are typically developed using the Relationship wizard.

For details on developing and maintaining data services see Using Data Services Design View.

#### XQuery Editor View

It is through the XQuery Editor View that you can develop query functions by projecting data service function elements, as well as transformations, to the function's return type.

Figure 2-13 Sample XQuery Editor Query with Its Return Type

The graphical editor directly supports common constructs of the emerging XQuery standard. Several resources are available to help in the development and maintenance of query business logic. These are all available from the Workshop View or View —>Windows menu).

For details on developing queries using XQuery Editor View see Using Query Editor View.

XQuery Function Palette

An XQuery function palette (Figure 2-14) that supports standard XQuery and BEA-specific functions. This function palette is also available from the Workshop View —>Windows menu.

Figure 2-14 XQuery Function Palette

Like all Workshop panes, the XQuery Function Palette can be placed anywhere in the Workshop window. Functions can be dragged into the XQuery Editor View as well as Source View.

XQuery Constructs Palette

Liquid Data projects also have access to the XQuery Constructs palette (Figure 2-15). This palette supports creation of different types of XQuery statements in the XQuery Editor View or Source View. Many of the construct prototypes such as FLWGR, FGWOR, FWGR, and so forth are variations on the most common XQuery construct, FLWR (for-let-where-return).

Figure 2-15 XQuery Constructs Palette

For example, FLWGR adds the Liquid Data extension Group By. The prototype is shown below in Source View.

>     for $var in ()
>     let $var2:=()
>     where (true)
>     group by () as $var3 with partitions $var as $var4
>     return
>     	 	()

For details on Group By and other Liquid Data XQuery extensions see the XQuery Developer's Guide.

Liquid Data Palette

The Liquid Data palette (Figure 2-16) is only available to Liquid Data projects. It provides the XQuery Editor access to data service and XFL (XQuery function library) routines.

Figure 2-16 Liquid Data Palette

For details on using the XQuery Editor see Using Query Editor View.

#### Editing XML Types and Return Types

A schema editor for modifying XML types in model diagrams and data services, as well as return types in the XQuery Editor, is available. See Working with XML Types.

Right-click menu commands for return types differ slightly from the right-click menu commands available for editing XML types. This is because you can use the XQuery Editor to create if-then-else constructs, zones, and cloned elements as a means of exactly specifying the form your query result document should take. (See Modifying a Return Type.)

Figure 2-17 Editing an XML Type Element

#### Test View

After you have developed a query you can run it using Test View. For details see Testing Query Functions and Viewing Query Plans.

#### Source View

If you are working in Source View you can easily add pre-built XQuery functions and constructs to your source, as well as make other changes to your data service. For additional details see Using Source View.

#### Query Plan View

You can review the query plan developed by Liquid Data for a particular function in order to verify the generated SQL or look for opportunities to improve performance. See Analyzing Queries Using Plan View.

### XQuery Function Library (XFL) Files

In any Liquid Data project you can create XQuery libraries containing functions which can be used by any data service in your application. XQuery function libraries can be created in two ways:

- Using the File —> New Library option
- Automatically, when Java functions returning primitive types are imported as metadata

An XQuery function library is ideal for containing transformation and other types of functions without the overhead of having to build a data service.

An XQuery function library can also be used to hold security functions which, in turn, can be used by any data service.

#### Create An XQuery Function Library

Since an XQuery function library can hold any number of heterogeneous functions, only namespace conflicts need to be resolved before you can make your function generally available.

For example the following function is available in the Credit Card data service provided with the Liquid Data sample application, RTLApp (namespace declarations from a separate section of the source file are included):

>     declare namespace ns1="ld:DataServices/BillingDB/CREDIT_CARD";

>     import schema namespace ns0="urn:retailerType" at "ld:DataServices/RTLServices/schemas/CreditCard.xsd";

>     declare namespace tns="ld:DataServices/RTLServices/CreditCard";

>     (: ... :)

>     declare function tns:getCreditCard() as element(ns0:CREDIT_CARD)* {
>     for $CREDIT_CARD in ns1:CREDIT_CARD()
>     return <ns0:CREDIT_CARD>
>         <CreditCardID>{fn:data($CREDIT_CARD/CC_ID)}</CreditCardID>
>         <CustomerID>{fn:data($CREDIT_CARD/CUSTOMER_ID)}</CustomerID>
>         <CustomerName>{fn:data($CREDIT_CARD/CC_CUSTOMER_NAME)}</CustomerName>
>         <CreditCardType>{fn:data($CREDIT_CARD/CC_TYPE)}</CreditCardType>
>         <CreditCardBrand>{fn:data($CREDIT_CARD/CC_BRAND)}</CreditCardBrand>
>         <CreditCardNumber>{fn:data($CREDIT_CARD/CC_NUMBER)}</CreditCardNumber>
>         <LastDigits>{fn:data($CREDIT_CARD/LAST_DIGITS)}</LastDigits>
>         <ExpirationDate>{fn:data($CREDIT_CARD/EXP_DATE)}</ExpirationDate>
>         {fn-bea:rename($CREDIT_CARD/STATUS,<Status/>)}
>         {fn-bea:rename($CREDIT_CARD/ALIAS,<Alias/>)}
>         <AddressID>{fn:data($CREDIT_CARD/ADDR_ID)}</AddressID>
>     </ns0:CREDIT_CARD>

Here are the steps you would take to make this function available from an XQuery library:

1. The first step is to create and name a library, if you do not already have one:

File —> New —> XQuery Function Library

Figure 2-18 Creating a New XQuery Function Library

2. Name your library such as myXQueryLibrary.
3. Copy your function into the newly created file.
4. Change the function declaration to match the namespace of your library file.

Here is the complete source of the XQuery library file containing the CREDIT_CARD function. To simplify, the object is returned as $x rather than as a set of individually-mapped elements.

>     (::pragma xfl <x:xfl xmlns:x="urn:annotations.ld.bea.com"></x:xfl> ::)

>     xquery version "1.0" encoding "WINDOWS-1252";

>     declare namespace tns="lib:DataServices/MyXQueryLibrary";

>     declare namespace ns1="ld:DataServices/BillingDB/CREDIT_CARD";
>     import schema namespace ns0="urn:retailerType" at "ld:DataServices/RTLServices/schemas/CreditCard.xsd";

>     (: function pragma removed for readability :)

>     declare function tns:getCreditCard() as element(ns1:CREDIT_CARD)* {
>     for $x in ns1:CREDIT_CARD()
>     return $x

>     };

A common use of the XQuery Function Library would be as transformational functions that can then be made available through the Liquid Data palette to any data service in your application.

# Building and Deploying Applications, EARs, and SDO Mediator Clients

Liquid Data attempts to rebuild your application when necessary. However, there are times when you need to initiate a build directly.

## Building and Deploying Applications

The following table describes relevant Build menu options and their uses.

Build Menu Options | Usage
--- | ---
Build Application | Builds or rebuilds your application. The result is that the contents of all the project-specific `.jar` files are updated according to the underlying project script. If your application has already been deployed, this option will automatically redeploy after a successful build. You can also build individual projects.
Clean Application | Attempts to undeploy EJBs and other resources that were produced by the compilation process. In some cases this is not possible because of the state of the server. If Clean Application does not solve the problem, stop and restart WebLogic Server. Clean Application addresses problems that occur due to cyclic compilation of Java files during iterative development, not on production servers. You can also clean individual projects.
Build Ear | Creates an archive file of your application. The `.ear` file has the same name as your application.

### When to Rebuild Your Application or Project

You need to rebuild whenever you delete a file from a Liquid Data-enabled project. Rebuilds can occur on a project or at the application level. Generally speaking, there is no need to rebuild your entire application unless you have made changes to multiple projects.

Rebuild your project (or application) in two steps:

1. Clean your project (or application). You can do this by right-clicking on your project (or application) in the Application pane and selecting the available Clean option. Alternatively, use the appropriate Clean option available from the Workshop Build menu.
2. Build your project (or application) using the appropriate right-click or Build menu options.

Note: If you try to run a function in Test View and it fails unexpectedly, it is often curative to clean, then rebuild your application before attempting to run your query again.

## Deploying Your Application

If your application is already deployed, it is automatically redeployed whenever you rebuild it. Under some conditions you may want to undeploy your application before building it. The following table describes relevant options available when you click on your application folder in the Application pane.

Application Level Right-click Deployment Options | Usage
--- | ---
Deployment —> Redeploy | Redeploys your application. Note: If you build your application it is automatically redeployed.
Deployment—> Full Redeploy | First undeploys your application, then deploys it.
Deployment—> Undeploy | Removes your application from the Application Server.

For additional information on deploying Workshop applications see:

- "Building and Deploying Integrated Applications"
- "Deploying Applications to a Production Server"

## Creating the SDO Mediator API

After you have created and tested your application's query functions, you need to make them available to client applications. The SDO mediator API is the primary means of providing access to your updatable functions.

Note: For details on programming with SDO and accessing data in Java clients through the mediator API see the Liquid Data Client Application Developer's Guide.

A way to create the SDO mediator client Java archive (`.jar`) file is through the right-click menu option Build SDO Mediator Client. This is only available from the root folder of your application.

In order to build your client, you must first have successfully build an application `.ear` file. See Building and Deploying Applications on page 2-20.

When successful, your SDO mediator client will be created in the root directory of your application. The file will be named as:

>     <name_of_your_application>-ld-client.jar