# Client Application Developer’s Guide

# Introducing Data Services for Client Applications

This chapter provides an overview of Oracle Data Service Integrator for client application developers. It includes the following topics:

- 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
- Client Classpath Settings
- Performance Considerations

## Introduction

Oracle Data Service Integrator brings data access into the world of service-oriented architecture (SOA). Oracle Data Service Integrator enables organizations to consolidate, integrate, transform, and service-enable disparate data sources scattered throughout their enterprise, making enterprise data available as an easy-to-access, reusable commodity: a data service.

From the perspective of a client application, a data service typically represents a distinct business entity, such as a customer or order. Behind the scenes, the data service may aggregate the data that comprises a single view of the data, for example, assembling it from multiple sources and transforming it in a number of ways. A data service may be related to other data services, and it is easy to follow these relationships in Oracle Data Service Integrator. Data services insulate the client application from the details of the composition of each business entity. The client application only has to know the public interface of the data service.

With Oracle Data Service Integrator, client applications can use heterogeneous data through a unified service layer without having to contend with the complexity of working with distributed data sources using various connection mechanisms and data formats. For client developers, Oracle Data Service Integrator provides a uniform, consolidated interface for accessing and updating heterogeneous back-end data. It enables a services-oriented approach to information access using data services.

This document describes how to create Oracle Data Service Integrator-aware client applications. It explains the various client access mechanisms that Oracle Data Service Integrator supports and its main client-side data programming model, including Service Data Objects (SDO). It also describes how to create update-capable data services using the Oracle Data Service Integrator update framework.

- For information about server-side aspects of creating and managing data services, see the Data Services Developer’s Guide.
- For information on administering data services, including metadata, cache, and security management, see the Oracle Data Service Integrator Administration Guide.

## What Is a Data Service?

From a high-level perspective, a data service defines a distinct business entity such as a customer and the customer’s orders. The data service defines a unified view of the business entity by aggregating data from any number of sources — relational database management systems (RDBMS), Web services, enterprise applications, flat files, and XML files, for example. Data services can also transform data from the original sources as needed.

In order to use data services as a client, you need know only a few details, such as:

- The name of the data service.
- The functions and procedures exposed by the data service.
- The data types associated with the data service.

Data service client applications can use data services in the same way that a web service client application invokes the operations of a Web service.

For detailed information on developing data services, see the Data Services Developer’s Guide.

## What is an Oracle Data Service Integrator Client Application?

An Oracle Data Service Integrator client application is any application that invokes data service routines. Client applications can include Java programs, non-Java programs such as Microsoft ADO.NET applications, Oracle WebLogic Workshop applications, JDBC/ODBC, or web-service based applications in any programming language.

- Java client applications can use data service functions and procedures through the Data Services Mediator API (also known simply as the Mediator API).
- Java-based web service applications can use the Mediator API.
- WebLogic Workshop applications (such as portals, business processes, and Web applications) can leverage data services by means of Data Service controls. (Controls are reusable Java components that can be used in WebLogic Workshop applications.) Data Service controls can be used as the basis of many Oracle Data Service Integrator-enabled application scenarios. For example:

- Data Service controls can be added to Web services, portal projects, and Web projects.
- Data Service controls can be used to generate Web services that can make Oracle Data Service Integrator services available to a wide variety of WebLogic and non-WebLogic applications and integration channels.
- Data Service controls can be used within a JPD (Java process definition, a workflow component).

- The Oracle Data Service Integrator JDBC driver provides JDBC clients, such as reporting tools, with SQL-based read access to Oracle Data Service Integrator data. (ODBC clients can use a JDBC bridge to connect to the data.)
- Other web-service based applications can access data service operations through the Oracle Data Service Integrator web services API.

Figure 1-1 provides an overview of these multiple access methods.

Figure 1-1 Accessing Oracle Data Service Integrator Services

Regardless of the client type, Oracle Data Service Integrator provides a uniform, service-oriented mechanism for accessing and modifying distributed, heterogeneous data. Developers can focus on business logic rather than on the details of various data source connections and formats.

In your client application code, a client simply invokes the data service routine; in turn, Oracle Data Service Integrator:

- Gathers data from the appropriate sources (via XQuery).
- Integrates and instantiates the results as data objects.
- Returns the materialized data objects to your client application.

The Oracle Data Service Integrator data objects conform to the Service Data Object (SDO 2.1) specification, a Java-based API for data programming that is the result of joint effort by Oracle, IBM, SAP, and others.

## Choosing a Client Programming Model

Application developers can choose from among several client API models for accessing Oracle Data Service Integrator services. The model chosen will depend on the desired access mechanism. Each access method has its own advantages and uses. Table 1-2 provides a description of each of these access methods and summarizes the advantages of the various programming models for accessing Oracle Data Service Integrator data services.

Table 1-2 Summary of Techniques for Exposing Data Services to Clients
Data Access Technique | Description | Advantages | Other Details
Java Data Service Mediator | Instantiate a remote data service interface and invoke public methods on the interface. See Chapter 3, “Invoking Data Services from Java Clients.” | Full read/write access to data. | Requires adequate Java programming skills.
Web services | Data services can be directly mapped to web services. Clients have access to data through SOAP messages and/or SDOs. See Chapter 4, “Invoking Data Services Through Web Services.” | Read/write access to data. Industry standard. | N/A
SQL | Data service functions first need to be published as SQL objects. These SQL objects are then available to your application through JDBC. See Chapter 5, “Using SQL to Access Data Services.” | Accepted by commonly used reporting tools. | Read-only, and for use SQL-based clients only.
ADO.NET | Allows interoperability between Oracle Data Service Integrator data services and ADO.NET. See Chapter 7, “Supporting ADO.NET Clients.” | Enables Oracle Data Service Integrator data services to be used in Microsoft ADO.NET client applications. | Specific to ADO.NET applications.

## Introducing Service Data Objects (SDO)

Service Data Objects (SDO), a specification proposed jointly by Oracle, IBM, SAP, and others, is a Java-based API for data programming. SDO simplifies data programming against data sources of different types. It simplifies data access, giving data consumers a consistent, uniform approach to using data whether it comes from a database, web service, application, or any other system.

SDO uses the concept of disconnected data. Under this architecture, a client gets a copy of externally persisted data in an SDO data object or data graph, which is a structure for holding data. The client operates on the data remotely; that is, while disconnected from the data source.

If the client makes data changes that need to be saved to the data source, a connection to the source is re-acquired later. Keeping connections active for the minimum time possible maximizes scalability and performance of web and service-oriented applications.

To SDO clients, the data has a uniform appearance no matter where it originated or what its underlying source format is. Enabling this unified view of data in the SDO model is the concept of a data mediator.

The mediator is the intermediary between data clients and back-end systems. It allows clients to access data services and invoke their functions to acquire data or submit data changes. Oracle Data Service Integrator implements such an SDO mediator.

For details on SDO, see Chapter 2, “Data Programming Model and Update Framework.”

## Introducing the Data Service Mediator API

The SDO specification allows for many types of mediators, each intended for a particular type of query language or back-end system. Oracle Data Service Integrator provides a Data Service Mediator API, a server-side component of the Oracle Data Service Integrator XQuery processing engine that serves as the intermediary between data services and client applications or processes.

The Data Service Mediator facilitates access and updates to the various data sources that comprise any data service. The Mediator is also the core mechanism for the data service update framework. For details on using the Mediator API for web services clients and for Java clients, see:

- Chapter 3, “Invoking Data Services from Java Clients”
- Chapter 4, “Invoking Data Services Through Web Services”

Note: | Oracle Data Service Integrator 10gR3 does not support backward compatibility with ALDSP 2.x (all ALDSP 2.x deprecated APIs are no longer supported in Oracle Data Service Integrator 10gR3). This includes all classes in the com.bea.dsp.dsmediator.client and com.bea.ld.dsmediator.update packages.

## Typical Client Application Development Process

Developing an Oracle Data Service Integrator-enabled client applications encompasses these steps:

1. Identify the data services you want to use in your application. The Oracle Data Service Integrator Administration Console can be used to find all services available on your Oracle WebLogic Server. The Oracle Data Service Integrator Administration Console serves as a data service registry within the Oracle Data Service Integrator architecture; it shows available data services, including the specific functions and procedures that each data service provides.
2. Choose the data access approach that best suits your needs. ( Table 1-2, Summary of Techniques for Exposing Data Services to Clients, on page 1-5 describes the advantages of the different access mechanisms.) The approach you choose also depends on how the data service has been deployed.

For example, if the data service has been mapped out as a web service, you can develop a Web service client application using Java in conjunction with the service’s WSDL file.

Similarly, if the data service is incorporated in a portal, business process, or Web application, your client application development process may take place entirely in the context of the server, as a set of pageflows or other server-side artifacts, using a control.

3. Obtain the required JAR files. (See specific chapters in this guide for JAR file requirements.)

## Security Considerations in Client Applications

Oracle Data Service Integrator administrators can control access to deployed Oracle Data Service Integrator resources through role-based security policies. Oracle Data Service Integrator leverages and extends the security features of the underlying WebLogic platform. Roles can be set up in the WebLogic Administration Console. (See the Oracle Data Service Integrator Administration Guide for detailed information about the Oracle Data Service Integrator Administration Console.)

Access policies for resources can be defined at any level — on all data services in a deployment, individual data services, individual data service functions, or even on individual elements returned by the functions of a data service.

For information on Oracle Data Service Integrator security, see “Securing Oracle Data Service Integrator Resources,” in the Oracle Data Service Integrator Administration Guide. For complete information on WebLogic security, see Programming WebLogic Security on e-docs.

## Performance Considerations

Data service performance is the result of the end-to-end components that make up the entire system, including:

- Data service design. The number, types, and capabilities of data sources, complexity of logical data source aggregation, and other data service design considerations can affect performance.
- Number of clients accessing the data service. The number of simultaneous clients can affect performance.
- Performance of the underlying data sources. Since data services access underlying data, the performance and availability of those systems can affect performance.
- Hardware resources. The number of servers, processing power, memory, network structure, and other factors for each and every platform throughout the system, client and server alike, can affect performance.

Before creating a client application for a data service, it is recommended that you be aware of the performance of each underlying data source and benchmark the performance of the data services as you develop them. Use load-testing tools to determine the maximum number of clients that your deployed data services can support.

You can use the Oracle Data Service Integrator auditing capabilities to obtain performance profile information that you can use to identify and resolve performance problems if they occur. For detailed information on Oracle Data Service Integrator audit capabilities see Oracle Data Service Integrator Administration Guide.

## Client Classpath Settings

The following tables provide classpath requirements for:

- Java Mediator API clients (dynamic and static)
- Web Service clients (dynamic and static)
- DSP Control clients
- JMX Mbean Management API clients
- JDBC API clients

### Java Mediator API Clients

Client applications using the Oracle Data Service Integrator Mediator API need one of the following classpath settings:

Listing 1-1 Static Java Mediator API Client Classpath (with weblogic.jar)

    CLASSPATH=
       <dataspace-dsp-client>.jar <= this is the generated static client jar
       <ALDSP_HOME>/lib/ld-client.jar
       <BEA_HOME>/modules/com.bea.core.sdo_1.1.0.0.jar
       <WL_HOME>/server/lib/weblogic.jar

Listing 1-2 Static Java Mediator API Client Classpath (with wlfullclient.jar)

    CLASSPATH=
       <dataspace-dsp-client>.jar <= this is the generated static client jar
       <ALDSP_HOME>/lib/ld-client.jar
       <BEA_HOME>/modules/com.bea.core.sdo_1.1.0.0.jar
       <BEA_HOME>/modules/com.bea.core.xml.xmlbeans_1.0.0.0_2-4-0.jar
       <WL_HOME>/server/lib/wlfullclient.jar

Listing 1-3 Dynamic Mediator API Classpath (with weblogic.jar)

    CLASSPATH=
       <ALDSP_HOME>/lib/ld-client.jar
       <BEA_HOME>/modules/com.bea.core.sdo_1.1.0.0.jar
       <WL_HOME>/server/lib/weblogic.jar

Listing 1-4 Dynamic Mediator API Classpath (with wlfullclient.jar)

    CLASSPATH=
       <ALDSP_HOME>/lib/ld-client.jar
       <BEA_HOME>/modules/com.bea.core.sdo_1.1.0.0.jar
       <BEA_HOME>/modules/com.bea.core.xml.xmlbeans_1.0.0.0_2-4-0.jar
       <WL_HOME>/server/lib/wlfullclient.jar

### Web Services Clients

Client applications using the Oracle Data Service Integrator Native Web Services feature need one of the following classpath settings:

Listing 1-5 Static Web Service Client Classpath (with weblogic.jar)

    CLASSPATH=
       <dataspace-ws-client>.jar <= this is the generated static client jar
                                    for the webservices transport
       <ALDSP_HOME>/lib/ld-client.jar
       <BEA_HOME>/modules/com.bea.core.sdo_1.1.0.0.jar
       <WL_HOME>/server/lib/weblogic.jar

Listing 1-6 Static Web Service Client Classpath (with wlfullclient.jar)

    CLASSPATH=
       <dataspace-ws-client>.jar <= this is the generated static client jar
                                    for the webservices transport
       <ALDSP_HOME>/lib/ld-client.jar
       <BEA_HOME>/modules/com.bea.core.sdo_1.1.0.0.jar
       <BEA_HOME>/modules/com.bea.core.xml.xmlbeans_1.0.0.0_2-4-0.jar
       <BEA_HOME>/modules/com.bea.core.xml.beaxmlbeans_1.0.0.0_2-4-0.jar
       <BEA_HOME>/modules/glassfish.jaxws.rt_2.1.3.jar
       <WL_HOME>/server/lib/webserviceclient.jar
       <WL_HOME>/server/lib/wseeclient.jar
       <WL_HOME>/server/lib/wlfullclient.jar

Listing 1-7 Dynamic Web Service Clients (with weblogic.jar)

`CLASSPATH=
<ALDSP_HOME>/lib/ld-client.jar
<BEA_HOME>/modules/com.bea.core.sdo_1.1.0.0.jar
<WL_HOME>/server/lib/weblogic.jar`

Listing 1-8 Dynamic Web Service Clients (with wlfullclient.jar)

`CLASSPATH=
<ALDSP_HOME>/lib/ld-client.jar
<BEA_HOME>/modules/com.bea.core.sdo_1.1.0.0.jar
<BEA_HOME>/modules/com.bea.core.xml.xmlbeans_1.0.0.0_2-4-0.jar
<BEA_HOME>/modules/com.bea.core.xml.beaxmlbeans_1.0.0.0_2-4-0.jar
<BEA_HOME>/modules/glassfish.jaxws.rt_2.1.3.jar
<WL_HOME>/server/lib/webserviceclient.jar
<WL_HOME>/server/lib/wseeclient.jar
<WL_HOME>/server/lib/wlfullclient.jar`

### DSP Control Clients

DSP Control clients needs the following classpath settings:

Listing 1-9 DSP Control Client Classpath (with weblogic.jar)

`CLASSPATH=
<dataspace-dsp-client>.jar <= this is the generated static client jar
for the DSP Control transport
<ALDSP_HOME>/lib/ld-client.jar
<BEA_HOME>/modules/com.bea.core.sdo_1.1.0.0.jar
<WL_HOME>/server/lib/weblogic.jar`

Listing 1-10 DSP Control Client Classpath (with wlfullclient.jar)

`CLASSPATH=
<dataspace-dsp-client>.jar <= this is the generated static client jar
for the DSP Control transport
<ALDSP_HOME>/lib/ld-client.jar
<BEA_HOME>/modules/com.bea.core.sdo_1.1.0.0.jar
<BEA_HOME>/modules/com.bea.core.xml.xmlbeans_1.0.0.0_2-4-0.jar
<BEA_HOME>/modules/com.bea.core.xml.beaxmlbeans_1.0.0.0_2-4-0.jar
<BEA_HOME>/modules/glassfish.jaxws.rt_2.1.3.jar
<BEA_HOME>/modules/glassfish.stax.ex_1.0.0.0_1-2.jar
<BEA_HOME>/modules/glassfish.jaxb_2.1.6.jar
<BEA_HOME>/modules/glassfish.xmlstreambuffer_0.5.221.jar
<WL_HOME>/server/lib/webserviceclient.jar
<WL_HOME>/server/lib/wseeclient.jar
<WL_HOME>/server/lib/wlfullclient.jar`

### JMX Mbean Management API Client Classpath

The JMX Mbean Management API needs the following classpath settings:

Listing 1-11 JMX Mbean Management API Client Classpath (with weblogic.jar)

`CLASSPATH=
<ALDSP_HOME>/lib/ld-client.jar
<WL_HOME>/server/lib/weblogic.jar`

Listing 1-12 JMX Mbean Management API Client Classpath (with wlfullclient.jar)

`CLASSPATH=
<ALDSP_HOME>/lib/ld-client.jar
<WL_HOME>/server/lib/wlfullclient.jar`

### Oracle Data Service Integrator JDBC API Client Classpath

The Oracle Data Service Integrator JDBC API client needs the following classpath settings:

Listing 1-13 Oracle Data Service Integrator JDBC API Client Classpath (with weblogic.jar)

`CLASSPATH=
<ALDSP_HOME>/lib/ld-client.jar
<ALDSP_HOME>/lib/ldjdbc.jar
<WL_HOME>/server/lib/weblogic.jar`

Listing 1-14 Oracle Data Service Integrator JDBC API Client Classpath (with wlfullclient.jar)

`CLASSPATH=
<ALDSP_HOME>/lib/ld-client.jar
<ALDSP_HOME>/lib/ldjdbc.jar
<WL_HOME>/server/lib/wlfullclient.jar`