Client Application Developer’s Guide

Introducing Data Services for Client Applications

Introduction

What Is a Data Service?

What is an ALDSP Client Application?

Choosing a Client Programming Model

Introducing Service Data Objects (SDO)

Introducing The Data Service Mediator API

Typical Client Application Development Process

Security Considerations in Client Applications

Performance Considerations

Client Classpath Settings

Java Mediator API Clients

Web Services Clients

JMX Mbean Management API Client Classpath

ALDSP JDBC API Client Classpath

Backward Compatibility

Data Programming Model and Update Framework

Introduction

ALDSP and SDO

Static and Dynamic Data Object APIs

Static Data Object API

XML Schema-to-Java Type Mapping Reference

Dynamic Data Object API

XPath Expressions in the Dynamic Data Object API

Obtaining Type Information about Data Objects

Role of the Mediator API and SDO

Invoking Data Services from Java Clients

Introducing the Mediator API

What is SDO?

What is the Mediator API?

Dynamic and Static Mediator APIs

API Overview

Summary

Getting Started

Basic Steps

Setting the CLASSPATH

Static Java Mediator API Client CLASSPATH

Dynamic Java Mediator API Client CLASSPATH

Specifying the Class Loader Directly

Running the Sample Applications

Sample Static Mediator Application

Setting Up the Sample Data Service

Generating the Mediator Client JAR File

Setting Up the Java Project

Running and Testing the Code

Examining the Sample Code

Importing Packages

Obtaining a Data Access Service Handle

Retrieving Data from the Service

Obtaining a DataObject from the Result

Disposing the Result Object

Modifying the DataObject

Returning Changes to the Server

Sample Dynamic Mediator Application

Setting Up and Running the Sample Code

Sample Java Client Code (Dynamic Mediator API)

Examining the Sample Code

Importing Classes

Obtaining a DataAccessService Handle

Retrieving Data from the Service

Obtaining a DataObject from the Result

Disposing the Result Object

Modifying the DataObject

Returning Changes to the Server

Creating New DataObjects

Creating a New DataObject with the Static API

Setting Up and Running the Sample

Importing Packages

Obtaining a Data Access Service Handle

Creating a DataFactory

Create and Name the DataObject

Modifying the DataObject

Returning New DataObject to the Server

Returning the New DataObject Key

Creating a New DataObject with the Dynamic API

Running the Sample

Importing Packages

Creating a DataFactory

Create and Name the DataObject

Modifying the DataObject

Returning New DataObject to the Server

Returning the New DataObject Key

Mediator API Basics

Beyond the Sample Applications

More on the Static Mediator API

More on the Dynamic Mediator API

Invoking Data Service Operations

Getters and Setters

Naming Conventions for Generated Classes

Mediator Client JAR Naming Convention

Web Services Mediator Client JAR Naming Convention

Understanding DASResult

Overview of DASResult

Disposing of DASResult Objects

Dynamic Mediator APIs and DASResult

Static Mediator APIs and DASResult

Retrieving an Array of Objects

Obtaining the WebLogic JNDI Context for ALDSP

Working with Data Objects

Enabling Data Objects for Change Tracking

Modifying Data Object Properties

Creating a New Data Object

Mapping Data Service Types to Java Types

Conversion of Simple Types

Conversion of Date/Time Types

Passing Empty Sequence Arguments

Quantified Return Types

What is Autoboxing?

Web Services Support

Advanced Topics

Schema Management

Schema Scope

Schema Download

Schema Cache Management

Support for Stateless Operations

Cache Management

Forcing Data Cache Read-through and Update

SETTING the REFRESH_CACHE_EARLY Attribute

Specifying XPath Expressions as Arguments

Making Ad Hoc Queries

Understanding Transaction Behavior

Transaction Behavior for Read/Write Operations

Transaction Behavior for Read-Only Operations

Invoking Data Services Through Web Services

Overview

Before You Begin

Getting Started

Basic Steps

Setting the CLASSPATH

Running the Sample Applications

Sample Static Mediator Application

Setting Up the Sample Data Service

Creating a Web Service Map File

Generating the Web Services Mediator Client JAR File

Setting Up the Java Project

Running and Testing the Code

Examining the Sample Code

Importing Packages

Obtaining a Data Access Service Handle

Retrieving Data from the Service

Obtaining a DataObject from the Result

Disposing the Result Object

Modifying the DataObject

Returning Changes to the Server

Sample Dynamic Mediator Application

Setting Up and Running the Sample Code

Sample Java Client Code (Dynamic Mediator API)

Examining the Sample Code

Importing Classes

Obtaining a DataAccessService Handle

Retrieving Data from the Service

Obtaining a DataObject from the Result

Disposing the Result Object

Modifying the DataObject

Returning Changes to the Server

Transaction Behavior and Web Services

Securing Your Web Services Application

Using SQL to Access Data Services

Introducing SQL Access to Data Services

Features of the Data Services Platform JDBC Driver

Exploring Data Services Platform and JDBC Artifacts

JDBC and SQL Support in Data Services Platform

JDBC Support

SQL Support

Supported SQL Statements

Supported SQL Functions

Numeric Functions

String Functions

Datetime Functions

Aggregate Functions

JDBC Metadata Search Patterns

Table Parameter Support

Additional Details and Limitations

Preparing to Use SQL to Access Data Services

Publishing Data Service Operations

Configuring the Data Services Platform JDBC Driver

Accessing Data Services Using SQL From a Java Application

Obtaining a Connection

Configuring the Connection Using the Properties Object

Configuring the Connection in the JDBC URL

Using the PreparedStatement Interface

Using the CallableStatement Interface

Advanced Features

Using Table Parameters

When to Use Table Parameters

Setting Table Parameters Using JDBC

Creating Table Parameters

JDBC Usage

Table Parameter Example

Table Parameter ValueTypes

Accessing Custom Database Functions Using JDBC

Accessing Data Services Using SQL-Based Applications

Accessing Data Services Using SQL Explorer

Connecting to the Data Services Platform Client Using OpenLink ODBC-JDBC Bridge

Using OpenLink with Reporting Tools

Crystal Reports XI

Configuring Crystal Reports

Limitations

Connecting to Crystal Reports Using JDBC

Business Objects XI-Release 2 (ODBC)

Configuring Business Objects

Prerequisites and Limitations

Generating a Business Objects Report

Microsoft Access 2003-ODBC

Generating Reports Using Microsoft Access

Limitations and Usage Notes

Microsoft Excel 2003-ODBC

Limitations

Using Excel to Access Data Services

Introducing the Excel Add-in

Installing the Excel Add-in

System Requirements

Installation Instructions

Preparing To Install

Installing the Add-in

Accessing Excel Add-in Documentation

Preparing to Use the Excel Add-in

Accessing the Data Service Using Excel

Accessing Data Services Through a WebLogic Workshop Control

Introduction to Data Service Controls

Data Service Controls Defined

Description of the Data Service Control File

Design View

Source View

Creating Data Service Controls

Prerequisites

Step 1: Create a Project

Step 2: Start WebLogic Server

Step 3: Create a Package under src Folder

Step 4: Create the Data Service Control

Using ALDSP Control for Ad Hoc Queries

ALDSP Control Backward Compatibility

Modifying Existing ALDSP Control

Adding and Removing Operations Used by a Control

Updating an Existing Control When Schemas Change

Caching Considerations When Using Data Service Controls

Bypassing the Cache When Using a Data Service Control

Cache Bypass Example When Using a Data Service Control

ALDSP Control Security Considerations

Security Credentials Used to Create Data Service Controls

Testing Controls in the JWS File

Trusted Domains

Using ALDSP Control in Different Domains

Supporting ADO.NET Clients

Overview of ADO.NET Integration in Data Services Platform

Understanding ADO.NET

ADO.NET Client Application Development Tools

Understanding How ALDSP Supports ADO.NET Clients

Supporting Java Clients

Enabling ALDSP Support for ADO.NET Clients

Generating an ALDSP Web Services Mapper

Viewing an ADO.NET-Enabled WSDL

Creating a Web Reference in ADO.NET Client by Providing the ALDSP WSDL URL

Adapting ALDSP XML Types (Schemas) for ADO.NET Clients

Approaches to Adapting XML Types for ADO.NET

XML Type Requirements for Working With ADO.NET DataSets

Requirements for Complex Types

Requirements for Recurring References

Requirements for Simple Types

Requirements for Target Namespace and Namespace Qualification

References

Creating a Data Service Based on an RPC-Style Web Service

Generated Artifacts Reference

XML Schema Definition for ADO.NET Types DataSet

Web Services Description Language (WSDL) File for Microsoft ADO.NET Clients

Advanced Topics

ALDSP Control Source Upgrade

Accessing Metadata Using Catalog Services

Installing Catalog Services

Using Catalog Services

Application (application.ds)

DataService (DataService.ds)

DataServiceRef (DataServiceRef.ds)

Folder (folder.ds)

Function (Function.ds)

Relationship (Relationship.ds)

Schema (Schema.ds)

Filtering, Sorting, and Fine-tuning Query Results

Introducing the Filter API

addFilter()

createFilter()

addOrderBy()

setLimit()

Exploring the Filter Operators

Using Filters

Filtering Examples

Specifying a Compound Filter

Ordering and Truncating Data Service Results

Using Ad Hoc Queries to Fine-tune Results from the Client