Data Services Developer's Guide

Introduction to Data Services

Data Services and the Enterprise

Data Access Integration Architecture

AquaLogic Data Services Platform Applications and Projects

Services Available to a AquaLogic Data Services Platform-Based Project

AquaLogic Data Services Platform: Roles and Responsibilities

AquaLogic Data Services Platform: Typical Development Process

Examples, Samples, and Tutorials

AquaLogic Data Services Platform Projects and Project Components

AquaLogic Data Services Platform-Based BEA WebLogic Applications

Verifying Your AquaLogic Data Services Platform Version Number

Creating a AquaLogic Data Services Platform-based Application

Adding a AquaLogic Data Services Platform Project to an Existing BEA WebLogic Application

Major Components of a AquaLogic Data Services Platform Project

Data Service Project Right-click Menu Options

Data Service Right-click Menu Options

Using the WebLogic Workshop IDE

Property Editor

Finding Text in Files

Survey of AquaLogic Data Services Platform Additions to WebLogic Workshop

Editing XML Types and Return Types

Test View

Source View

Query Plan View

Usages of Data Services Artifacts

Updating Application or Project Data Service Libraries

Building and Deploying Applications, JARs, and SDO Mediator Clients

Building, Deploying, and Updating Applications

When to Rebuild Your AquaLogic Data Services Platform Project

Deploying Your Application

Creating the SDO Mediator API

Generating the SDO Mediator JAR in Workshop

Command-line Generation of the SDO Mediator API

When an EAR File is Available

Generating an SDO Mediator JAR File

Generating JAR Files in Non-default Directories

Refactoring AquaLogic Data Services Platform Artifacts

Artifacts Supporting Refactoring

Setting Refactor Options

Impacts of Various Refactoring Operations

Creating and Working with XQuery Function Libraries

XQuery Function Library Views

Creating an XFL Function

XFL Database Function Views

Support for Built-in and User-Defined SQL Functions

Creating a Database XFL and Registering Database Functions

Modifying XFL Database Function Information

Adding Data Sources to an XFL Database Function Library

Understanding XFL Database Function Calls Through Source View

XFL Database Function Declarations

Support for Polymorphism

Obtaining Enterprise Metadata

Creating Data Source Metadata

Identifying AquaLogic Data Services Platform Procedures

Obtaining Metadata from Relational Sources

Providing Role-based Access to AquaLogic Data Services Platform Relational Sources

Importing Web Services Metadata

Testing Metadata Import With an Internet Web Service URI

Setting Up Handlers for Web Services Accessed by AquaLogic Data Services Platform

Importing Java Function Metadata

Supported Java Function Types

Adding Java Function Metadata Using Import Wizard

Creating XMLBean Support for Java Functions

Creating a Metadata-enriched Java Class: An Example

Inspecting the Java Source

How Metadata for Java Functions Is Created

Technical Details, with Additional Example Code

Processing a Function Returning an Array of Java Primitives

Processing complex types represented via XMLBeans

Restrictions on Java Functions

Importing Delimited File Metadata

Providing a Document Name, a Schema Name, or Both

Using the Metadata Import Wizard on Delimited Files

Importing XML File Metadata

XML File Import Sample

Testing the Metadata Import Wizard with an XML Data Source

Updating Data Source Metadata

Considerations When Updating Source Metadata

Direct and Indirect Effects

Using the Update Source Metadata Wizard

Metadata Update Analysis

Synchronization Mismatches

Archival of Source Metadata

Designing Data Services

Data Services in the Enterprise

Comparing Data Services with Web Services

Physical and Logical Data Services

Data Service Functions

Data Service Design View Components

XML Types and Return Types

Where XML Types are Used

Where Return Types are Used

Creating a Data Service

Adding a Function to Your Data Service

Adding a Procedure to Your Data Service

Adding a Private Function to Your Data Service

Adding a Relationship to Your Data Service

Understanding Navigation Functions

Effect of Using a Navigation Function to Return Data

Creating a Relationship Between Data Services

Using the Relationship Wizard to Create Navigation Functions

Setting Relationship Notations: Role Names, Direction, Cardinality

Setting Function Name, Identifying the Opposite Data Service, Mapping Parameters, and Building Where Clauses

Example of Creating a Navigation Function

Testing Your Navigation Function

Navigation Functions in Source View

Working with Logical Data Service XML Types

Associating an XML Type

Selecting a Global Element

Editing an XML Type

External Editing of XML Types

Creating an XML Type

Managing Your Data Service

Refactoring Data Service Functions

Finding Usages of AquaLogic Data Services Platform artifacts

Setting Update Options

Allowing Updates

Setting the Override Class

Enable/Disable Optimistic Locking

Adding Security Resources

Create Necessary Security Resources

Structure Your Query To Support Security Resource Validation

Assign Security Resources Through the AquaLogic Data Services Platform Console

Validating Security Policies Through Test View

Caching Functions

Caching Considerations

Setting Caching Policy for a Function

Notable Design View Properties

Publishing Data Service Functions for SQL Use

Making Data Service Objects Available for SQL Use

Publishing Data Service Functions Example

Publish Data Service Functions Alert Dialog

Constraints on Publishing Data Service Objects to SQL

How Non-Tabular Element Types Affect the Ability to Publish Functions as SQL Objects

Modeling Data Services

Model-Driven Data Services

Logical and Physical Data Models

Physical Data Models

Logical Data Models

Rules Governing Model Diagrams

Building a Simple Model Diagram

Displaying Relationships Automatically

Generated Relationship Declarations in Source View

Modeling Logical Data

Building Data Service Relationships in Models

Direction, Role, and Relationships

Role Names

Relationships

Working with Model Diagrams

Model Right-click Menu Options

Creating Relationships in Model Diagrams

Locating Data Services in Large Model Diagrams

Generating Reports on Your Models

Creating a Model Report

Model Report Format

Zoom Mode

Editing XML Types in Model Diagrams

Model Diagram Properties

How Changes to Data Services and Data Sources Can Impact Models

How Metadata Update Can Affect Models

Working with the XQuery Editor

Role of the XQuery Editor

Data Source Representations

XQuery Editor Options

Creating a Simple Data Service Function

Importing Metadata from Physical Data Sources

Creating Your Logical Data Service

Finishing Up

Key Concepts of Query Function Building

Data Sources

Source Schemas and Return Types

XQuery Editor Components

Return Type Node

For Clause Nodes

Parameterized Input

For and Let Node Options

Converting Between For and Let Clauses

Let Statement Nodes

Parameter Nodes

Adding a Parameter Requiring a Simple Type

Adding a Complex Parameter

Using the Parameter Dialog to Create a WHERE Clause

Adding Relationship Functions to an Existing Data Service

Group By Statement Nodes

Creating Multiple Group By Elements

Using Multiple Group Nodes

Distinct By Statement Nodes

Setting Conditions

The Where Clause

Using a Where Clause as a Filtering Device

The Order By Clause

Creating Join Conditions

Using XQuery Functions

Using XQuery Functions in Where Clauses

Transforming Data Using XQuery Functions

Setting Expressions

Managing Query Components

Working With Data Representations and Return Type Elements

Mapping to Return Types

Mapping Elements and Attributes to the Type

Complex Element Mappings to a Return Type

Source-to-Target Mapping Options

Removing Mappings

Modifying a Return Type

Editing a Return Type

Adding a Complex Child Element

Setting Zones in Your Return Type

Associating XQuery Editor Nodes With Zones

Removing Zones

Validating and Saving Your Return Type

Testing Query Functions and Viewing Query Plans

Running Queries Using Test View

Using Test View

Running a Query That Needs No Parameters

Editing Results

Running a Query Function With Simple Parameters

Testing a Query Function With Complex Parameters

Using Prior Results as Input

Using the XML Type to Identify Input Parameters

Testing AquaLogic Data Services Platform Procedures

Limiting Array Results

Starting Client Transaction Option

Validating Results

Disregarding a Running Query

Auditing Query Performance

Running Ad Hoc Queries Under Test View

Example Ad Hoc XQuery

Using Query Plan View

Query Plan Information and Warnings

Printing Your Query Plan

Analyzing a Sample Query

Working With Your Query Plan

Identifying Problematic Conditions Through the Query Plan

Obtaining an Ad Hoc Query Plan

XQuery Ad Hoc Query Example

SQL Ad Hoc Queries

SQL Ad Hoc Query Example

Running an Ad Hoc SQL Query Containing Table Parameters

Working with XQuery Source

What is Source View?

XQuery Support

Using Source View

Finding Text

Function Navigation

Code Editing Features

Color Coding

Code Completion

Completing Xpath Expressions

Error Identification

Handling Updates Through Data Services

Updating Source Data

Update Overrides and Physical Data Services

What is an Update Override?

An Update Override is a Java Class

How an Update Override Affects Update Processing

When Update Override Classes Are Needed

Registering an Update Override Class

Developing an UpdateOverride Class

Creating Update Overrides for Relational Data Sources

Primary-Foreign Key Relationships Mapped Using a KeyPair

Managing Key Dependencies

Transaction Management

Invoking Data Service Procedures from an UpdateOverride

Testing Submit Results

Common Update Override Programming Patterns

Overriding the Decomposition and Update Process

Using the performChange( ) Method

Augmenting Data Object Content

Accessing the Data Service Mediator Context

Accessing the Decomposition Map

Customizing an Update Plan

Executing an Update Plan

Retrieving the Container of the Current Data Object

Invoking Other Data Service Functions and Procedures

Capturing Runtime Data About Overrides in the Server Log

Default Optimistic Locking Policy: What it Means, How to Change

Invoking JPDs from AquaLogic Data Services Platform

Invoking a JPD from an Update Override

Invoking a JPD by Using the JpdService API in an Update Override

Synchronous and Asynchronous Behavior

Error Handling and Use of Callbacks

Best Practices and Advanced Topics

Using a Layered Data Integration and Transformation Approach

Using Inverse Functions to Improve Query Performance

Sample Invertible Data

Considerations When Running Queries Against Logical Data

Situations Where Inverse Functions Can Improve Performance

Additional Inverse Function Scenarios

Improving Performance Using Inverse Functions: an Example

Deconstructing Composite Keys

Step 1: Create the necessary programming logic

Step 2: Importing Java Function Metadata

Step 3: Add Functionality to Your XFL File

Step 4: Configure Inverse Functions