Client Application Developer’s Guide

Introducing Data Services for Client Applications

Introduction

What Is a Data Service?

What is an Oracle Data Service Integrator 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

DSP Control Clients

JMX Mbean Management API Client Classpath

Oracle Data Service Integrator JDBC API Client Classpath

Data Programming Model and Update Framework

Introduction

Oracle Data Service Integrator 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

Adding the Oracle Data Service Integrator Client Library

Adding the Library to an Existing Project

Adding the Library When Creating a New Project

Manually 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 Oracle Data Service Integrator

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?

Support for Derived Simple Types

Mapping Derived Schema Types to Java Types

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

Adding the Oracle Data Service Integrator Client Library

Adding the Library to an Existing Project

Adding the Library When Creating a New Project

Manually Setting the CLASSPATH

Static Web Service Client CLASSPATH

Dynamic Web Service Client 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 Oracle Data Service Integrator JDBC Driver

Exploring Oracle Data Service Integrator and JDBC Artifacts

JDBC and SQL Support in Oracle Data Service Integrator

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 Oracle Data Service Integrator 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 Oracle Data Service Integrator 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

Accessing Data Services Through a Workshop for WebLogic 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

Step 1: Create a Project

Step 2: Start Oracle WebLogic Server

Step 3: Create a Package under src Folder

Step 4: Create the Data Service Control

Using Data Service control for Ad Hoc Queries

Modifying Existing Data Service 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

Data Service control Security Considerations

Security Credentials Used to Create Data Service Controls

Testing Controls in the JWS File

Trusted Domains

Using Data Service control in Different Domains

Supporting ADO.NET Clients

Overview of ADO.NET Integration in Oracle Data Service Integrator

Understanding ADO.NET

ADO.NET Client Application Development Tools

Understanding How Oracle Data Service Integrator Supports ADO.NET Clients

Supporting Java Clients

Enabling Oracle Data Service Integrator Support for ADO.NET Clients

Generating an Oracle Data Service Integrator Web Services Mapper

Viewing an ADO.NET-Enabled WSDL

Creating a Web Reference in ADO.NET Client by Providing the Oracle Data Service Integrator WSDL URL

Adapting Oracle Data Service Integrator 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

Data Service 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

Using Inverse Functions to Improve Query Performance

The Inverse Function Solution

Understanding Invertible Functions

How Inverse Functions Can Improve Performance

A Closer Look

Examining the Inverse Functions Sample

Creating the Underlying Java Functions

Creating the Physical Data Services Based on the Functions

Adding Comparison Logic to the Data Service

Configuring the Inverse Functions

Associating Custom Conditional Logic with Functions

Creating the Data Service

How To Set Up the Inverse Functions Sample

Requirements

Importing the Dataspace Project

Assigning a Targeted Runtime

Exploring the Inverse Functions Sample

Exploring the Projects

Exploring the InverseFnHowTo Dataspace Project

Exploring the JavaFunctionLib Project