Data Services Developer's Guide

Data Services Platform Projects and Components

BEA Aqualogic Data Services Platform (DSP) can be added to WebLogic Workshop in two ways:

• As a project in a new application
• As a project in any existing BEA WebLogic application.

The basic menus, common behavior, and look-and-feel associated with WebLogic Workshop 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 can 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:

• DSP-Based BEA WebLogic Projects
• Major Components of a DSP Project
• Building and Deploying Applications, EARs, and SDO Mediator Clients
• Refactoring DSP Artifacts

 

---

DSP-Based BEA WebLogic Projects

As noted above, 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.

Note: It often makes sense to consolidate DSP queries into 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 complete details related to how client applications can access Data Services Platform functions and procedures see the DSP Client Application Developer's Guide.

Verifying Your DSP Version Number

To ascertain that DSP is available to your application or to determine the version of DSP that you are running, start your BEA WebLogic Server and access its Administration Console.

As an example, the WebLogic Server 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 number and creation date for DSP.

Creating a DSP-based Application

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

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 —> Save, Save As, or Save All commands. Save All saves any modified files in your application.

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

An application can contain any number of DSP or other types of WebLogic Workshop projects.

Adding a DSP Project to an Existing BEA WebLogic Application

You can also add one or several DSP projects to any WebLogic Workshop application.

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

Figure 2-3 Application Tab of a New Data Services Platform Application

 

 

---

Major Components of a DSP Project

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. The latter file manages creation of Service Data Objects (SDOs), described in detail in the Client Application Developer's Guide.

Table 2-4 lists major DSP file types and their purposes.

Table 2-4 Data Services Platform Components, Including File Types

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.

Using the WebLogic Workshop IDE

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:

• WebLogic Workshop functionality extensively used by DSP.
• DSP extensions to the Workshop user interface.

Table 2-6 Summary of WebLogic Workshop Pane Used by DSP

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 WebLogic Workshop menu commands you will use with DSP projects.

Table 2-7 Summary of WebLogic Workshop Menu Services Used by DSP

Property Editor

You can use the Property Editor to view details related to any WebLogic Workshop 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 that service. If you click on a relationship representation in your 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

 

Finding Text in Files

WebLogic 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 DSP artifacts such as particular data sources, use of functions, and so forth.

Survey of DSP Additions to WebLogic Workshop

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

• Metadata Import
• Data Models
• Data Services
• XQuery Function Libraries
• Usages of Data Services Artifacts
• Updating Application or Project Data Service Libraries

Metadata Import

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.

Data Models

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 (XDS file).

Data services are composed of read and navigation functions and procedures. Read functions must return the XML type of the data service. Navigation functions, return the XML type of their native data service. Procedures, also known as side-effecting functions, need not return anything.

Figure 2-12 Sample Data Service

 

Design View

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

• Add or modify the XML type (associated schema).
• Add read functions using the XQuery Editor View.
• Add private functions.
• 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 Designing Data Services.

XQuery Editor View

Through the XQuery Editor View 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 1.0 XQuery standard. Several resources are available to help in the development and maintenance of business logic. These are all available from the WebLogic Workshop View or View —>Windows menu).

For details on developing queries using XQuery Editor View see Working with the XQuery Editor.

XQuery Function Palette

An XQuery function palette (Figure 2-14) is available 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 WebLogic Workshop window. Functions from this palette can be dragged into XQuery Editor View, as well as Source View.

XQuery Constructs Palette

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.

Data Services Palette

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

Figure 2-16 Data Services Palette

 

For details on using the XQuery Editor see Working with the XQuery Editor.

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 Logical Data Service XML Types. Most editor options are available from the right-click menu.

Right-click menu commands for return types differ slightly from those in the XML type editor. The reason is that you can use the XQuery Editor to create if-then-else constructs, zones, and cloned elements as a means of more 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 editing changes to your data service. For additional details see Working with XQuery Source.

Query Plan 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.

XQuery Function Libraries

You can create XQuery libraries containing functions that can be used by any data service in your application. XQuery function libraries can be created in two ways:

• Using the File —> New XQuery Function Library option.
• Automatically, when Java functions returning primitive types are imported as metadata (see Obtaining Enterprise Metadata).

An XQuery function library (.xfl file) is ideal for creating transformation, security, and other types of functions that are not associated with an XML type.

XQuery Function Library Views

An XQuery function library (XFL) holds any number of functions.

XFL Design View is similar to the data service Design View (shown in Sample Data Service). The primary differences are:

• Since no schema is associated with a library, there is no XML type.
• There are no relationship functions.

The tabular modes available in data services — Source View, XQuery Editor View, Test View, and Query Plan View — are available to XQuery function libraries as well.

XFL files play an important role in creating inverse functions. See Using Inverse Functions to Improve Performance During Updates in Best Practices and Advanced Topics.

Creating an XFL Function

It is not difficult to make a function in a data service available throughout your project as an XML function library.

Note: Namespace conflicts must to be resolved before you can make your function generally available.

The following function is available in the RTLApp's DataServices/RTLServices/Credit Card data service (namespace declarations from a separate section of the source file are also 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 create this function in an XQuery library:

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 an XQuery Function Library




 

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

Source for the XQuery library file containing the CREDIT_CARD function appears below. 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

};

Usages of Data Services Artifacts

It is often convenient to determine which Data Services Platform artifacts are in use by which other artifacts. For example, before making changes in an XML type it is important to determine what other data services might be impacted. Of course you can do this through the Metadata Browser, described in the "Viewing Metadata" chapter of the DSP Administration Guide. However, it is often more convenient to do this in the context of the WebLogic Workshop navigation pane or the DSP Design View.

For example, in the RTLApp, right-clicking on a data service shows a number of options including Find Usages (Figure 2-19).

Figure 2-19 Finding Usages of a Data Service in RTLApp

 

When you pick this option, usages of the artifact are displayed, as shown in Figure 2-20.

Figure 2-20 Usages of the Customer Data Service in the RTLAPP

 

You can find the usages of the following types of DSP artifacts:

• Data services
• XML library function files
• Read and relationship functions
• Procedures
• Private functions
• Schemas

Updating Application or Project Data Service Libraries

When you save a DSP application its JAR libraries files are bound to that application. If you subsequently migrate to a newer version of DSP, you also need to migrate your application to the latest library files. For details see "Migrating Legacy DSP Applications" in the DSP Installation Guide.

 

---

Building and Deploying Applications, EARs, and SDO Mediator Clients

DSP attempts to rebuild your application as necessary. However, there are times when you will need to initiate a build directly.

Building, Deploying, and Updating Applications

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

When to Rebuild Your DSP Project

You need to rebuild your project 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:

Clean your project (application). You can do this by right-clicking on your project (application) in the Application pane and selecting the available Clean option. Alternatively, use the appropriate Clean option available from the WebLogic Workshop Build menu.
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 will be automatically redeployed whenever you rebuild it. Under some conditions you may want to undeploy your application first. The following table describes relevant options available when you click on your application folder in the Application pane.

Table 2-21 Usages of Various Deployment Menu Options

For additional information on deploying WebLogic 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 SDO programming and accessing data in Java clients through the mediator API see the Data Services Platform Client Application Developer's Guide.

Generating the SDO Mediator JAR in Workshop

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

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

The SDO mediator JAR file will also be automatically added to your application's Libraries folder.

Note: Insure that all of your projects are up-to-date and built before creating your SDO mediator JAR file. See also Building, Deploying, and Updating Applications on page 2-22.

Command-line Generation of the SDO Mediator API

You can also create the SDO mediator client JAR file through the command line using ant scripts.

When an EAR File Is Available

If you already have an EAR file you can use the script:

ant -f $WL_HOME/liquiddata/bin/ld_clientapi.xml
-Darchive=</your_path/name_of_your_application>.ear>

in which case the name of your JAR file will be taken from the EAR file:

<name_of_your_application>-ld-client.jar

It will be created in the same directory as the EAR file.

Generating an SDO Mediator JAR File

You can generate an SDO mediator client JAR file (without needing an EAR file) by simply specifying an application directory:

ant -f $WL_HOME/liquiddata/bin/ld_clientapi.xml
-Dapproot=</your_path/name_of_your_application>/root>

This approach will use the directory name of the application root to compute the JAR file name; in the above case the name would be root-ld-client.jar. If that's not what is wanted, you could specify:

-Dsdojarname=<MyApp-ld-client.jar>

to override this. Either way the JAR file will be generated in the application root directory.

Generating JAR Files in Non-default Directories

For either case you could specify the additional ant parameter:

-Doutdir=</path/to/dir>

to generate the JAR file to a specific directory location.

Similarly you could use:

-Dtmpdir=</path/to/tmp>

to specify an alternate directory for temporary files, including the generated .java code.

The default tmp file location is specified by the Java system property:

java.io.tmpdir

In any case, when building from the command line, the SDO mediator.jar file will not be added to your application's Libraries folder (shown in Figure 2-2).

 

---

Refactoring DSP Artifacts

There are times when you will want to move, rename, or delete artifacts in your Data Services Platform projects. A typical example: your application is first developed with test data, so as to not expose confidential information to unauthorized individuals. Then, once developed, your application is ready for deployment with the actual, secured data sources. You can use refactoring to greatly simplify the renaming, deleting, or relocating of DSP components.

Figure 2-22 Refactoring Options Available for the RTLApp's Address Data Service

 

Without refactoring, changes you make to artifact names can easily result in invalid references. For example, renaming a data service file automatically invalids any relationship functions in other data services that refer to that file. The alternative to refactoring is to manually find all usages of a given artifact and make manual edits to data service source; this can be quite tedious and error-prone, particular as projects grow.

When you use the Refactor option you initially see the effect your refactoring change will have on impacted application artifacts (Figure 2-23). A checkbox allows you to exempt any artifact from the refactoring operation.

Note: Care should be taken when deselecting elements recommended for refactoring. Without additional manual changes to the underlying source you likely will no longer be able to build or deploy your application.

Figure 2-23 Artifacts Impacted by a Refactoring

 

Artifacts Supporting Refactoring

Table 2-24 describes artifacts subject to refactoring and their options.

Table 2-24 Data Service Artifacts Supporting Refactoring and Available Refactoring Options

Move, rename, and add/remove parameter operations are typically accomplished without adverse consequence. Delete operations, however, can adversely affect your project. For this reason the usages of the artifact you have identified for deletion are shown (see Figure 2-25). From this information you can easily determine the trade-offs between the automation of the refactoring operation and its consequences, which may require additional manual actions on your part.

Figure 2-25 Implications of a Safe Delete Operation

 

Setting Refactor Options

Access to refactor options depends on the artifact:

• Data services, XFL files, schemas. Refactor operations for data services, XFL files, and schemas can be accessed by right-clicking on the artifact in the Application pane.
• Functions and procedures. Refactor options for functions and procedures can be access by right-clicking on name of the function or procedure in Design View or by right-clicking on its associated arrow.

Figure 2-26 Refactoring a Data Service Function




 
• Namespace declarations and schema import declarations. Refactor operations related to namespaces and schema import declarations are accessed through the Prefix Bindings section of Property Editor.

You can refactor a namespace or external schema prefix simply by changing its prefix name (binding) in the Property Editor (Figure 2-26).

Figure 2-27 Refactoring Namespace Declarations




 

When you change a prefix binding you are also given the option of making the change throughout your project (globally).

If you choose this option (see anywhere the uri (urn:retailerType) appears in your project, the prefix will become "retailer1".

Figure 2-28 Changing a Prefix Binding Throughout Your Project




 

If you choose Yes, a list of usages of the URI appears.

Figure 2-29 List of Prefix Bindings Potentially Affected by a Global Prefix Change




 

Warning: Although you can deselect any artifact that you do not want to be included in a refactor operation, doing so will invalidate that artifact and any files dependent on that artifact. For this reason selective deselection of artifacts scheduled for refactoring should generally not be employed.

Note: In the case of namespace prefixes, names should be changed (or not) based on readability or consistency issues. Neither a local or a global change will adversely affect your code.

Impacts of Various Refactoring Operations

It is useful to understand the various potential effects of a refactoring operation.

In this section each type of refactoring operation is described in terms of its potential impact on related artifacts.

Table 2-30 Refactoring Effects on Artifact Types

Contact BEA |  Feedback |  Privacy  |