User Guide for Adapter SDK

PUBLICSAP Data ServicesDocument Version: 4.2 Support Package 14 (14.2.14.0) – 2021-12-03

User Guide for Adapter SDK

© 2

021 S

AP S

E or

an

SAP affi

liate

com

pany

. All r

ight

s re

serv

ed.

THE BEST RUN

Content

1 Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.1 Audience and assumptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.2 Related documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61.3 Installation contents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61.4 Naming conventions and variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

2 Adapter SDK Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.1 Adapter SDK components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.2 Installation details. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.3 After installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.4 Establishing adapter management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Configuring a Job Server for adapter management on Windows. . . . . . . . . . . . . . . . . . . . . . . . . 14Configuring a Job Server for adapter management on UNIX. . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

3 Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163.1 Adapters and information resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Information resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Adapters and front-end applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17Adapters and back-office systems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Adapter types and capabilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

3.2 Adapters in the Data Services platform. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Custom adapter usage examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Adapters in the Data Services architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Adapters and Job Servers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

3.3 Flexible adapter architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203.4 Adapter component model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Component overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21System-defined components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22User-defined components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

3.5 The Adapter SDK API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29com.acta.adapter.sdk. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29com.acta.metadata. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Interfaces implemented by the Adapter SDK. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31Interfaces implemented by adapter writers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31

3.6 Operation exchange models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33Message-oriented exchange model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Stream-oriented exchange model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

2 PUBLICUser Guide for Adapter SDK

Content

3.7 Adapters and operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343.8 Basic operation models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36

Interaction style. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Interface styles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Basic operation types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37

3.9 Adapter start-up sequence. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41Adapter operation execution. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

3.10 Adapters in the Data Services Designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Data flow sends a message to an adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42Adapter invokes real-time service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

3.11 Adapter administration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

4 Creating an Adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484.1 Preliminary considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Determine integration issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Understand your information resource. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Plan adapter components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Plan adapter operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

4.2 Write your custom adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51Adapter writer checklist. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Create an Adapter component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Create a Session component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54Create Metadata Node component(s). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Create a Metadata Browsing component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Create Metadata Import component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57Create an Operation component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63Customize presentation of adapter components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70Error handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76Trace and error logging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77Statistics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

4.3 Create adapter user documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 814.4 Adapter operation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Compile and package adapter components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Prepare configuration templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Configure adapter instance components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Debug the adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84Moving the adapter from test to production. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84Moving a production adapter to another environment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

5 Packaging and deployment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87

6 Configuring and Running an Adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

User Guide for Adapter SDKContent PUBLIC 3

6.1 Adapter configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88Preparing configuration templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88Configuring an adapter instance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94Configuring an adapter operation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

6.2 Starting the Adapter SDK driver. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95Starting an adapter using the command prompt. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95

7 TestAdapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 987.1 Understanding TestAdapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 987.2 TestAdapter and associated files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 987.3 TestAdapter source code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .997.4 Preparing and testing TestAdapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Populate the Data Services repository. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Configure real-time services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102Configure adapter (start-up and run-time). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103Configuring operations for TestAdapterInstance in the Administrator. . . . . . . . . . . . . . . . . . . . 104Starting the adapter instance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105Creating the TestAdapter datastore. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106Testing browse and import metadata capabilites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106Importing TestAdapter metadata by name. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Other options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107Starting real-time services for TestAdapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Verify message-oriented adapter operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Verify stream-oriented adapter operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

8 Debugging in Eclipse. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1148.1 Debugging in Eclipse. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114


Content

1 Introduction

SAP is committed to providing an open architecture that enables customers and partners to seamlessly integrate the 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 SAP Data Services documentation set that is compatible with this version of the Data Services Adapter SDK.

● A basic understanding of how to use the Data Services Designer to design data flows.

NoteA data flow must contain adapter-related transforms or use real-time job services to use an adapter.

● A basic understanding of how to use the SAP Data Services Management Console Administrator to administer Data Services processes.

NoteAdapters are administered from the Data Services Administrator only.

● Experience writing Java applications in the Java programming language.

User Guide for Adapter SDKIntroduction PUBLIC 5

1.2 Related documentation

Documentation Description

Adapter SDK API documentation The companion to this book, the online API documentation contains detailed information necessary for writing Data Services adapters. After you install the Adapter SDK, you can find the online API documentation in the following location:

● Windows: <DS_COMMON_DIR>\adapters\sdk\doc\API\index.html● UNIX: <LINK_DIR>/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.

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

To learn about administering Data Services processes, see the Administrator 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 and variables

This documentation uses specific terminology, location variables, and environment variables that describe various features, processes, and locations in SAP Business Objects and SAP Data Services.

Terminology

SAP Data Services documentation uses the following terminology:

● The terms Data Services system and SAP Data Services mean the same thing.● The term BI platform refers to SAP BusinessObjects Business Intelligence platform.● The term IPS refers to SAP BusinessObjects Information platform services.


Introduction

NoteData Services requires BI platform components. However, when you don't use other SAP applications, IPS, a scaled back version of BI, also provides these components for Data Services.

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

Variables

The following table describes the location variables and environment variables that are necessary when you install and configure Data Services and required components.

Variables Description

INSTALL_DIR The installation directory for SAP applications such as Data Services.

Default location:

● For Windows: C:\Program Files (x86)\SAP BusinessObjects

● For UNIX: $HOME/sap businessobjects

NoteINSTALL_DIR isn't an environment variable. The installation location of SAP software can be different than what we list for INSTALL_DIR based on the location that your administrator sets during installation.



BIP_INSTALL_DIR The directory for the BI or IPS platform.

Default location:

● For Windows: <INSTALL_DIR>\SAP BusinessObjects Enterprise XI 4.0

ExampleC:\Program Files (x86)\SAP BusinessObjects\SAP BusinessObjects Enterprise XI 4.0

● For UNIX: <INSTALL_DIR>/enterprise_xi40

NoteThese paths are the same for both BI and IPS.

NoteBIP_INSTALL_DIR isn't an environment variable. The installation location of SAP software can be different than what we list for BIP_INSTALL_DIR based on the location that your administrator sets during installation.

<LINK_DIR> An environment variable for the root directory of the Data Services system.

Default location:

● All platforms<INSTALL_DIR>\Data Services

ExampleC:\Program Files (x86)\SAP BusinessObjects\Data Services


Introduction


<DS_COMMON_DIR> An environment variable for the common configuration directory for the Data Services system.

Default location:

● If your system is on Windows (Vista and newer):<AllUsersProfile>\SAP BusinessObjects\Data Services

NoteThe default value of <AllUsersProfile> environment variable for Windows Vista and newer is C:\ProgramData.

ExampleC:\ProgramData\SAP BusinessObjects\Data Services

● If your system is on Windows (Older versions such as XP)<AllUsersProfile>\Application Data\SAP BusinessObjects\Data Services

NoteThe default value of <AllUsersProfile> environment variable for Windows older versions is C:\Documents and Settings\All Users.

ExampleC:\Documents and Settings\All Users\Application Data\SAP BusinessObjects\Data Services

● UNIX systems (for compatibility)<LINK_DIR>

The installer automatically creates this system environment variable during installation.

NoteStarting with Data Services 4.2 SP6, users can designate a different default location for <DS_COMMON_DIR> during installation. If you can't find the <DS_COMMON_DIR> in the listed default location, ask



your System Administrator to find out where your default location is for <DS_COMMON_DIR>.

<DS_USER_DIR> The environment variable for the user-specific configuration directory for the Data Services system.

Default location:

● If you're on Windows (Vista and newer):<UserProfile>\AppData\Local\SAP BusinessObjects\Data Services

NoteThe default value of <UserProfile> environment variable for Windows Vista and newer versions is C:\Users\{username}.

● If you're on Windows (Older versions such as XP):<UserProfile>\Local Settings\Application Data\SAP BusinessObjects\Data Services

NoteThe default value of <UserProfile> environment variable for Windows older versions is C:\Documents and Settings\{username}.

NoteThe system uses <DS_USER_DIR> only for Data Services client applications on Windows. UNIX platforms don't use <DS_USER_DIR>.

The installer automatically creates this system environment variable during installation.


Introduction

2 Adapter SDK Installation

2.1 Adapter SDK components

Adapter SDK components include:

● Adapter SDK API documentation.● Adapter SDK library in the Adapter runtime jar file named acta_adapter_sdk.jar. The library contains

the following elements:○ Interfaces for the adapter components.○ Supporting classes.○ Adapter container: An unexposed adapter container that instantiates and manages objects for the

adapter component classes.○ Adapter driver: An unexposed adapter driver that is the executable java code that creates an instance

of the adapter container.● The broker client file: acta_broker_client.jar ● Third party libraries file: XML parser file xerces.jar● A test adapter that 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, which includes instructions for using the test adapter.

2.2 Installation details

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

For both Windows and UNIX, the SAP Data Services installer installs the Adapter SDK during a normal installation. During the Data Services installation procedure, make sure to select the Message Client component.

2.3 After installation

The installation of the Adapter SDK includes library files that the SAP Data Services installer places on the install machine. The following table describes the directories.

User Guide for Adapter SDKAdapter SDK Installation PUBLIC 11

Directory Description

/adapters Contains all information related to adapter startup and runtime. Besides containing several subdirectories, the /adapters directory contains the following files:

● AdapterInstallationTemplate.xml: A generic template for creating your own adapter startup installation template.

● startup_script.xml: A startup script that the Adapter SDK generates automatically when you run an adapter for the first time. Adapter SDK also updates the script automatically each time you configure, update, or remove the adapter instance. The script contains an entry for each adapter instance configured on the computer where it resides. The script file isn’t present after the initial Adapter SDK installation you haven't config-ured an adapter instance yet.

● rtt.bat: (rtt.sh on UNIX) The batch file that generates the adapter runtime configuration template.

/lib Contains the following software files:

● acta_adapter_admin.jar● acta_adapter_sdk.jar● acta_broker_client.jar● acta_test_adapter.jar● acta_tool.jar

The adapters directory contains subdirectories and associated files as described in the following table.

Subdirectory Description

/config Contains an XML runtime configuration script for each adapter instance that you configure on this computer. The Adapter SDK uses the following naming convention for script files: <adapter_instance_name>.xml.

/config/templates Contains an XML runtime template related to each adapter installed on the computer. The Adapter SDK uses the following naming convention for template files: <adapter_name>.xml.

The Adapter SDK generates scripts in the config subdirectory based on the templates. After the initial installation, the subdirectory contains only the TestAdapter.xml runtime template for the test adapter.

12 PUBLICUser Guide for Adapter SDKAdapter SDK Installation

Subdirectory Description

/install Contains startup installation template files that the SAP Data Services Administrator uses to create the startup script entry in the startup_script.xml file.

Contains one XML descriptor file for each installed adapter. After the initial installation, the subdirectory contains only the TestAdapter.xml descriptor file for the test adapter.

The Adapter SDK uses the following naming convention for each descriptor file: <adapter_name>.xml

/log Generated automatically when you run an adapter for the first time. Contains up to two log files (trace and error) for each running adapter instance.

The Adapter SDK uses the following naming convention for each log file:

● Trace logs: <adapter_instance_name>_trace.txt

● Error logs: <adapter_instance_name>_error.txt

After initial installation, the /log subdirectory is empty.

/sdk/doc/API Contains the Adapter SDK API documentation. The index.html file contains the online documentation for you to open and view.

/sdk/samples Contains all information related to the sample adapter, called TestAdapter, which is included with the Adapter SDK. Also includes the /testadapter subdirectory.

/sdk/samples/testadapter Contains batch files, XML documents, DTD files, and the ATL file that the test adapter uses. Also includes the /data subdirectory.

/sdk/samples/testadapter/data Contains a session data subdirectory (Session1), the sample adapter source file subdirectory (src), and files that TestAdapter uses to demonstrate message-oriented adapter operations.

/sdk/samples/testadapter/data/session1 Contains the data files that TestAdapter uses to demonstrate metadata browsing, metadata import, and stream-oriented adapter operations.

/sdk/samples/testadapter/src Contains the following subdirectory structure: com/acta/adapter/testadapter. The /testadapter subdirectory contains all the java source files that the Adapter SDK uses to create TestAdapter.

The <LINK_DIR>/ext/ directory contains the Java Runtime environment and an additional library used by the Adapter SDK that contains the following files:

● <LINK_DIR>/ext/lib/xerces.jar● <LINK_DIR> /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.

NoteYou 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 on Windows

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.

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 Config button.3. In the Job Server Configuration Editor window, do one of the following:

○ Click Add to configure a new a job server○ Click to select a Job Server already listed, then click Edit.

The Job Server Properties window 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 Resync button.

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 Guide for more information.

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

NoteIf 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 communication check box for the existing adapter management Job Server.

7. Click OK to return to the Data Services Server Manager window.8. Click Restart to close the window and restart Data Services services on the computer.

14 PUBLICUser Guide for Adapter SDKAdapter SDK Installation

2.4.2 Configuring a Job Server for adapter management on UNIX

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.

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

2. Run svrcfg tool.

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 Resync option. 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.

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 Guide for more information.


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 applications—with 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

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, stream-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,

User Guide for Adapter SDKOverview PUBLIC 17

from 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

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.


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 same computer. 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 orientations for “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

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).

AdapterEnvironment 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. (Requires 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.

OperationEnvironment

System


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 AdapterEnvironment interface 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 operation

setSessionClassName (String sessionClassName)

Sets the fully qualified class names of the adapter's Session interface implementation

Related Information

Run-time configuration template structure [page 90]

3.4.2.2 OperationEnvironment

The OperationEnviroment component implements the OperationEnviroment interface provided by the Adapter SDK as a set of methods that access an adapter operation's:

● Configured system properties


Overview

● 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

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

Related Information

Run-time configuration template structure [page 90]

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:


● 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, AdapterEnvironment adapterEnvironment, 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

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 create this component, you must implement the Operation interface—the 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;


Overview

_adapter = (TestAdapter)adapter; _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 configurable—the 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 configurable—the 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.


Method Description

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 component by implementing the ImportByName interface. Metadata Import uses the instance of this component as a parameter of the importMetadata method to represent the properties the user must define for importing the metadata.

For both ways of obtaining metadata, the implementation of the ImportMetadata method returns the vector of AWMetadata objects. AWMetadata is 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.

NoteSee 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 or AWMessageFuctionCallMetadata.

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.java and ReceiveFromRtdf.java implementation details in the TestAdapter source code. See the 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

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 SDK API 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 database communication

AdapterEnvironment 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 delimited format.

DocumentSource and DocumentTarget 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

ListenerOperation Automatically subscribes an operation to the message type derived from the operation instance name

MetadataBrowsing and MetadataImport Used for browsing and importing metadata, respectively

MetadataNode Required for metadata browsing implementations (objects returned by the MetadataBrowsing interface must implement MetadataNode)

Operation Required for message-oriented and stream-oriented operations

OperationEnvironment Provides access to adapter and operation properties



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

PollAdapter and PollOperation 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)

StreamOperation 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

CreateTable Creates a temporary table and then loads data to that table using the TableTarget interface.

ExecuteAny Indicates that the adapter can handle commands in the SQL function.

DescribeQuery Describes the input SQL to obtain output columns.

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

AWFunctionCallMetadata Defines Data Services function call metadata for streams

AWIndex Sets the index for Data Services table metadata


Overview

Class Description

AWMessageFunctionCallMetadata Defines the Data Services message function call metadata

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

AWOutboundMessageMetadata Defines Data Services outbound message metadata

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

AWTableMetadata Defines Data Services table metadata

AWUniqueKey Sets the unique key for Data Services table metadata

ResourceMetadata 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:


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

OperationEnviroment 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)


Component Interface(s)Capability (w/exchange model)

Adapter Data Services

Session Adapter datastore REQUIRED: Session

OPTIONAL: EnableCDC

Configure adapter datastore properties in the Designer (stream)

Adapter Operation Real-time services REQUIRED: Operation (use the OperationEnvironment.invokeservice method)

OPTIONAL: PollOperation

Handle a request from the IR for real-time service (message)

Outbound message or Message function call

REQUIRED: Operation and ListenerOperation

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)

MetadataBrowsing Browser window REQUIRED: MetadataBrowsing and MetadataNode

Browse metadata (both)

Metadata Import Browser window and Import by name dialog

REQUIRED: MetadataImport Import metadata (both)

Import by name dialog REQUIRED: ImportByName Import metadata by name (both)


Overview

Related Information

Operation exchange models [page 33]

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 package—they vary depending on exchange model used for your operation).

Related Information

Interfaces implemented by adapter writers [page 31]

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 running—either 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 small—though semantically rich—amounts 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.

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 be used 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.


Overview

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.

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.)


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

3.8.2 Interface styles

The two basic adapter interface styles are: the IR requests an interaction with Data Services, and Data Services requests 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.


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

● 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.

NoteIn 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.


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 adapter operations 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.

NoteA 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

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 message—for 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.


NoteFor message-oriented operations, the Adapter SDK begins to accept messages for the ListenerOperation.handleRequest() method and poll the resource using the PollOperation.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.

NoteFor 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 in the 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

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 instance 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 Exportable interface to expose operation metadata through the metadata browsing and import framework. Name the metadata object returned by the Exportable interface by giving the same name as the operation instance. Extract the operation instance name from the OperationEnvironment object using the getInstanceName() method. Use AWMessageFunctionCallMetadata.setMessageFunctionCallName (String OperationInstanceName) and AWOutboundMessageMetadata.setOutboundMessageName (String operationInstanceName) 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 imported metadata name as the operation instance name. The data flow outbound message 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 function calls Function calls inside query transforms


Metadata Used in Data Services as:

Outbound messages 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.

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 Object Behavior

Document source Asks the adapter operation for a batch of documents in the XML format defined by the operation's metadata.

Document target Sends the adapter operation a batch of documents in the XML format defined by the operation's metadata.

Function call Sends an input XML document to the adapter and waits to receive an output XML reply document from the adapter operation.

Outbound message Sends an input XML document and waits to receive a confir-mation 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 separated by getRowDelimiter(), with columns separated by getColumnDelimiter(). If the Delimiter interface is not implemented, the operation uses default values.

For XML formats, the operation should pack the data as XML in the following structure:

<AWA_BatchWrapper> < AWA_Row> <colname>...</colname> ... <colname>...</colname> </ AWA_Row> ... < AWA_Row> <colname>...</colname> ... <colname>...</colname> </ AWA_Row> </AWA_BatchWrapper>


Overview

Table target Sends the adapter operation the 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 separated by getRowDelimiter(), with columns separated by getColumnDelimiter(). If the Delimiter interface is not implemented, the engine uses default values.

For XML formats, see the Table source row above.

In the following example, a real-time job sends a message to an adapter operation instance using an outbound message object. This type of job is useful for testing purposes.

In the example, the Employment source and target objects represent message schemas in XML format. The "PublishMessageToR..." object represents an outbound message to an adapter operation instance of the same name. The adapter converts the message format and interacts with the resource. Upon completion, the adapter operation sends confirmation (an empty reply) to the data flow. If the adapter operation cannot process the outbound message, it sends an error reply (AdapterException) and the data flow terminates with the error message reply.

3.10.2 Adapter invokes real-time service

Data Services users can create real-time jobs for the “IR requests Data Services service and waits for reply” and “IR requests Data Services service with no reply” basic adapter operation types discussed previously. In both cases, the adapter invokes a named real-time service in the Data Services Access Server. The service associates with the appropriate real-time job needed to process the IR's request (relayed by the adapter) and return the XML result to the adapter.

In the following real-time job, the adapter is both source and target. Once the adapter receives the results message from the real-time job, it resumes processing. This type of real-time job would be used when the IR waits for a reply or when the IR waits only for an acknowledgement.


3.11 Adapter administration

This section discusses adapter administration and summarizes how application designers use the Data Services Administrator to administer adapters. For more information about the Administrator and adapter administration, see the Data Services Administrator Guide.

After an adapter is successfully installed, Data Services users can perform the following adapter administration functions from the Administrator:

● Add new adapter instances (configure the adapter start-up)● Start adapter instances● Shutdown adapter instances● Abort adapter instances● Start operations● Stop operations● Edit start-up configurations● Remove adapter instances

Data Services users must complete adapter start-up and run-time configuration before they can start an adapter instance. For more information, see the “Configure adapter” section.

When an adapter is started, the Access Server starts the adapter driver as the Java application runner and passes the fully qualified adapter class name as the parameter. This name appears automatically in the Adapter Class field on the Adapter start-up Configuration page.

The adapter driver creates an adapter container. The adapter container creates adapter instances and associated components. The adapter's run-time configuration is provided by its adapter instance configuration file, represented in XML format. This file configures the adapter and one or more instances for each component class the adapter owns.

Adapter instances are started from the Adapter Instance Status page. To start an adapter instance in the Management Console, go to Administrator Adapter Instance Job Server . The status page opens. Select one or more adapter instances and click the Start button. To verify which adapter instances started successfully, click the Status tab to refresh the Adapter Instance Status page view, then look for a green indicator next to the adapter instance name and the word “Started” in the Status column.


Overview

After starting an adapter instance in the Administrator, Data Services users can:

● Start/stop adapter operation instances● Verify that operation instances are started

Configured operations are also listed on the Status page.

Administrator users can start adapter operation instances, from the Adapter Instance Status page. To start an adapter operation instance, click to select it, then click the Start button. To verify which adapter operation instances started successfully, click the Status tab to refresh the Adapter Instance Status page view, then look for a green indicator next to the operation instance name.

Related Information

Configure adapter (start-up and run-time) [page 103]


4 Creating an Adapter

4.1 Preliminary considerations

The Data Services Adapter SDK is designed so that you only need to define classes for your adapter and operation objects. For example:

public class MyOperation implements Operation, PollOperation

In each class, you implement the appropriate Adapter SDK interfaces, then call or define the appropriate methods for the operations you want to develop. When you compile and package adapter and operation classes and start the adapter, the Adapter SDK instantiates objects for each class you defined.

Before writing an adapter to integrate Data Services with an information resource, you must:

● Determine integration issues● Understand your information resource● Plan adapter components

4.1.1 Determine integration issues

There are various ways to integrate an information resource (IR) with Data Services. First, determine if a custom adapter is necessary. If so, consider what kind of adapter you need.


Creating an Adapter

4.1.2 Understand your information resource

Consider adapter/information resource relationship details. In particular, determine:

● Which IR will the adapter integrate and how will the adapter connect to the IR?● How will the adapter interact with the IR? Java API or JNI is required by the Adapter SDK to access IR data

from the adapter (Java program).● With which IR objects will your adapter interact? For example, determine which database tables your

adapter should be able to access.

4.1.3 Plan adapter components

The overall purpose of your adapter will be key in determining necessary components and how they work within the adapter. Remember that:

● The Adapter component (the class that implements the Adapter interface) is the only required component.This component binds all other adapter components together on the adapter's initialize method. An adapter instance can have only one Adapter component. The Adapter component is available from all other components within the adapter. Because of this, you may want the Adapter component to host information resource initialization.

● If your adapter requires SQL capabilities, you must implement the SQLAdapter interface.

4.1.4 Plan adapter operations

Each operation type requires specific planning. However, for all operations, you must:

● Determine the objective for the operation.● Understand what kind of data transformation should occur inside each adapter operation implementation.

Data Services expects certain data formats, and if the IR requires different data formats, data transformation will be necessary.

● Decide how the adapter operation will process IR data for operations initiated by Data Services . Data Services supports five metadata types that can be processed from or sent to the adapter operation. They are:○ Documents○ Tables○ Function Calls○ Outbound Messages○ Message Function Calls

Imported metadata must be converted to one of these five types. Implement interfaces associated with metadata type(s) you choose.

User Guide for Adapter SDKCreating an Adapter PUBLIC 49

4.1.4.1 Message-oriented operations

Determine whether Data Services or the IR initiates the operation.

● If the IR initiates the operation, design real-time services to process IR data.● If Data Services initiates the operation, design real-time services or data flows that initiate adapter

operations from either an Outbound Message or a Message Function Call. See Data Services documentation for more information.

4.1.4.2 Stream-oriented operations

● Stream-oriented operations are always initiated by Data Services.● Determine if you need a Session component. If you plan to have multiple adapter datastores per adapter

instance, include the Session component.● Choose a data format for exchanging data between the stream-oriented adapter operation and the Data

Services engine. This format will dictate what interface you should implement.● Decide which additional interfaces to implement for the adapter operation class to cover special cases like

SQL support for table sources.

4.1.4.3 Plan metadata browsing and import

Decide if you want to import resource metadata only and use native Data Services sources and targets (native SQL support), or if your want to map IR metadata to Data Services metadata and use adapter operations associated with this metadata as sources, targets, and function calls.

Decide how IR metadata will be imported into Data Services. The MetadataImport interface contains two importMetadata methods, each supporting a different way to import metadata from the Data Services Designer:

● Import metadata from the browsing window● Import metadata using the Import-By-Name dialog

Plan metadata import for message-oriented operations.

● Implement Exported interface to expose metadata from the message-oriented operation (only for operations initiated by Data Services )

● Use generic metadata import framework and manually configure stream-oriented operations using imported to Data Services metadata

● For message-oriented operations initiated by the information resource, the metadata consists of real-time services configured in the Administrator

For document metadata, DTD information can be imported from DTD files and from XML files containing a DTD element. When using DTD files to import metadata, you must define the root XML element.


Creating an Adapter

4.2 Write your custom adapter

Clearly defining the characteristics you require in your adapter should make it easy to identify the right components for the adapter. All components are optional, except the Adapter component.

After identifying components, you create corresponding classes by implementing interfaces included with the Adapter SDK . For each class, you must:

● Implement appropriate Adapter SDK interfaces● Define all required methods for your chosen components

When writing your adapter, use instructions in this section and detailed information from the Adapter SDK API documentation. For adapter interface sample implementations, see the TestAdapter source code provided with your Adapter SDK .

Related Information

Interfaces implemented by adapter writers [page 31]Run-time configuration template structure [page 90]

4.2.1 Adapter writer checklist

Use this checklist as a guideline for writing your adapter.

Task Done?

Create an Adapter component [page 52] (Required)

Create a Session component [page 54] (if needed)

Create Metadata Node component(s) [page 55] (if needed)

Create a Metadata Browsing component [page 56] (if needed)

Create Metadata Import component [page 57] (if needed)

Create an Operation component [page 63] for each operation type (if needed)

Customize presentation of adapter components [page 70] in the Administrator or Designer (if needed)

For each task, did you set up:

● Error handling?● Trace and error logging?● Statistics?

Usually, very simple code is required to satisfy Adapter SDK requirements. The basic requirement for all adapter components is compliance with the JavaBeans standard regarding “Properties” and “Introspection” specifications.


After you write your custom adapter, you will compile and package the components, referring to this package later, during adapter instance configuration. Finally, when you start the adapter, the Adapter SDK will instantiate objects (create the component's instance) for each component you defined. The Adapter SDK will operate with the instances of these classes.

After writing an adapter, you will need to create documentation for your adapter users. The section “Create adapter user documentation” provides suggestions, outlines naming conventions, and provides a pointer to an included Adapter Documentation template you can use.

Related Information

http://java.sun.com/products/javabeans/docs/ Create adapter user documentation [page 81]Error handling [page 76]Trace and error logging [page 77]Statistics [page 78]

4.2.2 Create an Adapter component

Create your Adapter component by creating the Adapter class and implementing the Adapter interface, which all custom adapters must implement. The Adapter interface is the core life-cycle interface for all Data Services adapters. The Adapter component:

● Starts the adapter instanceWhen we start an adapter, we actually trigger a start-up process that revolves around the Adapter component. When this start process is triggered, the adapter driver creates an instance of the Adapter component.There are three ways to trigger the adapter start process:○ Automatically — When "Autostart" is set to true and the Data Services Designer is started.○ Manually — Start from the Administrator.○ Upon Designer or engine request — When a job or real-time service starts (if not already started

manually or automatically).● Binds together adapter components

The adapter is considered "started" after the Adapter component instance binds together all other adapter component instances (the start() method is executed).After it is created and before it is destroyed, the Adapter component can be referenced by operations and other components within the adapter container.○ Individual operation instances can access the Adapter component as needed using the

getAdapter() method defined in the OperationEnvironment interface.○ For metadata browsing, metadata import, and session instances, the reference is passed as a

parameter of the initialize() method.● Stops the adapter instance

When we stop an adapter, we tell the adapter driver to destroy the Adapter component instance. An adapter instance is triggered to stop when:


Creating an Adapter

http://help.sap.com/disclaimer?site=http%3A%2F%2Fjava.sun.com%2Fproducts%2Fjavabeans%2Fdocs%2F

○ The adapter is stopped or aborted from the Administrator.○ The Adapter SDK encounters an unrecoverable error.○ The associated Data Services service is stopped.

4.2.2.1 Adapter component life cycle

First, the adapter container creates an Adapter component instance, MyAdapter myAdapter = new MyAdapter();, then it calls associated interface methods. The adapter container then:

1. Calls the initialize method: myAdapter.initialize(AdapterEnvironment environment);This method links the adapter component instance with the AdapterEnvironment object instance (also created by the adapter driver). If needed, store the reference to AdapterEnvironment for later use. (Find AdapterEnvironment interface details in Adapter SDK API documentation.)Also, this method binds the adapter components together. For example:

public void initialize(AdapterEnvironment environment) { //always a good idea to save the reference to the AdapterEnvironment object _adapterEnvironment = environment; _adapterEnvironment.setOperationDescriptor(_operationClassNames); _adapterEnvironment.setMetadataBrowsingClassName ("com.acta.adapter.testadapter.Browse"); _adapterEnvironment.setMetadataImportClassName ("com.acta.adapter.testadapter.Import"); _adapterEnvironment.setSessionClassName ("com.acta.adapter.testadapter.TestSession"); }

2. Introspects and sets adapter parameters from the configuration XML script. The configurable adapter properties must be coded as Java Bean properties. Example:

private String test = "abc"; public void setTest( String param) { test = param; } public String getTest() { return test ; }

The property test will be exposed for adapter configuration.3. Calls the myAdapter.start() method to start adapter processing. This method is called to connect and

initialize all necessary adapter-wide resources after all properties are set.Under Adapter SDK control, the adapter processes data for the adapter operation, metadata browsing, and metadata import. All these objects reference the Adapter component.

4. Calls the myAdapter.stop() method when the adapter is being shut down or aborted. You must close resource connections and de-initialize the adapter.○ When you make a request to stop the adapter from the Data Services Administrator, the Adapter SDK

allows the adapter an unlimited amount of time to stop after processing all outstanding requests.○ When you abort the adapter from the Administrator or stop the Data Services service, the adapter's

process is immediately stopped, without waiting for adapter operations to complete.For details, see online API documentation for this interface.Find an example of this interface implementation in <LINK_DIR>/adapters/sdk/samples/testadapter/data/src/com/adapter/testadapter/TestAdapter.java.


4.2.2.2 SQL-enabled adapter

If your adapter must read/write records from/to the database, implement the SQLEnable interface for your adapter in addition to the Adapter interface.

For details, see online API documentation for this interface

Related Information

Interfaces implemented by adapter writers [page 31]

4.2.3 Create a Session component

The Session component is optional for Data Services adapters.

Create your Session component by implementing the Session interface. Create this component if one or more of the following applies:

● Your adapter will include metadata browsing, metadata import, or stream-oriented operation components.● You want to create multiple adapter datastores for the same running adapter instance. The Session

component (or session object) supports a Data Services user's ability to create multiple datastores for the same adapter instance. Different adapter datastores using the Session component can have different properties configured for the same datastore.

● You want to share the Session component instance with other component instances belonging to the adapter datastore.

4.2.3.1 Session component life cycle

Each adapter datastore created in the Data Services Designer is associated with an adapter session object which is also associated with a specific adapter instance. In the Designer, all objects imported into the adapter datastore are also related to that session object.

An instance of the Session component is created and destroyed upon request from a Data Services client (Designer for metadata browsing/import or engine for run-time data exchange between Data Services and the adapter).

Adapter developers do not have direct control over Session object life-cycle management. Internally, the Designer shares the session object among multiple metadata browsing and import requests. During run-time, the Session object is shared inside the data flow.

When you expose Session object properties for configuration, Data Services users see that information and provide configuration values in the Designer by going to the adapter datastore Adapter Properties tab.

The Adapter SDK can handle the multiple Session objects simultaneously. Upon client request, the adapter container creates the Session object with a unique session ID. Then, it:


Creating an Adapter

1. Calls the public void initialize(Adapter adapter, AdapterEnvironment environment) method of the session component.

2. Calls the public void start() throws AdapterExceptionmethod.3. Returns the unique Session ID to the client.

The client requests the data using the unique Session ID. The adapter container uses the unique Session ID to access the correct Session object.

4. Calls (upon client request — unique Session ID a parameter of the request) the public void stop() throws AdapterException method for the Session object and destroys it.

4.2.4 Create Metadata Node component(s)

The Metadata Node component is optional for Data Services adapters. However, for adapters requiring metadata browsing capability, you must create this component before creating the Metadata Browsing component. Implement the MetadataNode interface to present information resource (IR) metadata as a hierarchy of metadata nodes consisting of known IR metadata types.

The basic characteristics of metadata nodes are:

● Some nodes are "root" nodes at the top of the metadata hierarchy. They do not have parent nodes.● Some nodes can be expanded, producing one or more child nodes for which the expanded node is the

parent.● Some nodes can be imported into Data Services.

4.2.4.1 Metadata browsing nodes

The MetadataNode interface requires you implement the following methods:

Method Description

getUniqueName Returns the unique name of the metadata browsing node.

public java.lang.String getUniqueName()

getDisplayName Returns the metadata browsing node display name.

public java.lang.String getDisplayName()

getDescription Returns the metadata browsing node description.

public java.lang.String getDescription()

isRoot Returns true for root node, otherwise, returns false.

public boolean isRoot()

isImportable Returns true for a metadata browsing node that can be imported to Data Services, otherwise returns false.

public boolean isImportable()


Method Description

isExpandable Returns true for a metadata browsing node that can be expanded to other child metadata browsing nodes, otherwise, returns false.

public boolean isExpandable()

Instances of the Metadata Node component are created by the adapter container in response to metadata browsing requests from the Data Services Designer:

1. The adapter container first creates instances of root MetadataNode methods (implementations that return true for the IsRoot method) in response to an initial metadata browsing request from the Designer (using the getRootNode method from the MetadataBrowsing interface).

2. The adapter container then creates instances of the non-root MetadataNode methods (they also return true for the IsRoot method) when the Designer sends subsequent requests to expand nodes (using the expandNode method from the MetadataBrowsing interface).

For details, see TestAdapter code for MetadataNode interface implementation samples. Look in the following files:

● com.acta.adapter.testadapter.RootNode.java● com.acta.adapter.testadapter.ColumnNode.java ● com.acta.adapter.testadapter.FileNode.java

4.2.5 Create a Metadata Browsing component

The Metadata Browsing component is optional for Data Services adapters. However, to visually present information resource (IR) metadata in the Designer, implement the MetadataBrowsing interface to create the Metadata Browsing component.

This component is not configurable from the Designer or from the Administrator. The Adapter SDK does not introspect this component's properties.

NoteTo hierarchically represent visually presented IR metadata in a Data Services metadata browsing window, you must implement both the MetdataBrowsing interface (to create the Metadata Browsing component) and the MetadataNode interface (to create the Metadata Node component which controls metadata browsing nodes that hierarchically present the IR metadata).

Related Information

Create Metadata Node component(s) [page 55]


Creating an Adapter

4.2.5.1 Metadata Browsing component activity sequence

When a Data Services user attempts to browse information resource metadata in the Designer, a request triggers the adapter container to create an instance of the Metadata Browsing component. Then, the adapter container:

1. Initializes the MetadataBrowsing component with the initialize() method:public void initialize (Adapter adapter, AdapterEnvironment adapterEnvironment, Session session)This method is called after the constructor is called and sets references to the Adapter, AdapterEnvironment and Session objects. References to Adapter, AdapterEnvironment and Session objects can be stored for later use, if needed. Reference to the Session object is optional and could be null.

2. Starts metadata browsing by calling the start() method then the getRootNodes() method.3. For each request from the Designer to expand an information resource metadata node, the adapter

container calls the associated expandNode(MetadataNode node) method, which expands the metadata node selected in the Designer (the Metadata Node component that corresponds to the node selected) as a parameter and should return the vector of the expanded metadata nodes. For non-expandable nodes, (when MetadataNode.isExpandable returns false) the method must return null.

4. When the user closes metadata browsing windows in the Designer, the adapter container calls the Metadata Browsing stop() method to destroy the component instance.

NoteBecause an adapter that merely browses metadata is usually impractical, you should include in your adapter the ability to import browsable IR metadata.

Related Information

Create Metadata Node component(s) [page 55]Create Metadata Import component [page 57]

4.2.6 Create Metadata Import component

For each adapter operation initiated by Data Services, the corresponding Data Services metadata must be defined (imported) from the IR using the Metadata Import component. Metadata import functionality and the Metadata Import component are optional for Data Services adapters.

4.2.6.1 Metadata mapping

Data Services supports widely used metadata formats such as XML and database records. Often, information resource metadata and Data Services metadata are identical. However, Data Services has proprietary presentation for metadata imported into its repository. So, even if IR metadata matches Data Services metadata, you must still map IR/Data Services metadata.


The Adapter SDK presents Data Services metadata with objects instantiated from the classes of the com.acta.metadata package.

Use classes derived from the Adapter SDK AWMetadata super class to create Data Services metadata:

com.acta.metadata class Data Services metadata Use in data flow

AWTableMetadata Table Table Source or Table Target

AWDocumentMetadata Document Document Source or Document Target

AWFunctionCallMetadata Function call Function call in Query Transform

AWOutBoundMessageMetadata Outbound message Outbound Message Target

AWMessageFunctionCallMetadata

Message function call Message function call in Query Transform

Helper classes do not directly represent the Data Services metadata, but are used to build the metadata:

More com.acta.metadata classes Usage in AWMetadata classes

AWAttribute Metadata attributes. View these attributes from the metadata property pages in the Designer.

AWColumn Column of the AWTableMetadata object.

AWForeignKey Foreign key of the AWTableMetadata object.

AWIndex Index of the AWTableMetadata object.

AWPkFkPair Primary key-foreign key pairs for the AWForeignKey object.

AWUniqueKey Unique key of the AWTableMetadata object.

ResourceMetadata Use to associate the Data Services and information resource metadata.

Example Java code that creates the AWTableMetadata object in the adapter's import metadata code:

AWTableMetadata awTable = new AWTableMetadata () ; … AWColumn col1 = new AWColumn(); col1.setDatatype (AWColumn.AWT_VARCHAR); col1.setName ("col1"); col1.setNullable(true); col1.setLength(64); ... AWColumn col2 = new AWColumn(); col2.setDatatype (AWColumn.AWT_INT); col2.setName ("col2"); col2.setNullable(false); col2.setLength(4); col2.setDescription("Order number"); col2.addElement(col); ... AWAttribute attr1 = new AWAttribute("Attribute1", "Attribute value 1") ; AWAttribute attr2 = new AWAttribute("Attribute2", "Attribute value 2") ; ... awTable.setColumns ( new AWColumn [] { col1, col22} ); awTable.setAttributes(new AWAttribute [] { attr1, attr2} );


Creating an Adapter

4.2.6.2 Data Services XML metadata

Several Query metadata types are associated with XML documents and XML data type definition (DTD) documents. Each metadata type corresponds with an AWMetadata object:

Data Services metadata types Corresponding AWMetadata objects

Document AWDocumentMetadata

Outbound Message AWOutBoundMessageMetadata

Function Call AWFunctionCallMetadata

Message Function Call AWMessageFunctionCallMetadata

When instantiating the AWMetadata objects, use DTD strings. Set one DTD string each for the AWOutBoundMessageMetadata and AWDocumentMetadata objects.

Because functions must both input and output XML, you must use two DTD strings for the AWFunctionCallMetadata and AWMessageFunctionCallMetadata functions.

The Adapter SDK accepts DTD strings in both DTD and XML formats. However, when a DTD string is defined in DTD format, the DTD root element must be defined. For example:

<!ELEMENT Identifier (#PCDATA)> <!ELEMENT BusinessDescription (#PCDATA)> <!ELEMENT PhysicalAddress (#PCDATA)> <!ELEMENT shipTo (BusinessDescription,PhysicalAddress)> <!ELEMENT OrderQuantity (#PCDATA)> <!ELEMENT ProductLineItem (OrderQuantity,Identifier,shipTo?)> <!ELEMENT CreditCard (#PCDATA)> <!ELEMENT DebitCard (#PCDATA)> <!ELEMENT formOfPayment (CreditCard|DebitCard)> <!ELEMENT PurchaseOrder (Identifier,shipTo?,ProductLineItem*,formOfPayment?)>

If this DTD were used for the AWOutboundMessage metadata object, you could use these methods to define the DTD string:

AWOutboundMessageMetadata dm = new AWOutboundMessageMetadata (); … String dtd = new String() ; // read dtd from file or hard code it … dm.setOutboundMessageDTD(dtd); dm.setOutboundMessageDTDRoot("PurchaseOrder"); …

NoteDo not add standard XML headers to the beginning of the DTD (Example:<?xml version='1.0' encoding='utf-8' ?>). DTD formats allowed by the Data Services Designer and the Adapter SDK differ slightly; the Designer allows such a header while the Adapter SDK does not.

When you define the DTD string in XML, do not define the DTD root element. Example XML:

<?xml version='1.0' encoding='utf-8' ?> <!DOCTYPE PurchaseOrder [ <!ELEMENT Identifier (#PCDATA)> <!ELEMENT BusinessDescription (#PCDATA)>


<!ELEMENT PhysicalAddress (#PCDATA)> <!ELEMENT shipTo (BusinessDescription,PhysicalAddress)> <!ELEMENT OrderQuantity (#PCDATA)> <!ELEMENT ProductLineItem (OrderQuantity,Identifier,shipTo?)> <!ELEMENT CreditCard (#PCDATA)> <!ELEMENT DebitCard (#PCDATA)> <!ELEMENT formOfPayment (CreditCard|DebitCard)> <!ELEMENT PurchaseOrder (Identifier,shipTo?,ProductLineItem*,formOfPayment?)> ]>

So, if this XML-formatted DTD were used for the AWOutboundMessage metadata object, you could use these methods to define the DTD string:

AWOutboundMessageMetadata dm = new AWOutboundMessageMetadata () ; … String dtd = new String() ; // read dtd from file or hard code it … dm.setOutboundMessageDTD(dtd); …

For specific method details see the online API documentation (com.acta.metadata package).

See an example of the Query metadata class usage in <LINK_DIR>/adapters/samples/testadapter/data/src/com/adapter/TestAdapter/Import.java.

4.2.6.3 Metadata types supported in the Designer

Adapters can support some Data Services metadata types. When a metadata type is supported by an adapter, the associated MetadataImport interface method should return true. Methods and associated Data Services metadata types include:

Metadata type Description

public boolean isTables() Returns true if metadata import can return the AWTableMetadata object.

public boolean isDocuments() Returns true if metadata import can return the AWDocumentMetadata object.

public boolean isFunctionCalls() Returns true if metadata import can return the AWFunctionCallMetadata object.

public boolean isOutboundMessages() Returns true if metadata import can return the AWOutboundMessageMetadata object.

public boolean isMessageFunctionCalls() Returns true if metadata import can return the AWMessageFunctionCallMetadata object.

4.2.6.4 About the MetadataImport interface

To support IR metadata import in Data Services, implement the MetadataImport interface. The Adapter SDK creates the MetadataImport object after receiving a request to import metadata. It calls the method that sets


Creating an Adapter

references to the Adapter, AdapterEnvironment and Session objects: initialize (Adapter adapter, AdapterEnvironment adapterEnvironment, Session session).

Adapter SDK assumes that necessary resources are allocated in the Adapter or Session instances, so start() and stop() methods are not required by the MetadataImport interface.

After the Metadata Import component is instantiated and initialized, the Adapter SDK is ready to serve the Designer by fulfilling metadata import requests.

The MetadataImport interface supports two types of metadata import in the Designer:

● Import through metadata browsing● Import through Import-By-Name

4.2.6.5 Import through metadata browsing

To support metadata import through the adapter metadata browsing window, you must first implement both the MetadataNode and the MetadataBrowsing interfaces in your adapter.

The MetadataBrowsing interface makes it possible for Data Services users to view IR metadata from the Designer. When Data Services users browse IR metadata in the Designer, they navigate through a hierarchy of nodes. Each node is represented in the Adapter SDK by an instance of the MetadataNode interface. Users can select a metadata node and execute the “import” command (if MetadataNode.isImportable implementation returns true for the selected node). Then, the adapter container calls the MetadataImport.importMetadata(MetadataNoderesourceMetadataNode) method, which returns the vector of the Data Services metadata objects. See the com.acta.metadata package for details.

Related Information

Create Metadata Node component(s) [page 55]Create a Metadata Browsing component [page 56]

4.2.6.6 Import through Import-By-Name

For your adapter to include Import-By-Name functionality, you must implement the ImportByName interface. This is an empty interface (no methods are required by the Adapter SDK).

For example, if you want to import some IR metadata by name and need two properties (table and owner names) to supply the information necessary to perform the metadata import.

● Enter the value for these properties in the Designer's Import-By-Name dialog.● Access the entered values in your implementation of the MetadataImport interface.

You must define properties for the ImportByName interface implementation. Example code you might add includes:

public class MyImportByName implements ImportByName {


private String tableName ; public String getTableName() { return tableName }; public void setTableName (string s ) { tableName=s}; private String ownerName ; public String getOwnerName() { return ownerName }; public void setOwnerName (string s ) { ownerName = s}; }

The Adapter SDK should return the instance of the Import By Name component from the ImportByName method implemented for MetadataImportInterface.

Continuing with the example, a typical ImportByNamemethod implementation might include the following code:

public MyImportByName importByName() { return new TestImportByName() ; }

4.2.6.7 Link between Data Services and IR metadata

Your information resource and Data Services only understand their own metadata, so just as you map IR metadata to Data Services for importing purposes, you must also provide a way for Data Services to send IR metadata back during run-time.

At run-time, Data Services must be able to pass IR metadata description information to the adapter operation (which already knows how to work with the information resource).

Stream-oriented adapter operations are not directly linked to their Data Services counterparts—the tables, documents, function calls importable through your adapter. So, to create an indirect link between imported adapter metadata and stream-oriented adapter operations:

1. Use the ResourceMetadata object when creating the Metadata Import component.2. Set the IR metadata object to the Data Services metadata object that the Import method must return. Use

ResourceMetadata.setMetadataObject (Object resourceMetadata). Implement the resourceMetadata object as a Java Bean. For more details, see the com.acta.metadata.ResourceMetadata API documentation.During metadata import, Data Services stores a serialized version of the IR object with the imported metadata in the Data Services repository.At run-time, immediately after the stream-oriented adapter operation is initialized, Data Services sends the serialized IR metadata image to the adapter operation.The Adapter SDK de-serializes the IR metadata object.Then, to make the IR metadata object available for the stream-oriented operation, the Adapter SDK calls the com.acta.adapter.sdkStreamOperation.metadata(Object resourceMetadata) method, implemented for all stream-oriented operations. For details, see com.acta.adapter.sdkStreamOperation API documentation.


Creating an Adapter

4.2.7 Create an Operation component

All adapter Operation components must implement the Operation interface, either explicitly for message-oriented operations, or implicitly (throwing sub-interfaces of the Operation interface) for all stream-oriented operations.

Each class implemented as an adapter operation represents a different operation type. Operation types are similar in that they:

● Implement the Operation interface● Are coded as JavaBeans with properties configurable from the Administrator or the Designer● Are associated with one of the Data Services metadata types● Have the same basic life cycle (create—initialize—start—stop)

However, there are substantial differences between stream-oriented and message oriented operations.

4.2.7.1 Operation life-cycle

After the Adapter SDK creates an instance of an operation component, the adapter container:

1. Calls the public void initialize (OperationEnvironment operationEnvironment) method immediately after the instance is constructed. You can store a reference to the OperationEnvironment object for future use. The OperationEnvironment object is implemented by the Adapter SDK and contains an important method that accesses adapter and operation properties (references to the Adapter and Session instances, trace and error logs, instance name, and so on). See the Adapter SDK API documentation for more details.

2. Introspects an operation and sets the adapter operation parameters from the adapter instance configuration.You define adapter “get” and “set” configuration properties for the operation component (similar to defining other adapter components). Set values for operation properties in the Administrator (for message-oriented operations) or in the Designer (for stream-oriented operations).

3. Calls the start() method.All initializations must be specific for this operation inside start() because the start() method is called only once per operation life cycle.

4. The operation processes message-oriented or steam-oriented data. What occurs during this part of the life-cycle is specific to the adapter operation type and is discussed in:○ Message-oriented operations○ Stream-oriented operations

5. Calls the stop() method triggering the Adapter SDK to destroy the operation instance. De-allocate the operation resources allocated in start().

4.2.7.2 Message-oriented operations

Once created and initialized by the Adapter SDK, the message-oriented operation is ready to process messages from Data Services or an information resource. Normally, a message-oriented operation starts when the adapter starts and stops when the adapter stops. However, you can start and stop individual message-oriented adapter operations from the Administrator.


Every class that implements the Operation interface (operation type) for message-oriented operations can be used to configure multiple instances of the adapter operation running in parallel. See the TestAdapter for an example of how to configure two instances of the com.acta.adapter.testadapter.InvokeService.class. See the Adapter SDK API documentation for details.

4.2.7.3 Message-oriented operations initiated by the IR

Metadata for message-oriented operations initiated by information resources is provided from real-time services configured in the Administrator. This metadata is created when you configure the real-time service for a specified Access Server. Each adapter instance can work with only one Access Server. You configure message broker host and port for this Access Server from the adapter instance configuration in the Administrator.

To implement adapter operations initiated by an information resource, you can choose one of two options:

● Implement the PollOperation interface and its single method, poll(). Call the invokeService method of the OperationEnvironment interface from poll() . The Adapter SDK calls the poll() method periodically (in "polling interval" milliseconds). Configure polling interval value from the operation configuration form in the Designer. Find a sample implementation of the PollOperation interface in com/acta/adapter/InvokeServeice.java source code.With this option, the Adapter SDK is responsible for stopping the adapter operation and stops calling the poll() method immediately after receiving a request from the Administrator to stop the operation.

● Loop inside the start() method and call the invokeService method of the OperationEnvironment interface.Note that if you use this more flexible option, you are responsible for providing an exit from the start() method. A stop request from the Administrator tells the Adapter SDK to return "false" for the canContinue() method. Build in a way to check the canContinue() flag periodically as a trigger to exit the start() method. After exiting start(), the Adapter SDK will call the stop() method.

public void initialize ( OperationEnvironment adapterOperationEnvironment ) { _adapterOperationEnvironment = adapterOperationEnvironment ; } … public void start() throws AdapterException { while (true) { // do your processing here … String reply = _adapterOperationEnvironment.invokeService ( service2Invoke, inputXml, timeOut) ; … if ( false == _adapterOperationEnvironment.canContinue() ) break ; }

4.2.7.4 Message-oriented operations initiated by Data Services

Metadata for the message-oriented operations initiated by Data Services are Outbound Messages or Message Function Calls. You must import the metadata in Data Services and create Outbound Message Targets and


Creating an Adapter

Message Function Calls in the data flow before processing messages that the data flow sends to the adapter operation.

Implement the ListenerOperation interface. The Adapter SDK automatically subscribes that operation to the message type derived from the operation instance name (the value of the OperationInstanceName element from the adapter instance configuration).

Note that the operation instance must have the same name as the Outbound Message or Message Function Call metadata used in the Designer to define the object sending a message to this particular adapter operation instance.

To expose IR metadata for import into Data Services message-oriented operations, you can choose either of the following options:

● Implement the optional Exportable interface in addition to the Operation and ListenerOperation interfaces.This option is preferred because it allows you automatically import metadata into Data Services, seamlessly linking this metadata and the operation.

● Use the generic metadata browsing framework described earlier to import the resource Outbound Message or Message Function Call metadata. Then, manually configure the message-oriented operation with the same operation instance name assigned to the imported metadata object.For this option, you must manually link the adapter operation and Data Services metadata.

4.2.7.5 Message-oriented interfaces

The Exportable interface has only two methods to implement:

● public int getMetadataType() Returns the metadata type exportable by the adapter operation. Possible return types are:

com.acta.metadata.AWMetadata.AWT_OUTBOUND_MESSAGE

com.acta.metadata.AWMetadata.AWT_MESSAGE_FUNCTION_CALL

● public AWMetadata[] exportMetadata() throws AdapterExceptionReturns the array of com.acta.metadata.AWMetadata objects. The return array can contain one (typical) or more elements. Based on metadata types returned by the getMetadataType() method, the return array can contain:

com.acta.metadata.AWOutboundMessageMetadata objects for com.acta.metadata.AWMetadata.AWT_OUTBOUND_MESSAGET type, or

com.acta.metadata.AWMessageFunctionCallMetadata objects for com.acta.metadata.AWMetadata.AWT_MESSAGE_FUNCTION_CALL type

Example implementation of this method:

… public int getMetadataType () { return AWMetadata.AWT_OUTBOUND_MESSAGE ; } …


public AWMetadata [] exportMetadata() throws AdapterException { if ( null == dtdFileName ) return null ; AWOutboundMessageMetadata dm = new AWOutboundMessageMetadata () ; String metadata = new String() ; // read DTD try { FileInputStream fi = new FileInputStream ( dtdFileName ) ; byte[] buffer = new byte[4096]; int bytes_read; while ( (bytes_read = fi.read(buffer)) != -1 ) metadata += new String (buffer, 0, bytes_read) ; fi.close(); } catch ( Exception e ) { throw new AdapterException (e, "Cannot export the operation metadata.") ; } // Define the return AWOutboundMessageMetadata metadata. dm.setOutboundMessageDTD(metadata); dm.setOutboundMessageDescription("Exposes the DTD for this operation XML."); // Must use the operation instance name as the outbound message name. dm.setOutboundMessageName(_adapterOperationEnvironment.getInstanceName()) ; return new AWMetadata [] { dm } ; }

The ListenerOperation interface requires that you implement only one method:

● public java.lang.String handleRequest (Operation oper, java.lang.String xml) throws RecoverableOperationAdapterException, AdapterExceptionHandles requests from Data Services data flow.

Parameter Description

oper Reference to the adapter operation using this interface to handle messages from the resource.

xml Input XML string sent by the real-time service to the adapter operation.

Returns: XML String to send back to service.If the adapter operation processes Message Function Call from the data flow Query transform, the handleRequest method should return an XML message with the DTD defined for the output XML of the metadata for the Message Function Call used in Data Services for this operation.If the adapter operation processes Outbound Message from the data flow, then the handleRequest method must return null. When this happens, the Adapter SDK sends acknowledgment to verify that message processing was successful.Also see API documentation, com/acta/adapter/testadaper/ReceiveFromRTDF.java, and com/acta/adapter/testadaper/CallFromRTDF.java for reference implementation.

4.2.7.6 Stream-oriented operations

The Adapter SDK treats stream-oriented operations differently than message-oriented operations. While instances of message-oriented operations stay in adapter memory ready to process messages from different sources (different data flows and messages from the information resource), stream-oriented operation instances are associated with a single object in a particular data flow.


Creating an Adapter

Each stream oriented-operation:

● Is created upon request from the Data Services engine (from an object using metadata associated with the operation)

● Exchanges data between data flow and operation● Destroyed on data flow request

For stream-oriented operations, implement one of five available interfaces:

Interface Data flow object Returned metadata

TableSource Table source AWTableMetadata

TableTarget Table target AWTableMetadata

DocumentSource Document source AWDocumentMetadata

DocumentTarget Document target AWDocumentMetadata

FunctionCall Function call AWFunctionCallMetadata

All stream-oriented operation classes must implement the Operation and StreamOperation interfaces.

The StreamOperation is a subinterface of the Operation interface and requires you to implement three methods in addition to those implemented for the Operation interface:

● begin()● end() ● metadata()

Because of these methods, the implemented StreamOperation interface expands the operation life-cycle for stream-oriented operations. The Adapter SDK:

1. Creates an instance of the stream-oriented operation component when requested from the operation client — data flow target, source, or function call of the running job or real-time service.

2. Calls the public void initialize (OperationEnvironment operationEnvironment) method immediately after the instance is constructed. (You can store a reference to the OperationEnvironment object for future use.)The OperationEnvironment object is implemented by the Adapter SDK and has important methods for accessing the adapter and operation properties (references Adapter and Session instances, trace and error logs, instance name, and so on). See API documentation for the details.

3. Introspects an operation and sets the adapter operation parameters from the adapter instance configuration.You define the "get" and "set" configuration properties for the operation component, same as for the Adapter and other components. You also set values for the operation properties in the Data Services Designer when configuring the adapter operation.

4. Calls the com.acta.adapter.sdkStreamOperation.metadata (Object resourceMetadata) method to make the resource metadata object imported in the Designer available for the stream-oriented operation.

5. Calls the operation's client request start() method.Make all initializations specific for this operation inside start() because the start() method is called once for the operation life time.

6. Calls the operation's client request begin() method.Data Services logic may require the operation to restart processing. For instance, the Data Services engine might make a request to read the same table several times. While you cannot control this in the adapter operation code, it is handled with begin() and end() method implementation. These methods are responsible for re-starting processing. For example, you can reset the cursor if reading the database table.


Execution of the begin() and end() method pair can be requested by the operation's client multiple times during the life of an operation.

7. Now operation is ready to process data. This part is specific for the type of adapter operation and will be discussed later.

8. Calls the operation's client request end() method. See notes for the begin() methods.9. Calls the stop() method before the Adapter SDK destroys the operation instance, de-allocating the

operation resources allocated in start().

Related Information

Link between Data Services and IR metadata [page 62]

4.2.7.7 Stream-oriented interfaces

The Table interface is the super interface for TableSource and TableTarget interfaces which you must implement to support table sources and table targets in Data Services data flows. Methods for this interface are:

● getDateFormat public java.lang.String getDateFormat()Returns the data format. Use "yyyy.mm.dd hh24:mi:ss" as the default value. For other formats see Data Services technical documentation.

● getRecordFormat public int getRecordFormat() Returns the record format com.acta.adapter.sdk.Table.RecordFormatXml or com.acta.adapter.sdk.Table.RecordFormatDelimited.If com.acta.adapter.sdk.StreamOperation.RecordFormatDelimited is returned for the TableSource interface implementation, the operation should pack the data as records separated by Delimited.getRowDelimiter() with columns separated by Delimited.getColumnDelimiter().

NoteIf the Delimiter interface is not implemented, the operation must use the default values.

If com.acta.adapter.sdk.StreamOperation.RecordFormatDelimited is returned for the TableTarget interface implementation, the data that operation receives from the engine is packed as records separated by the value returned by Delimited.getRowDelimiter(), with columns separated by the value returned from Delimited getColumnDelimiter().

NoteSee other delimiters in Delimited interface. If the Delimited interface is not implemented, Data Services uses the default values.


Creating an Adapter

If com.acta.adapter.sdk.Table.RecordFormatXml is returned for the TableSource interface implementation, the operation should pack the data as XML with the following structure:


While you can vary <AWA_BatchWrapper> and <AWA_Row> element names, the <colname> elements must match column names defined in the Data Services metadata imported for the TableSource receiving the data in the Data Services data flow associated with this operation.If com.acta.adapter.sdk.Table.RecordFormatXml is returned for the TableTarget interface implementation, the data that operation receives from Data Services is packed as XML with the following structure:


The <AWA_BatchWrapper> and <AWA_Row> element names can be different but <colname> elements must match column names defined in the Data Services metadata to be imported for the TableTarget that sends the data in the Data Services data flow from this operation.

Implement the Delimited interface for stream-oriented adapter operations that must read or write data using a custom (not default) delimited format. You may want to implement this interface in addition to TableSource or TableTarget interfaces, for the adapter operation implementation to customize the delimiters for data exchanges between your adapter and the Data Services engine. Methods for this interface are:

● getColumnDelimiterpublic java.lang.String getColumnDelimiter()Returns the field separator. Default is ",".

● getEscapeCharpublic java.lang.String getEscapeChar()Returns the escape character. Default is "".

● getRowDelimiterpublic java.lang.String getRowDelimiter()Returns the record separator. Default is "/n".

● getTextDelimiterpublic java.lang.String getTextDelimiter()


Returns the text delimiter. Default is "".

Default data exchange uses the delimited format and the default values documented for each method of this interface.

For custom-delimited data exchange between your adapter and Data Services, implement this interface. Then, to enable delimiter configuration for each operation instance from the Designer, use the "get" and "set" methods. For instance:

String rowDelimiter = ";" // Default value different from the system default. public String getRowDelimiter () { return rowDelimiter ; } public String setRowDelimiter (String delim) { // Allows configuration of this property from the // Designer. rowDelimiter = delim ; }

For details see the API documentation for this interface.

Implement the SQLEnable interface to complement the TableSource interface if your adapter is SQL-enabled. The SQLAdapter interface implementation of the getSqlSupport() method must return com.acta.adapter.sdk.SQLAdapter.AWA_FullSQL.

The Adapter SDK will call the sqlText(String sql) method to set the SQL string generated by Data Services to select data from the database. When executed, this SQL statement returns rows with the columns required by Data Services to continue data transformations.

4.2.8 Customize presentation of adapter componentsSome component properties for Data Services adapters are exposed and are configurable in the Data Services Management Console Administrator, some in the Designer.

To enable users to find and configure adapter component properties, use the following table to map adapter components with the Data Services user interface in which they are exposed and the specific context in which the user will configure properties:

Component Exposed in Configuration context

Adapter Administrator Adapter configuration form

Session Designer Adapter datastore tab of datastore window

ImportByName Designer Import-By-Name window

Operation

Message-oriented Administrator Operation configuration form

Stream-oriented Designer Adapter sources, targets, function calls

MetadataNode Designer Metadata browsing window

Statistics Administrator Select a running adapter instance

All adapter components are Java Beans compliant with JavaBeans standards for properties and introspection. Java Beans can have configurable properties which you can customize using the BeanInfo class. You can add


Creating an Adapter

simple user interfaces to the Administrator or Designer for adapter components quickly by coding set and get methods (see the Adapter SDK API for details). However, to add more customization, such as default values, descriptions, and so forth, create a complimentary BeanInfo class.

The following two sections are a configurable properties customization tutorial and include instructions for modifying configurable properties in your sample adapter (TestAdapter) and viewing customized results in both the Administrator and Designer. Use these instructions as a guideline for customizing configurable properties for other adapter components.

4.2.8.1 Customize using get() and set()

The following instructions explain how to create an adapter operation with a configurable property. These instructions use TestAdapter as an example.

4.2.8.1.1 Creating an adapter operation component with a configurable property

1. Create your adapter operation component, adding a set method for the configurable property.

For the purpose of this exercise, add the following TestOperation class containing a property named "testProperty" to TestAdapter:

package com.acta.adapter.testadapter; import com.acta.adapter.sdk.*; public class TestOperation implements Operation { //Configurable property testProperty String testProperty ; public void setTestProperty ( String test ) { testProperty = test ; } //Interface implementation OperationEnvironment _operationEnvironment ; public void initialize ( OperationEnvironment operationEnvironment ) { _operationEnvironment = operationEnvironment ; } public void start() throws AdapterException { _operationEnvironment.println ( "TestAdapter::TestOperation Started." ) ; } public void stop() throws AdapterException { _operationEnvironment.println ( "TestAdapter::TestOperation Stopped." ) ; } }

2. If TestAdapter is running, go to the Data Services Administrator and stop it.3. Open the TestAdapter.java source code file in the <LINK_DIR>/adapters/sdk/samples/

testadapter/data/src/com/adapter/testadapter directory and update the TestAdapter class by adding a line (indicated below in bold) for the new TestOperation class under operationClassNames:

… private String[] _operationClassNames = { "com.acta.adapter.testadapter.InvokeService" ,"com.acta.adapter.testadapter.ReceiveFromRtdf" …


,"com.acta.adapter.testadapter.WriteDocument" ,"com.acta.adapter.testadapter.FunctionCallTest" ,"com.acta.adapter.testadapter.TestOperation" } ; …

4. Re-create TestAdapter.jar and re-generate the adapter run-time configuration. Use LINK_DIR/adapters/sdk/samples/testadapter/buildTestAdapter.bat to:

○ Compile the java source code○ Package TestAdapter in acta_test_adapter.jar file○ Re-generate the adapter run-time configuration file, LINK_DIR/adapters/config/template/

TestAdapter.xml5. Start TestAdapter.6. Use a text editor to open the adapter run-time configuration template located in the LINK_DIR/

adapters/config/templates directory (for this example, TestAdapter.xml).

7. View your new configuration property with the system properties added to all message-oriented operations.

<com.acta.adapter.testadapter.TestOperation DisplayName ="TestOperation" SDKVersion ="2.0.0"> <operationInstanceName DisplayName="Operation instance" Description="For the messages that this operation receives from Data Services this name should match the correspondent outbound message or function call name."></operationInstanceName> <threadCount DisplayName="Thread count" Description="Number of copies of this operation to run in parallel.">1</threadCount> <displayName DisplayName="Display name" Description="Display name for metadata browsing."></displayName> <description DisplayName="Description" Description="Description for metadata browsing."></description> <enable DisplayName="Enable" Description="Enable to run operation when adapter starts." Choices="true|false" >true</enable> <testProperty DisplayName ="testProperty"></testProperty> </com.acta.adapter.testadapter.TestOperation>

8. Open the Data Services Administrator and configure a new adapter operation.

In the Operation type list, you should see your new operation.9. From the Operation type list, select TestOperation and click Apply to see the operation configuration form

for TestOperation. Here, you can see your newly configured property: testProperty. Please note that:○ The operation name appearing above the configuration form (TestOperation) is the class name, and it

is not very informative.○ There is no description provided for testProperty.○ There is no default value for testProperty.

10. Open the TestOperation class file added at the beginning of this procedure and add a default value for testProperty by providing a “get” and assigning an initial value of “ABC”.The new source code will look something like this:

package com.acta.adapter.testadapter; import com.acta.adapter.sdk.*; public class TestOperation implements Operation { //Configurable property testProperty String testProperty = "ABC"; public void setTestProperty ( String test ) { testProperty = test ;


Creating an Adapter

} public String getTestProperty () { return testProperty ; } //Interface implementation OperationEnvironment _operationEnvironment ; public void initialize ( OperationEnvironment operationEnvironment ) { _operationEnvironment = operationEnvironment ; } public void start() throws AdapterException { _operationEnvironment.println ( "TestAdapter::TestOperation Started." ) ; } public void stop() throws AdapterException { _operationEnvironment.println ( "TestAdapter::TestOperation Stopped." ) ; } }

11. Repeat the deployment procedure described the previous steps to see your TestOperation configuration form changes. The value “ABC” should appear in the text box next to testProperty.

To provide a more user-friendly configuration form display name and a property description, you must provide default values and value choices by customizing the Java Bean.

4.2.8.2 Customizing the Java Bean

To further customize an adapter component, create the BeanInfo class for that component. So, to further customize your new TestOperation class, you must create the TestOperationBeanInfo class. For more information, see JavaBeans specifications at: http://java.sun.com/products/javabeans/docs/

The code for TestOperationBeanInfo class will look something like this:

package com.acta.adapter.testadapter; import java.beans.*; import com.acta.adapter.sdk.*; public class TestOperationBeanInfo extends SimpleBeanInfo { public TestOperationBeanInfo() { super() ; } public BeanDescriptor getBeanDescriptor() { BeanDescriptor bn = new BeanDescriptor (com.acta.adapter.testadapter.TestOperation.class) ; bn.setName("Test Operation." ); bn.setShortDescription ("This is the description for the Test Operation." ); return bn; } public PropertyDescriptor[] getPropertyDescriptors() { PropertyDescriptor[] pd = null; try { PropertyDescriptor testProperty = new PropertyDescriptor ( "testProperty",com.acta.adapter.testadapter.TestOperation.class ) ; testProperty.setDisplayName("Test Property") ; testProperty.setShortDescription("Enter the value for the Test Property.") ; pd = new PropertyDescriptor [] { testProperty } ; } catch (Exception exc) { new AdapterException ( exc, "Introspection error. Cannot construct the property descriptor." ) ; } return pd;


http://help.sap.com/disclaimer?site=http%3A%2F%2Fjava.sun.com%2Fproducts%2Fjavabeans%2Fdocs%2F

}

Update your adapter with these changes using the same procedure provided in Customize using get() and set() [page 71]. The new TestOperation configuration form will look like this:

Customization code essentials include the following (for complete information see JavaBeans documentation):

1. For your adapter component, Foo, create the class FooBeanInfo.2. Extend the SimpleBeanInfo interface.3. To customize the component, overwrite the public BeanDescriptor getBeanDescriptor() method.4. To customize component properties, overwrite PropertyDescriptor[]getPropertyDescriptors()

method.The returned PropertyDescriptor[] array will contain PropertyDescriptor for each property. Each PropertyDescriptor can have the standard customizers:○ Display name○ Short Description○ Hidden○ Attributes. The Designer and Administrator respect the following attributes defined in

com.acta.adapter.GuiAttributes:

Name Value Description Default

Echo "true"

"false"

Echo typing with "*".

Do not echo typing.

"false"

isEditable "true"

"false"

Property can be edited.

Cannot edit the property

"true"


Creating an Adapter

Name Value Description Default

isRequired "true"

"false"

Value required.

Value not required.

"false"

Default Attribute associated with the property default value. The attribute value you set becomes the default value that initially displays the Data Services Designer and Administrator.

N/A

Choices Attribute associated with the choices available for the property. The attribute value should be text with the choices separated by "|".

N/A

Order Numeric value:

"1" = the first property

"2" = the second property

... and so on.

Controls display order of properties in the Designer and Administrator. The property with the value of this attribute equals "2" will be displayed next in order in the configuration form or dialog.

0 (Order does not matter.)

Below the sample of the customizer for the ImportByName component of the TestAdapter:

package com.acta.adapter.testadapter; import java.beans.*; import com.acta.adapter.sdk.*; public class TestImportByNameBeanInfo extends SimpleBeanInfo { public TestImportByNameBeanInfo() { super() ; } public BeanDescriptor getBeanDescriptor() { return null ; } public PropertyDescriptor[] getPropertyDescriptors() { PropertyDescriptor[] pd = null; try { PropertyDescriptor metadataType = new PropertyDescriptor ( "metadataType",com.acta.adapter.testadapter.TestImportByName.class ) ; metadataType.setDisplayName("Metadata Type") ; metadataType.setShortDescription("Enter the metadata type choice") ; metadataType.setValue ( GuiAttributes.ATTR_CHOICES, Browse.METADATA_TABLE + "|" + Browse.METADATA_DOCUMENT + "|" + Browse.METADATA_FUNCTION_CALL ) ; metadataType.setValue(GuiAttributes.ATTR_DEFAULT, Browse.METADATA_TABLE ); PropertyDescriptor metadataName = new PropertyDescriptor ("metadataName",com.acta.adapter.testadapter.TestImportByName.class ) ; metadataName.setDisplayName("Metadata Name") ; metadataName.setShortDescription("Enter the metadata name") ; pd = new PropertyDescriptor [] { metadataType, metadataName } ; } catch (Exception exc) { new AdapterException ( exc, "Introspection error. Cannot construct the property descriptor.") ; } return pd; } }

Please note:

● We do not need the description and display name for this component therefore getBeanDescriptor() method returns null.


● We use GuiAttributes.ATTR_CHOICES attribute to provide the choice of values from the Import By Name dialog in the Data Services Designer.

The result you will see in the Designer is:

All get and set methods should be defined as the public methods.

If property does not have get or set use the appropriate constructor for PropertyDescription in getPropertyDescriptors() method. For instance when set and get are defined, use:

PropertyDescriptor testProperty = new PropertyDescriptor ( "testProperty",com.acta.adapter.testadapter.TestOperation.class ) ;

If only "set" is defined, use:

PropertyDescriptor testProperty = new PropertyDescriptor ( "testProperty",com.acta.adapter.testadapter.TestOperation.class, null, "settestProperty" ) ;

4.2.9 Error handling

Methods implemented by the Adapter SDK throw exceptions that must be caught and processed by the developer. The Adapter SDK logs error text in the error and trace log files. Also, consult the Adapter SDK API documentation for more details.

Methods you implement can throw two types of exceptions:

● AdapterException● RecoverableOperationAdapterException

The Adapter SDK catches these exceptions and responds as follows:


Creating an Adapter

● AdapterException: Logs an error and stops the adapter or operation based on where the exception was thrown.

● RecoverableOperationAdapterException: Logs an error and continues adapter operation. (This exception can be thrown only from operation-related classes.)

The following code provides an example of both AdapterException and RecoverableOperationAdapterException:

public void poll() throws RecoverableOperationAdapterException, AdapterException { ... try { ... // call real-time service reply = _adapterOperationEnvironment.invokeService ( _service2Invoke, inputXml, timeOut) ; ... } catch ( TimeoutAdapterException e ){ //log the error and continue throw new RecoverableOperationAdapterException (e) ; } catch ( RecoverableOperationAdapterException e ) { //log the error and continue throw e ; } ... catch ( AdapterException e ) { //stop operation throw e ; } ... }

Related Information

Trace and error logging [page 77]

4.2.10 Trace and error logging

The Adapter SDK allows you to log error and trace messages.

Error messages are stored in error log files and named according to the structure: <adapter instance name>_error.txt. These files appear in the <LINK_DIR>/adapters/log/ directory.

Located in the same directory, trace log files use a similar naming convention: <adapter instance name>_trace.txt . These files contain error and trace messages.

The Adapter SDK lists error and trace messages in the following format:

<date> <time> <message> <new line>

Examples:


11/16/01 5:20:16 PM TestAdapter::InvokeService Poll()

11/16/01 5:20:29 PM TestAdapter::InvokeService Poll()

To log an error or trace message, use the following methods in the AdapterEnvironment interface:

● logError(String message) — Send a string to the error log file.● logTrace(String message) — Send a string to the trace and error log file.● println(String message) — Send a string to the trace log file, only if Trace mode is set to “true” .

You can set the Trace mode in the Data Services Administrator, from the adapter configuration form. From the adapter code, use the AdapterEnvironment interface method isDebug() to check if Trace mode is set to “true”.

Use println(String message) method to generate extra output if Trace mode is set to “true” .

You can obtain the same results using two slightly different pieces of code:

● adapterEnvironment.println("message to log") Recommendation: use this selection during development and testing of your adapter.

● if(adapterEnvironment.isDebug())● adapterEnvironment.printin("message to log");

Recommendation: use this selection for time-critical code. At run-time, Java will not create the extra String object (parameter for printIn) if isDebug() returns “false”.

When you debug your adapter, the Adapter SDK duplicates all messages (error and trace) to the system.out(screen).

Find log file information for an adapter instance in the Adapter Instance Status page of the Data Services Administrator. Select Status Adpater instances to view all configured adapter instances. Under Log Files, each adapter instance lists a Trace and an Error link. Click a link to see current error or trace information for that instance. To clear the log, scroll to the bottom of the log file and click Truncate.

NoteThe Adapter Operation Status page in the Administrator shows a Last Error status column. However, the last error message does not necessarily correspond to the source of the problem. To analyze an error, always refer to the log files.

4.2.11 Statistics

You can accept adapter default statistics or implement the Statistics interface to define your own.

If you use the default statistics, you can view them in the Data Services Administrator by selecting a running adapter instance in the Adapter Status tab.


Creating an Adapter

Statistics (for example, instance names, status, and last errors) are provided by the Adapter SDK. To provide Request, Processed, and Rejected counter values for message-oriented operations, you can add code for the operation implementation.

The semantics for the counters are:

● Request count — Adapter operation received message from information resource or from Data Services.● Processed count — Adapter operation successfully processed a message from the information resource or

from Data Services.● Rejected count — Error occurred when operation processed a message from the information resource or

from Data Services and processing failed.

Use the following methods for the OperationEnvironment interface:

● incrementRequestCount public void incrementRequestCount()

Increments by 1 the number of requests received by the operation. Call this method after the adapter operation receives a processing request.


● incrementProcessedCount public void incrementProcessedCount() Increments by 1 the number of requests processed by the operation. Call this method after an adapter operation successfully processes a request.

● incrementRejectedCount public void incrementRejectedCount()Increments by 1 the number of requests rejected by the operation. Call this method after the adapter operation has rejected the request for processing.

● getRequestCount public int getRequestCount()Returns the number of requests received by the operation. Useful for custom statistics when incrementRequestCount() method is used to track the number of requests received.

● getProcessedCount public int getProcessedCount() Returns the number of requests processed by the operation. Useful for custom statistics when incrementProcessedCount() method is used to track the number of requests processed.

● getRejectedCount public int getRejectedCount()Returns the number of requests rejected by the operation. Useful for custom statistics when incrementRejectedCount() method is used to track the number of requests rejected.

The code sample from the previous “Error handling” section is modified (shown in bold) to illustrate.

public void poll() throws RecoverableOperationAdapterException, AdapterException { ... try { ... // receive message _adapterOperationEnvironment.incrementRequestCount() ; ... // call real-time service reply = _adapterOperationEnvironment.invokeService ( _service2Invoke, inputXml, timeOut) ; ... // process message _adapterOperationEnvironment.incrementProcessedCount() ; } catch ( TimeoutAdapterException e ){ // reject message _adapterOperationEnvironment.incrementRejectedCount() ; //log the error and continue throw new RecoverableOperationAdapterException (e) ; } catch ( RecoverableOperationAdapterException e ) { // reject message _adapterOperationEnvironment.incrementRejectedCount() ; //log the error and continue throw e ; } ... catch ( AdapterException e ) { // reject message _adapterOperationEnvironment.incrementRejectedCount() ; //stop operation throw e; } ... }


Creating an Adapter

To provide custom statistics, implement the Statistics interface and link the implementation in the initialize method of the Adapter interface implementation using the AdapterEnvironment.setStatisticsClassName method.

There are only two methods to implement:

● initialize public void initialize (Adapter adapter, AdapterEnvironment environment,Vector sessions, Vector operations,Vector operationEnvironments) throws AdapterException; Sets references to the currently active adapter, adapter environment, sessions, operations, and operation environment objects.

● collectpublic void collect() throws AdapterException; Collects the statistic. Implementing this method assigns the value to the properties of the custom statistics class.

Click the running adapter instance in the adapter Status tab of the Administrator to see Properties. When you click the adapter instance, the Adapter SDK creates the statistics object, then calls the initialize method with the instances of all major adapter components currently available.

Save references to the statistics object and use it in the collect method that the

Adapter SDK calls next. While not critical, it is important to have the thread save access to these objects because statistics change constantly while the adapter runs and you do not change, but access the data inside the collect method.

The collect method should assign values to statistics object properties. These properties are displayed in the Administrator as property name/property value pairs.

4.3 Create adapter user documentationYour adapter is not complete without adapter user documentation. You must create a document to instruct adapter users on how to install, configure, and use your custom adapter. Your document should contain:

● Introduction—Provide any information that would help users understand the rest of the document (include terms, conventions, and so forth).

● Overview—Discuss your information resource, what users can do with your customer adapter, and mention related adapters.

● Installation—Discuss system pre-requisites, introduce adapter file/component architecture, discuss how to prepare the computer environment (both from the Data Services end and the information resource end), and provide explicit installation instructions.

● Use—Explain what can be moved from Data Services to the information resource and what can be moved from the IR to Data Services, explicitly provide adapter configuration instructions, perhaps provide a test/tutorial use scenario.

● Technical implementation—List any potential limitations of and assumptions about the adapter, describe how to trace and handle errors (including where error information is stored).

A sample document called AdapterDocTemplate is provided as a guideline to help you assemble documentation about your custom adapter. When you create your own document, you can duplicate this structure and:


● Replace all references to “information resource” and “IR” with the name of your adapter's information resource

● Enter specific details for using your custom adapter

4.4 Adapter operation

After writing the adapter code complete the following steps to:

● Compile and package adapter components● Prepare configuration templates (run-time and start-up)● Configure adapter instance components (to work with Data Services and the information resource)● Debug the adapter● Move the adapter from test to production

4.4.1 Compile and package adapter components

Since Data Services custom adapters are Java applications, you must use the available Java compiler and utilities to compile and package your adapter. Use a batch file to:

● Compile adapter source code● Package classes to the jar file

Find the sample batch file for the TestAdapter at: <LINK_DIR>/adapters/sdk/samples/testadapter/buildTestAdapter.bat.

After it is compiled and packaged, you can run your custom adapter as a stand-alone application. However, to run the adapter as part of the Data Services system, you must prepare adapter configuration templates.

4.4.2 Prepare configuration templates

Custom adapters cannot work as part of the Data Services system without two necessary files: the adapter start-up configuration template and the adapter run-time configuration template.

Both configuration templates:

● Are XML files you can manually edit (not recommended)● Must be installed with your custom adapter

The Administrator uses the configuration templates to provide configuration screens where Data Services users can enter information to create configuration scripts during adapter instance configuration. Users can also modify and remove configuration scripts using the Administrator.

When you install a custom adapter, these two configuration templates must be provided with the installation.

EXAMPLE: If you had created TestAdapter you would manually create <LINK_DIR>/adapters/install/TestAdapter.xml from <LINK_DIR>/adapters/AdapterInstallationTemplate.xml and by using


Creating an Adapter

rtt.bat (rtt.sh on UNIX), would generate <LINK_DIR>/adapters/config/templates/TestAdapter.xml.

4.4.3 Configure adapter instance components

Before using an adapter with Data Services, you must configure components in the Administrator and Designer.

In the Data Services Administrator, configure:

● Adapter instance start-up and run-time properties● Message-oriented operation run-time properties

These scripts and message-oriented operations are configured in the Administrator because they are created once and run for the entire adapter life cycle. If you reconfigure an adapter instance or a message-oriented operation, you must restart the adapter instance.

In the Data Services Designer, configure:

● SessionsThese translate to adapter datastore properties. Set values in the Adapter Properties tab of the Adapter Datastore Editor.

● Stream-oriented adapter operations

Sessions and stream-oriented operations are configured in the Data Services Designer because they are created each time the client (Designer or engine) makes a request. These components can be created and configured for each running adapter instance.

When you initially create adapter instance and message-oriented operation configurations, you actually convert the adapter configuration templates to configuration scripts by setting values for the adapter instance and operation properties.

For Session and stream-oriented operations, the Data Services Designer provides windows in its graphical user interface for configuration of all exposed (public) properties that implement “set” methods.

When you configure an adapter instance, the Adapter SDK creates (for the first configured adapter instance) or modifies the <LINK_DIR>/adapters/startup_script.xml that contains startup configuration scrips dor all configured adapter instances.

The Adapter SDK also creates the <LINK_DIR>/adapters/config/<Adapter Instance Name>.xml file containing adapter and message-oriented adapter operation configuration scripts.

EXAMPLE: For TestAdapter this second file is <LINK_DIR>/adapters/config/TestAdapterInstance.xml.

When you update the adapter run-time or start-up configuration you are modifying these two files.

When you create a message-oriented adapter operation you actually modify the <LINK_DIR>/adapters/config/<Adapter Instance Name>.xml file using the adapter run-time configuration template from <LINK_DIR>/adapters/config/tempate<Adapter Type Name>.xml.

When configuring Adapter Properties (Sessions) or stream-oriented operations the Data Services Designer provides the windows to configure all exposed (public) properties that implement a “set” method. See the Designer Guide for details on how to use a custom adapter in the Data Services Designer.


Related Information

Configuring an adapter instance [page 94]Configuring an adapter operation [page 95]Creating the TestAdapter datastore [page 106]

4.4.4 Debug the adapter

Debug your custom adapter after you have:

● Developed your adapter● Configured the adapter and operations● Created an adapter datastore in the Data Services Designer● Imported adapter metadata● Created correspondent data flows and real-time data flows● Configured real-time services● Configured your information resource

Because at least three different applications are involved (resource, adapter, and Data Services) the process of stabilizing a custom adapter for a production environment is not trivial.

If data you receive as a result of integrated data processing is incorrect, or if some integrated components fail to run, you can debug your adapter to understand and correct any problems.

Two ways to debug include:

1. "Trace mode" — In the Administrator, go to the adapter configuration form and set the value to true (false is default).

2. You can debug the adapter as the Java application.

When Trace mode is true, the Adapter SDK will provide verbose output. Methods AdapterEnvironment.println(String message) and OperationEnvironment.println(String message) will output messages to the adapter trace log file. When Trace mode is false these methods do not produce output. AdapterEnvironment.isDebug() returns "true". You can use this flag to code special actions for the custom adapter when Trace mode is true.

4.4.5 Moving the adapter from test to production

After testing is complete, you can move your adapter into a production environment.

1. Ensure that a compatible version of Data Services is already installed in the production environment. The Data Services Job Server and Access Server must be installed on the workstation before you install your custom adapter.

2. In the Data Services production environment directory, create the following adapters file structure:


Creating an Adapter

3. Move the custom adapter installation template, configuration template, and jar file to their designated

directories:

File Directory location

Installation template <LINK_DIR>/adapters/install/<adapter_name>.xml configuration template <LINK_DIR>/adapters/config/templates/<adapter_name>.xml adapter jar file <LINK_DIR>/lib/<adapter_name>.jar

4. Stop and re-start Data Services services.5. If you have not already done so for this environment, configure a “Primary” repository and a Job Server for

adapter management.6. In the Administrator, configure an instance of your adapter, then start the adapter instance.7. In the Designer, create a corresponding adapter datastore. Manually associate the adapter manager Job

Server.

Related Information

Establishing adapter management [page 14]Configuring an adapter instance [page 94]

4.4.6 Moving a production adapter to another environment

To move an existing custom adapter and all associated jobs into another production environment, you will need to use Data Services Designer export capabilities.

1. Install your adapter in the new production environment. (See steps 1 through 5 in Moving the adapter from test to production [page 84] for details.)

2. Open the Administrator and configure an adapter instance using name and attribute values specific to the production environment.


NoteYou are not required to use the same adapter instance name you used in the test environment. However, you must use the name you choose to:

○ Configure the adapter instance.○ Rename the adapter run-time configuration file (copied from the test environment).○ Update the adapter instance name for the imported adapter datastore in the Designer.

3. Start the adapter instance, verify it runs, then stop the adapter.4. Move the adapter configuration script file from the old environment to the new environment.5. Stop the Data Services service, then restart it.6. Reconfigure all message-oriented operations in the Administrator, or copy the adapter run-time

configuration file <LINK_DIR>/adapter/config/<adapter_instance_name>.xml from the old to the new production environment.

7. From the old environment Designer, export any jobs you created using the adapter to the new production repository. See the Designer Guide for details on exporting objects.

8. Open the Designer in the new environment.9. Reconfigure the adapter datastore. Choose an adapter manager Job Server and adapter instance name for

the new environment, if necessary. Save the new configurations.10. Re-import environment-dependent metadata through the adapter browsing window.11. If necessary, update the properties of second class objects (sources, targets...)for the new environment.12. Restart the adapter from the Administrator. This step is particularly important if you run message-oriented

operations, and/or associated a new Job Server with the adapter datastore.

Related Information

Configuring an adapter instance [page 94]


Creating an Adapter

5 Packaging and deployment

Data Services provides you with a script file that packages and deploys the new adapter to the Data Services environment. To package and deploy your new adapter, perform the following:

1. Add an entry for the new adapter into the AdaptersLatestVersions.csv file, located at <DS_COMMON_DIR>\adapters\upgrade\.For example: MyAdapter|My Adapter|test.MyAdapter|14.2.0.0|/lib/my_adapter.jar

2. Edit to match your Data Services environment and execute the sample script <DS_COMMON_DIR>\sdk\samples\TestAdapter\buildTestAdapter.bat. This script performs the following:○ Builds the adapter java files○ Packages the adapter classes into a .jar○ Creates both required .xml configuration files (Script automatically creates XML files as shown above)○ Copies the .jar and .xml files into Data Services environment

3. You can review the error and trace messages of the script in the file below: <DS_COMMON_DIR>\adapters\upgrade\upgrade_trace.txt

User Guide for Adapter SDKPackaging and deployment PUBLIC 87

6 Configuring and Running an Adapter

6.1 Adapter configuration

Before an adapter can integrate an information resource (IR) with the Data Services system, two types of configuration must occur to facilitate communication between Data Services an IR:

● The adapter writer configures the adapter start-up template and generates a run-time configuration template

● Data Services user configures each adapter instance and associated adapter operations

6.1.1 Preparing configuration templates

For each adapter, you must prepare two important files: the Adapter start-up configuration template and the Adapter run-time confugration template.

Later, when an Data Services user configures adapters from the Administrator, the adapter start-up and run-time XML template files are converted to configuration scripts.

The Data Services Administrator configures each instance of an adapter type as an Data Services subsystem using the adapter's start-up configuration script. In addition, each adapter instance has its own configuration file that configures one or more instances of each operation that the adapter owns and acts as the adapter's run-time configuration. Both start-up and run-time configuration scripts are represented in XML format.

The Adapter SDK includes a function that automatically generates a template for you to use in creating the adapter instance configuration file.

6.1.1.1 Preparing the adapter start-up configuration template

1. Copy the AdapterInstallationTemplate.xml file provided with the Adapter SDK installation from the <LINK_DIR> \/adapters directory to the LINK_DIR/adapters/install/ directory, then change the name of this file to <<AdapterName>>.xml .

2. Edit this file with a text or XML editor. Change element values:

Element name Element value

adapterJarFile Adapter directories and zip/jar files separated by semicolons. Show the location relative to <LINK_DIR>. <LINK_DIR> will be attached automatically when a new adapter instance is configured in the Administrator.


Configuring and Running an Adapter

Element name Element value

adapter3PartyJarFiles Adapter directories and zip/jar files separated by semicolons. Will be added to the classpath without changes when you configure the new adapter instance in the Administrator.

adapterTypeName The name of the installed adapter. The adapter installation template and the adapter run-time template file names must use this name with the .XML extension.

adapterTypeVersion The adapter version number that appears in the Administrator.

adapterMainClass The fully qualified adapter class name.

adapterAdditionalParameters

Additional command line parameters used when starting the adapter.

3. Save the file as <LINK_DIR>/adapters/install/<AdapterName>.xml.

When installing the adapter on a workstation, you must include this adapter start-up configuration template.

6.1.1.2 Generating the adapter run-time configuration template

After you finish coding an adapter, you can generate the adapter run-time configuration template. At the command prompt, enter:

java -classpath <list_of_JAR_files> com.acta.adapter.sdk.AdapterMain -a <adapter_class> -d <configuration_template_file_name>

where:

<list_of_JAR_files> — all Java libraries necessary to run an adapter type. These are:

● <LINK_DIR>/lib/acta_adapter_sdk.jar; ● <LINK_DIR>/lib/acta_broker_client.jar;● <LINK_DIR>/lib/acta_tool.jar; ● <LINK_DIR>/ext/lib/xerces.jar; ● <LINK_DIR>/lib/<adapter type name>.jar

<<adapter_class>> — the fully qualified name of the adapter type class.

<<configuration_template_file_name>> — the name of the file for the generated adapter configuration template.

NoteFor adapter installation, the template file must be saved as <LINK_DIR>/adapters/config/templates/<AdaperName>.xml. Note that the file name is the same as the adpater installation template, but location and contents are different.

The batch file, rtt.bat (rtt.sh on UNIX) generates the adapter run-time configuration template and is provided with the Adapter SDK installation.

User Guide for Adapter SDKConfiguring and Running an Adapter PUBLIC 89

The syntax for using this file is rtt.bat <Adapter jar file> <Adapter type name> <Adapter main class>. For example:

rtt.bat c:/actaworks/lib/acta_test_adapter.jar TestAdapter com.acta.adapter.testadapter.TestAdapter

and on UNIX,

rtt.sh $LINK_DIR/lib/acta_test_adapter.jar TestAdapter com.acta.adapter.testadapter.TestAdapter

6.1.1.3 Run-time configuration template structure

The generated configuration template contains two basic parts:

● The DTD describing required syntax for the XML configuration script● A DTD-compliant XML script containing definitions of configuration elements and their attributes for the

adapter type and its operation types

The Administrator uses this template to create the run-time configuration script from the configuration dialog after adding, updating, and removing the adapter and adapter operation instances. This script provides information necessary to configure adapter and message-oriented operations (values for adapter configuration properties).

NoteAdapter and operaton run-time configuration results are saved in the <LINK_DIR>/adapters/config<AdapterName>.xml file. Although it is not recommended, you can edit this file manually using an XML or text editor.

The TestAdapter (the sample adapter provided with the Adapter SDK) run-time configuration template looks something like this:

<?xml version="1.0" encoding="utf-8"?> <!DOCTYPE AdapterConfiguration[<!ELEMENT AdapterConfiguration ( com.acta.adapter.testadapter.TestAdapter*,com.acta.adapter.testadapter.InvokeService*,com.acta.adapter.testadapter.ReceiveFromRtdf*, com.acta.adapter.testadapter.CallFromRtdf*)*><!ELEMENT com.acta.adapter.testadapter.CallFromRtdf (operationInstanceName,threadCount,displayName,description, enable,responseXmlFileName?,outputDtdFileName?,inputDtdRootElement?, inputDtdFileName?,outputDtdRootElement?)> <!ELEMENT outputDtdRootElement (#PCDATA)><!ELEMENT inputDtdFileName (#PCDATA)><!ELEMENT inputDtdRootElement (#PCDATA)><!ELEMENT outputDtdFileName (#PCDATA)><!ELEMENT responseXmlFileName (#PCDATA)><!ELEMENT com.acta.adapter.testadapter.ReceiveFromRtdf (operationInstanceName,threadCount,displayName,description,enable, dtdRootElement?,targetFileName?,dtdFileName?)><!ELEMENT dtdFileName (#PCDATA)><!ELEMENT targetFileName (#PCDATA)><!ELEMENT dtdRootElement (#PCDATA)>



<!ELEMENT com.acta.adapter.testadapter.InvokeService (operationInstanceName,pollingIntervalMSec,threadCount,displayName, description,enable,timeOut?,sourceXmlFileName?)><!ELEMENT sourceXmlFileName (#PCDATA)><!ELEMENT timeOut (#PCDATA)><!ELEMENT enable (#PCDATA)><!ELEMENT description (#PCDATA)><!ELEMENT displayName (#PCDATA)><!ELEMENT threadCount (#PCDATA)><!ELEMENT pollingIntervalMSec (#PCDATA)><!ELEMENT operationInstanceName (#PCDATA)><!ELEMENT com.acta.adapter.testadapter.TestAdapter (rootDirectory?)><!ELEMENT rootDirectory (#PCDATA)><!ATTLIST com.acta.adapter.testadapter.CallFromRtdf DisplayName CDATA #IMPLIED Description CDATA #IMPLIED isHidden CDATA #IMPLIED isArray CDATA #IMPLIED SDKVersion CDATA #IMPLIED><!ATTLIST outputDtdRootElement DisplayName CDATA #IMPLIED Description CDATA #IMPLIED isHidden CDATA #IMPLIED isArray CDATA #IMPLIED Order CDATA #IMPLIED><!ATTLIST inputDtdFileName DisplayName CDATA #IMPLIED Description CDATA #IMPLIED isHidden CDATA #IMPLIED isArray CDATA #IMPLIED Order CDATA #IMPLIED><!ATTLIST inputDtdRootElement DisplayName CDATA #IMPLIED Description CDATA #IMPLIED isHidden CDATA #IMPLIED isArray CDATA #IMPLIED Order CDATA #IMPLIED><!ATTLIST outputDtdFileName DisplayName CDATA #IMPLIED Description CDATA #IMPLIED isHidden CDATA #IMPLIED isArray CDATA #IMPLIED Order CDATA #IMPLIED ><!ATTLIST responseXmlFileName DisplayName CDATA #IMPLIED Description CDATA #IMPLIED isHidden CDATA #IMPLIED isArray CDATA #IMPLIED Order CDATA #IMPLIED><!ATTLIST com.acta.adapter.testadapter.ReceiveFromRtdf DisplayName CDATA #IMPLIED Description CDATA #IMPLIED isHidden CDATA #IMPLIED isArray CDATA #IMPLIED SDKVersion CDATA #IMPLIED><!ATTLIST dtdFileName DisplayName CDATA #IMPLIED Description CDATA #IMPLIED isHidden CDATA #IMPLIED isArray CDATA #IMPLIED><!ATTLIST targetFileName DisplayName CDATA #IMPLIED Description CDATA #IMPLIED isHidden CDATA #IMPLIED isArray CDATA #IMPLIED><!ATTLIST dtdRootElement DisplayName CDATA #IMPLIED Description CDATA #IMPLIED isHidden CDATA #IMPLIED isArray CDATA #IMPLIED><!ATTLIST com.acta.adapter.testadapter.InvokeService DisplayName CDATA #IMPLIED Description CDATA #IMPLIED isHidden CDATA #IMPLIED isArray CDATA #IMPLIED SDKVersion CDATA #IMPLIED><!ATTLIST sourceXmlFileName DisplayName CDATA #IMPLIED Description CDATA #IMPLIED isHidden CDATA #IMPLIED isArray CDATA #IMPLIED Order CDATA #IMPLIED><!ATTLIST timeOut DisplayName CDATA #IMPLIED Description CDATA #IMPLIED isHidden CDATA #IMPLIED isArray CDATA #IMPLIED Order CDATA #IMPLIED><!ATTLIST com.acta.adapter.testadapter.TestAdapter DisplayName CDATA #IMPLIED Description CDATA #IMPLIED isHidden CDATA #IMPLIED isArray CDATA #IMPLIED SDKVersion CDATA #IMPLIED><!ATTLIST rootDirectory DisplayName CDATA #IMPLIED Description CDATA #IMPLIED isHidden CDATA #IMPLIED isArray CDATA #IMPLIED> ]><AdapterConfiguration>


<com.acta.adapter.testadapter.TestAdapter DisplayName ="TestAdapter." Description ="Sample adapter to demonstrate features." SDKVersion ="2.0.0.0.B"> <rootDirectory DisplayName ="Root directory" Description ="Enter the name of root directory where the adapter will wait for files-events to arrive."> C:/Actaworks/adapters/samples/TestAdapter/Data</rootDirectory></com.acta.adapter.testadapter.TestAdapter><com.acta.adapter.testadapter.InvokeService DisplayName ="Invoke a RealTime service" Description ="Invoke the configured RealTime service with an XML message extracted from a file." SDKVersion ="2.0.0.0.B"> <operationInstanceName DisplayName="Operation instance" Description="For messages that this operation receives from ActaWorks this name should match the correspondent outbound message or function call name."></operationInstanceName><pollingIntervalMSec DisplayName="Polling interval" Description="Interval in msec. to call PollOperation.poll() method.">1000</pollingIntervalMSec> <threadCount DisplayName="Thread count" Description="Number of copies of this operation to run in parallel.">1</threadCount> <enable DisplayName="Enable" Description="Enable to run operation when adapter starts." Choices="true|false" >true</enable> <sourceXmlFileName DisplayName ="Source XML File Name" Description ="Enter the name of the source XML file to invoke the RealTime service." Order="1"></sourceXmlFileName> <timeOut DisplayName ="Timeout value" Description ="Enter the timeout value (in milliseconds)." Order="2"></timeOut> </com.acta.adapter.testadapter.InvokeService> <com.acta.adapter.testadapter.ReceiveFromRtdf DisplayName ="Receive message from ActaWorks." Description ="Process message from the dataflow's outbound message." SDKVersion ="2.0.0.0.B"> <operationInstanceName DisplayName="Operation instance" Description="For the messages that this operation receives from ActaWorks this name should match the correspondent outbound message or function call name."></operationInstanceName> <threadCount DisplayName="Thread count" Description="Number of copies of this operation to run in parallel.">1</threadCount> <displayName DisplayName="Display name" Description="Display name for metadata browsing."></displayName> <description DisplayName="Description" Description="Description for metadata browsing."></description> <enable DisplayName="Enable" Description="Enable to run operation when adapter starts." Choices="true|false" >true</enable> <dtdRootElement DisplayName ="The root element name" Description ="Enter the name of the root element for the DTD for this operation."></dtdRootElement> <targetFileName DisplayName ="Target file" Description ="Enter the name of the target file to store the xml received from the outbound message."></targetFileName> <dtdFileName DisplayName ="File name with DTD" Description ="Enter the file name that contain the DTD fro the xml used in this operation."></dtdFileName> </com.acta.adapter.testadapter.ReceiveFromRtdf> <com.acta.adapter.testadapter.CallFromRtdf DisplayName ="Receive message from ActaWorks and send response" Description ="Process message from the dataflow's Message Function call." SDKVersion ="2.0.0.0.B"> <operationInstanceName DisplayName="Operation instance" Description="For the messages that this operation receives from ActaWorks this name should match the correspondent outbound message or function call name."></operationInstanceName> <threadCount DisplayName="Thread count" Description="Number of copies of this operation to run in parallel.">1</threadCount> <displayName DisplayName="Display name" Description="Display name for metadata browsing."></displayName> <description DisplayName="Description" Description="Description for metadata browsing."></description> <enable DisplayName="Enable" Description="Enable to run operation when adapter starts." Choices="true|false" >true</enable> <responseXmlFileName DisplayName ="XML Response File" Description ="Enter the name of the file to store the xml response from message function call." Order="1"></responseXmlFileName> <inputDtdFileName DisplayName ="File name with input DTD" Description ="Enter the file name that contain the input DTD for the xml used in this operation." Order="2"></inputDtdFileName>



<inputDtdRootElement DisplayName ="The root element name for input DTD" Description ="Enter the name of the root element for the input DTD for this operation." Order="3"></inputDtdRootElement> <outputDtdFileName DisplayName ="File name with output DTD" Description ="Enter the file name that contain the output DTD for the xml used in this operation." Order="4"></outputDtdFileName> <outputDtdRootElement DisplayName ="The root element name for output DTD" Description ="Enter the name of the root element for the output DTD for this operation." Order="5"></outputDtdRootElement> </com.acta.adapter.testadapter.CallFromRtdf> </AdapterConfiguration>

Adapter type and adapter operation type configuration elements contain system properties and user-defined properties (presented as XML elements), as follows:

System properties

Property Description

operationInstanceName

The operation instance name. No default value (you must define the value). For adapter operations that implement the ListenerOperation interface, the operation instance name must be the same as the “outbound message” name or the “function call” name defined for the associated real-time job in the Data Services Designer.

threadCount The number of copies of the adapter operation to run in parallel. Default value is 1. Use more than one copy for asynchronous (parallel) processing of inbound and outbound messages. If the message sequence is important, do not use more than one thread; use synchronous processing.

For adapter operations that invoke a real-time service, multiple copies of the operation should be supported by an equal number of real-time services. Each operation waits for its associated real-time service to finish processing before the next message can be processed. This makes it impractical to run multiple copies of the adapter operation when not supported by multiple copies of real-time services.

For adapter operations that process messages from Data Services, use multiple copies of the operation when:

● The same adapter operation receives messages from different real-time services (running in parallel) through “function call” or “outbound message” Designer objects.

● The same adapter operation receives messages from multiple copies of the same real-time services, and real-time processing is faster than information resource (IR) processing in the adapter operation.

pollingIntervalMSec

This system property is generated in the configuration template if the adapter type or adapter operation type implements the PollAdapter or PollOperation interface. It specifies the frequency at which the adapter polls the information resource. The Adapter SDK is guaranteed to poll the resource at a time interval greater than or equal to pollingIntervalMSec. Actual polling intervals can be greater than pollingIntervalMSec because the time necessary to perform the adapter operation may be greater than pollingIntervalMSec. We recommend that you define pollingIntervalMSec to be no more than a few seconds so that the Adapter SDK can periodically regain control from the adapter operation, providing for effective life-cycle management (start/stop).

displayName The operation instance display name. View the display name in the Designer's metadata browsing window.

description The operation instance description. View this description in the Designer's metadata browsing window.

enable True if the Adapter SDK will start this operation instance when adapter starts, otherwise, false.


User-defined properties

The Adapter SDK generates a configuration property for each public set<Configuration_property> method defined in the adapter class or adapter operation class. <Configuration_property> represents the name of the configuration property. The first character of <Configuration_property> must be in uppercase. The configuration property data type can be any of the following:

● arrays (of any of the following object types)● boolean● char● double● float● int● java.lang.String● long● object (any java objects that contain these property types)● short

For example, if the adapter code contains:

package com.acta.adapter.testadapter; public class TestAdapter implements Adapter{ ... public String rootDirectory; public void setRootDirectory (String directory){ rootDirectory=directory; } ... }

then, the generated adapter configuration template will contain:

.... <!ELEMENT com.acta.adapter.testadapter.TestAdapter (rootDirectory?)> .... <!ELEMENT rootDirectory(#PCDATA)> .... <rootDirectory DisplayName=""Description=""></rootDirectory>

6.1.2 Configuring an adapter instance

After an adapter is installed, the Data Services user must configure adapter instances using the Administrator in the Management Console.

1. In the Administrator, under Adapter Instances, click on a <Job Server> name. Job Servers are listed under this node after you enable them for use with adapters using the Server Manager.

2. On the Adapter Instance Status page, click the Configuration tab.3. Click Add.4. Click the link of the adapter for which you want to create a new instance. Adapters are listed if they are

installed on the Job Server's computer.



5. Complete the Adapter instance start-up and configuration form. For more information, see the Administrator Guide.

6. Click Apply to set the configuration parameters.7. See the <LINK_DIR>/adapters/startup_script.xml file to verify adapter instance start-up

configuration changes.

See the <LINK_DIR>/adapters/config/<adapter instance name>.xml file to verify adapter instance run-time configuration changes

Start the adapter, verify that it functions, then stop the adapter before attempting to configure message-oriented adapter operations.

6.1.3 Configuring an adapter operation

1. In the Administrator, under Adapter Instances, click a <Job Server>.

2. On the Adapter Instance Status page, click the Configuration tab.3. Under Dependent Objects, next to the adapter instance for which you want to configure operations, click

Operations.4. Click Add to configure a new operation.

Here, you can also click the link of an existing operation to edit the configuration of an existing operation.5. After you click Add, select an operation from the Operation type list and click Apply.6. Complete the configuration form for that operation and click Apply.7. Repeat the previous steps for each operation you want to configure.

Configuration forms may differ between operations.8. Restart the adapter for adapter operation configurations to take affect.9. See the <LINK_DIR>/adapters/config/<<adapter instance name>>.xml file to verify your

operation run-time configuration changes.

6.2 Starting the Adapter SDK driver

There are two ways to start the Adapter SDK driver:

● Use the adapter Start function in the Data Services Administrator.● Start an adapter from a command prompt or under a debugging tool.

6.2.1 Starting an adapter using the command prompt

For debugging purposes, you can start an adapter using the command prompt or from debugging tools. (This assumes the adapter instance is not running.)


1. Open the <LINK_DIR>/adapters/startup_script.xml file in your text editor, manually change the value of the “debugDeveloperMode” element to “true”, then save the file.

2. From the Data Services Administrator, start the adapter instance. The Job Server:○ Prints to the Job Server log file the background command line that it will execute.○ Waits indefinitely for the registration message from the adapter.

3. Use your text editor to open the Job Server log file, <LINK_DIR>/log/<JobServerName>/server_eventlog.txt.Find the command line to start the adapter instance at the end of the file.

4. Copy the command line and paste in the command prompt or in your debugging tool for use in starting the adapter. The command line syntax for starting an adapter is:

java -classpath <list_of_jar_files> com.acta.adapter.sdk.AdapterMain -a <adapter_class> -i <adapter_instance_name> -r LINK_DIR -h <job_server_host_name> -p <job_server_port> [-v] -c <adapter_manager_id> -51 -sh <access _server_host_name> -sp <access_server port>

where:

<<list_of_jar_files>> — all Java libraries necessary to run an adapter. The jar files required by the Adapter SDK are:

<LINK_DIR>/lib/acta_adapter_sdk.jar Adapter SDK

<LINK_DIR>/lib/acta_broker_client.jar Broker Client

<LINK_DIR>/lib/acta_tool.jar Helper classes

<LINK_DIR>/ext/lib/xerces.jar XML parser

<LINK_DIR>/lib/<adapter type name>.jar Adapter's jar file

NoteBrokerClient.jar is an implementation of the broker client API.

com.acta.adapter.sdk.AdapterMain — The Adapter SDK driver class name.

<<adapter_class>> — The fully qualified name of the adapter type class.

<<adapter_instance_name>> — The name of the adapter instance (the same name used by the adapter instance's datastore in the Data Services Designer).

<LINK_DIR> — The value for the LINK_DIR environmental variable.

<job_server_<host_name>> — The host name of the computer where the Job Server runs.

<job_server_<port>> — The Job Server port.

[-v] — Turns off the "trace" mode. Refer to the Data Services Administrator Guide for more information.



<<access_server_host_name>> — The host name of the computer where the Access Server runs.

<<access_server_port>> — The Access Server port.

<<adapter_manager_id>> — The unique ID used by the Job Server to communicate with the adapter. When starting an adapter from the command line, you must use this value. Find this value in the Job Server log file.


7 TestAdapter

7.1 Understanding TestAdapter

TestAdapter, the sample adapter included with the Adapter SDK, uses your computer's file system as an information resource (IR) to demonstrate how the following features are implemented using the Adapter SDK :

● Metadata browsing and metadata import. Import both by browsing and by name.● Message-oriented operations initiated by both Data Services and the information resource.● Stream-oriented operations (shows each of the five basic batch interactions between Data Services and an

information resource).● Adapter datastore configuration. Implementing the Session interface exposes configuration properties in

the adapter datastore.● Adapter component customization. Provides user-friendly configuration from the Data Services

Administrator and Designer.

You can use TestAdapter as a working prototype for developing your own custom adapters.

This section provides an overview of TestAdapter as well as step-by-step instructions for preparing and operating it. Use this section to:

● Identify TestAdapter and its associated files● Configure TestAdapter instances and operations● Create data flows that use TestAdapter operations● Configure client interfaces that use TestAdapter operations● Launch TestAdaper● Start real-time services, jobs, and test applications to verify TestAdapter's functionality.

7.2 TestAdapter and associated files

After installing the Adapter SDK , on Windows, find the TestAdapter jar file at <LINK_DIR>/lib/acta_test_adapter.jar.

After installing the Adapter SDK, on UNIX, find the TestAdapter jar file at <LINK_DIR> /lib/acta_test_adapter.jar.

All files necessary to operate TestAdapter are located at <LINK_DIR> /adapters/sdk/samples/testadapter.

The following table provides a quick description of the testadapter directory and some of its subdirectory structure.


TestAdapter

Item Description

buildTestAdapter.bat Batch file to build the adapter.

in_sales_details.txt Source file used in Job_Table_delim_target job.

InvokeTest1.xml Source XML document used to invoke the real-time service defined for the RTJob_InvokeTest1 job.

InvokeTest2.xml Source XML document used to invoke the real-time service defined for the RTJob_InvokeTest2 job.

ListOfOrderEntrySample.dtd DTD file imported into Data Services . DTD used to create the Document Source for the RTDF_OutboundMessage real-time data flow in the RTJob_OutboundMessage job. (This DTD is already imported into the repository.)

mtrl_avail.xml XML document used to run RTJob_OutboundMessage and RTJob_MessageFunction jobs in test mode.

mtrl_avail_in.dtd DTD file imported into Data Services . DTD used to create the input XML Document for RTDF_MessageFunction real-time data flow from Job RTJob_MessageFunction job. (This DTD is already imported into the repository.)

mtrl_avail_in_OK.xml XML document used to test real-time services created from JobsRTJob_MessageFunction and RTJob_OutboundMessage jobs. Used in StartOutboundTest.bat and StartFunctionCallTest.bat.

mtrl_avail_out.dtd DTD file imported into Data Services . DTD used to create the output XML Document for RTDF_MessageFunction real-time data flow from Job RTJob_MessageFunction job. (This DTD is already imported into the repository.)

StartFunctionCallTest.bat Batch file to test ReceiveFromRtdf operation.

StartOutboundTest.bat Batch file to test CallFromRtdf operation.

TestAdapter.atl File that populates the Data Services repository.

<DIR> data Directory of test results for the message-oriented operations.

Data/Session1 Directory for session-related data, table , XML, and DTD files

Data/FunctionCallTest.xml Response message file for CallFromRtdf

<DIR> src Directory for test adapter source files

7.3 TestAdapter source code

Your Adapter SDK installation includes a pre-built jar file for TestAdapter (acta_test_adapter.jar). The jar file contains classes for the TestAdapter components.

Your installation also includes buildTestAdapter.bat, a batch file used to recreate the acta_test_adapter.jar file . This batch file also serves as an example of how to build (compile and package) your custom adapter. This batch file also recreates the run-time configuration file, <DS_COMMON_DIR>/adapters/config/templates/TestAdapter.xml.

The source code for TestAdapter includes the following files:

User Guide for Adapter SDKTestAdapter PUBLIC 99

File Contains a sample implementation of:

Browse.java The MetadataBrowsing interface.

CallFromRtdf.java The ListenerOperation interface. The CallFromRtdf operation type works like the ReceiveFromRtdf adapter operation type, only the real-time function call sending the message waits for a reply.

CallFromRtdfBeanInfo.java The customizer for the CallFromRtdf.java class.

ColumnNode.java The MetadataNode interface.

FileNode.java The MetadataNode interface.

FunctionCallTest.java The FunctionCall interface.

Import.java The MetadataImport interface.

InvokeService.java The PollOperation interface, which polls the information resource (our sample files), seeking certain events (in this case, a file written to a configured location).

InvokeServiceBeanInfo.java The customizer for InvokeService.java class.

ReadDocument.java The DocumentSource, Operation, and StreamOperation interfaces.

ReadTable.java The Delimited, Operation, StreamOperation, Table, and TableSource interfaces.

ReceiveFrom Rtdf.java The ListenerOperation interface, which processes messages received from real-time services.

ReceiveFromRtdfBeanInfo.java The customizer for the ReceiveFrom Rtdf.java class.

RootNode.java The MetadataNode interface.

TestAdapter.java The Adapter interface.

TestAdapterBeanInfo.java The customizer for the Adapter class.

TestImportByName.java The ImportByName interface.

TestImportByNameBeanInfo.java

The customizer for the TestImportByName class.

TestSession.java The Session interface.

TestSessionBeanInfo.java The customizer for the TestSession class.

WriteDocument.java The DocumentTarget, Operation, and StreamOperation interfaces.

WriteTable.java The Delimited, Operation, StreamOperation, Table, and TableTarget interfaces.

WriteTableBeanInfo.java The customizer for the WriteTable class.

7.4 Preparing and testing TestAdapter

This section explains how to prepare, run, and test TestAdapter. Use this section to:


TestAdapter

● Populate the Data Services repository● Configure real-time services● Configure adapter (start-up and run-time)● Configure adapter operation(s)● Start the adapter● Create the TestAdapter datastore● Test browse and import metadata capabilities● Test import by name● Start real-time services● Verify message-oriented adapter operations● Verify stream-oriented adapter operations

7.4.1 Populate the Data Services repository

To use TestAdapter with Data Services, you must first populate the Data Services repository. To do this, open the Data Services Designer and import the following file into the Data Services repository.

<LINK_DIR>/adapters/sdk/samples/testadapter/TestAdapter.atl

See the Designer Guide for specific instructions on how to import an ATL file.

After you import this file, all objects necessary to support the test adapter are automatically added to the Data Services repository.

In the Object Library, select the Datastores tab and open the TestAdapter datastore to view all available datastore type objects for this sample adapter.

In the Projects tab, double-click to open TestAdapter_Project. This project contains seven batch jobs and four real-time jobs. The following illustration shows drill-down details (sources, query transforms, and targets) for three of these jobs.


Notice that the four real-time jobs contain simple real-time data flows. They are:

Job Description

RTDF_InvokeTest1 Tests InvokeService adapter operation template.

RTDF_InvokeTest2 Tests another instance of the InvokeService adapter operation template.

RTDF_MessageFunction Tests the CallFromRtdf adapter operation template.

RTDF_OutboundMessage Tests the ReceiveFromRtdf adapter operation template.

7.4.2 Configure real-time services

After you import the ATL file into the Designer, use the Data Services Administrator to add services for the real-time jobs. Refer to the Administrator Guide for specific instructions on how to add the following job services:

Service Real-time job Data flow

InvokeTest1 RTJob_InvokeTest1 RTDF_InvokeTest1

InvokeTest2 RTJob_InvokeTest2 RTDF_InvokeTest2


TestAdapter

Service Real-time job Data flow

ReceiveFromAWAndReply RTJob_MessageFunction RTDF_MessageFunction

ReceiveFromAW RTJob_OutboundMessage RTDF_OutboundMessage

7.4.3 Configure adapter (start-up and run-time)

In the Data Services Administrator, you configure an adapter instance by first choosing a Job Server. Install the adapter on a Job Server computer, then, using the Server Manager, edit the Job Server configuration by selecting the Enable adapter and message broker communication check box. Next, open the Administrator and click the Adapter Instances node. You should see the Job Servers you enabled to support adapters listed under this node.

7.4.3.1 Configuring a new adapter instance

1. In the Administrator, under Adapter Instances, click a Job Server name. Job Servers are listed under this node after they are enabled for use with adapters in the Server Manager.

2. On the Adapter Instance Status page, click the Configuration tab.3. Click Add.4. Click the link of the adapter for which you want to create a new instance. Adapters are listed if they are

installed on the Job Server's computer.5. Complete the Adapter instance start-up and configuration form.

Related Information

Configuring a new TestAdapter instance [page 103]

7.4.3.2 Configuring a new TestAdapter instance

1. Follow the instructions for “Configuring a new adapter instance”.2. Complete the Adapter instance start-up configuration form according to the following table. For the run-

time configuration, the value of Root directory must refer to the directory where Data Services is installed.Specific entries are enclosed in quotation marks. Additional information is listed within parenthesis.

Field Name Enter:

Adapter instance name “TestAdapterInstance”"


Field Name Enter:

Access Server Host The name of the computer where your Access Server is running.

Access Server Port “4000”

NoteThis should be the port number associated with the client interfaces for the Access Server Host you specified above, unless you changed it.

Adapter retry count (Leave unchanged.)

Adapter retry interval (Leave unchanged.)

Classpath (Automatically entered.)

Autostart (Automatically entered.)

Trace mode (Automatically entered.)

Application java launch options

(Leave unchanged.)

Adapter type name (Automatically entered.)

Adapter version (Automatically entered.)

Adapter class (Automatically entered.)

Root directory "LINK_DIR/Data Services/adapters/sdk/samples/testadapter/data"

3. Click Apply to set the configuration parameters.4. View the status of the adapter instance on the Adapter Instance Status page.

7.4.3.3 About TestAdapter configuration files

Adapter instance start-up and run-time configuration information is contained in XML files that Data Services users can edit using the Administrator. However, you can edit these files manually using a text editor.

For the TestAdapter, the configuration file is located in the following directory:

<LINK_DIR>/adapters/sdk/samples/testadapter/TestAdapterInstance.xml

7.4.4 Configuring operations for TestAdapterInstance in the Administrator

1. In the Administrator, under Adapter Instances, click a Job Server name.2. On the Adapter Instance Status page, click the Configuration tab.3. Next to TestAdapterInstance, click Operations under Dependent Objects.4. Click Add to configure a new operation.

Here, you can also click the link of an existing operation to edit the configuration of an existing operation.


TestAdapter

5. After you click Add, select Invoke a RealTime service from the Operation type list and click Apply.6. Complete the Invoke a RealTime service configuration form for InvokeTest1 operation and click Apply.

7. Repeat the previous steps, substituting InvokeTest2 for the operation in step #6.

8. Repeat steps 1 through 5, but choose Receive message from Data Services from the Operation type list and click Apply.

9. Complete the Receive message from Data Services service configuration form for the ReceiveFromAW operation and click Apply.

Parameter Value

Operation instance ReceiveFromAW

Thread count 1

Display name Receive from AW

Description Outbound Message for TestAdapter

Enable true

The root element name mtrl_avail_document

Target file OutboundTarget.xml

File name with DTD ..\adapters\sdk\samples\TestAdapter\mtrl_avail_in.dtd

10. Repeat steps 1 through 5, but choose Receive message from Data Services and send response from the Operation type list and click Apply.

11. Complete the Receive message from Data Services and send response service configuration form for the ReceiveFromAWAndReply operation and click Apply.

Parameter Value

Operation instance ReceiveFromAWAndReply

Thread count 1

Display name Receive from AW And Reply

Description Receive from AW And Reply Description

Enable true

XML response file FunctionCallTest.xml

File name with input DTD ..\adapters\sdk\samples\TestAdapter\mtrl_avail_in.dtd

Root element name for DTD mtrl_avail_document

File name with output DTD ..\adapters\sdk\samples\TestAdapter\mtrl_avail_out.dtd

Root element name for output DTD ord_create_document

You will have added four new operations to TestAdapterInstance. These operations are closely associated with jobs you previously imported into the Data Services Designer.

7.4.5 Starting the adapter instance

1. In the Administrator, select Adapter Instances Job Server .


2. Mark the Select box next to the TestAdapter instance you configured previously.3. Click Start.

When your adapter instance and its operations start, the message, “Started” appears in the Status column and the status for each Operation Instance is indicated by a status icon.

7.4.6 Creating the TestAdapter datastore

Create a TestAdapter datastore in the Designer to use TestAdapter metadata in applications designed with Data Services . The procedures you will need to follow are described below.

1. In the Datastores tab of the Designer Object Library, right-click and select New.

The Datastore Editor appears showing a Connection tab.2. In the name text box, type TestAdapter.3. Select Adapter for Application type.

The Adapter Properties tab appears.4. Select the Job Server associated with TestAdapter.5. Choose TestAdapterInstance as Adapter instance name.6. Click to select the Adapter Properties tab.7. In the Value column, enter Session1, then click OK.

In the Description column, you'll see the following text:

“Enter the name of the subdirectory for the adapter directory defined for the directory adapter property in the adapter configuration.”

For this adapter, the developer required one property. The Data Services user is required to enter the name of a metadata sub-directory. The value of this property affects how the metadata appears in the adapter browser window.

After you create the TestAdapter datastore, you can browse and import sample data.

7.4.7 Testing browse and import metadata capabilites

The TestAdapter provides access to sample metadata, organized by categories. Each category is a primary node in the Adapter Metadata Browser window. Files are listed in alphabetical order while message functions are categorized by operation type.

1. Double-click the TestAdapter datastore icon.The Adapter Metadata Browser window opens.

2. Click to open nodes and browse the available metadata.3. Right-click any node to find out if that metadata can be imported into Data Services . If Import appears as

the right-click menu option, you can import the metadata. For example:○ Open the Q...Z category node.○ Right-click the sales_details_delim(table) object, and click Import.


TestAdapter

7.4.8 Importing TestAdapter metadata by name

Scan the browser window to become familiar with metadata available from TestAdapter, then import some metadata objects by name.

1. Right-click the TestAdapter datastore icon and select Import By Name from the menu.2. In the Import By Name window, select a metadata type from the Value list (choose table), then enter the

metadata name (enter sales_details_delim_target).3. Click OK to import that metadata object.

4. Look in the Object Library under TestAdapter Tables to verify that the “sales_details_delim_target” table was imported to your repository.

7.4.9 Other options

From the Data Services Designer, you can delete imported metadata by right-clicking an imported object and selecting Delete from the menu.

You can also create new resource metadata using existing metadata files in the .../Data/Session1 directory as a prototypes. You can open a prototype file using any text editor. Modify the information within existing structure constraints (see the FileNode class in the Adapter SDK API documentation for structure details), and save as a new metadata file.

In the Designer, close and reopen the metadata browsing window to save and view the new metadata. You should be able to import the new metadata from the browsing window.

7.4.10 Starting real-time services for TestAdapter

1. In the Data Services Administrator, select Real-time Access Server Real-time services .2. Click Select all.3. Click Start.

When all services are started, the message “<Service started>” appears in the Status column.

7.4.11 Verify message-oriented adapter operations

This section describes methods to verify message-oriented adapter operations.


7.4.11.1 InvokeTest1 and InvokeTest2

InvokeTest1 and InvokeTest2 are configured instances of the InvokeService adapter operation template. For more information on these operation types, refer to the comments inside InvokeService.java.

To exercise and verify these two operation instances on the Job Server computer, copy the following two XML files:

<LINK_DIR>/adapters/sdk/samples/testadapter/InvokeTest1.xml

<LINK_DIR>/adapters/sdk/samples/testadapter/InvokeTest2.xml

to the following directory:

<LINK_DIR>/adapters/sdk/samples/testadapter/data

If the test adapter successfully processes these two XML files, it deletes them and places two reply files in the same directory. The reply file names include the timestamp and have a form like:

__reply__989622999190__InvokeTest1.xml

__reply__989623001153__InvokeTest2.xml

7.4.11.2 TestAdapterOutboundMessage

TestAdapterOutboundMessage is a configured instance of the ReceiveFromRtdf adapter operation template. For more information on this operation type, refer to the comments inside ReceiveFromRtdf.java.

To verify this operation, go to the command prompt and change directories to the following directory:

<LINK_DIR>/adapters/sdk/samples/testadapter

Enter the following command:

StartOutboundTest.bat <host_name> <message_broker_client_port>

This batch file starts the ClientTest application that initiates the OutboundMessageTest service. The service processes the input XML message mtrl_avail_in_OK.xml and sends the reply XML message to TestAdapterOutboundMessage operation. The operation saves the reply XML message on the Job Server computer in the <LINK_DIR>/adapters/sdk/samples/testadapter/data directory. You will see something like:

received__989976693948__OutboundTarget.xml

if the operation completes successfully. You will also see the reply XML message from the service as an output of the ClientTest application. The presence of the element <CHECK_RULE>Ok</CHECK_RULE> in the message confirms that the ClientTest application received the correct reply message.

7.4.11.3 TestAdapterRequest

TestAdapterRequest is a configured instance of the CallFromRtdf adapter operation template. For more information on this operation type, refer to the comments inside CallFromRtdf.java.


TestAdapter

To verify this operation, go to the command prompt and change directories to the following directory.

<LINK_DIR>/adapter/sdk/samples/testadapter

Enter the following command.

StartFCallTest.bat <host_name> <message_broker_client_port>

This batch file starts the ClientTest application that initiates the FunctionCallTest service. This service processes the input XML message mtrl_avail_in_OK.xml and sends the request XML message from the Query transform to the TestAdapterRequest operation. The operation ignores this message and sends the configured XML message inside the Data/FunctionCallTest.xml file as the reply. The service continues processing and sends the reply XML message to the ClientTest application, which displays a message.

An empty value for the <RETURNED_MESSAGE> element confirms that the ClientTest application received the correct reply message.

If a problem occurs during real-time service message processing, the <RETURNED_MESSAGE> element contains an error message and the <RETURNED_ID> element contains an error code.

7.4.12 Verify stream-oriented adapter operations

To verify TestAdapter's stream-oriented operations, run the following jobs from the Data Services Designer. These jobs are populated in the Data Services repository after you import the TestAdapter.atl file provided with your Adapter SDK installation.

Job Data flow demonstrates TestAdapter source code

Job_Document_source Adapter document source. src/com/acta/adapter/testadapter/ReadDocument.java

Job_Table_delim_source Adapter table source.

Delimited format data exchange.

src/com/acta/adapter/testadapter/ReadTable.java

Job_Table_xml_source Adapter table source.

XML format data exchange.


Job_Document_target Adapter table source. src/com/acta/adapter/testadapter/ReadTable.java

Job_Table_delim_target Adapter table target.

Delimited format data exchange.

src/com/acta/adapter/testadapter/WriteTable.java

Job_Table_xml_target Adapter table target.

XML format data exchange.


Job_FunctionCall Adapter function call in the query transform. src/com/acta/adapter/testadapter/FunctionCallTests.java


7.4.12.1 Job_Document_source

Demonstrates how a stream-oriented adapter operation supports a document source in a Data Services data flow. Implements the com.acta.adapter.sdk.DocumentSource interface.

Source code:

src/com/acta/adapter/testadapter/ReadDocument.java

Imported adapter metadata:

Document: mtrl_avail_doc(TestAdapter)

Other metadata involved:

DTD file: mtrl_avail_document

Input data:

<LINK_DIR>/adapters/sdk/samples/testadapter/data/Session1/mtrl_avail_doc.dat

Expected output:

<LINK_DIR>/adapters/sdk/samples/testadapter/data/out_mtrl_avail.xml

Should generate a new file with the same results as the source document.

7.4.12.2 Job_Table_delim_source

Demonstrates how a stream-oriented adapter operation supports a table source in a Data Services data flow (delimited format data exchange). Implements com.acta.adapter.sdk.TableSource and com.acta.adapter.sdk.Delimited interfaces.

Adapter operation:



sales_details_delim(TestAdapter)


File Format: NoHeaderFF

Input data:

<LINK_DIR>/adapters/sdk/samples/testadapter/data/Session1/sales_details_delim.dat

Expected output:

<LINK_DIR>/adapters/sdk/samples/testadapter/data/out_sales_delim.txt

Should generate a copy of the source file.


TestAdapter

7.4.12.3 Job_Table_xml_source

Demonstrates how a stream-oriented adapter operation supports a table source in a Data Services data flow (XML format data exchange). Implements the com.acta.adapter.sdk.TableSource interface.

Adapter operation:



sales_details_xml(TestAdapter)


File Format: NoHeaderFF

Input data:

<LINK_DIR>/adapters/sdk/samples/TestAdapter/Data/Session1/sales_details_delim.dat

Expected output:

<LINK_DIR>/adapters/sdk/samples/testadapter/data/out_sales_xml.txt

Should generate a copy of the source file.

7.4.12.4 Job_Document_target

Demonstrates how a stream-oriented adapter operation supports a table source in a Data Services data flow. Implements the com.acta.adapter.sdk.DocumentTarget interface.

Adapter operation:

src/com/acta/adapter/testadapter/WriteDocument.java


sales_details_delim(TestAdapter)


DTD file: material_avail_document

Input data:

<LINK_DIR>/adapters/sdk/samples/TestAdapter/mtrl_avail.xml

Expected output:

<LINK_DIR>/adapters/samples/testadapter/data/Session1/sales_details_delim.dat

Should overwrite the existing file with the input document contents.


7.4.12.5 Job_Table_delim_target

Demonstrates how a stream-oriented adapter operation supports a table target in a Data Services data flow (delimited format data exchange). Implements the com.acta.adapter.sdk.TableTarget and com.acta.adapter.sdk.Delimited interfaces.

Adapter operation:



sales_details_delim_target(TestAdapter)


DTD material_avail_document

Input data:

<LINK_DIR>/adapters/sdk/samples/testadapter/in_sales_details.txt

Expected output:

<LINK_DIR>/adapters/sdk/samples/testadapter/data/Session1/ sales_details_delim_target.dat, the copy of the source file. The new data will be appended because the append option is true for the adapter target.

7.4.12.6 Job_Table_xml_target

Demonstrates how a stream-oriented adapter operation supports a table target in a Data Services data flow (XML format data exchange). Implements the com.acta.adapter.sdk.TableTarget interface.

Adapter operation:


Imported Adapter metadata:

sales_details_xml_target(TestAdapter)


File Format: sales_details

Input data:

<LINK_DIR>/adapters/sdk/samples/testadapter/in_sales_details.txt

Expected output:

Should generate a copy of the source file. The new data will be appended because the append option is true for the adapter target.

<LINK_DIR>/adapters/sdk/samples/testadapter/data/Session1/sales_details_xml_target.dat.


TestAdapter

7.4.12.7 Job_FunctionCall

Demonstrates how a stream-oriented adapter operation supports a function call in a Data Services data flow query transform. Implements the com.acta.adapter.sdk.FunctionCall interface.

Adapter operation:

src/com/acta/adapter/testadapter/FunctionCallTest.java

Imported Adapter metadata:

func_call(TestAdapterInstance)


DTD files: mtrl_avail_in and mtrl_avail_out

Input data:

<LINK_DIR>/adapters/sdk/samples/testadapter/mtrl_avail_in_OK.xml

Expected output:

<LINK_DIR>/adapters/sdk/samples/testadapter/data/out_mtrl_avail_func.xml


8 Debugging in Eclipse

8.1 Debugging in Eclipse

Before you debug in Eclipse, you need to do the following:

● Stop the Data Services service.● Edit <DS_COMMON_DIR>\adapters\startup_script.xml. Set the element debugDeveloperMode to

true● Start the Data Services service● In Management Console, your adapter instance should have a 'Starting' status. Other adapter instances

should have a 'Started' status.● Set a breakpoint in your adapter code.

Perform the following to debug your adapter in Eclipse:

1. To open Debug Configurations, click the Debug icon and clicking Debug Configurations.2. Create a new configuration by right-clicking Java Application and clicking New.3. Under Main class, click Search, and choose com.acta.adapter.sdk.AdapterMain.4. Click the Arguments tab, and enter the following:

-a test.MyAdapter -i my_adapter -h PALD00494877A -p 4001 -ssl No -c com.acta.adapter.ServiceProvider.my_adapter -cs default -mcs default -51 -js win_j1 -r "<LINK_DIR>" -cr "<DS_COMMON_DIR>"

NoteIn the text above, you must replace “my_adapter” with the name of your adapter instance. Also replace the paths.

5. Click Debug to start the debug process.

● MetadataNode interface: Even though the interface doesn't require, users should provide at minimal the methods below in order to identify the current node for further browsing and importing○ public void setUniqueName(String v)○ public void setDisplayName(String v)

● When 'Pushdown' is used, users should implement both 'SQLEnable' and 'QueryInXML' along with 'TableSource' at the reader level.


Debugging in Eclipse

Important Disclaimers and Legal Information

HyperlinksSome links are classified by an icon and/or a mouseover text. These links provide additional information.About the icons:

● Links with the icon : You are entering a Web site that is not hosted by SAP. By using such links, you agree (unless expressly stated otherwise in your agreements with SAP) to this:

● The content of the linked-to site is not SAP documentation. You may not infer any product claims against SAP based on this information.● SAP does not agree or disagree with the content on the linked-to site, nor does SAP warrant the availability and correctness. SAP shall not be liable for any

damages caused by the use of such content unless damages have been caused by SAP's gross negligence or willful misconduct.

● Links with the icon : You are leaving the documentation for that particular SAP product or service and are entering a SAP-hosted Web site. By using such links, you agree that (unless expressly stated otherwise in your agreements with SAP) you may not infer any product claims against SAP based on this information.

Videos Hosted on External PlatformsSome videos may point to third-party video hosting platforms. SAP cannot guarantee the future availability of videos stored on these platforms. Furthermore, any advertisements or other content hosted on these platforms (for example, suggested videos or by navigating to other videos hosted on the same site), are not within the control or responsibility of SAP.

Beta and Other Experimental FeaturesExperimental features are not part of the officially delivered scope that SAP guarantees for future releases. This means that experimental features may be changed by SAP at any time for any reason without notice. Experimental features are not for productive use. You may not demonstrate, test, examine, evaluate or otherwise use the experimental features in a live operating environment or with data that has not been sufficiently backed up.The purpose of experimental features is to get feedback early on, allowing customers and partners to influence the future product accordingly. By providing your feedback (e.g. in the SAP Community), you accept that intellectual property rights of the contributions or derivative works shall remain the exclusive property of SAP.

Example CodeAny software coding and/or code snippets are examples. They are not for productive use. The example code is only intended to better explain and visualize the syntax and phrasing rules. SAP does not warrant the correctness and completeness of the example code. SAP shall not be liable for errors or damages caused by the use of example code unless damages have been caused by SAP's gross negligence or willful misconduct.

Bias-Free LanguageSAP supports a culture of diversity and inclusion. Whenever possible, we use unbiased language in our documentation to refer to people of all cultures, ethnicities, genders, and abilities.

User Guide for Adapter SDKImportant Disclaimers and Legal Information PUBLIC 115

www.sap.com/contactsap

© 2021 SAP SE or an SAP affiliate company. All rights reserved.

No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP SE or an SAP affiliate company. The information contained herein may be changed without prior notice.

Some software products marketed by SAP SE and its distributors contain proprietary software components of other software vendors. National product specifications may vary.

These materials are provided by SAP SE or an SAP affiliate company for informational purposes only, without representation or warranty of any kind, and SAP or its affiliated companies shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP or SAP affiliate company products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty.

SAP and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP SE (or an SAP affiliate company) in Germany and other countries. All other product and service names mentioned are the trademarks of their respective companies.

Please see https://www.sap.com/about/legal/trademark.html for additional trademark information and notices.

THE BEST RUN

https://www.sap.com/about/legal/trademark.html