ds 42 adapter sdk en

7/27/2019 Ds 42 Adapter Sdk En

1/114

SAP Data Services

Document Version: 4.2 Support Package 2 (14.2.2.0) - 2014-05-29

User Guide for Adapter SDK


2/114

Table of Contents

1 Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

1.1 Audience and assumptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

1.2 Related documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

1.3 Installation contents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

1.4 Naming Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

2 Adapter SDK Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9

2.1 Adapter SDK components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

2.2 Installation details. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

2.3 After installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

2.4 Establishing adapter management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

2.4.1 Configuring a Job Server for adapter management on Windows. . . . . . . . . . . . . . . . . . . . . . . 11

2.4.2 Configuring a Job Server for adapter management on UNIX. . . . . . . . . . . . . . . . . . . . . . . . . . 12

3 Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

3.1 Adapters and information resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

3.1.1 Information resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

3.1.2 Adapters and front-end applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

3.1.3 Adapters and back-office systems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

3.1.4 Adapter types and capabilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .153.2 Adapters in the Data Services platform. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

3.2.1 Custom adapter usage examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16

3.2.2 Adapters in the Data Services architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

3.2.3 Adapters and Job Servers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18

3.3 Flexible adapter architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18

3.4 Adapter component model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

3.4.1 Component overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

3.4.2 System-defined components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

3.4.3 User-defined components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

3.5 The Adapter SDK API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

3.5.1 com.acta.adapter.sdk. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

3.5.2 com.acta.metadata. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

3.5.3 Interfaces implemented by the Adapter SDK. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

3.5.4 Interfaces implemented by adapter writers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

3.6 Operation exchange models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

3.6.1 Message-oriented exchange model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

3.6.2 Stream-oriented exchange model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

3.7 Adapters and operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

3.8 Basic operation models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

2 2014 SAP AG or an SAP affiliate co mpany. All rights reserved.User Guide for Adapter SDK

Table of Contents


3/114

3.8.1 Interaction style. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

3.8.2 Interface styles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

3.8.3 Basic operation types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

3.9 Adapter start-up sequence. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39

3.9.1 Adapter operation execution. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

3.10 Adapters in the DataServices Designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

3.10.1 Data flow sends a message to an adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

3.10.2 Adapter invokes real-time service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

3.11 Adapter administration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

4 Creating an Adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

4.1 Preliminary considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

4.1.1 Determine integration issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454.1.2 Understand your information resource. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

4.1.3 Plan adapter components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

4.1.4 Plan adapter operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

4.2 Write your custom adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

4.2.1 Adapter writer checklist. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

4.2.2 Create an Adapter component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

4.2.3 Create a Session component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51

4.2.4 Create Metadata Node component(s). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

4.2.5 Create a Metadata Browsing component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

4.2.6 Create Metadata Import component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

4.2.7 Create an Operation component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60

4.2.8 Customize presentation of adapter components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

4.2.9 Error handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

4.2.10 Trace and error logging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

4.2.11 Statistics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

4.3 Create adapter user documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

4.4 Adapter operation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

4.4.1 Compile and package adapter components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

4.4.2 Prepare configuration templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .79

4.4.3 Configure adapter instance components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

4.4.4 Debug the adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

4.4.5 Moving the adapter from test to production. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

4.4.6 Moving a production adapter to another environment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

5 Packaging and deployment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

6 Configuring and Running an Adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .85

6.1 Adapter configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

6.1.1 Preparing configuration templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85


Table of Contents 2014 SAP AG or an SAP affiliate company. All rights reserved. 3


4/114

6.1.2 Configuring an adapter instance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

6.1.3 Configuring an adapter operation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

6.2 Starting the Adapter SDK driver. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

6.2.1 Starting an adapter using the command prompt. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93

7 TestAdapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

7.1 Understanding TestAdapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

7.2 TestAdapter and associated files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

7.3 TestAdapter source code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

7.4 Preparing and testing TestAdapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

7.4.1 Populate the Data Services repository. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

7.4.2 Configure real-time services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .99

7.4.3 Configure adapter (start-up and run-time). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1007.4.4 Configuring operations for TestAdapterInstance in the Administrator. . . . . . . . . . . . . . . . . .102

7.4.5 Starting the adapter instance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

7.4.6 Creating the TestAdapter datastore. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103

7.4.7 Testing browse and import metadata capabilites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

7.4.8 Importing TestAdapter metadata by name. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

7.4.9 Other options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

7.4.10 Starting real-time services for TestAdapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

7.4.11 Verify message-oriented adapter operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

7.4.12 Verify stream-oriented adapter operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

8 Debugging in Eclipse. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

8.1 Debugging in Eclipse. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112


Table of Contents


5/114

1 Introduction

SAP is committed to providing an open architecture that enables customers and partners to seamlessly integratethe Data Services Platform and its processes with non-SAP and other data and processes. Data Services

interfaces use adapters to accomplish this objective.

The Data Services Adapter Software Development Kit (SDK) contains tools for creating adapters that integrate

Data Services with information resources (IRs). An information resource is a producer or consumer of

enterprise information. Information resources range from flat files and back-office applications to EAI systems

and Web applications.

This version of the Adapter SDK provides tools for creating full-capability adapters that support Data Services

batch and real-time operations beyond message-oriented operations.

This user guide provides Data Services Adapters relationship framework information, instructions to help you

install the Adapter SDK, and guidelines for writing full-capability adapters.

1.1 Audience and assumptions

This document assumes that you have:

Access to an Data Services documentation set that is compatible with this version of the Data Services

Adapter SDK.

A basic understanding of how the Data Services Designer is used to design data flows. (To use an adapter, a

data flow must contain adapter-related transforms or must use real-time job services.)

A basic understanding of how the Data Services Management Console Administrator is used to administer

Data Services processes. (Adapters are administered from the Data Services Administrator only.)

Experience writing Java applications in Java programming language.

1.2 Related documentation

Documentation Description

Adapter SDK API documenta

tionThe companion to this book, the online API documentation contains detailed in

formation necessary for writing Data Services adapters. After you install the

Adapter SDK, you can find the online API documentation in the following loca

tion:

Windows:\adapters\sdk\doc\API\index.html

UNIX:/adapters/sdk/doc/API/index.html

Data Services documentation Data Services comes with a complete documentation set that describes the

Data Services suite of related applications and features.


Introduction 2014 SAP AG or an SAP affiliate company. All rights reserved. 5


6/114

Documentation Description

To learn about designing batch and real-time data flows, see the Designer

Guide.

To learn about administering Data Services processes, see theAdministrator

Guide

1.3 Installation contents

This version of the Data Services Adapter SDK includes:

Adapter SDK API documentation

Java libraries to support the Adapter SDK

Test adapter (basic full-function adapter) with source code and step-by-step instructions on how to use it

User Guide for Adapter SDK (published in PDF format)

1.4 Naming Conventions

In this documentation, the following naming conventions apply:

Terminology

Data Services system refers to SAP Data Services.

BI platform refers to SAP BusinessObjects BI platform.

Note

The BI platform components required by Data Services may also be provided by SAP BusinessObjects

Information platform services (IPS).

CMC refers to the Central Management Console provided by the BI or IPS platform.

CMS refers to the Central Management Server provided by BI or IPS platform.

Variables

Variables Description

The installation directory for the SAP software.


Introduction


7/114


Default location:

C:\Program Files (x86)\SAP BusinessObjects

$HOME/sap businessobjects

The root directory of the BI or IPS platform.

Default location:

\SAP BusinessObjects Enterprise XI 4.0

/enterprise_xi40

Note

These paths are the same for both the SAP BusinessObjects BI platform and SAP

BusinessObjects Information platform services.

The root directory of the Data Services system.

Default location:

All platforms

/Data Services

This system environment variable is created automatically during installation.

The common configuration directory for the Data Services system.

Default location:

Windows (Vista and newer)

ALLUSERSPROFILE\SAP BusinessObjects\Data Services

Windows (Older versions)

ALLUSERSPROFILE\Application Data\SAP BusinessObjects\Data

Services

UNIX systems (for compatibility)

This system environment variable is created automatically during installation.

The user-specific configuration directory for the Data Services system.

Default location:

Windows (Vista and newer)

USERPROFILE\AppData\Local\SAP BusinessObjects\Data Services

Windows (Older versions)

USERPROFILE\Local Settings\Application Data\SAP BusinessObjects

\Data Services

This user environment variable is created automatically during installation.


Introduction 2014 SAP AG or an SAP affiliate company. All rights reserved. 7


8/114


Note

This variable is used only for Data Services client applications on Windows, such as the

Designer.is not used on UNIX platforms.


Introduction


9/114

2 Adapter SDK Installation

2.1 Adapter SDK components

Adapter SDK components include:

Adapter SDK API documentation.

Adapter SDK library acta_adapter_sdk.jar(also called Adapter run-time jar file).

Interfaces for the adapter components.

Supporting classes.

Adapter container This unexposed adapter container instantiates and manages objects for the adapter

component classes. Adapter driver This unexposed adapter driver is the executable java code that creates an instance of

the adapter container.

The broker client acta_broker_client.jar

Third party libraries xerces.jar(the XML parser)

A test adapter you can use as a design template acta_test_adapter.jar

Utilities to support the Adapter SDK acta_tool.jar

User Guide for Adapter SDK This book. Instructions for using the test adapter are included in this

document.

2.2 Installation details

You can install the Adapter SDK on both Windows and UNIX operating systems.

For both Windows and UNIX, the Adapter SDK is installed during a normal Data Services installation. During the

Data Services installation procedure, need to select the Message Client component.

2.3 After installation

After installing the Adapter SDK on your computer, you should have the following primary directories and files:

Directory Description

adapters This directory contains all information related to adapter start-up and run-time. Besides con

taining several sub-directories, this directory contains the following files:

AdapterInstallationTemplate.xml: This XML file is a generic template for creating

your own adapter start-up installation template


Adapter SDK Installation 2014 SAP AG or an SAP affiliate company. All rights reserved. 9


10/114


startup_script.xml: This XML start-up script is automatically generated when you

run an adapter for the first time, and automatically updated each time you configure, update, or remove the adapter instance. It contains an entry for each adapter instance con

figured on the computer where it resides. This file does not appear during initial Adapter

SDK installation because no adapter instances are configured yet.

rtt.bat: (rtt.shon UNIX) This is the batch file that generates the adapter run-time

configuration template.

lib This directory contains the following software files:

acta_adapter_admin.jar

acta_adapter_sdk.jar

acta_broker_client.jar

acta_test_adapter.jar

acta_tool.jar

Inside the adapters directory, you should have the following sub-directories and associated files:


config For each adapter instance configured on this computer, this sub-directory contains an

XML run-time configuration script for that instance. The naming convention for script files

is: .xml.

config/

templates

For each adapter installed on this computer, this sub-directory contains an XML run-time

template related to that adapter. The naming convention for template files is:

.xml. The scripts in the config sub-directory are generated based on

these templates (described below). During initial installation, this directory contains only

the TestAdapter.xmlrun-time template for the test adapter.

install Files in this sub-directory are start-up installation templates used by the Data Services Ad

ministrator to create the start-up script entry in the startup_script.xmlfile. This sub-

directory contains one XML descriptor file for each installed adapter. The naming conven

tion for descriptor files is .xml. During initial installation, this directory

contains only the TestAdapter.xmldescriptor file for the test adapter.

log This sub-directory is generated automatically when you run an adapter for the first time. It

contains up to two (trace and error) log files for each running adapter instance. The nam

ing convention for these log files is _trace.txtfor trace

files and _error.txtfor error files.During initial installa

tion, this directory is empty.

sdk/doc/API This directory contains the Adapter SDK API documentation. Open index.htmlto view

the online documentation.

sdk/samples This directory contains all information related to the sample adapter included with the

Adapter SDK (TestAdapter) and includes the testadapter sub-directory.

sdk/samples/

testadapter

This directory contains batch files, XML documents, DTD files, and the ATL file used by the

test adapter as well as the data subdirectory.


Adapter SDK Installation


11/114


sdk/samples/

testadapter/

data

This directory contains a session data sub-directory (Session1), the sample adapter

source file sub-directory (src), and files that TestAdapter uses to demonstrate message-

oriented adapter operations.

sdk/samples/

testadapter/

data/session1

This directory contains the data files that TestAdapter uses to demonstrate metadata

browsing, metadata import, and stream-oriented adapter operations.

sdk/samples/

testadapter/src

This directory contains the sub-directory structure: com/acta/adapter/testadapter.

This testadapter sub-directory contains all the java source files used to create TestAdap

ter.

In the/ext/directory, you should also find the Java Run-Time environment and additional library

used by the Adapter SDK (LINK_DIR/ext/lib/xerces.jarand/ext/lib/

roguewave.jar).

2.4 Establishing adapter management

Before or after installing the Adapter SDK on a computer, you must configure a repository and a Job Server for

adapter management.

Note

You cannot configure or use a Data Services adapter (including the sample TestAdapter) unless adapter

management is established.

2.4.1 Configuring a Job Server for adapter management onWindows

Context

Choose a Job Server to perform adapter management per computer. The adapter management Job Server

brokers messages between Data Services and all adapter instances on that computer.

Procedure

1 On a Windows operating system, choose Start Programs SAP Data Services 4.2 Server Manager .

2 In the Data Services Server Manager, click the Edit Job Server Configbutton.

3 In theJob Server Configuration Editorwindow, do one of the following:




12/114

ClickAddto configure a new a job server

Click to select a Job Server already listed, then click Edit.

TheJob Server Propertieswindow opens.

4 Besides adding/editing the Job Server name, port number, and associated repository information, click to

mark the Enable adapter and message broker communication check box.

5 You may need to re-synchronize your Job Server/repository configuration. If so, click the Resyncbutton. You

must re-synchronize your Job Server and repository when:

You uninstall Data Services then reinstall the same Data Services version without creating a new

repository.

You create a new repository using the Repository Manager after Data Services is installed.

If you re-synchronize a Job Server/repository configuration, you must reassociate this repository with the

Administrator and the metadata reporting tool. See the Data Services Administrator Guidefor more

information.

6 Click OKto save the adapter management setting and return to the Job Server Configuration Editor.

Note

If another Job Server on this computer is already configured to manage adapters, a warning message

appears to let you know that Data Services cannot save your adapter management configuration for the

second Job Server. To configure another Job Server for adapter management, you must first de-select the

Enable adapter and message broker communicationcheck box for the existing adapter management Job

Server.

7 Click OKto return to the Data Services Server Manager window.

8 Click Restartto close the window and restart Data Services services on the computer.

2.4.2 Configuring a Job Server for adapter management onUNIX

Context

Choose a Job Server to perform adapter management per computer. The adapter management Job Server

brokers messages between Data Services and all adapter instances on that computer.

Procedure

1 Change directory to/bin. Run the command: $ . ./al_env.sh.

2 Run svrcfgtool.

3 Select Configure Job Server.

You can edit an existing Job Server or create a new Job Server.

4 After adding/editing a Job Server configuration, you may need to re-synchronize your Job Server/repository

configuration. If so, choose the Resyncoption. You must re-synchronize your Job Server and repository when:


Adapter SDK Installation


13/114

You uninstall Data Services then reinstall the same Data Services version without creating a new

repository.

You create a new repository using the Repository Manager after Data Services is installed.

5 If you re-synchronize a Job Server/repository configuration, you must reassociate this repository with the

Administrator and the metadata reporting tool. See the Managment Console Guidefor more information.




14/114

3 Overview

3.1 Adapters and information resources

Each Data Services Adapter is an application you create using the Data Services Adapter SDK. Data Services

Adapters are part of the Data Services platform and integrate "information resources" source or target

applicationswith Data Services.

Each adapter integrates an information resource with the Data Services platform by communicating with that

resource and translating the resource's information into a format that the Data Services message broker and the

Data Services platform can understand.

Data Services adapters can also publish information from the data platform to the resource in a format that the

information resource understands.

3.1.1 Information resources

Today, information resources are used for in-house data analysis, sell-side e-commerce, supply chain

management, customer relationship management, e-procurement, and more. Regardless of whether they are

front-end or back-office applications, you can integrate many different information resources with Data Services

using custom adapters. Common information resources include:


Overview


15/114

Resource Description

Databases Relational databases such as Oracle, DB2, file system (as the database)

EAI Enterprise Application Integration resources such as Tibco, WEB Methods, and Vitria

ERP Enterprise Resource Planning systems such as Enterprise SAP and PeopleSoft

MOM Message oriented middleware such as IBM MQSeries, Microsoft MSMQ

3.1.2 Adapters and front-end applications

For front-end application integration, an adapter bridges the disparate interfaces of the Data Services message

broker and the resource.

An front-end application adapter is:

relatively simple to develop

connectionless

slow when used for bulk data transfer

This type of adapter usually contains a message-oriented interface and is most appropriate for connecting to EAI

systems.

E-commerce application developers using adapters to integrate data platforms with information resources are

shielded from much integration complexity and are able to perform more transparent application design.

3.1.3 Adapters and back-office systems

Back-office system adapters can support non-SQL based applications like Manugistics as well as applications like

Oracle Financials, Siebel, and Clarify, which contain application level complexity that makes it difficult to extract

data using only a SQL interface.

A back-office system adapter:

is complex

requires connections over a span of time is optimized for moving large amounts of relational data

This type of adapter usually contains a stream-oriented interface appropriate for connecting to bulk data

movement systems.

3.1.4 Adapter types and capabilities

Using the Data Services Adapter SDK, you can create different types of adapters: message-oriented, steam-

oriented, or full capability containing both message- and stream-oriented behavior. Adapter types depend on

the capabilities you include. For example, you can define whether requests can initiate from Data Services, from


Overview 2014 SAP AG or an SAP affiliate company. All rights reserved. 15


16/114

the information resource, or from both. Also, you can specify how adapter metadata imported by Data Services is

handled. It can be handled by:

Native Data Services transforms (sources, targets), or

The adapter's Data Services transforms (sources, targets, function calls)

Using the Adapter SDK, you can program an adapter to do some or all of the following:

Browse resource metadata

Import resource metadata

Receive messages from data flow outbound messages and send acknowledgement

Receive messages from data flow message function calls and send reply

Invoke real-time services

Send records to the Data Services adapter table source transform for table metadata imported from the

adapter

Receive records from the Data Services adapter table target transform defined by table metadata imported

from the adapter

Send records to the Data Services adapter document source transform for document metadata imported

from the adapter

Receive records from the Data Services adapter document target transform defined by document metadata

imported from the adapter

Process SQL generated by Data Services table sources

3.2 Adapters in the Data Services platform

The Data Services platform provides combined batch and real-time data movement services, enabling companies

to leverage ERP and other back-office systems in analytics and e-business. The Adapter SDK significantly extends

these services, allowing you to write custom adapters that integrate Data Services with:

messaging systems (such as EAI)

other types of EAI systems

message-oriented middleware

other real-time information resources

With custom adapters, you can design and implement complex business processes across disparate system and

messaging environments (such as Siebel, SAP ERP and R/3, and Clarify).

3.2.1 Custom adapter usage examples

Example 1

Suppose a customer enters an order through your e-commerce Web site. Data Services collects and augments

the order data, transforms fields, and sends the order information to SAP R/3.

With a custom adapter, you could extend the use of this data beyond SAP R/3. For example, you can update your

data cache and a Siebel instance to keep your entire system synchronized.


Overview


17/114

The capability to integrate data and populate a data cache provides flexibility within the integration layer without

the need to modify existing systems.

Example 2

Perhaps, an application developer wants to use Data Services for populating a data warehouse with Clarify data.

Data Services uses SQL to extract data from the underlying database (either Oracle or Microsoft SQL Server).

SQL cannot be used for the metadata because Clarify does not use the underlying databases's dictionary to store

metadata.

With a custom adapter, you can support a batch data flow that extracts the data. In this case, you can use a

custom adapter to extract the requisite metadata (such as table descriptions, column descriptions, and table

relationships) from Clarify.

3.2.2 Adapters in the Data Services architecture

Data Services uses Job Servers to communicate with clients (including the Data Services engine, adapters, and

real-time services). Each Data Services adapter fits into the overall architecture as a client of an adapter manager

Job Server. This Job Server translates messages between the data format used by Data Services and the format

native to the information resource (IR). The following shows one example of Data Services adapters in the Data

Services architecture.




18/114

3.2.3 Adapters and Job Servers

All adapter instances on a given computer interact with Data Services through a Job Server installed on the samecomputer. Data Services Job Servers contain message brokering capability and multiple Job Servers can be

installed on a single computer. However, only one Job Server is allowed to manage adapters installed on that

computer. So, each adapter instance on a computer is a managed by the same Job Server.

The Job Server starts the adapter driver application which:

Manages the adapter's life cycle by starting, stopping, monitoring, and restarting it if necessary

Performs run-time adapter configuration

Manages multithreading complexities and hides message broker client complexities (you only need to

configure the number of threads for each operation)

Supports centralized adapter administration (through the Data ServicesAdministrator)

Manages resource connections based on connection information in the adapter instance configuration file

Handles and reports errors by responding to exceptions thrown by the developer using the exceptions classes

provided by the API

Performs error and trace logging

3.3 Flexible adapter architecture

The Adapter SDK 2.0 is designed so you can implement a single adapter with message-oriented interfaces (for

real-time operations), "stream-oriented" interfaces (for batch data operations), or interfaces of both orientationsfor full capability. A full-capability adapter would include metadata browsing and import capabilities as well as

both types of interfaces. The Adapter SDK 2.0 has sufficient flexibility to accommodate a variety of adapter

architectures, based on your adapter requirements.

In a full-capability adapter, adapter operations can be presented through the metaphor of a two-lane bridge

between Data Services and an information resource (IR). Each lane of the bridge contains bi-directional traffic for

a specific orientation: one lane implementing stream-oriented interfaces (Examples: TableSource, TableTarget)

and the other lane implementing message-oriented interfaces (Examples: ListenerOperation, PollOperation). See

the online API documentation in for interface details.

While all adapter operation instances must implement the Operation interface, all metadata capabilities do not

necessarily require an operation interface (unless you want to expose operation instance metadata for message-

oriented operations to Data Services). To obtain external metadata browsing and import capabilities, implement

associated metadata interfaces.


Overview


19/114

3.4 Adapter component model

The Adapter SDK includes an unexposed adapter container. This container is an internal structure that

instantiates and holds all user-defined adapter components. Each component is:

An instance of a user-defined Java class that implements one or more interfaces exposed by the Adapter SDK

A Java Bean requiring compliance with Java Bean properties and introspection specifications

3.4.1 Component overview

Each component plays at least one role in an adapter. The following table alphabetically lists each component with

how it is defined and what it does.

Component name Defined by Component role

Adapter Adapter writer Connects adapter to the information resource (IR).

AdapterEnviron

ment

System Links user-defined components.

Adapter Operation Adapter writer Supports adapter stream and message operations.

Import by Name Adapter writer Allows users to import IR metadata by name into Data Services. (Re

quires Metadata Import.)

Metadata Browsing Adapter writer Allows users to visually browse IR metadata.

Metadata Import Adapter writer Allows users to import IR metadata into Data Services.

Metadata Node Adapter writer Makes it possible for IR metadata to be visually represented as a node-

delimited hierarchy.

OperationEnviron

ment

System




20/114

Component name Defined by Component role

Session Adapter writer Groups components and maintains state (associated with Data

Services adapter datastore).

3.4.2 System-defined components

The Adapter SDK provides two important, system-defined components: AdapterEnvironment and

OperationEnvironment.

3.4.2.1 AdapterEnvironment

The AdapterEnvironment component implements the AdapterEnvironmentinterface provided by the Adapter

SDK as a set of methods that:

Access an adapter's related pre-defined objects

Access an adapter's configured system properties, for each instance

Set the link between user-defined components

Some methods implemented for this interface include:

Method Description

getInstanceName() Accesses the adapter instance name

logTrace(String text) Puts the text string to the adapter's instance trace log

file

setOperationDescriptor (String[]

operationClassNames)

Sets the fully qualified class names of the adapter's op

eration

setSessionClassName (String

sessionClassName)

Sets the fully qualified class names of the adapter's

Session interface implementation

Related Information

Run-time configuration template structure[page 87]

3.4.2.2 OperationEnvironment

The OperationEnviroment component implements the OperationEnviromentinterface provided by the Adapter

SDK as a set of methods that access an adapter operation's:


Overview


21/114

Configured system properties

Dynamic properties

Related pre-defined objects

Some methods implemented for this interface include:

Method Description

getInstanceName() Accesses the adapter instance name

println(String text); Adds text strings to the adapter instance trace log file

when debug trace is activated

public void incrementRequestCount() Increments by 1 the number of requests received by

the operation

invokeService(String serviceName, String

xml, int timeout)

Invokes real-time services provided by Data Services

The adapter container:

Creates instances of the AdapterEnvironment and OperationEnvironement components, then

Passes references for user-defined components (based on initialize method parameters) to these system-

defined components

Note

All methods implemented by the Adapter SDK are listed in the Adapter SDK API documentation.

Related Information

Run-time configuration template structure[page 87]

3.4.3 User-defined components

You define each component in its own class by implementing the corresponding (and other associated)

interface(s) exposed by the Adapter SDK (see online API documentation for details). User-defined components

include:

Adapter

Adapter Operation (for both stream- and message-oriented operations)

Session

Metadata Node (required for Metadata Browsing)

Metadata Browsing

Metadata Import (can include the Import by Name component)

When an adapter starts, the adapter driver instantiates the adapter container that creates and manages the

instances of the user-defined adapter components. The rules governing relationships among instances of user-

defined adapter components in an adapter container are:




22/114

One Adapter component instance allowed per container.

One or more instances of the Adapter Operation, Session, Metadata Browsing, and Metadata Import

components allowed per container.

One or more Metadata Node and Import By Name components allowed per container.

The Adapter component is directly or indirectly associated with all other components in its container,

referenced inside the initialize()method.

Example of Direct Reference: Initialization of the Import object from the TestAdapter (Import.java):

public void initialize (Adapter adapter, AdapterEnvironmentadapterEnvironment, Session session) { _adapterEnvironment = adapterEnvironment ; _adapter = (TestAdapter)adapter ; _session = (TestSession)session ; }

Example of Indirect Reference: Initialization of the Operation interface initialize ()method:

public void initialize (OperationEnvironment adapterOperationEnvironment) {_adapterOperationEnvironment=adapterOperationEnvironment;_adapter = (TestAdapter)_adapterOperationEnvironment.getAdapter();}

An instance of the Session component can be associated with one or more instances of Adapter Operation,

Metadata Browsing, and Metadata Import components.

The following diagrams show adapter components and relationships among adapter component instances:


Overview


23/114

3.4.3.1 Adapter

This component is required for all adapters. To create this component, you must implement the Adapter interface

the core life-cycle interface for all Data Services adapter instances. The Adapter interface includes a set of

methods called by the adapter container. All adapters must implement the Adapter interface. An additional

interface you can implement for this component is the SQLEnable interface.

The Adapter component is configurable and responsible for connecting the adapter to an information resource. A

reference to the Adapter component is available for Session, MetadataBrowsing, and Import objects as a

parameter of the initialize() method.

Adapter operations can access the adapter object through the getAdapter()method of the

OperationEnvironment object, which is also a parameter of the initialize()method of the adapter operation.

3.4.3.2 Adapter Operation

The Adapter Operation component is optional, configurable, and supports either a message-oriented or a stream-

oriented exchange model for adapter operations, depending on which additional interfaces you implement. To




24/114

create this component, you must implement the Operation interfacethe basic life-cycle interface for all Data

Services adapter operations.

3.4.3.3 Session

The Session component is optional and used by the adapter container for grouping and maintaining state. To

create this stream-oriented component, you must implement the Session interface. This component can be

associated with every Adapter Operation, Metadata Browsing, and Metadata Import component in the adapter's

environment. With a Session component, the adapter container creates a Session object upon request from an

adapter client (Data Services Designer or engine).

The Session component is associated with the adapter datastore, created and configured in the Data Services

Designer. Session property values, configured in the datastore Adapter Properties tab, determine Session state.

The Designer allows users to create multiple adapter datastores for each running adapter instance. Each adapter

datastore with configured session properties is unique and associated with a unique set of datastore objects,

grouped as follows:

Metadata browsing objects

Metadata import objects

Data Services metadata imported from the IR

Adapter sources, targets, and function calls belonging to the datastore (because they were created from the

datastore's metadata)

For these Data Services objects, the adapter container creates and manages corresponding stream-oriented

Operation, Metadata Browsing, and Metadata Import component instances. All these instances share the same

Session state (configured datastore properties) associated with that Data Services object.

However, the adapter writer does not have direct control over the Session object life-cycle as it is both created

and destroyed on request from an adapter client (Data Services Designer or engine).

The Adapter SDK can handle simultaneous Session components. For every component associated with a Session,

the Adapter SDK generates a unique ID for that component/Session pair. An adapter client uses use this ID when

making metadata browsing and import requests, or when starting a stream-oriented operation.

To refer to the Session component from an operation, use the getSession()method from the

OperationEnvironment interface implemented by the Adapter SDK . For example:

public void initialize (OperationEnvironment OperEnv) { _operEnvironment=operEnvt; _adapter=(TestAdapter)_operEnvironment.getAdapter(); _adapterEnvironment= _operEnvironment.getAdapterEnvironment(); _session= (TestSession)_operEnvironment.getSession(); }

To refer to the Session component from another component, like the Metadata Browsing and Metadata Import

components, use a parameter within the initialize ( ) method. For example:

public void initialize (Adapter adapter, AdapterEnvironment adapterEnvironment, Session session) {

_adapterEnvironment = adapterEnvironment; _adapter = (TestAdapter)adapter;


Overview


25/114

_session = (TestSession)session; }

The Session component is associated with the adapter datastore, which is created and configured in the Data

Services Designer. Session properties are configured in the datastore's Adapter Properties tab.

3.4.3.4 Metadata Node

The Metadata Node component is optional and supports the external metadata browsing framework by providing

an organizational structure for representing IR metadata. You can implement different MetadataNode interfaces if

you want your adapter to show hierarchy. The adapter container creates the Metadata Node object upon request

from the Data Services Designer.

3.4.3.5 Metadata Browsing

The Metadata Browsing component is also optional and, combined with the Metadata Node component, supports

the information resource (IR) metadata browsing framework. Implement this interface to give your adapter the

ability to visually browse information resource metadata. To create this component, you must implement the

MetadataBrowsing interface after you implement the MetadataNode interface.

The adapter container creates the Metadata Browsing object upon request from the Data Services Designer. The

Metadata Browsing component is not configurablethe Adapter SDK does not introspect its properties.Metadata Browsing relies upon Metadata Node components to organize and hierarchically represent information

resource metadata.

3.4.3.6 Metadata Import

The Metadata Import component is optional and supports metadata import from information resources to Data

Services . Implement this interface if you want your adapter to have metadata import capability. To create this

component, you must implement the MetadataImport interface.

The adapter container creates the Metadata Import object upon request from the Data Services Designer. The

Metadata Import component is not configurablethe Adapter SDK does not introspect its properties.

The Metadata Import component supports two methods of obtaining information resource metadata:

Method Description

Import metadata from the

browser

From the Designer's metadata browsing window, the "import" command imports

metadata while browsing a node or group of nodes. Implement the public Vector

importMetadata (MetadataNode resourceMetadataNode)method of the

MetadataImport interface.

Import metadata by name Right-click in the Designer's Adapter Datastore to use the Import By Name option.

To support an adapter's import-by-name capabilities, create the Import by Name




26/114

Method Description

component by implementing the ImportByName interface. Metadata Import uses

the instance of this component as a parameter of the importMetadatamethod

to represent the properties the user must define for importing the metadata.

For both ways of obtaining metadata, the implementation of the ImportMetadatamethod returns the vector of

AWMetadataobjects. AWMetadatais the super class for objects that represent all types of Data Services

metadata:

AWTableMetadata

AWDocumentMetadata

AWFunctionCallMetadata

AWOutboundMessageMetadata

AWMessageFuctionCallMetadata

Each of these objects represents Data Services native metadata.

importMetadata()methods of the MetadataImport interface implementation should return the Vector of these

objects.

Note

See the TestAdapter source code for the examples of the importMetadata()implementation.

To import metadata from the metadata browser for message-oriented operations, implement the Exportable

interface for the adapter operation. The AWMetadata[] exportMetadata()method of this interface should

return an array of AWMetadata objects that could be either AWOutboundMessageMetadata orAWMessageFuctionCallMetadata.

Another method of this interface, int getMeadataType(), should return the type of the metadata the message-

oriented operation can expose:

com.acta.metadata.AWMetadata.AWT_OUTBOUND_MESSAGE

or

com.acta.metadata.AWMetadata.AWT_MESSAGE_FUNCTION_CALL

To export metadata belonging to a message-oriented adapter operation implementing the ListenerOperation

interface, use the AW- classes in the adapter.metadata package. For more information, see

CallFromRtdf.javaand ReceiveFromRtdf.javaimplementation details in the TestAdapter source code. Seethe com/acta/adapter/testadapter directory.

3.4.3.7 Import by Name

The Import By Name component is also optional and supports metadata import from information resources to

Data Services. Implement this interface if you want your adapter to have metadata import capability. To create

this component, you must implement the MetadataImport interface. The adapter driver creates the Metadata

Import object upon request from the Data Services Designer.


Overview


27/114

3.5 The Adapter SDK API

You implement interfaces, classes, and methods exposed by the Adapter SDK API to define adapter components.

Interfaces and classes are contained in two Adapter SDK API packages:

com.acta.adapter.sdk

com.acta.metadata

For detailed information about all Adapter SDKAPI classes, interfaces, and methods view the online

documentation:LINK_DIR/Data Services/adapters/sdk/doc/API/index.html.

3.5.1 com.acta.adapter.sdk

Use this package for all adapters. The com.acta.adapter.sdk package includes the following interfaces:

Interface Description

Adapter The core interface required for all adapters; this class has been updated to reflect binary da

tabase communication

AdapterEnviron

ment

Used to access an adapter's configuration properties and system objects and link adapter

components

Delimited The interface for stream-oriented adapter operations that must read or write data using a de

limited format.

Document

Source and Doc

umentTarget

Used for document readers and document loaders, respectively

EnableCDC

Exportable Exposes a message-oriented operation's metadata to the Adapter SDK

FunctionCall Used for BAPI-like function calls made to an information resource

GuiAttributes Used for JavaBeans (adapter, operations, import by name and session) customization

ImportByName Used for importing metadata by name

ListenerOpera

tion

Automatically subscribes an operation to the message type derived from the operation in

stance name

MetadataBrows

ing and Metada

taImport

Used for browsing and importing metadata, respectively

MetadataNode Required for metadata browsing implementations (objects returned by the MetadataBrows

ing interface must implement MetadataNode)

Operation Required for message-oriented and stream-oriented operations

OperationEnvir

onment

Provides access to adapter and operation properties




28/114


Pushdown Used for controlling pushdown at the datastore and column levels.

PollAdapter andPollOperation

Used for adapters that must perform actions periodically

QueryInXML

Session Optional life-cycle interface providing adapter properties configuration for stream adapters

SourceCDC

SQLAdapter Used for native, full, or partial SQL calls on an information resource.

SQLEnable Returns rows as described by the metadata for the TableSource in the Data Services data

flow

Statistics Used for collecting and displaying adapter statistics in the Data Services Administrator (for

example, adapter status, number of messages processed, and so on)

StreamOpera

tion

The basic interface for stream-oriented operations

Table Supports Table Sources and Table Targets from the Data Services data (a sub-interface for

TableSource and TableTarget interfaces)

TableSource and

TableTarget

Used for table sources and table targets, respectively

3.5.2 com.acta.metadata

This package contains optional classes for working with Data Services metadata in stream-oriented adapters. It

contains no interfaces, but includes the following classes:

Class Description

AWAttribute Sets attributes for Data Services table metadata

AWColumn Sets columns for Data Services table metadata

AWDocumentMetadata

Defines the Data Services document metadata

AWForeignKey Sets foreign keys for Data Services table metadata

AWFunctionCall

Metadata

Defines Data Services function call metadata for streams

AWIndex Sets the index for Data Services table metadata

AWMessage

FunctionCallMe-

tadata

Defines the Data Services message function call metadata

AWMetadata The super class for all Adapter SDK objects representing Data Services metadata


Overview


29/114

Class Description

AWOutbound

MessageMeta-

data

Defines Data Services outbound message metadata

AWPkFkPair Sets the primary key/foreign key pairs for the AWForeignKey object

AWTableMeta

data

Defines Data Services table metadata

AWUniqueKey Sets the unique key for Data Services table metadata

ResourceMeta

data

Sets user-defined metadata in the Data Services repository

3.5.3 Interfaces implemented by the Adapter SDK

The Adapter SDK provides implementations of these interfaces:


AdapterEnviron

ment

A set of methods to access an adapter instance's objects (for example,

getInstanceName()).

OperationEn

viroment

A set of methods to access an adapter (for example,getAdapter()) and its operations'

properties (for example, getInstanceName()).

3.5.4 Interfaces implemented by adapter writers

The only interface you must implement in your adapter is adapter.sdk.Adapter to create the required Adapter

component. To expand adapter capabilities, implement other available interfaces. Some capabilities apply to only

message-oriented operations, others apply only to stream-oriented operations, some apply to both.

This table lists each adapter component with associated Data Services component(s), associated interface(s)

capability, and exchange model:

Component Interface s) Capability w/exchange

model)

Adapter Data Services

Adapter Adapter datastore REQUIRED: SQLAdapter

OPTIONAL: Pushdown

Provide support for native SQL

(import metadata only) or full

SQL (stream)

Session Adapter datastore REQUIRED: Session

OPTIONAL: EnableCDC

Configure adapter datastore

properties in the Designer

(stream)




30/114

Component Interface s) Capability w/exchange

model)

Adapter Data Services

Adapter Opera

tion

Real-time services REQUIRED: Operation (use the Op

erationEnvironment.invokeservice

method)

OPTIONAL: PollOperation

Handle a request from the IR

for real-time service (mes

sage)

Outbound message or

Message function call

REQUIRED: Operation and Liste

nerOperation

OPTIONAL: Exportable

Handle a request from an Data

Services real-time service or

data flow (message)

Table sources REQUIRED: TableSource

OPTIONAL: Delimited, SQLEnable,

QueryInXML, SourceCDC

Read operations for use with a

Designer table source

(stream)

Table targets REQUIRED: TableTarget

OPTIONAL: Delimited

Write operations for use with a

Designer table target (stream)

Document sources REQUIRED: DocumentSource Read operations for use with a

Designer document source

(stream)

Document targets REQUIRED: DocumentTarget Write operations for use with a

Designer document target

(stream)

Function calls REQUIRED: FunctionCall Write operations for use with a

Designer function call

(stream)

MetadataB

rowsing

Browser window REQUIRED: MetadataBrowsing and

MetadataNode

Browse metadata (both)

Metadata Im

port

Browser window and Im

port by name dialog

REQUIRED: MetadataImport Import metadata (both)

Import by name dialog REQUIRED: ImportByName Import metadata by name

(both)

Related Information

Operation exchange models[page 31]


Overview


31/114

3.6 Operation exchange models

The Adapter SDK supports two adapter operation exchange models:

Message-oriented exchange model (real-time)

Stream-oriented exchange model (batch)

Each model is associated with different components (component-exchange model associations are mentioned in

the last table of the Interfaces implemented by adapter writers section). Both exchange models implement the

Operation interface (plus one or more additional interfaces included in the com.acta.adapter.sdk packagethey

vary depending on exchange model used for your operation).

Related Information

Interfaces implemented by adapter writers[page 29]

3.6.1 Message-oriented exchange model

The message-oriented exchange model associates Data Services with real-time applications. Typically part of a

real-time job, a message-oriented operation is designed to stay available and runningeither monitoring for

messages to be forwarded to Data Services from an information resource (poll() method of the PollOperation

interface or start() method of the Operation interface), or monitoring for messages to be forwarded to an

information resource from Data Services (ListenerOperation interface). Although message-oriented adapter

operations are designed and optimized for real-time connectivity, they can also be used in batch data flows.

Message-oriented adapter operations process one real-time message at a time and do not require high

throughput movements of data. Otherwise known as "real-time adapter operations", message-oriented adapter

operations move relatively smallthough semantically richamounts of data between external systems and Data

Services .

Each message handled by a message-oriented adapter operation is complete, independent of any preceding or

following message. This type of message does not participate in a "stream." Message "calls" (routed by the Job

Server managing adapters) to such adapter operations have no associated context. Therefore, establishing a

"session" (usage of the Session object) is not supported for this context.

Operations that implement the ListenerOperation interface, associate with the Outbound Message and Message

Function objects in the Designer. Operations that implement the PollOperation interface or no additional

interfaces associate with the real-time service defined for the Access Server in the Administrator.

3.6.2 Stream-oriented exchange model

The stream-oriented exchange model is primarily intended for moving large amounts of data between Data

Services and an information resource. For example, you might use a stream-oriented operation to read a high

volume of data from an ERP (or non-relational) system and load it into a data cache.




32/114

Typically part of a batch data flow, adapters containing a stream-oriented operation are life-cycle dependent on

the Data Services engine. When a data flow is executed, the Data Services engine starts the life-cycle of a stream-

oriented adapter operation. When the data flow completes execution, the engine stops the adapter operation.

Though the architecture has been optimized for high data throughput, a stream-oriented operation can also beused in a real-time job. However, since a stream-oriented operation is not constantly available and running, it is

not suitable for exchange with EAI systems.

Stream-oriented operations require that you implement one of the sub-interfaces associated with the

StreamOperation interface. By implementing the appropriate sub-interface, you can write stream-oriented

operations for use with a Designer table source or target (TableSource or TableTarget sub-interface), a Designer

document source or target (DocumentSource or DocumentTarget sub-interface), or a Designer function call

(FunctionCall sub-interface).

The stream-oriented exchange model can make use of a Session component to retain context. Context allows

stream-oriented operations to maintain the prolonged connections needed to process large batches of rows for a

job. You establish a session, carry out operations, and end the session. Each data flow source or target that uses a

stream-oriented operation has a dedicated connection (session) with the adapter.

The Adapter SDK can run multiple stream-oriented operation instances in parallel. Since stream-oriented

operations typically share one or more objects (for example, a Session object), we recommend that you write

thread-safe code for stream-oriented operations. In particular, you should synchronize usage of the Session and

Adapter objects.

3.7 Adapters and operations

For each adapter type you want to develop, you must create an adapter class, and for each operation type you

want to develop you must create an operation class.

At run-time, the Adapter container instantiates one object for each adapter class and multiple instances of the

operation class type. Each instance of the message-oriented operation type must be configured with a unique

operation instance name.


Overview


33/114

The following example illustrates a simplified adapter model for a hypothetical Clarify x.x adapter. (The illustration

does not show relevant metadata and session instances used to support the operations shown.)




34/114

3.8 Basic operation models

The Data Services Adapter SDK supports one adapter interaction style and two adapter interface styles. Using the

provided API, you can express these interaction and interface styles in the form of two basic operation types (or

business cases), which are discussed later in this section.

3.8.1 Interaction style

Adapter interaction with IRs is always request/reply and the reply is either empty (acknowledgement) or contains

data. In any interaction, when the client requests a service, the server must always send a response. An empty

reply is sent to the client when an outbound message completes. An empty reply is also the response to an invoke

service request.


Overview


35/114

3.8.2 Interface styles

The two basic adapter interface styles are: the IR requests an interaction with Data Services, and Data Servicesrequests an interaction with the IR. With Data Services adapters, all operation types resolve to one of these two

interface styles, with the client initiating the request for service and the server processing the request.

3.8.2.1 IR as client

For example, a sales representative creates a sales order for a customer using a Siebel Enterprise System (IR).

The order is sent as a message to Data Services. Data Services processes the order through a back-office ERP

system application. (Stream-oriented operations do not use this model.)

3.8.2.2 Data Services as client

For example, Data Services requests Available to Promise (ATP) information from i2. (Stream-oriented

operations always use this model.)

3.8.3 Basic operation types

The two basic adapter operation types you can create using the Adapter SDK API are:

Data Services requests IR service and handles reply

IR requests Data Services real-time service and waits for reply

There are also two variations, which are the same as the base case but without a reply. The rest of this section

explains base cases and their variations.




36/114

3.8.3.1 Data Services requests IR service and handles reply

The following illustration shows a real-time scenario applying Data Services as client interface style to message-oriented adapter operations.

This scenario could illustrate how a customer using a Web application might make changes to their profile on the

company Web site. The data is stored in an information resource (IR0).

To process those changes, the Web application sends an XML message to a named real-time service on the Data

Services Access Server. The Access Server starts a job that corresponds to the named service. The job runs the

appropriate real-time job (IR0) processing the Web application's requested changes.

IR sends a request message (using a "message function call" object inside the real-time job) to an adapter

(Adapter:IR0). An adapter operation owned by Adapter:IR0 implements a Java interface (ListenerOperation)

provided by the API.

ListenerOperation listens for and handles the "message function call" that belongs to IR0. To implement the

ListenerOperation interface, the developer writes only one method, handleRequest(). Typically, such an

implementation would include:

Receiving the XML request


Overview


37/114

Providing data mapping between XML and the native format, if necessary

Any other necessary processing

Returning the XML reply

The XML reply is received by the waiting adapter operation. Adapter:IR0 then passes the XML reply to IR0 and IR0

completes its processing.

Note

In a variation of this scenario, Data Services requests IR service and receives an acknowledgement. In this

variation, IR0 uses an "outbound message," not a message function call. The outbound message just waits for

the acknowledgement. In this variation, the ListenerOperation implementation returns a null (empty) message

from the handleRequest() method. This variation is for message-oriented adapter operations only.

This illustration shows a way (for batch or real-time scenarios) the "Data Services as client" interface style applies

to stream-oriented operations.




38/114

3.8.3.2 IR requests Data Services service and handles reply

The following illustration shows an example of the IR as client interface style. It is for message-oriented adapteroperations only.

In the illustration, the adapter receives a request message by polling the resource using the poll()or start()

method in its native format. The adapter translates the message to XML (if necessary).

The Adapter SDK provides implementation of the OperationEnvironment interface and uses the

invokeService()method to pass the request data to a named real-time service on the Access Server. The

service runs the appropriate real-time job to process the data (perhaps enriching it with cached information) and

returns an XML result to the adapter.

The adapter completes the operation by translating the XML result to the IR application's native format (if

necessary) and sending the information to the IR application, which is waiting for a reply to its request.

Note

A variation of this scenario is IR requests Data Services service and receives acknowledgement. In such a

variation, the developer would not code a return for the poll()method (return is null), if used. This variation is

for message-oriented adapter operations only.


Overview


39/114

3.9 Adapter start-up sequence

Configure adapters and adapter operations in the Data Services Administrator . After configuring start-up and

run-time information, you can start adapter instances. Starting an adapter instance causes the adapter driver to

create an adapter container which runs the following start-up sequence:

1 Create a new instance of your adapter class.

2 Invoke the adapter's initialize()method and set a reference to the AdapterEnvironment object created

by the Adapter SDK where it binds adapter components operations, session, metadata browser, metadata

import, statistics (if applicable) together. See the Adapter SDK API document for details.

3 Introspect the adapter's system and user-defined properties to the values configured for them in the adapter

instance run-time configuration.

4 Invoke the start()method, which starts adapter processing. (This is where you write code that connects

your adapter to the information resource.)After the start() method exits, the adapter is ready to start its operations and to poll an information resource.

5 Invoke the stop()method to stop adapter message processing when the Job Server gets an adapter

shutdown or abort messagefor example, from the Data Services Administrator. (This is where you write

code to close the connection to the information resource and deinitialize the system.)

With a shutdown message, the Adapter SDK gives the adapter an unlimited amount of time to stop gracefully

(by completing processing of all outstanding requests). With an abort message, the adapter process stops

immediately (without waiting for adapter operations to complete processing outstanding requests).

3.9.1 Adapter operation execution

After an adapter starts (when the adapter start()method exits), message-oriented and stream-oriented

operations can be started.

The Adapter SDK automatically starts all message-oriented operations whose enable system property is set to

"true". The operator must manually start all other message-oriented operations.

Stream-oriented operations are started upon client (Data Services Designer or engine) request. Operators cannot

manually start stream-oriented adapter operations from the Administrator. Only a client request to start a

stream-oriented adapter operation will cause an unstarted adapter to start.

The Adapter SDK runs the following start operation instance sequence which:

1 Creates a new instance of the adapter operation.

2 Invokes the initialize()method and uses your code to initialize the operation instance.

For stream-oriented operations, the Adapter SDK will create a new or reuse the existing session object (refer

to AdapterOperationEnvironment.getSession()inside the initialize()method).

3 Introspects the operation instance code and sets configurable properties to the values configured for them in

the adapter operation instance configuration script from the run-time configuration file (message-oriented

operations) or received from the Data Services engine (stream-oriented operations).

4 Invokes the start()method, which starts adapter operation message processing.




40/114

Note

For message-oriented operations, the Adapter SDK begins to accept messages for the

ListenerOperation.handleRequest()method and poll the resource using thePollOperation.poll()method only after the start()method exits.

The start()method must exit when the Adapter SDK receives a request from the Data Services

Administrator to stop the adapter operation. To catch this event, use the

OperationEnvironment.canContinue()method.

Note

For stream-oriented operations, the pairs of begin()and end()methods can be called repeatedly after

start()and before stop()upon engine request to restart data exchange between the adapter and the

engine.

5 Invokes the stop()method when it receives a request from the Data Services Administrator to stop the

adapter or the operation. The stop()method stops operation instance processing.

3.10 Adapters in the Data Services Designer

This section describes how application designers integrate custom adapters into batch jobs and real-time jobs inthe Data Services Designer. For more information about the Data Services Designer, see the Data Services

Designer Guide.

The two basic data flow types used with an adapter are:

Data flow sends a message to an adapter instance (using adapter-related objects in the data flow)

Adapter invokes real-time service (the service provider is a real-time job)

These basic data flow types are discussed in the following sections.

3.10.1 Data flow sends a message to an adapter

Data Services-initiated adapter operation instances are associated with adapter operation-related data flow

objects. All adapter operation-related data flow objects must be created using adapter datastore metadata.

Import information resource metadata into the adapter datastore using the adapter metadata import framework.

Add adapter operation-related data flow objects to Data Services jobs as part of batch or real-time data flows.

Operation instances associated with adapter operation-related data flow objects exchange data upon data flow

request.

Adapter objects in data flows are related to adapter operation instances as follows:


Overview


41/114

Operation Description

Stream-oriented

operations

The adapter operation instance is limited to the metadata types shown in the table below for

creating the data flow's adapter counterpart (source, target, or function call). An adapter

can host only one of each stream-oriented operation type. For example, the adapter can

host only one operation that implements the TableSource interface. Multiple instances of a

stream-oriented operation can be configured within a data flow (adapter table sources) and

created at run-time.

Message-oriented

operations

The adapter operation instance corresponds to the data flow's adapter object counterpart.

This object is created by placing metadata with the same name as the adapter operation in

stance name in the flow. Synchronize the adapter operation instance name with the adapter

object in one of two different ways:

(Recommended) When creating a message-oriented operation, implement the Exporta

ble interface to expose operation metadata through the metadata browsing and import

framework. Name the metadata object returned by the Exportable interface by givingthe same name as the operation instance. Extract the operation instance name from the

OperationEnvironment object using the getInstanceName() method. Use AWMessage

FunctionCallMetadata.setMessageFunctionCallName (String OperationInstanceName)

and AWOutboundMessageMetadata.setOutboundMessageName (String operationIn

stanceName) methods. The operation instance and derived data flow object (message

function call or outbound message) are connected at run-time using this name.

Use the metadata import framework to import information resource metadata. Then,

you can configure the message-oriented operation in the Administrator using the im

ported metadata name as the operation instance name. The data flow outbound mes

sage or message function call derived from this metadata sends a message to the

adapter operation instance having the same metadata name.

When you add metadata importing capabilities to your adapter, Data Services users can:

Import metadata from your adapter

Drag and drop imported adapter metadata objects into their (batch or real-time) data flows

The metadata importable through an adapter datastore is limited to five metadata types, described in the

following table:

Metadata Used in Data Services as:

Documents Document sources or targets in data flows

Function calls Function calls inside query transforms

Message func

tion calls

Function calls inside query transforms

Outbound mes

sages

Outbound messages in data flows

Tables Table sources or targets in data flows

In Data Services , these metadata types (and any metadata objects imported to them) appear under the adapter

datastore icon in the Designer's object library. These metadata types are owned by the Adapter class in the Data

Services repository.




42/114

When an Data Services user runs an application with (batch or real-time) data flows containing imported adapter

metadata, each imported adapter metadata object behaves as follows:

Metadata Ob

ject

Behavior

Document

source

Asks the adapter operation for a batch of documents in the XML format defined by the opera

tion's metadata.

Document tar

get

Sends the adapter operation a batch of documents in the XML format defined by the opera

tion's metadata.

Function call Sends an input XML document to the adapter and waits to receive an output XML reply docu

ment from the adapter operation.

Outbound mes

sage

Sends an input XML document and waits to receive a confirmation message from the adapter

operation.

Table source Asks the adapter operation for a batch of data in the specific XML or delimited format defined

in the operation's metadata.

The data that operation receives from the Data Services engine is packed as records sepa

rated by getRowDelimiter(), with columns separated by getColumnDelimiter(). If the

Delimiter interface is not implemented, the operation uses default value