Skip navigation.
Downloads | Product Documentation | Support

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 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 WebLogic Workshop all apply to DSP.

Note: WebLogic Workshop online documentation is available at:

>     http://e-docs.bea.com/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:

- DSP-Based BEA WebLogic Projects
- Major Components of a DSP Project

# DSP-Based BEA WebLogic Projects

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.

### Verifying Your DSP Version Number

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 —>Versions page (Console being the top menu item) and find the version and creation date for DSP.

## Creating a Data Services Platform-based Application

To create a DSP-based application select File —>New —>Application from the 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 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.

## 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 Pane 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`, 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

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 DSP queries. Model diagrams have the extension `.md` and can be located anywhere in your DSP 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).
XQuery function library files (`.xfl`) | 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.

## Using the WebLogic Workshop IDE

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

>     http://e-docs.bea.com/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

Service | Purpose
--- | ---
File menu | When working with DSP 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 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.

### 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

### 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

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 WebLogic 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 WebLogic Workshop window. Functions can be dragged into the 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 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.

#### 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 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 Library (XFL) Files

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:

- 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 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:

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 Data Services Palette to any data service in your application.

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

DSP 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 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:

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 WebLogic 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 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 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