Data Services Developer's Guide
|
 |
 |
|
 |
 |
BEA Aqualogic Data Services Platform (DSP) can be added to WebLogic Workshop in two ways:
The basic menus, common behavior, and look-and-feel associated with WebLogic Workshop all apply to DSP.
Note: WebLogic Workshop online documentation is available at:
http://download.oracle.com/docs/cd/E13226_01/workshop/docs81/index.html
This chapter discusses various WebLogic Workshop facilities that you will likely use in creating and managing your DSP-based projects. DSP extensions to WebLogic Workshop are also described from an interface perspective.
The following topics are covered:
You can create a WebLogic Workshop application that automatically includes a Data Services Platform project. Or you can add DSP projects to any BEA WebLogic application. When an application contains a DSP project it is considered DSP-based.
Note: It often makes sense to consolidate DSP queries in a WebLogic Workshop application dedicated to DSP development. Other applications can then access these queries through the DSP Mediator API or a Data Services Platform control. For details see the DSP Client Application Developer's Guide.
To ascertain that DSP is available to your application or to determine the version of DSP 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 DSP-based application select File
Figure 2-1 Creating a New Data Services Platform Application
You probably will want to change the name of the application from Untitled to something else. Your new application automatically contains an initial DSP-based project.
Figure 2-2 Application View of a New Data Services Platform Application
You can save your application at any time using the File
When you initially create a WebLogic 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 DSP or other types of WebLogic Workshop projects.
You can also add one or several DSP projects to any WebLogic Workshop application.
To do this select File
Figure 2-3 Application Pane of a New Data Services Platform Application
When a new Data Services Platform application or project is created, a DSP 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 DSP file types and their purposes.
Table 2-4 Data Services Platform 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 DSP queries. Model diagrams have the extension |
|
|
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. |
|
|
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). |
|
|
XQuery function libraries typically 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 DSP 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.
WebLogic 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, WebLogic Workshop provides complete on-line help.
Figure 2-5 Some WebLogic Workshop Components in a DSP-based Project
The following table briefly describes:
Table 2-6 Summary of WebLogic Workshop Pane Used by DSP
Table 2-7 describes the several WebLogic Workshop menu commands you will use with DSP projects.
Table 2-7 Summary of WebLogic Workshop Menu Services Used by DSP
|
When working with DSP projects you will often use the following File menu options: |
You can use the Property Editor to view details related to any DSP 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.
WebLogic 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 DSP artifacts such as particular data sources, use of functions, and so forth.
A DSP project adds menu items and views to the basic WebLogic 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 DSP 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 DSP Project
For details related to importing and updating metadata into your DSP 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 WebLogic 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 WebLogic Workshop window. Functions can be dragged into the XQuery Editor View as well as Source View.
DSP 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 DSP 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 BEA XQuery extensions see the XQuery Developer's Guide.
The Data Services Palette (Figure 2-16) is only available toDSP projects. It provides the XQuery Editor access to data service and XFL (XQuery function library) routines.
Figure 2-16 Data Services 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 DSP 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 Data Services Platform 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 DSP 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 Data Services Palette to any data service in your application.
DSP 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 DSP-based 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 WebLogic 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 Data Services Platform 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
|
|
|
