Data Services Developer's Guide
|
 |
 |
|
 |
 |
BEA Liquid Data for WebLogic® can be added to Workshop in two ways:
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:
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.
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
To create a Liquid Data-enabled application select File
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
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.
You can also add one or several Liquid Data projects to any Workshop application.
To do this select File
Figure 2-3 Application Pane of a New Liquid Data Application
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
|
Data services are contained in Note: Since a |
|
|
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 |
|
|
Metadata information is contained in META-INF folders associated with |
|
|
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 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). |
|
|
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.
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:
Table 2-6 Summary of Workshop Pane Used by Liquid Data
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
|
When working with Liquid Data projects you will often use the following File menu options: |
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.
Workshop provides a comprehensive file search facility with its Find in Files option, available from the Edit menu (Edit
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.
A Liquid Data project adds menu items and views to the basic Workshop environment to support the following functionality:
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.
It is through the data model interface that you can:
Figure 2-11 Creating a Data Model Diagram From the File Menu
For details on developing and maintaining data models see Modeling 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 is the central reference point of every data service. It is through Design View that you can:
For details on developing and maintaining data services see Using Data Services Design 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
For details on developing queries using XQuery Editor View see Using Query Editor View.
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
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.
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.
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.
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
After you have developed a query you can run it using Test View. For details see Testing Query Functions and Viewing Query Plans.
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.
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.
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:
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.
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:
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.
Liquid Data attempts to rebuild your application when necessary. However, there are times when you need to initiate a build directly.
The following table describes relevant Build menu options and their uses.
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:
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.
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.
For additional information on deploying Workshop applications see:
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
|
|
|
