You are on page 1of 114

SAP Data Services

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


User Guide for Adapter SDK
Table of Contents
1 Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1 Audience and assumptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.2 Related documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.3 Installation contents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.4 Naming Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2 Adapter SDK Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9
2.1 Adapter SDK components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.2 Installation details. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.3 After installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.4 Establishing adapter management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.4.1 Configuring a Job Server for adapter management on Windows. . . . . . . . . . . . . . . . . . . . . . . 11
2.4.2 Configuring a Job Server for adapter management on UNIX. . . . . . . . . . . . . . . . . . . . . . . . . . 12
3 Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
3.1 Adapters and information resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
3.1.1 Information resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
3.1.2 Adapters and front-end applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.1.3 Adapters and back-office systems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.1.4 Adapter types and capabilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15
3.2 Adapters in the Data Services platform. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
3.2.1 Custom adapter usage examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16
3.2.2 Adapters in the Data Services architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.2.3 Adapters and Job Servers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
3.3 Flexible adapter architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18
3.4 Adapter component model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
3.4.1 Component overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
3.4.2 System-defined components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
3.4.3 User-defined components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
3.5 The Adapter SDK API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3.5.1 com.acta.adapter.sdk. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3.5.2 com.acta.metadata. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
3.5.3 Interfaces implemented by the Adapter SDK. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
3.5.4 Interfaces implemented by adapter writers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
3.6 Operation exchange models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
3.6.1 Message-oriented exchange model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
3.6.2 Stream-oriented exchange model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
3.7 Adapters and operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
3.8 Basic operation models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
2

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
Table of Contents
3.8.1 Interaction style. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
3.8.2 Interface styles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
3.8.3 Basic operation types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
3.9 Adapter start-up sequence. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
3.9.1 Adapter operation execution. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
3.10 Adapters in the Data Services Designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
3.10.1 Data flow sends a message to an adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
3.10.2 Adapter invokes real-time service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
3.11 Adapter administration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
4 Creating an Adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
4.1 Preliminary considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
4.1.1 Determine integration issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
4.1.2 Understand your information resource. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
4.1.3 Plan adapter components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
4.1.4 Plan adapter operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
4.2 Write your custom adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
4.2.1 Adapter writer checklist. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
4.2.2 Create an Adapter component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
4.2.3 Create a Session component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51
4.2.4 Create Metadata Node component(s). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
4.2.5 Create a Metadata Browsing component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
4.2.6 Create Metadata Import component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
4.2.7 Create an Operation component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
4.2.8 Customize presentation of adapter components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
4.2.9 Error handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
4.2.10 Trace and error logging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
4.2.11 Statistics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
4.3 Create adapter user documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
4.4 Adapter operation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
4.4.1 Compile and package adapter components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
4.4.2 Prepare configuration templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
4.4.3 Configure adapter instance components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
4.4.4 Debug the adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
4.4.5 Moving the adapter from test to production. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
4.4.6 Moving a production adapter to another environment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
5 Packaging and deployment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
6 Configuring and Running an Adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .85
6.1 Adapter configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
6.1.1 Preparing configuration templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
User Guide for Adapter SDK
Table of Contents

2014 SAP AG or an SAP affiliate company. All rights reserved. 3
6.1.2 Configuring an adapter instance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
6.1.3 Configuring an adapter operation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
6.2 Starting the Adapter SDK driver. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
6.2.1 Starting an adapter using the command prompt. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93
7 TestAdapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
7.1 Understanding TestAdapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
7.2 TestAdapter and associated files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
7.3 TestAdapter source code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
7.4 Preparing and testing TestAdapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
7.4.1 Populate the Data Services repository. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
7.4.2 Configure real-time services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
7.4.3 Configure adapter (start-up and run-time). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
7.4.4 Configuring operations for TestAdapterInstance in the Administrator. . . . . . . . . . . . . . . . . . 102
7.4.5 Starting the adapter instance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
7.4.6 Creating the TestAdapter datastore. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103
7.4.7 Testing browse and import metadata capabilites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
7.4.8 Importing TestAdapter metadata by name. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
7.4.9 Other options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
7.4.10 Starting real-time services for TestAdapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
7.4.11 Verify message-oriented adapter operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
7.4.12 Verify stream-oriented adapter operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
8 Debugging in Eclipse. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
8.1 Debugging in Eclipse. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
4

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
Table of Contents
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 Data Services documentation set that is compatible with this version of the Data Services
Adapter SDK.
A basic understanding of how the Data Services Designer is used to design data flows. (To use an adapter, a
data flow must contain adapter-related transforms or must use real-time job services.)
A basic understanding of how the Data Services Management Console Administrator is used to administer
Data Services processes. (Adapters are administered from the Data Services Administrator only.)
Experience writing Java applications in Java programming language.
1.2 Related documentation
Documentation Description
Adapter SDK API documenta
tion
The companion to this book, the online API documentation contains detailed in
formation necessary for writing Data Services adapters. After you install the
Adapter SDK, you can find the online API documentation in the following loca
tion:
Windows: <<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.
User Guide for Adapter SDK
Introduction

2014 SAP AG or an SAP affiliate company. All rights reserved. 5
Documentation Description
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
In this documentation, the following naming conventions apply:
Terminology
Data Services system refers to SAP Data Services.
BI platform refers to SAP BusinessObjects BI platform.
Note
The BI platform components required by Data Services may also be provided by SAP BusinessObjects
Information platform services (IPS).
CMC refers to the Central Management Console provided by the BI or IPS platform.
CMS refers to the Central Management Server provided by BI or IPS platform.
Variables
Variables Description
<INSTALL_DIR> The installation directory for the SAP software.
6

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
Introduction
Variables Description
Default location:
C:\Program Files (x86)\SAP BusinessObjects
$HOME/sap businessobjects
<BIP_INSTALL_DIR
>
The root directory of the BI or IPS platform.
Default location:
<INSTALL_DIR>\SAP BusinessObjects Enterprise XI 4.0
<INSTALL_DIR>/enterprise_xi40
Note
These paths are the same for both the SAP BusinessObjects BI platform and SAP
BusinessObjects Information platform services.
<LINK_DIR> The root directory of the Data Services system.
Default location:
All platforms
<INSTALL_DIR>/Data Services
This system environment variable is created automatically during installation.
<DS_COMMON_DIR> The common configuration directory for the Data Services system.
Default location:
Windows (Vista and newer)
ALLUSERSPROFILE\SAP BusinessObjects\Data Services
Windows (Older versions)
ALLUSERSPROFILE\Application Data\SAP BusinessObjects\Data
Services
UNIX systems (for compatibility)
<LINK_DIR>
This system environment variable is created automatically during installation.
<DS_USER_DIR> The user-specific configuration directory for the Data Services system.
Default location:
Windows (Vista and newer)
USERPROFILE\AppData\Local\SAP BusinessObjects\Data Services
Windows (Older versions)
USERPROFILE\Local Settings\Application Data\SAP BusinessObjects
\Data Services
This user environment variable is created automatically during installation.
User Guide for Adapter SDK
Introduction

2014 SAP AG or an SAP affiliate company. All rights reserved. 7
Variables Description
Note
This variable is used only for Data Services client applications on Windows, such as the
Designer. <DS_USER_DIR> is not used on UNIX platforms.
8

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
Introduction
2 Adapter SDK Installation
2.1 Adapter SDK components
Adapter SDK components include:
Adapter SDK API documentation.
Adapter SDK library acta_adapter_sdk.jar (also called Adapter run-time jar file).
Interfaces for the adapter components.
Supporting classes.
Adapter container This unexposed adapter container instantiates and manages objects for the adapter
component classes.
Adapter driver This unexposed adapter driver is the executable java code that creates an instance of
the adapter container.
The broker client acta_broker_client.jar
Third party libraries xerces.jar (the XML parser)
A test adapter you can use as a design template acta_test_adapter.jar
Utilities to support the Adapter SDK acta_tool.jar
User Guide for Adapter SDK This book. Instructions for using the test adapter are included in this
document.
2.2 Installation details
You can install the Adapter SDK on both Windows and UNIX operating systems.
For both Windows and UNIX, the Adapter SDK is installed during a normal Data Services installation. During the
Data Services installation procedure, need to select the Message Client component.
2.3 After installation
After installing the Adapter SDK on your computer, you should have the following primary directories and files:
Directory Description
adapters This directory contains all information related to adapter start-up and run-time. Besides con
taining several sub-directories, this directory contains the following files:
AdapterInstallationTemplate.xml: This XML file is a generic template for creating
your own adapter start-up installation template
User Guide for Adapter SDK
Adapter SDK Installation

2014 SAP AG or an SAP affiliate company. All rights reserved. 9
Directory Description
startup_script.xml: This XML start-up script is automatically generated when you
run an adapter for the first time, and automatically updated each time you configure, up
date, or remove the adapter instance. It contains an entry for each adapter instance con
figured on the computer where it resides. This file does not appear during initial Adapter
SDK installation because no adapter instances are configured yet.
rtt.bat: (rtt.sh on UNIX) This is the batch file that generates the adapter run-time
configuration template.
lib This directory contains the following software files:
acta_adapter_admin.jar
acta_adapter_sdk.jar
acta_broker_client.jar
acta_test_adapter.jar
acta_tool.jar
Inside the adapters directory, you should have the following sub-directories and associated files:
Directory Description
config For each adapter instance configured on this computer, this sub-directory contains an
XML run-time configuration script for that instance. The naming convention for script files
is: <adapter_instance_name>.xml.
config/
templates
For each adapter installed on this computer, this sub-directory contains an XML run-time
template related to that adapter. The naming convention for template files is:
<adapter_name>.xml. The scripts in the config sub-directory are generated based on
these templates (described below). During initial installation, this directory contains only
the TestAdapter.xml run-time template for the test adapter.
install Files in this sub-directory are start-up installation templates used by the Data Services Ad
ministrator to create the start-up script entry in the startup_script.xml file. This sub-
directory contains one XML descriptor file for each installed adapter. The naming conven
tion for descriptor files is <adapter_name>.xml. During initial installation, this directory
contains only the TestAdapter.xml descriptor file for the test adapter.
log This sub-directory is generated automatically when you run an adapter for the first time. It
contains up to two (trace and error) log files for each running adapter instance. The nam
ing convention for these log files is <adapter_instance_name>_trace.txt for trace
files and <adapter_instance_name>_error.txt for error files.During initial installa
tion, this directory is empty.
sdk/doc/API This directory contains the Adapter SDK API documentation. Open index.html to view
the online documentation.
sdk/samples This directory contains all information related to the sample adapter included with the
Adapter SDK (TestAdapter) and includes the testadapter sub-directory.
sdk/samples/
testadapter
This directory contains batch files, XML documents, DTD files, and the ATL file used by the
test adapter as well as the data subdirectory.
10

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
Adapter SDK Installation
Directory Description
sdk/samples/
testadapter/
data
This directory contains a session data sub-directory (Session1), the sample adapter
source file sub-directory (src), and files that TestAdapter uses to demonstrate message-
oriented adapter operations.
sdk/samples/
testadapter/
data/session1
This directory contains the data files that TestAdapter uses to demonstrate metadata
browsing, metadata import, and stream-oriented adapter operations.
sdk/samples/
testadapter/src
This directory contains the sub-directory structure: com/acta/adapter/testadapter.
This testadapter sub-directory contains all the java source files used to create TestAdap
ter.
In the <<LINK_DIR>>/ext/ directory, you should also find the Java Run-Time environment and additional library
used by the Adapter SDK (LINK_DIR/ext/lib/xerces.jar and <<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.
Note
You cannot configure or use a Data Services adapter (including the sample TestAdapter) unless adapter
management is established.
2.4.1 Configuring a Job Server for adapter management on
Windows
Context
Choose a Job Server to perform adapter management per computer. The adapter management Job Server
brokers messages between Data Services and all adapter instances on that computer.
Procedure
1. On a Windows operating system, choose Start Programs SAP Data Services 4.2 Server Manager .
2. In the Data Services Server Manager, click the Edit Job Server Config button.
3. In the Job Server Configuration Editor window, do one of the following:
User Guide for Adapter SDK
Adapter SDK Installation

2014 SAP AG or an SAP affiliate company. All rights reserved. 11
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.
Note
If another Job Server on this computer is already configured to manage adapters, a warning message
appears to let you know that Data Services cannot save your adapter management configuration for the
second Job Server. To configure another Job Server for adapter management, you must first de-select the
Enable adapter and message broker 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.
2.4.2 Configuring a Job Server for adapter management on
UNIX
Context
Choose a Job Server to perform adapter management per computer. The adapter management Job Server
brokers messages between Data Services and all adapter instances on that computer.
Procedure
1. Change directory to <<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:
12

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
Adapter SDK Installation
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.
User Guide for Adapter SDK
Adapter SDK Installation

2014 SAP AG or an SAP affiliate company. All rights reserved. 13
3 Overview
3.1 Adapters and information resources
Each Data Services Adapter is an application you create using the Data Services Adapter SDK. Data Services
Adapters are part of the Data Services platform and integrate "information resources" source or target
applicationswith Data Services.
Each adapter integrates an information resource with the Data Services platform by communicating with that
resource and translating the resource's information into a format that the Data Services message broker and the
Data Services platform can understand.


Data Services adapters can also publish information from the data platform to the resource in a format that the
information resource understands.
3.1.1 Information resources
Today, information resources are used for in-house data analysis, sell-side e-commerce, supply chain
management, customer relationship management, e-procurement, and more. Regardless of whether they are
front-end or back-office applications, you can integrate many different information resources with Data Services
using custom adapters. Common information resources include:
14

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
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 Vit
ria
ERP Enterprise Resource Planning systems such as Enterprise SAP and PeopleSoft
MOM Message oriented middleware such as IBM MQSeries, Microsoft MSMQ
3.1.2 Adapters and front-end applications
For front-end application integration, an adapter bridges the disparate interfaces of the Data Services message
broker and the resource.
An front-end application adapter is:
relatively simple to develop
connectionless
slow when used for bulk data transfer
This type of adapter usually contains a message-oriented interface and is most appropriate for connecting to EAI
systems.
E-commerce application developers using adapters to integrate data platforms with information resources are
shielded from much integration complexity and are able to perform more transparent application design.
3.1.3 Adapters and back-office systems
Back-office system adapters can support non-SQL based applications like Manugistics as well as applications like
Oracle Financials, Siebel, and Clarify, which contain application level complexity that makes it difficult to extract
data using only a SQL interface.
A back-office system adapter:
is complex
requires connections over a span of time
is optimized for moving large amounts of relational data
This type of adapter usually contains a stream-oriented interface appropriate for connecting to bulk data
movement systems.
3.1.4 Adapter types and capabilities
Using the Data Services Adapter SDK, you can create different types of adapters: message-oriented, steam-
oriented, or full capability containing both message- and stream-oriented behavior. Adapter types depend on
the capabilities you include. For example, you can define whether requests can initiate from Data Services, from
User Guide for Adapter SDK
Overview

2014 SAP AG or an SAP affiliate company. All rights reserved. 15
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.
16

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
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.


User Guide for Adapter SDK
Overview

2014 SAP AG or an SAP affiliate company. All rights reserved. 17
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.

18

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
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).
AdapterEnviron
ment
System Links user-defined components.
Adapter Operation Adapter writer Supports adapter stream and message operations.
Import by Name Adapter writer Allows users to import IR metadata by name into Data Services. (Re
quires Metadata Import.)
Metadata Browsing Adapter writer Allows users to visually browse IR metadata.
Metadata Import Adapter writer Allows users to import IR metadata into Data Services.
Metadata Node Adapter writer Makes it possible for IR metadata to be visually represented as a node-
delimited hierarchy.
OperationEnviron
ment
System
User Guide for Adapter SDK
Overview

2014 SAP AG or an SAP affiliate company. All rights reserved. 19
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 op
eration
setSessionClassName (String
sessionClassName)
Sets the fully qualified class names of the adapter's
Session interface implementation
Related Information
Run-time configuration template structure [page 87]
3.4.2.2 OperationEnvironment
The OperationEnviroment component implements the OperationEnviroment interface provided by the Adapter
SDK as a set of methods that access an adapter operation's:
20

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
Overview
Configured system properties
Dynamic properties
Related pre-defined objects
Some methods implemented for this interface include:
Method Description
getInstanceName() Accesses the adapter instance name
println(String text); Adds text strings to the adapter instance trace log file
when debug trace is activated
public void incrementRequestCount() Increments by 1 the number of requests received by
the operation
invokeService(String serviceName, String
xml, int timeout)
Invokes real-time services provided by Data Services
The adapter container:
Creates instances of the AdapterEnvironment and OperationEnvironement components, then
Passes references for user-defined components (based on initialize method parameters) to these system-
defined components
Note
All methods implemented by the Adapter SDK are listed in the Adapter SDK API documentation.
Related Information
Run-time configuration template structure [page 87]
3.4.3 User-defined components
You define each component in its own class by implementing the corresponding (and other associated)
interface(s) exposed by the Adapter SDK (see online API documentation for details). User-defined components
include:
Adapter
Adapter Operation (for both stream- and message-oriented operations)
Session
Metadata Node (required for Metadata Browsing)
Metadata Browsing
Metadata Import (can include the Import by Name component)
When an adapter starts, the adapter driver instantiates the adapter container that creates and manages the
instances of the user-defined adapter components. The rules governing relationships among instances of user-
defined adapter components in an adapter container are:
User Guide for Adapter SDK
Overview

2014 SAP AG or an SAP affiliate company. All rights reserved. 21
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:



22

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
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
User Guide for Adapter SDK
Overview

2014 SAP AG or an SAP affiliate company. All rights reserved. 23
create this component, you must implement the Operation interfacethe basic life-cycle interface for all Data
Services adapter operations.
3.4.3.3 Session
The Session component is optional and used by the adapter container for grouping and maintaining state. To
create this stream-oriented component, you must implement the Session interface. This component can be
associated with every Adapter Operation, Metadata Browsing, and Metadata Import component in the adapter's
environment. With a Session component, the adapter container creates a Session object upon request from an
adapter client (Data Services Designer or engine).
The Session component is associated with the adapter datastore, created and configured in the Data Services
Designer. Session property values, configured in the datastore Adapter Properties tab, determine Session state.
The Designer allows users to create multiple adapter datastores for each running adapter instance. Each adapter
datastore with configured session properties is unique and associated with a unique set of datastore objects,
grouped as follows:
Metadata browsing objects
Metadata import objects
Data Services metadata imported from the IR
Adapter sources, targets, and function calls belonging to the datastore (because they were created from the
datastore's metadata)
For these Data Services objects, the adapter container creates and manages corresponding stream-oriented
Operation, Metadata Browsing, and Metadata Import component instances. All these instances share the same
Session state (configured datastore properties) associated with that Data Services object.
However, the adapter writer does not have direct control over the Session object life-cycle as it is both created
and destroyed on request from an adapter client (Data Services Designer or engine).
The Adapter SDK can handle simultaneous Session components. For every component associated with a Session,
the Adapter SDK generates a unique ID for that component/Session pair. An adapter client uses use this ID when
making metadata browsing and import requests, or when starting a stream-oriented operation.
To refer to the Session component from an operation, use the getSession() method from the
OperationEnvironment interface implemented by the Adapter SDK . For example:
public void initialize (OperationEnvironment OperEnv) {
_operEnvironment=operEnvt;
_adapter=(TestAdapter)_operEnvironment.getAdapter();
_adapterEnvironment=
_operEnvironment.getAdapterEnvironment();
_session= (TestSession)_operEnvironment.getSession();
}
To refer to the Session component from another component, like the Metadata Browsing and Metadata Import
components, use a parameter within the initialize ( ) method. For example:
public void initialize (Adapter adapter,
AdapterEnvironment adapterEnvironment,
Session session) {
_adapterEnvironment = adapterEnvironment;
_adapter = (TestAdapter)adapter;
24

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
Overview
_session = (TestSession)session;
}
The Session component is associated with the adapter datastore, which is created and configured in the Data
Services Designer. Session properties are configured in the datastore's Adapter Properties tab.
3.4.3.4 Metadata Node
The Metadata Node component is optional and supports the external metadata browsing framework by providing
an organizational structure for representing IR metadata. You can implement different MetadataNode interfaces if
you want your adapter to show hierarchy. The adapter container creates the Metadata Node object upon request
from the Data Services Designer.
3.4.3.5 Metadata Browsing
The Metadata Browsing component is also optional and, combined with the Metadata Node component, supports
the information resource (IR) metadata browsing framework. Implement this interface to give your adapter the
ability to visually browse information resource metadata. To create this component, you must implement the
MetadataBrowsing interface after you implement the MetadataNode interface.
The adapter container creates the Metadata Browsing object upon request from the Data Services Designer. The
Metadata Browsing component is not configurablethe Adapter SDK does not introspect its properties.
Metadata Browsing relies upon Metadata Node components to organize and hierarchically represent information
resource metadata.
3.4.3.6 Metadata Import
The Metadata Import component is optional and supports metadata import from information resources to Data
Services . Implement this interface if you want your adapter to have metadata import capability. To create this
component, you must implement the MetadataImport interface.
The adapter container creates the Metadata Import object upon request from the Data Services Designer. The
Metadata Import component is not configurablethe Adapter SDK does not introspect its properties.
The Metadata Import component supports two methods of obtaining information resource metadata:
Method Description
Import metadata from the
browser
From the Designer's metadata browsing window, the "import" command imports
metadata while browsing a node or group of nodes. Implement the public Vector
importMetadata (MetadataNode resourceMetadataNode) method of the
MetadataImport interface.
Import metadata by name Right-click in the Designer's Adapter Datastore to use the Import By Name option.
To support an adapter's import-by-name capabilities, create the Import by Name
User Guide for Adapter SDK
Overview

2014 SAP AG or an SAP affiliate company. All rights reserved. 25
Method Description
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.
Note
See the TestAdapter source code for the examples of the importMetadata() implementation.
To import metadata from the metadata browser for message-oriented operations, implement the Exportable
interface for the adapter operation. The AWMetadata[] exportMetadata() method of this interface should
return an array of AWMetadata objects that could be either AWOutboundMessageMetadata 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.
26

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
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 da
tabase communication
AdapterEnviron
ment
Used to access an adapter's configuration properties and system objects and link adapter
components
Delimited The interface for stream-oriented adapter operations that must read or write data using a de
limited format.
Document
Source and Doc
umentTarget
Used for document readers and document loaders, respectively
EnableCDC
Exportable Exposes a message-oriented operation's metadata to the Adapter SDK
FunctionCall Used for BAPI-like function calls made to an information resource
GuiAttributes Used for JavaBeans (adapter, operations, import by name and session) customization
ImportByName Used for importing metadata by name
ListenerOpera
tion
Automatically subscribes an operation to the message type derived from the operation in
stance name
MetadataBrows
ing and Metada
taImport
Used for browsing and importing metadata, respectively
MetadataNode Required for metadata browsing implementations (objects returned by the MetadataBrows
ing interface must implement MetadataNode)
Operation Required for message-oriented and stream-oriented operations
OperationEnvir
onment
Provides access to adapter and operation properties
User Guide for Adapter SDK
Overview

2014 SAP AG or an SAP affiliate company. All rights reserved. 27
Interface Description
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)
StreamOpera
tion
The basic interface for stream-oriented operations
Table Supports Table Sources and Table Targets from the Data Services data (a sub-interface for
TableSource and TableTarget interfaces)
TableSource and
TableTarget
Used for table sources and table targets, respectively
3.5.2 com.acta.metadata
This package contains optional classes for working with Data Services metadata in stream-oriented adapters. It
contains no interfaces, but includes the following classes:
Class Description
AWAttribute Sets attributes for Data Services table metadata
AWColumn Sets columns for Data Services table metadata
AWDocument
Metadata
Defines the Data Services document metadata
AWForeignKey Sets foreign keys for Data Services table metadata
AWFunctionCall
Metadata
Defines Data Services function call metadata for streams
AWIndex Sets the index for Data Services table metadata
AWMessage
FunctionCallMe-
tadata
Defines the Data Services message function call metadata
AWMetadata The super class for all Adapter SDK objects representing Data Services metadata
28

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
Overview
Class Description
AWOutbound
MessageMeta-
data
Defines Data Services outbound message metadata
AWPkFkPair Sets the primary key/foreign key pairs for the AWForeignKey object
AWTableMeta
data
Defines Data Services table metadata
AWUniqueKey Sets the unique key for Data Services table metadata
ResourceMeta
data
Sets user-defined metadata in the Data Services repository
3.5.3 Interfaces implemented by the Adapter SDK
The Adapter SDK provides implementations of these interfaces:
Interface Description
AdapterEnviron
ment
A set of methods to access an adapter instance's objects (for example,
getInstanceName()).
OperationEn
viroment
A set of methods to access an adapter (for example, getAdapter()) and its operations'
properties (for example, getInstanceName()).
3.5.4 Interfaces implemented by adapter writers
The only interface you must implement in your adapter is adapter.sdk.Adapter to create the required Adapter
component. To expand adapter capabilities, implement other available interfaces. Some capabilities apply to only
message-oriented operations, others apply only to stream-oriented operations, some apply to both.
This table lists each adapter component with associated Data Services component(s), associated interface(s)
capability, and exchange model:
Component Interface(s) Capability (w/exchange
model)
Adapter Data Services
Adapter Adapter datastore REQUIRED: SQLAdapter
OPTIONAL: Pushdown
Provide support for native SQL
(import metadata only) or full
SQL (stream)
Session Adapter datastore REQUIRED: Session
OPTIONAL: EnableCDC
Configure adapter datastore
properties in the Designer
(stream)
User Guide for Adapter SDK
Overview

2014 SAP AG or an SAP affiliate company. All rights reserved. 29
Component Interface(s) Capability (w/exchange
model)
Adapter Data Services
Adapter Opera
tion
Real-time services REQUIRED: Operation (use the Op
erationEnvironment.invokeservice
method)
OPTIONAL: PollOperation
Handle a request from the IR
for real-time service (mes
sage)
Outbound message or
Message function call
REQUIRED: Operation and Liste
nerOperation
OPTIONAL: Exportable
Handle a request from an Data
Services real-time service or
data flow (message)
Table sources REQUIRED: TableSource
OPTIONAL: Delimited, SQLEnable,
QueryInXML, SourceCDC
Read operations for use with a
Designer table source
(stream)
Table targets REQUIRED: TableTarget
OPTIONAL: Delimited
Write operations for use with a
Designer table target (stream)
Document sources REQUIRED: DocumentSource Read operations for use with a
Designer document source
(stream)
Document targets REQUIRED: DocumentTarget Write operations for use with a
Designer document target
(stream)
Function calls REQUIRED: FunctionCall Write operations for use with a
Designer function call
(stream)
MetadataB
rowsing
Browser window REQUIRED: MetadataBrowsing and
MetadataNode
Browse metadata (both)
Metadata Im
port
Browser window and Im
port by name dialog
REQUIRED: MetadataImport Import metadata (both)
Import by name dialog REQUIRED: ImportByName Import metadata by name
(both)
Related Information
Operation exchange models [page 31]
30

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
Overview
3.6 Operation exchange models
The Adapter SDK supports two adapter operation exchange models:
Message-oriented exchange model (real-time)
Stream-oriented exchange model (batch)
Each model is associated with different components (component-exchange model associations are mentioned in
the last table of the Interfaces implemented by adapter writers section). Both exchange models implement the
Operation interface (plus one or more additional interfaces included in the com.acta.adapter.sdk packagethey
vary depending on exchange model used for your operation).
Related Information
Interfaces implemented by adapter writers [page 29]
3.6.1 Message-oriented exchange model
The message-oriented exchange model associates Data Services with real-time applications. Typically part of a
real-time job, a message-oriented operation is designed to stay available and runningeither monitoring for
messages to be forwarded to Data Services from an information resource (poll() method of the PollOperation
interface or start() method of the Operation interface), or monitoring for messages to be forwarded to an
information resource from Data Services (ListenerOperation interface). Although message-oriented adapter
operations are designed and optimized for real-time connectivity, they can also be used in batch data flows.
Message-oriented adapter operations process one real-time message at a time and do not require high
throughput movements of data. Otherwise known as "real-time adapter operations", message-oriented adapter
operations move relatively smallthough semantically richamounts of data between external systems and Data
Services .
Each message handled by a message-oriented adapter operation is complete, independent of any preceding or
following message. This type of message does not participate in a "stream." Message "calls" (routed by the Job
Server managing adapters) to such adapter operations have no associated context. Therefore, establishing a
"session" (usage of the Session object) is not supported for this context.
Operations that implement the ListenerOperation interface, associate with the Outbound Message and Message
Function objects in the Designer. Operations that implement the PollOperation interface or no additional
interfaces associate with the real-time service defined for the Access Server in the Administrator.
3.6.2 Stream-oriented exchange model
The stream-oriented exchange model is primarily intended for moving large amounts of data between Data
Services and an information resource. For example, you might use a stream-oriented operation to read a high
volume of data from an ERP (or non-relational) system and load it into a data cache.
User Guide for Adapter SDK
Overview

2014 SAP AG or an SAP affiliate company. All rights reserved. 31
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.


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.

32

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
Overview

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

User Guide for Adapter SDK
Overview

2014 SAP AG or an SAP affiliate company. All rights reserved. 33

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

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
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.
User Guide for Adapter SDK
Overview

2014 SAP AG or an SAP affiliate company. All rights reserved. 35
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
36

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
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.
Note
In a variation of this scenario, Data Services requests IR service and receives an acknowledgement. In this
variation, IR0 uses an "outbound message," not a message function call. The outbound message just waits for
the acknowledgement. In this variation, the ListenerOperation implementation returns a null (empty) message
from the handleRequest() method. This variation is for message-oriented adapter operations only.
This illustration shows a way (for batch or real-time scenarios) the "Data Services as client" interface style applies
to stream-oriented operations.


User Guide for Adapter SDK
Overview

2014 SAP AG or an SAP affiliate company. All rights reserved. 37
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.
Note
A variation of this scenario is IR requests Data Services service and receives acknowledgement. In such a
variation, the developer would not code a return for the poll() method (return is null), if used. This variation is
for message-oriented adapter operations only.
38

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
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 messagefor example, from the Data Services Administrator. (This is where you write
code to close the connection to the information resource and deinitialize the system.)
With a shutdown message, the Adapter SDK gives the adapter an unlimited amount of time to stop gracefully
(by completing processing of all outstanding requests). With an abort message, the adapter process stops
immediately (without waiting for adapter operations to complete processing outstanding requests).
3.9.1 Adapter operation execution
After an adapter starts (when the adapter start() method exits), message-oriented and stream-oriented
operations can be started.
The Adapter SDK automatically starts all message-oriented operations whose enable system property is set to
"true". The operator must manually start all other message-oriented operations.
Stream-oriented operations are started upon client (Data Services Designer or engine) request. Operators cannot
manually start stream-oriented adapter operations from the Administrator. Only a client request to start a
stream-oriented adapter operation will cause an unstarted adapter to start.
The Adapter SDK runs the following start operation instance sequence which:
1. Creates a new instance of the adapter operation.
2. Invokes the initialize() method and uses your code to initialize the operation instance.
For stream-oriented operations, the Adapter SDK will create a new or reuse the existing session object (refer
to AdapterOperationEnvironment.getSession() inside the initialize() method).
3. Introspects the operation instance code and sets configurable properties to the values configured for them in
the adapter operation instance configuration script from the run-time configuration file (message-oriented
operations) or received from the Data Services engine (stream-oriented operations).
4. Invokes the start() method, which starts adapter operation message processing.
User Guide for Adapter SDK
Overview

2014 SAP AG or an SAP affiliate company. All rights reserved. 39
Note
For 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.
Note
For stream-oriented operations, the pairs of begin() and end() methods can be called repeatedly after
start() and before stop() upon engine request to restart data exchange between the adapter and the
engine.
5. Invokes the stop() method when it receives a request from the Data Services Administrator to stop the
adapter or the operation. The stop() method stops operation instance processing.
3.10 Adapters in the Data Services Designer
This section describes how application designers integrate custom adapters into batch jobs and real-time jobs 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:
40

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
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 in
stance name in the flow. Synchronize the adapter operation instance name with the adapter
object in one of two different ways:
(Recommended) When creating a message-oriented operation, implement the Exporta
ble interface to expose operation metadata through the metadata browsing and import
framework. Name the metadata object returned by the Exportable interface by giving
the same name as the operation instance. Extract the operation instance name from the
OperationEnvironment object using the getInstanceName() method. Use AWMessage
FunctionCallMetadata.setMessageFunctionCallName (String OperationInstanceName)
and AWOutboundMessageMetadata.setOutboundMessageName (String operationIn
stanceName) methods. The operation instance and derived data flow object (message
function call or outbound message) are connected at run-time using this name.
Use the metadata import framework to import information resource metadata. Then,
you can configure the message-oriented operation in the Administrator using the im
ported metadata name as the operation instance name. The data flow outbound mes
sage or message function call derived from this metadata sends a message to the
adapter operation instance having the same metadata name.
When you add metadata importing capabilities to your adapter, Data Services users can:
Import metadata from your adapter
Drag and drop imported adapter metadata objects into their (batch or real-time) data flows
The metadata importable through an adapter datastore is limited to five metadata types, described in the
following table:
Metadata Used in Data Services as:
Documents Document sources or targets in data flows
Function calls Function calls inside query transforms
Message func
tion calls
Function calls inside query transforms
Outbound mes
sages
Outbound messages in data flows
Tables Table sources or targets in data flows
In Data Services , these metadata types (and any metadata objects imported to them) appear under the adapter
datastore icon in the Designer's object library. These metadata types are owned by the Adapter class in the Data
Services repository.
User Guide for Adapter SDK
Overview

2014 SAP AG or an SAP affiliate company. All rights reserved. 41
When an Data Services user runs an application with (batch or real-time) data flows containing imported adapter
metadata, each imported adapter metadata object behaves as follows:
Metadata Ob
ject
Behavior
Document
source
Asks the adapter operation for a batch of documents in the XML format defined by the opera
tion's metadata.
Document tar
get
Sends the adapter operation a batch of documents in the XML format defined by the opera
tion's metadata.
Function call Sends an input XML document to the adapter and waits to receive an output XML reply docu
ment from the adapter operation.
Outbound mes
sage
Sends an input XML document and waits to receive a confirmation message from the adapter
operation.
Table source
Asks the adapter operation for a batch of data in the specific XML or delimited format defined
in the operation's metadata.
The data that operation receives from the Data Services engine is packed as records sepa
rated by getRowDelimiter(), with columns separated by getColumnDelimiter(). If the
Delimiter interface is not implemented, the operation uses default 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>
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 sepa
rated by getRowDelimiter(), with columns separated by getColumnDelimiter(). If the De
limiter 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.

42

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
Overview

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.
User Guide for Adapter SDK
Overview

2014 SAP AG or an SAP affiliate company. All rights reserved. 43
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.
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 100]
44

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
Overview
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.


4.1.2 Understand your information resource
Consider adapter/information resource relationship details. In particular, determine:
User Guide for Adapter SDK
Creating an Adapter

2014 SAP AG or an SAP affiliate company. All rights reserved. 45
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 accessible 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.
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.
46

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
Creating an Adapter
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.
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:
User Guide for Adapter SDK
Creating an Adapter

2014 SAP AG or an SAP affiliate company. All rights reserved. 47
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 29]
Run-time configuration template structure [page 87]
4.2.1 Adapter writer checklist
Use this checklist as a guideline for writing your adapter.
Task Done?
Create an Adapter component [page 49] (Required)
Create a Session component [page 51] (if needed)
Create Metadata Node component(s) [page 52] (if needed)
Create a Metadata Browsing component [page 53] (if needed)
Create Metadata Import component [page 54] (if needed)
Create an Operation component [page 60] for each operation type (if needed)
Customize presentation of adapter components [page 67] 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.
48

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
Creating an Adapter
Related Information
http://java.sun.com/products/javabeans/docs/
Create adapter user documentation [page 78]
Error handling [page 73]
Trace and error logging [page 74]
Statistics [page 75]
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 instance
When 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:
The adapter is stopped or aborted from the Administrator.
The Adapter SDK encounters an unrecoverable error.
The associated Data Services service is stopped.
User Guide for Adapter SDK
Creating an Adapter

2014 SAP AG or an SAP affiliate company. All rights reserved. 49
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.
50

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
Creating an Adapter
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 29]
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:
User Guide for Adapter SDK
Creating an Adapter

2014 SAP AG or an SAP affiliate company. All rights reserved. 51
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()
getDisplayNam
e
Returns the metadata browsing node display name.
public java.lang.String getDisplayName()
getDescriptio
n
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()
52

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
Creating an Adapter
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.
Note
To 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 52]
User Guide for Adapter SDK
Creating an Adapter

2014 SAP AG or an SAP affiliate company. All rights reserved. 53
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.
Note
Because 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 52]
Create Metadata Import component [page 54]
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.
54

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
Creating an Adapter
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
AWFunctionCallMetad
ata
Function call Function call in Query Transform
AWOutBoundMessageMe
tadata
Outbound message Outbound Message Target
AWMessageFunctionCa
llMetadata
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") ;
User Guide for Adapter SDK
Creating an Adapter

2014 SAP AG or an SAP affiliate company. All rights reserved. 55
...
awTable.setColumns ( new AWColumn [] { col1, col22} );
awTable.setAttributes(new AWAttribute [] { attr1, attr2} );
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");

Note
Do 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.
56

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
Creating an Adapter
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 ob
ject.
public boolean isDocuments() Returns true if metadata import can return the AWDocumentMetadata
object.
public boolean isFunctionCalls() Returns true if metadata import can return the AWFunctionCallMeta
data object.
public boolean
isOutboundMessages()
Returns true if metadata import can return the AWOutboundMessage
Metadata object.
public boolean
isMessageFunctionCalls()
Returns true if metadata import can return the AWMessageFunction
CallMetadata object.
User Guide for Adapter SDK
Creating an Adapter

2014 SAP AG or an SAP affiliate company. All rights reserved. 57
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
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 52]
Create a Metadata Browsing component [page 53]
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.
58

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
Creating an Adapter
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 counterpartsthe 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.
User Guide for Adapter SDK
Creating an Adapter

2014 SAP AG or an SAP affiliate company. All rights reserved. 59
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 (createinitializestartstop)
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.
60

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
Creating an Adapter
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
User Guide for Adapter SDK
Creating an Adapter

2014 SAP AG or an SAP affiliate company. All rights reserved. 61
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 AdapterException
Returns 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 )
62

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
Creating an Adapter
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, AdapterException
Handles requests from Data Services data flow.
Parameter Description
oper Reference to the adapter operation using this interface to handle messages from the re
source.
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.
Each stream oriented-operation:
Is created upon request from the Data Services engine (from an object using metadata associated with the
operation)
User Guide for Adapter SDK
Creating an Adapter

2014 SAP AG or an SAP affiliate company. All rights reserved. 63
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.
64

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
Creating an Adapter
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 59]
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().
Note
If 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().
Note
See other delimiters in Delimited interface. If the Delimited interface is not implemented, Data Services
uses the default values.
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:
<AWA_BatchWrapper>
< AWA_Row>
<colname>...</colname>
...
<colname>...</colname>
User Guide for Adapter SDK
Creating an Adapter

2014 SAP AG or an SAP affiliate company. All rights reserved. 65
</ AWA_Row>
...
< AWA_Row>
<colname>...</colname>
...
<colname>...</colname>
</ AWA_Row>
</AWA_BatchWrapper>
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:
<AWA_BatchWrapper>
< AWA_Row>
<colname>...</colname>
...
<colname>...</colname>
</ AWA_Row>
...
< AWA_Row>
<colname>...</colname>
...
<colname>...</colname>
</ AWA_Row>
</AWA_BatchWrapper>
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:
getColumnDelimiter
public java.lang.String getColumnDelimiter()
Returns the field separator. Default is ",".
getEscapeChar
public java.lang.String getEscapeChar()
Returns the escape character. Default is "".
getRowDelimiter
public java.lang.String getRowDelimiter()
Returns the record separator. Default is "/n".
getTextDelimiter
public 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.
66

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
Creating an Adapter
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 components
Some 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
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.
User Guide for Adapter SDK
Creating an Adapter

2014 SAP AG or an SAP affiliate company. All rights reserved. 67
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
Procedure
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 =


68

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
Creating an Adapter
{ "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.xml
5. 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 {
User Guide for Adapter SDK
Creating an Adapter

2014 SAP AG or an SAP affiliate company. All rights reserved. 69
//Configurable property testProperty
String testProperty = "ABC";
public void setTestProperty ( String test ) {
testProperty = test ;
}
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.
Results
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;
70

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
Creating an Adapter
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;
}
Update your adapter with these changes using the same procedure provided in Customize using get() and set()
[page 68]. 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:
User Guide for Adapter SDK
Creating an Adapter

2014 SAP AG or an SAP affiliate company. All rights reserved. 71
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"
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 or
der 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.") ;
}
72

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
Creating an Adapter
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.
User Guide for Adapter SDK
Creating an Adapter

2014 SAP AG or an SAP affiliate company. All rights reserved. 73
Methods you implement can throw two types of exceptions:
AdapterException
RecoverableOperationAdapterException
The Adapter SDK catches these exceptions and responds as follows:
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 74]
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:
74

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
Creating an Adapter
<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.
Note
The 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.

User Guide for Adapter SDK
Creating an Adapter

2014 SAP AG or an SAP affiliate company. All rights reserved. 75

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

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
Creating an Adapter
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;
}
...
}
User Guide for Adapter SDK
Creating an Adapter

2014 SAP AG or an SAP affiliate company. All rights reserved. 77
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.
collect
public 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 documentation
Your 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:
IntroductionProvide any information that would help users understand the rest of the document (include
terms, conventions, and so forth).
OverviewDiscuss your information resource, what users can do with your customer adapter, and mention
related adapters.
InstallationDiscuss 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.
UseExplain 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 implementationList 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:
78

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
Creating an Adapter
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
User Guide for Adapter SDK
Creating an Adapter

2014 SAP AG or an SAP affiliate company. All rights reserved. 79
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:
Sessions
These 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.
80

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
Creating an Adapter
Related Information
Configuring an adapter instance [page 91]
Configuring an adapter operation [page 92]
Creating the TestAdapter datastore [page 103]
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
Context
After testing is complete, you can move your adapter into a production environment.
User Guide for Adapter SDK
Creating an Adapter

2014 SAP AG or an SAP affiliate company. All rights reserved. 81
Procedure
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:


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 11]
Configuring an adapter instance [page 91]
82

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
Creating an Adapter
4.4.6 Moving a production adapter to another environment
Context
To move an existing custom adapter and all associated jobs into another production environment, you will need to
use Data Services Designer export capabilities.
Procedure
1. Install your adapter in the new production environment. (See steps 1 through 5 in Moving the adapter from
test to production [page 81] for details.)
2. Open the Administrator and configure an adapter instance using name and attribute values specific to the
production environment.
Note
You 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 91]
User Guide for Adapter SDK
Creating an Adapter

2014 SAP AG or an SAP affiliate company. All rights reserved. 83
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
84

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
Packaging and deployment
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
Procedure
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.
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.
User Guide for Adapter SDK
Configuring and Running an Adapter

2014 SAP AG or an SAP affiliate company. All rights reserved. 85
Element name Element value
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.
Note
For 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.
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
86

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
Configuring and Running an Adapter
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).
Note
Adapter 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)>
User Guide for Adapter SDK
Configuring and Running an Adapter

2014 SAP AG or an SAP affiliate company. All rights reserved. 87
<!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
88

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
Configuring and Running an Adapter
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>
User Guide for Adapter SDK
Configuring and Running an Adapter

2014 SAP AG or an SAP affiliate company. All rights reserved. 89
<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:
Table 1: System properties
Property Description
operationIn
stanceName
The operation instance name. No default value (you must define the value). For adapter opera
tions 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 mes
sage 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 im
practical 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.
pollingInter
valMSec
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 fre
quency 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 de
fine pollingIntervalMSec to be no more than a few seconds so that the Adapter SDK can pe
riodically regain control from the adapter operation, providing for effective life-cycle manage
ment (start/stop).
displayName
The operation instance display name. View the display name in the Designer's metadata brows
ing 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.
90

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
Configuring and Running an Adapter
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
Context
After an adapter is installed, the Data Services user must configure adapter instances using the Administrator in
the Management Console.
User Guide for Adapter SDK
Configuring and Running an Adapter

2014 SAP AG or an SAP affiliate company. All rights reserved. 91
Procedure
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
Results
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
Procedure
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.
92

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
Configuring and Running an Adapter
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
Context
For debugging purposes, you can start an adapter using the command prompt or from debugging tools. (This
assumes the adapter instance is not running.)
Procedure
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>
Results
where:
<<list_of_jar_files>> all Java libraries necessary to run an adapter. The jar files required by the Adapter
SDK are:
User Guide for Adapter SDK
Configuring and Running an Adapter

2014 SAP AG or an SAP affiliate company. All rights reserved. 93
<<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
Note
BrokerClient.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.
94

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
Configuring and Running an Adapter
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.
Item Description
buildTestAdapter.bat Batch file to build the adapter.
in_sales_details.txt Source file used in Job_Table_delim_target job.
User Guide for Adapter SDK
TestAdapter

2014 SAP AG or an SAP affiliate company. All rights reserved. 95
Item Description
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 re
pository.)
mtrl_avail.xml XML document used to run RTJob_OutboundMessage and RTJob_Messa
geFunction 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 repo
sitory.)
mtrl_avail_in_OK.xml XML document used to test real-time services created from JobsRT
Job_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 repo
sitory.)
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:
96

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
TestAdapter
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 interfa
ces.
ReadTable.java The Delimited, Operation, StreamOperation, Table, and
TableSource interfaces.
ReceiveFrom Rtdf.java The ListenerOperation interface, which processes messages re
ceived 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 interfa
ces.
WriteTable.java The Delimited, Operation, StreamOperation, Table, and
TableTarget interfaces.
WriteTableBeanInfo.java The customizer for the WriteTable class.
User Guide for Adapter SDK
TestAdapter

2014 SAP AG or an SAP affiliate company. All rights reserved. 97
7.4 Preparing and testing TestAdapter
This section explains how to prepare, run, and test TestAdapter. Use this section to:
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.

98

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
TestAdapter

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
User Guide for Adapter SDK
TestAdapter

2014 SAP AG or an SAP affiliate company. All rights reserved. 99
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
Procedure
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 100]
7.4.3.2 Configuring a new TestAdapter instance
Procedure
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.
100

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
TestAdapter
Field Name Enter:
Adapter instance
name
TestAdapterInstance"
Access Server Host The name of the computer where your Access Server is running.
Access Server Port 4000
Note
This should be the port number associated with the client interfaces for the Ac
cess 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
User Guide for Adapter SDK
TestAdapter

2014 SAP AG or an SAP affiliate company. All rights reserved. 101
7.4.4 Configuring operations for TestAdapterInstance in the
Administrator
Procedure
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.
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
102

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
TestAdapter
Parameter Value
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
Results
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
Procedure
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.
Results
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
Context
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.
Procedure
1. In the Datastores tab of the Designer Object Library, right-click and select New.
The Datastore Editor appears showing a Connection tab.
User Guide for Adapter SDK
TestAdapter

2014 SAP AG or an SAP affiliate company. All rights reserved. 103
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.
Results
After you create the TestAdapter datastore, you can browse and import sample data.
7.4.7 Testing browse and import metadata capabilites
Context
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.
Procedure
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.
104

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
TestAdapter
7.4.8 Importing TestAdapter metadata by name
Context
Scan the browser window to become familiar with metadata available from TestAdapter, then import some
metadata objects by name.
Procedure
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
Procedure
1. In the Data Services Administrator, select Real-time Access Server Real-time services .
2. Click Select all.
3. Click Start.
User Guide for Adapter SDK
TestAdapter

2014 SAP AG or an SAP affiliate company. All rights reserved. 105
Results
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
106

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
TestAdapter
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.
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/testadap
ter/ReadDocument.java
Job_Table_delim_source
Adapter table source.
Delimited format data exchange.
src/com/acta/adapter/testadap
ter/ReadTable.java
Job_Table_xml_source
Adapter table source.
src/com/acta/adapter/testadap
ter/ReadTable.java
User Guide for Adapter SDK
TestAdapter

2014 SAP AG or an SAP affiliate company. All rights reserved. 107
Job Data flow demonstrates TestAdapter source code
XML format data exchange.
Job_Document_target
Adapter table source.
src/com/acta/adapter/testadap
ter/ReadTable.java
Job_Table_delim_target
Adapter table target.
Delimited format data exchange.
src/com/acta/adapter/testadap
ter/WriteTable.java
Job_Table_xml_target
Adapter table target.
XML format data exchange.
src/com/acta/adapter/testadap
ter/WriteTable.java
Job_FunctionCall
Adapter function call in the query transform.
src/com/acta/adapter/testadap
ter/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:
src/com/acta/adapter/testadapter/ReadTable.java
108

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
TestAdapter
Imported adapter metadata:
sales_details_delim(TestAdapter)
Other metadata involved:
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.
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:
src/com/acta/adapter/testadapter/ReadTable.java
Imported adapter metadata:
sales_details_xml(TestAdapter)
Other metadata involved:
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
Imported adapter metadata:
sales_details_delim(TestAdapter)
User Guide for Adapter SDK
TestAdapter

2014 SAP AG or an SAP affiliate company. All rights reserved. 109
Other metadata involved:
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:
src/com/acta/adapter/testadapter/WriteTable.java
Imported adapter metadata:
sales_details_delim_target(TestAdapter)
Other metadata involved:
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:
src/com/acta/adapter/testadapter/WriteTable.java
Imported Adapter metadata:
sales_details_xml_target(TestAdapter)
Other metadata involved:
110

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
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.
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)
Other metadata involved:
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
User Guide for Adapter SDK
TestAdapter

2014 SAP AG or an SAP affiliate company. All rights reserved. 111
8 Debugging in Eclipse
8.1 Debugging in Eclipse
Prerequisites
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.
Context
Perform the following to debug your adapter in Eclipse:
Procedure
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>>"
Note
In 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.
112

2014 SAP AG or an SAP affiliate company. All rights reserved.
User Guide for Adapter SDK
Debugging in Eclipse
Results
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.
User Guide for Adapter SDK
Debugging in Eclipse

2014 SAP AG or an SAP affiliate company. All rights reserved. 113
www.sap.com/contactsap

2014 SAP AG 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 AG.
The information contained herein may be changed without prior
notice.
Some software products marketed by SAP AG and its distributors
contain proprietary software components of other software
vendors. National product specifications may vary.
These materials are provided by SAP AG and its affiliated
companies ("SAP Group") for informational purposes only, without
representation or warranty of any kind, and SAP Group shall not be
liable for errors or omissions with respect to the materials. The only
warranties for SAP Group 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 AG in Germany and other countries.
Please see http://www.sap.com/corporate-en/legal/copyright/
index.epx for additional trademark information and notices.