SAP Business objects DATA SERVICES JMS Adapter Interface

Data Services JMS Adapter Interface

BusinessObjects Data Services XI 3.1 (12.1.0)

Copyright

© 2008 Business Objects, an SAP company. All rights reserved. Business Objects
owns the following U.S. patents, which may cover products that are offered and
licensed by Business Objects: 5,295,243; 5,339,390; 5,555,403; 5,590,250;
5,619,632; 5,632,009; 5,857,205; 5,880,742; 5,883,635; 6,085,202; 6,108,698;
6,247,008; 6,289,352; 6,300,957; 6,377,259; 6,490,593; 6,578,027; 6,581,068;
6,628,312; 6,654,761; 6,768,986; 6,772,409; 6,831,668; 6,882,998; 6,892,189;
6,901,555; 7,089,238; 7,107,266; 7,139,766; 7,178,099; 7,181,435; 7,181,440;
7,194,465; 7,222,130; 7,299,419; 7,320,122 and 7,356,779. Business Objects and
its logos, BusinessObjects, Business Objects Crystal Vision, Business Process
On Demand, BusinessQuery, Cartesis, Crystal Analysis, Crystal Applications,
Crystal Decisions, Crystal Enterprise, Crystal Insider, Crystal Reports, Crystal
Vision, Desktop Intelligence, Inxight and its logos , LinguistX, Star Tree, Table
Lens, ThingFinder, Timewall, Let There Be Light, Metify, NSite, Rapid Marts,
RapidMarts, the Spectrum Design, Web Intelligence, Workmail and Xcelsius are
trademarks or registered trademarks in the United States and/or other countries
of Business Objects and/or affiliated companies. SAP is the trademark or registered
trademark of SAP AG in Germany and in several other countries. All other names
mentioned herein may be trademarks of their respective owners.

Third-party
Contributors

Business Objects products in this release may contain redistributions of software
licensed from third-party contributors. Some of these individual components may
also be available under alternative licenses. A partial listing of third-party
contributors that have requested or permitted acknowledgments, as well as required
notices, can be found at: http://www.businessobjects.com/thirdparty

2008-08-26

Contents

Introduction 7Chapter 1

About this guide...........................................................................................8

Adapter overview.........................................................................................9

Installation and configuration 11Chapter 2

Installing the JMS adapter.........................................................................12

JMS adapter configuration.........................................................................14

Who should read this guide....................................................................8

About Java Messaging Service (JMS)...................................................9

Scope of the JMS adapter....................................................................10

System prerequisites............................................................................12

Adapter product components...............................................................12

Installing JMS adapter..........................................................................14

Configuring the JMS adapter................................................................15

Configuring an adapter instance..........................................................16

Configuring an operation instance.......................................................20

Put Operation (request/acknowledgment) options...............................21

Defining a JMS adapter datastore........................................................28

Importing message functions and outbound messages to the

datastore..............................................................................................29

Using the JMS Adapter 31Chapter 3

Starting an instance of the JMS adapter...................................................32

Operations from Data Services to the JMS Adapter............................32

Operations from Information Resource (IR) to Data Services..............33

Running the sample...................................................................................34

Data Services JMS Adapter Interface 3

Contents

To run the sample.................................................................................34

Configuring the JMS provider...............................................................35

Using MQ instead of JNDI configuration..............................................36

Testing PutGet: Request/Reply..................................................................37

Testing on Windows NT........................................................................38

Testing on UNIX...................................................................................38

Testing PutTopic Operation........................................................................39

Testing on Windows NT........................................................................40

Testing on UNIX...................................................................................40

Testing Get: Request/Reply.......................................................................41

Testing on Windows NT........................................................................41

Testing on UNIX...................................................................................42

Testing GetTopic Operation.......................................................................42

Testing on Windows.............................................................................43

Testing on UNIX...................................................................................43

Testing Get: Request/Acknowledge...........................................................44

Testing on Windows NT........................................................................45

Testing on UNIX...................................................................................45

Testing Put: Request/Acknowledge...........................................................45

Testing on Windows NT........................................................................46

Testing on UNIX...................................................................................47

Technical implementation..........................................................................47

Design considerations..........................................................................47

Error handling and tracing....................................................................48

Appendix 49Chapter 4

Weblogic as JMS Provider ........................................................................50

To create a JMS Connection Factory........................................................50

To configure the Connection Factory...................................................50

Create a JMS queue..................................................................................51

4 Data Services JMS Adapter Interface

Contents

Index 53

Data Services JMS Adapter Interface 5

Contents

6 Data Services JMS Adapter Interface

Introduction

1

Introduction

1

About this guide

About this guide

This guide provides a detailed step-by-step method of installing and
configuring the Data Services JMS adapter. It includes a description of
required support software, including supported versions, details of the adapter
components, environment setup both for Data Services and external
applications, and instructions for executing the adapter.

Who should read this guide

This document assumes the following:

• You understand how to use Data Services Designer to design and run

real-time data flows (RTDFs) and batch jobs.

• You have a basic understanding of how to use Data Services Administrator

to administer Data Services processes. (You administer adapters from
the Administrator.)

• You have a working knowledge of the environment this adapter is

targeting.

• You know the role an adapter plays in business systems integration.

• You have some familiarity with XML and XML configuration schemas.

• Also, to integrate Data Services with an external system, Business Objects

recommends that you be familiar with systems administration and systems
integration issues.

General Data Services product documentation assumes the following:

• You are an application developer, consultant or database administrator

working on data extraction, data warehousing, or data integration.

• You understand your source and target data systems, DBMS, legacy

systems, business intelligence, and messaging concepts.

• You understand your organization's data needs.

• If you are interested in using this product to design real-time processing

you are familiar with:

• DTD and XML Schema formats for XML files

8 Data Services JMS Adapter Interface

• Publishing Web Services (WSDL, HTTP/S and SOAP protocols, etc.)

• You are familiar with Data Services installation environments: Microsoft

Windows or UNIX.

Adapter overview

Typical enterprise infrastructure is a complex mix of off-the-shelf and custom
applications, databases, ERP applications etc. Data Services combines and
extends critical Extraction Transformation Loading (ETL) and Enterprise
Application Integration (EAI) technology components required for true
enterprise data integration.

Integrating disparate applications with the Business Objects Data Integration
platform requires adapters. These adapters help facilitate otherwise
incompatible applications and systems work together, thereby sharing data.

About Java Messaging Service (JMS)

Introduction

Adapter overview

1

Enterprise-messaging or Message Oriented Middleware (MOM) products
are fast becoming an essential component for integrating intra-company
operations. They allow separate business components to be combined into
a reliable, yet flexible, system. In addition to the traditional MOM vendors,
several database vendors and Internet-related companies also provide
enterprise-messaging products.

Java language clients and Java language middle-tier services must be
capable of using these messaging systems. Java Messaging Service (JMS)
provides a common way for Java language programs to access these
systems.

JMS is a set of interfaces and associated semantics that define how a JMS
client accesses the facilities of an enterprise-messaging product. Since
messaging is peer-to-peer, all users of JMS are generically referred to as
clients. A JMS application is composed of a set of application-defined
messages and a set of clients that exchange them. Products that implement
JMS do this by supplying a provider that implements the JMS interfaces.

Data Services JMS Adapter Interface 9

Introduction

1

Adapter overview

Scope of the JMS adapter

• Data Services initiates Request/Reply

Data Services initiates the request by sending the message on a
pre-configured request queue and gets the reply on a pre-configured reply
queue.

• Data Services initiates Request/Acknowledgment

Data Services initiates the request by sending the message on a
pre-configured target queue or by publishing a message to a JMS topic.
In this case, only the acknowledgment is sent back to Data Services.

• IR initiates Request/Acknowledgment & Request/Reply

In this case, an external Information Resource (IR is a JMS compatible
application) sends the requests to Data Services and gets the reply or
acknowledgment.

Alternatively, the IR publishes a message to a JMS topic to which the
JMS Adapter has subscribed.

10 Data Services JMS Adapter Interface

Installation and configuration

2

Installation and configuration

2

Installing the JMS adapter

Installing the JMS adapter

This section details the components of the Data Services Adapter for JMS
as well as system requirements and installation information.

System prerequisites

Before you install your Data Services Adapter for JMS, ensure that the
following software is installed. For specific installation instructions, see the
technical documentation for each product.

CommentVersionSoftware

JMS Provider

11.7.0 or laterData Services

Data Services Adapter
SDK

2.0.0.0 or later

Adapter product components

The following diagram shows a functional overview of the Data Services
Adapter for JMS with other components and their potential interrelationships:

For example, Weblogic
Application Server

Use Data Services to
configure the services
and adapter

12 Data Services JMS Adapter Interface

Installation and configuration

Installing the JMS adapter

2

The diagram shows the architecture and functionality of the Data Services
Adapter for JMS as well as how the Data Services Adapter for JMS interacts
with the external JMS application through the JMS Provider. The Data
Services Adapter for JMS sends or receives data on queues using the Point
to Point (P2P) mode of communication, or publishes or subscribes to a JMS
topic using the Publish/Subscribe mode of communication.

The flow of control in the previous diagram is as follows:

1. External application invokes a service on Data Services.

2. Based on the service invoked on Data Services, its respective real-time

data flow (RTDF) invokes the Operation instance with XML data sent by
the external application as input.

3. This operation instance sends the message to the configured queue or

topic in the JMS provider. Based on the type of operation (such as
Request/Reply or Request/Acknowledge), the JMS provider sends the
Reply/Acknowledgment message back to Data Services.

Data Services JMS Adapter Interface 13

Installation and configuration

2

JMS adapter configuration

4. External JMS application sends messages to the JMS Provider on a

request queue or publishes the message to a topic. The JMS Adapter
receives these messages after polling them from the JMS Provider and
for P2P, sends the reply back to external JMS application on a configured
reply queue. No reply is sent if the message was from a topic.

Installing JMS adapter

The Data Services Adapter for JMS is automatically installed when you install
Data Services version 12.0.0 or later.

JMS adapter configuration

Before the Data Services Adapter for JMS can begin integrating the JMS
Provider with the Data Services system you must create and configure at
least one adapter instance and at least one operation for each instance.
Adapter instances identify the JMS Application used in the integration.
Adapter operations identify the integration operations to be used with the
configured adapter instance.

Operations provided with Data Services Adapter for JMS include the following:

• PutGet Operation (Request/Reply): Data Services initiates a request,

sending a message on a pre-configured request queue. Simultaneously,
Data Services listens on a pre-configured reply queue. An external
JMS-compatible application listens on the request queue, processes the
request, and returns an XML response message to the reply queue. The
adapter sends the message to the Data Services service.

• Put Operation (Request/Acknowledgment): Data Services initiates a

request, sending a message on a pre-configured target queue. If the
message was sent successfully, the adapter sends an acknowledgement
to the Data Services service. The adapter raises an exception if it was
unable to send the message.

• Get Operation (Request/Acknowledgment and Request/Reply from

Information Resource): An external information resource (IR) sends a
request XML message to a JMS queue. The adapter polls the JMS queue
at a time interval you specify in the configuration. When the adapter
receives a message from the JMS queue, it sends the message to the
pre-configured Data Services service.

14 Data Services JMS Adapter Interface

After processing the XML message, the Data Services service may send
a response message to the adapter. When this happens, the adapter
puts the message in a pre-configured response queue. If the response
queue is not configured, it becomes a request/acknowledgment operation
and no reply is sent. If there is any error in invoking another service from
the Data Services service, the original message is sent to the undelivered
queue for reference by the IR.

• PutTopic Operation (Request/Acknowledgment): A Data Services service

initiates a request, publishing an XML message to a pre-configured target
topic. If the message was sent successfully, the adapter sends an
acknowledgement to the Data Services service. The adapter raises an
exception if it was unable to send the message.

• GetTopic Operation (Request/Acknowledgment): An external information

resource (IR) publishes an XML message to a JMS topic. The adapter
polls the topic at the time intervals specified in the configuration. When
the adapter receives the message from the topic, it sends the message
to the Data Services service that handles the message.

Configuring the JMS adapter

Installation and configuration

JMS adapter configuration

2

All Data Services adapters communicate with Data Services through a
designated Adapter Manager Job Server. Install adapters on the computer
containing your designated Adapter Manager Job Server. This special Job
Server integrates adapters with Data Services using the Administrator and
Designer. After you install your adapter:

1. Use the Server Manager utility to configure adapter connections with the

Adapter Manager Job Server.

2. From the Data Services Administrator, perform the following tasks:

• Add at least one instance of the adapter to Data Services system.

• Add at least one operation for each adapter instance.

• Start the adapter instance (operations are started automatically).

3. Open the Data Services Designer and create an adapter datastore. Use

metadata accessed through the adapter to create batch and/or real-time
jobs.

Data Services JMS Adapter Interface 15

Installation and configuration

2

JMS adapter configuration

Related Topics

• Installation Guide: To configure Job Servers

Configuring an adapter instance

From the Data Services Administrator you can add a JMS adapter to the
Data Services system as well as edit existing adapter configurations. Add
the adapter in the Administrator before you run jobs that use information
from that adapter.

To add an adapter instance in the Administrator

1. Select Adapter Instances > Job Server.

2. Select the Configuration tab.

3. Click Add.

4. Select JMSAdapter from the list of adapters available on this Job Server

and click Apply.

5. Enter the required information to create a JMS Adapter instance and click

Apply.

The Administrator makes the adapter instance available to Data Services.

Adapter instance configuration information

To configure a JMS adapter instance in Data Services, you need to complete
the fields in the Administrator under Adapter instance startup configuration.

16 Data Services JMS Adapter Interface

Installation and configuration

JMS adapter configuration

DescriptionField

2

Adapter Instance
Name

Access Server
Host

Access Server
Port

Adapter Retry
Count

Interval

Classpath

Enter a unique name that identifies this instance of the
adapter.

Enter the host ID of the computer running the Access
Server that connects to this adapter instance. To run a real­time job, you must configure a service that the Access
Server will use to run the job. When a job uses adapter­based data, the Access Server must be able to connect to
the adapter instance.

The message broker port of the Access Server host. After
you log into the Administrator for this Access Server, select
Configuration > Client Interfaces to view message broker
port information.

Applies if adapter instance fails or crashes. Enter 0 for no
retries; enter a negative number for indefinite retries.

Wait in msec. between adapter retry attempts.Adapter Retry

The adapter is a Java program, so you must configure the
jar files required by the adapter CLASSPATH. The adapter
is pre-configured with all necessary jar files except for the
vendor-specific JMS provider jar files. Add your JMS
provider's jar files to the CLASSPATH. For example:

• <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/acta_jms_adapter.jar

• <LINK_DIR>/ext/lib/jms/<JMS Provider Jar File>

Autostart

Note:

Specify the jar file provided with the JMS provider that you
are using. For Weblogic, the name of jar file is weblogic.jar.

When set to True, the adapter interface automatically starts
when the Administrator starts.

Data Services JMS Adapter Interface 17