IBM WebSphere Adapter Toolkit User Manual

WebSphere

Version 6 Release 2

®

Adapters



WebSphere Adapter Toolkit User Guide
Version 6 Release 2

WebSphere

Version 6 Release 2

®

Adapters



WebSphere Adapter Toolkit User Guide
Version 6 Release 2

Note

Before using this information and the product it supports, read the information in “Notices” on page 211.

December 2008

This edition applies to version 6, release 2, modification 0 of and to all subsequent releases and modifications until
otherwise indicated in new editions.

To send us your comments about this document, email mailto://[e-mail]. We look forward to
hearing from you.

When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any
way it believes appropriate without incurring any obligation to you.

© Copyright International Business Machines Corporation 2006, 2008. All rights reserved. US Government Users
Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

© Copyright International Business Machines Corporation 2006, 2008.

US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.

Contents

WebSphere Adapter Toolkit ......1

IBM WebSphere Adapter Toolkit technology

overviews ...............2

IBM WebSphere Adapters .........2

Architectural overview ..........4

How metadata is used at build time and run time 7
Using Enterprise Metadata Discovery to build

services ...............7

IBM WebSphere Adapter Toolkit overview ....8

New Connector Project wizard overview ....9

Resource Adapter Deployment Descriptor Editor

overview ..............10

Adapter Foundation Classes overview ....10

IBM WebSphere Adapter Toolkit tasks .....11

IBM WebSphere Adapter Toolkit installation

requirements ..............11

Samples overview ............12

Running the Twine Ball sample using WebSphere

Integration Developer ..........13

Running the Twine Ball sample using Rational

Application Developer..........26

Troubleshooting the samples........28

Using the New Connector Project wizard ....28

Launching the New Connector Project wizard . . 29

Specify project properties .........31

Specify project facets ..........32

Specify connector project module settings . . . 32

Specify resource adapter properties .....33

Specify generation options ........34

Generating an IBM WebSphere Resource Adapter 35

Generating a JCA resource adapter .....49

Generated code and deployment descriptor. . . 55
Using the Resource Adapter Deployment Descriptor

editor ................56

Displaying the deployment descriptor ....56

Modifying deployment descriptor properties . . 66

Editing deployment descriptor source ....67

Implementing code from the IBM WebSphere

Adapter Toolkit .............68

Foundation Classes implementation overview . . 68

Data model .............69

Inbound event notification ........79

Inbound callback event notification .....89

Outbound support ...........97

Data and metadata ..........115

Enterprise Metadata Discovery general

interfaces and implementation for application

adapters ..............123

Enterprise Metadata Discovery interfaces and

implementation for technology adapters . . . 157

Structured record implementation .....162

Data binding implementation .......166

Bidirectional language support ......167

Problem determination .........168

Validating the code ...........193

Testing enterprise metadata discovery (EMD) of

the adapter .............193

Testing the adapter in unmanaged mode . . . 194

Testing the adapter in managed mode ....197

Validating code with Rational Application

Developer and WebSphere Application Server . 203
Creating and exporting a resource adapter . . . 206

Reference...............208

Terminology.............208

Notices ..............211

Programming interface information ......213

Trademarks and service marks .......213

Index ...............215

© Copyright IBM Corp. 2006, 2008 iii

iv WebSphere Adapters: WebSphere Adapter Toolkit User Guide

WebSphere Adapter Toolkit

The IBM®WebSphere®Adapter Toolkit provides the development tools, libraries
and sample code to assist you in creating JCA resource adapters.

With the toolkit you may create either of the following:

v A resource adapter based on the interfaces defined by the JCA Resource

Adapter 1.5 specification. Choose this path if your goal is developing a resource

adapter that can run either unmanaged or managed within any JCA 1.5
compliant container.

v A resource adapter that extends the WebSphere Adapter Foundation Classes

library. Choose this path if your goal is to create a resource adapter

implementation that can run in a managed server runtime environment like
WebSphere Process Server and that exhibits the common functionality and
extended qualities of service offered specifically by WebSphere Adapters.
WebSphere Adapters are based on the JCA 1.5 specification. These adapters are
supported on multiple runtime environments and brokers.

Implementing a WebSphere adapter allows you to take advantage of the quality of
services offered in the WebSphere Adapter foundation classes (AFC) and the
flexibility of being able to run the adapter on runtime environments other than
WebSphere Process Server.

In either case, the toolkit provides a project creation wizard that generates the code
that you then implement. In addition, the toolkit provides a specialized editor that
facilitates the task of creating and configuring a resource adapter deployment
descriptor.

This document focuses primarily on development of resource adapters and
artifacts that extend the WebSphere Adapter Foundation Class library.

The following figure illustrates the process of developing a JCA resource adapter
using the WebSphere Adapter Toolkit.

Using the WebSphere Adapter Toolkit

© Copyright IBM Corp. 2006, 2008 1

The development process using the IBM WebSphere Adapter Toolkit includes the
following as shown in the illustration:

1. Run the New JCA Resource Adapter Project wizard.

The wizard generates a resource adapter deployment descriptor and code. The
code can include sequence of calls, log and trace messages and comments.

2. Use the Resource Adapter Deployment Descriptor Editor to configure your

deployment descriptor.

3. Implement the code to correctly interface with your enterprise information

system (EIS).

4. Export the resource adapter as a resource adapter archive (RAR) or enterprise

application archive (EAR) file.

The purpose of this documentation

Adapter development requires a great deal of software engineering, which varies
from customer to customer. The process of integrating adapter functionality into
your business processes will require you to design, build and test the solution that
utilizes the adapter. The purpose of the WebSphere Adapter Toolkit documentation
is to lay out the requirements of the architecture and provide guidance on how
and when to implement the various facets of it, so that you can apply your
engineering discipline to the adapter-specific requirements, capabilities and
architecture.

IBM WebSphere Adapter Toolkit technology overviews

The IBM WebSphere Adapter Toolkit helps developers implement the Adapter
Foundation Classes, which establish a WebSphere Adapter standard for building
resource adapters that conform to the Java 2 Connector Architecture (JCA) 1.5
specification.

IBM WebSphere Adapters

An IBM WebSphere Adapter implements the Java 2 Enterprise Edition (J2EE)
Connector architecture (JCA), version 1.5. Also known as resource adapters or JCA
adapters, WebSphere Adapters enable managed, bidirectional connectivity between
enterprise information systems (EIS) and J2EE components supported by multiple
server runtime environments, including WebSphere Process Server and WebSphere
Application Server.

IBM WebSphere adapters support outbound request processing and inbound event
processing.

Note: IBM WebSphere adapters support outbound and inbound processing for
WebSphere Process Server and outbound processing only for WebSphere Application
Server.

Outbound processing refers to a process in which request data flows from a client
application to the EIS. In an outbound processing scenario, the adapter acts as the
connector between the application component and the EIS. The adapter provides a
set of standard operations, which process either after-image or delta style business
objects. An outbound request can read data from or write data to the EIS.

Inbound event processing refers to a process that is initiated by an event on the
EIS. In inbound event processing the adapter converts events generated from the
EIS into business objects and sends the business object to the client application.

2 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

Inbound event notification complements outbound request processing, enabling
adapters to provide bidirectional communication between business processes and
EIS applications.

WebSphere Process Server Enterprise information

system

J2E component

Figure 1. A WebSphere Adapter

The IBM WebSphere Adapter portfolio of adapters is based on the Java 2 Platform,
Enterprise Edition (J2EE) standard. JCA is a standard architecture for integrating
J2EE applications with enterprise information systems. Each of these systems
provides native APIs for identifying a function to call, specifying its input data,
and processing its output data. The goal of the JCA standard is to provide an
independent API for coding these functions, to facilitate data sharing, and to
integrate J2EE applications with existing and other enterprise information systems.
The JCA standard accomplishes this by defining a series of contracts that govern
interactions between an EIS and J2EE components within an application server.

WebSphere

Adapter

Business

function

Files

Fully compliant with the JCA standard, WebSphere Adapters have been developed
to run on multiple server runtimes. A WebSphere Adapter does the following:

v Integrates with multiple server runtimes, including WebSphere Process Server,

WebSphere Enterprise Service Bus, and WebSphere Application Server.

v Connects an application running on WebSphere Process Server with an EIS.

v Enables data exchange between the application and the EIS.

Each WebSphere Adapter is made up of the following:

v An implementation of the (J2EE) Connector Architecture (JCA), version 1.5,

which supports WebSphere Process Server and WebSphere Application Server.

v An enterprise metadata discovery component.

You use this component with the external service discovery wizard to introspect
the EIS to discover and generate business objects and other service component
architecture (SCA) artifacts that are compiled in a standard enterprise
application archive (EAR) file. You can also use the external service discovery
wizard to build a service (rather than discover a service). For example, you can
use the enterprise service discovery wizard to build services (based on search
criteria you provide), and generate business objects and interfaces.

The enterprise metadata discovery component implements version 1.1 of the
enterprise metadata discovery specification.

WebSphere Adapter development overview 3

WebSphere adapters utilize a format-independent data model for representing data
objects. In a WebSphere Process Server or WebSphere Enterprise Service Bus
runtime environment, WebSphere adapters use an extension of the service data
objects (SDO) for representing data objects.

Architectural overview

In conjunction with the appropriate EIS-specific subclasses, the WebSphere Adapter
Foundation Classes provide a JCA-compliant resource adapter implementation that
can be managed by the application server to enable bidirectional connectivity to an
enterprise information system (EIS).

Outbound requests, those requests intended for the EIS, can be sent to the resource
adapter by any J2EE component via the Common Client Interface (CCI) defined by
the JCA specification. For inbound events, events within the EIS sent to the
adapter, message-driven beans that implement the InboundListener interface are
registered with the adapter by the application-server enabling them to receive any
appropriate inbound events from the EIS via the adapter.

Regardless of the whether data is intended for inbound or outbound delivery, the
resource adapter (i.e. Adapter Foundation Classes plus EIS-specific subclasses) acts
as a conduit for any J2EE application to communicate with the EIS.

Figure 2. Architecture overview

Runtime architecture component model

The adapter runtime architecture is a collection of components interacting through
well-defined interfaces and based on the J2EE Connector Architecture (JCA)
specification version 1.5.

At run time, the adapters implement both the Data Exchange Service Provider
Interface (DESPI) contracts to interact with the runtime container and the CCI
contracts to interact with the application component. The JCA architecture has been
extended with the data exchange component that allows efficient data exchange
between the adapter and the server runtime and supports multiple runtime
environments.

The layered approach provides a set of elements that can be assembled to provide
desired functionality and quality of service. The componentized approach allows
the separate, independent development of each element, as well as their reuse. The
following illustration presents the runtime architecture component model. The

4 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

processing performed by each component (and subcomponent) in the model is
described in sections that follow the illustration.

Application interface

SCA J2EE CC Proprietary. .

Data
Exchange

Common

Application
Component

JCA Connector

JCA Connector

Services

Monitoring

Problem
Determination

Figure 3. Runtime architecture component model

SDO DAAPI

Record Other

Connectivity

Data exchange

Programming

Model

Metadata

Common Client

Interface (CCI)

Connections

Security

Transactions

DESPI Records

Metadata

Adapter

Foundation

Classes

The component model allows for a single architecture for adapter development
and evolution. It uses recognized standards but extends them as necessary, for
example with high performance, runtime-independent data exchange interface that
enables full adapter functionality in various environments. The layered component
model reduces complexity and allows extensibility. The use of the adapter
foundation classes (the standard library for building adapters) supports common
adapter capabilities and ensures adapter consistency.

JCA connector component

The JCA connector component provides the standard architecture for connecting
the J2EE platform to heterogeneous enterprise information systems (EIS),
facilitating bidirectional data exchange with the EIS. The JCA connector component
can be driven by the metadata that describes the interaction with the EIS. The JCA
connector component includes separate subcomponents for connecting to the EIS
and for exchanging data.

JCA connector connectivity subcomponent

The connectivity subcomponent of the JCA connector component includes
functionality for establishing, maintaining and closing connections to the target EIS
and provides support for transactions and security for these connections.

WebSphere Adapter development overview 5

The connectivity subcomponent interacts with the target enterprise information
system’s specific libraries and functionality. The subcomponent is exposed to the
application interface component through standard JCA CCI interfaces, which
include Connection, ConnectionFactory, Interaction and InteractionSpec for
outbound processing and ResourceAdapter and ActivationSpecWithXid for the
inbound event processing.

JCA connector Data exchange SPI (DESPI) subcomponent

The data exchange subcomponent of the JCA connector component includes
functionality for sending or receiving data from the application component through
the data exchange interface (DESPI). This interface is format and runtime neutral,
and permits any kind of structured or streamed data to be moved between the
connector and the application. The connector component understands the data
format of the EIS and is able to convert it to invocations of Data Exchange SPI. The
main advantage of DESPI is its high efficiency rate of passing data between
components without introducing any intermediate format.

Common services and adapter foundation classes

The adapter foundation classes provide base adapter implementation ensuring that
all the interfaces required by the contracts supported by the Connector component
are provided.

As shown in Figure 3 on page 5, the adapter foundation classes provide support
across all the elements of the connector component, including the JCA interfaces, as
well as data exchange interfaces implementing Data Exchange SPI (DESPI) and
various quality of service.

The adapter foundation classes support all the required JCA contracts for outbound
and inbound connectivity. For the outbound interactions, the support includes
standard create, retrieve, update, and delete (CRUD) operations through the
Command Manager, the application sign-on and transactions when supported by
EIS. For the inbound connectivity, support includes reliable event delivery to the
endpoint, support for polling as well as event listening pattern.

The adapter foundation classes provide full support for DESPI with full
implementation of required interfaces including abstract representation of the
metadata. An important component of the runtime environments, and thus
architecture, is monitoring and problem determination support. The adapter
foundation classes provide a set of utility classes for robust and consistent logging
and tracing in different deployment scenarios by hiding the underlying runtime
implementation.

The adapter foundation classes also support various monitoring and events and
allow all adapters take advantage of that functionality. The supported quality of
service includes Performance Monitoring Infrastructure (PMI), Application
Response Measurement (ARM) and Common Event Infrastructure (CEI). For more
information on the monitoring capabilities available, see “Monitoring and
measuring performance” on page 181.

Application interface component

The application interface component bridges the runtime environment and the
connector component. It enables invocation of the connector from the clients, using

6 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

the appropriate programming model. It is responsible for mapping the specific
invocation to the invocation of the connector component through the JCA common
client interface (CCI).

The component developer who has knowledge of the connector invocation
interfaces and the runtime programming model, delivers the application
component. The application component consists of data exchange, application
interface, and metadata elements.

Metadata

The metadata subcomponent describes the structure of the data exchanged with
the EIS through the data exchange interfaces. The metadata can also provide
information to the connector component about how the data can be exchanged
with the EIS. For more information on the metadata subcomponent, see “How
metadata is used at build time and run time.”

How metadata is used at build time and run time

Metadata is a set of characteristics that describe the structure of a WebSphere
business integration component, such as a business object, collaboration, or
adapter. Metadata describes facets common across an entire class of objects. For
example, attributes, properties, verbs, and application-specific information constitute
the metadata for a business object. Application-specific information is the part of
metadata of a business object that enables the adapter to interact with its
application or a data source.

At build time, you use the adapter to access data on an EIS, and from that data to
generate metadata in the form of annotated XML schemas. This build time
representation of the metadata contains the annotations with application-specific
information (ASI) that the adapter needs at run time in order to associate objects or
individual properties with their equivalent in the external resource.

The application-specific information portion of metadata identifies key fields,
mappings to external types, or for any other purpose that the adapter dictates. At
run time, an appropriate runtime representation of the metadata is passed to the
adapter. The adapter generates the data as XML annotations. All other components
apart from the adapter itself ignore the XML annotations. The runtime
representation must correspond to the XML schemas that were the result of the
import during enterprise metadata discovery, however their method of creations
may be specific to the given environment.

Note: The XML Schema generated as part of Enterprise Metadata Discovery can be
thought of as the canonical form.

You may prefer to construct the data object metadata programmatically from its
own metadata representation, which would have been created from the original
XML schemas, in other cases different representations, such as Records are used.
However, it is required that any application-specific information annotations in the
schemas be preserved by such environments and then provided along with the
type definition for consumption by the adapter.

Using Enterprise Metadata Discovery to build services

In addition to using enterprise metadata discovery to discover existing services,
you can use it to build services that include integrated processes that exchange
information with a technology like email or a file system.

WebSphere Adapter development overview 7

Version 1.1 of Enterprise Metadata Discovery includes enhancements for
configurable data handlers, function selectors, and data bindings, and a way to
build service descriptions using these configured artifacts and existing schemas. For
information on implementing interfaces for technology-style adapters, see
“Enterprise Metadata Discovery interfaces and implementation for technology
adapters” on page 157.

IBM WebSphere Adapter Toolkit overview

WebSphere Adapter Toolkit contains everything you need to create a resource
adapter. The adapters are metadata-driven components designed for bidirectional
communication with external services on Enterprise Information Systems (EIS),
such as transaction systems or ERP systems, as well as bidirectional
communication with technologies such as Email or Flat File.

Developing application components or processes that interact with the EIS through
an adapter requires tools that allow you to discover the services available on the
EIS. When the EIS does not include a metadata repository, the tool should allow
you to build the appropriate interactions with the EIS using adapters. The
enterprise metadata discovery (EMD) specification implemented by the WebSphere
Adapters enables you to discover services from an existing metadata repository or
build the appropriate interactions with an EIS. The specification defines the
interaction between adapters and tools and allows for plugging adapters into a
compatible tool implementation that supports the specification.

The enterprise metadata discovery-compliant tools are based on the Eclipse
platform and include IBM WebSphere Integration Developer and IBM Rational
Application Developer. The current tools support generation of SCA and J2EE
programming model artifacts, and is extensible to also support generation of
artifacts for other programming models and server runtimes. Enterprise metadata
discovery provides pluggability for artifact writers, which store the metadata and
configuration information in a manner compatible with the tools and runtime
requirements. The current enterprise metadata discovery implementation supports
SCA artifacts, but other artifacts can be generated by implementing a writer
plug-in. Such implementations may choose to write the configuration information
and metadata directly to their native repository, or to create classes or
configuration files to contain properties required for runtime.

In the service discovery mode, you use the adapter to connect to the EIS metadata
repository and browse its contents. You can select objects or services required by
the business application from the repository, specify properties for the objects and
import them (as business objects) into the development environment.

The enterprise metadata discovery process defines an abstract representation of the
imported services that allows the external service wizard to generate artifacts that
are specific to the programming model and the supported server runtime.

If you need to build a service (rather than discover a service), you can use the
external service wizard to create services from existing artifacts in the context of
the particular adapter to be used at run time. You can select the existing data types
to be exchanged and defined the transformation to be performed on these data
types.

The toolkit includes the following:

v An adapter development wizard and editor - Both are Eclipse plug-ins targeted

for use with WebSphere Integration Developer, v. 6.2:

8 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

– The New Connector Project Wizard - Prompts you to specify information

about the resource adapter you wish to develop, and then generates code and
a deployment descriptor.

The code generated by the wizard can include sequence of calls, log and trace
messages and comments.

– Resource Adapter Deployment Descriptor Editor - An Eclipse multi-page

form editor that allows you to display and configure your deployment
descriptor. As changes are made to configuration properties using the editor,
the appropriate Java bean properties are added to your code.

v Adapter Foundation Classes - A common set of services for all IBM WebSphere

resource adapters.

v Samples - To assist you in creating custom WebSphere resource adapters.

New Connector Project wizard overview

The wizard installed with the WebSphere Adapter Toolkit guides you through
creation of a Connector Project, including the generation of code and a deployment
descriptor for a custom JCA resource adapter.

Figure 4. New Connector Project wizard

The New Connector Project Wizard is an Eclipse plug-in intended for use with
WebSphere Integration Developer. The wizard allows you to create code in a Java
Connector Project for a custom resource adapter. Working with the wizard, you can
do the following:

v Generate implementations of the JCA 1.5 interface specification or extensions

to the Adapter Foundation Classes API

The wizard prompts you for information that is then used to create the
appropriate code for your adapter.

WebSphere Adapter development overview 9

v Generate a resource adapter deployment descriptor

You can view and edit this deployment descriptor using the Resource Adapter
Deployment Descriptor Editor.

Resource Adapter Deployment Descriptor Editor overview

This multi-page editor allows you to display, configure, and validate the resource
adapter deployment descriptor generated by the wizard.

Figure 5. Resource Adapter Deployment Descriptor

The Resource Adapter Deployment Descriptor is an Eclipse plug-in intended for
use with WebSphere Integration Developer. The editor allows you to do the
following:

v Display and configure the resource adapter deployment descriptor without

having to modify the XML file directly

v Automatically generate Java bean properties in the generated source code that

correspond to the configuration properties you add using the editor

v Validate the deployment descriptor against the against the JCA 1.5 deployment

descriptor schema.

Adapter Foundation Classes overview

The Adapter Foundation Classes installed with theWebSphere Adapter Toolkit
provide the foundation services for a custom JCA resource adapter that can run on
multiple server runtimes, including WebSphere Process Server.

The New Connector Project wizard uses the Adapter Foundation Classes to
generate an implementation of classes for your custom adapter. The Adapter
Foundation Classes conform to, and extend, the Java 2 Connector Architecture JCA

1.5 specification. The foundation classes include generic contracts and methods to
develop a working resource adapter. The New Connector Project wizard collects
information from you to create enterprise information system-specific extensions to
the foundation classes.

This document contains implementation guidelines for the Adapter Foundation
Classes. The Javadoc for the Adapter Foundation Classes, as well as the Javadoc
for the Data exchange service provider interface (DESPI) and the Javadoc for
Enterprise Metadata Discovery, are included as part of the WebSphere Adapter
Toolkit installation. For more information, see “IBM WebSphere Adapter Toolkit
tasks” on page 11.

10 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

IBM WebSphere Adapter Toolkit tasks

The tasks range from installing the toolkit, samples, and Adapter Foundation
Classes (using the Eclipse Update Manager in WebSphere Integration Developer) to
implementing and validating your code.

Table 1. WebSphere Adapter Toolkit tasks

Task Task description

Validate WebSphere Adapter Toolkit installation
requirements

Installing WebSphere Adapter Toolkit You do not run an installer program for the toolkit. Instead, you

Access the Javadoc for the Adapter Foundation
Classes, EMD 1.1 and DESPI.

Using the New J2C Resource Adapter Project
wizard

Using the Resource Adapter Deployment
Descriptor editor

Implementing code stubs A topic-by-topic guide to implementing the generated code.

Validating code How to validate your code.

Exporting the resource adapter How to export a standalone (RAR file) or embedded (EAR file)

See the developerWorks site for WebSphere Adapter Toolkit for
hardware and software prerequisites for the toolkit and for
specific information on how to integrate the toolkit into the
version of WebSphere Integration Developer or Rational
Application Developer for WebSphere Software that is installed
on your system.
Note: Make sure you select the tab for version 6.2 of the
WebSphere Adapter Toolkit.

bring the toolkit, the samples, and the adapter foundation classes
(including the Javadoc for the Adapter Foundation Classes and
the Javadoc for DESPI and EMD) into WebSphere Integration
Developer by launching the Eclipse Update Manager.

To access the Javadoc, perform the following steps:

1. From the Rational Application Developer for WebSphere

Software or WebSphere Integration Developer menu, select

Help → Help Contents

2. Choose Websphere Adapter Toolkit documentation and then

select the Javadoc you want to view.

Note: To view the Javadoc for JCA 1.5, go to the download
section of the J2EE Connector Architecture site.

How to launch it, specify properties, choose generation options,
and generate classes.

How to launch it, display features, change and add properties,
and edit source.

resource adapter.

®

IBM WebSphere Adapter Toolkit installation requirements

The WebSphere Adapter Toolkit installation has operating system requirements and
hardware requirements.

Among the requirements are a Windows or Linux operating system and successful
installation of WebSphere Integration Developer.

Operating system requirements

Make sure that you meet the operating system requirements shown in the table.

Operating system Versions

Linux Red Hat Enterprise Linux AS/ES/WS 3 Update 4, Version 3.0

SUSE LINUX Enterprise Server (SLES and SLSS), Version 9.0

WebSphere Adapter development overview 11

Operating system Versions

Windows 2000 Windows 2000 Professional (SP4)

Windows 2000 Server (SP4)
Windows 2000 Advanced Server (SP 4)

Windows XP Windows XP SP 2

Windows 2003 Windows Server 2003 Standard

Windows Server 2003 Enterprise

Hardware requirements

The table shows the hardware requirements for supported operating systems.

Operating system Hardware requirements

®

Linux
Windows®2000
Windows 2003
Windows XP

®

v Intel

v 1024 x 768 display or higher resolution monitor

v Memory: requirements

v Disk space requirements:

Pentium®III 800 MHZ processor or faster

– 768 MB minimum

– 1 GB recommended

– 3.5 GB minimum to installing software prerequisites

– Additional disk space for your development

resources.

You can reduce the minimum disk space if optional
features and runtimes are not installed.

Software requirements

The components that comprise the WebSphere Adapter toolkit are Eclipse plug-ins.
You must install WebSphere Integration Developer software before attempting to
install IBM WebSphere Adapter Toolkit software plug-ins.

Samples overview

When you installed the IBM WebSphere Adapter Toolkit, two sample resource
adapters were placed on your system. The samples installed with WebSphere
Adapter Toolkit are a reference for the creation of custom JCA resource adapters.

There are two samples as follows:

v The TwineBall sample is an implementation of a custom WebSphere Adapter

based on the Adapter Foundation Classes. This sample is located in the
adapter/twineball directory of the install location you selected.

The sample adapter connects to a sample enterprise information system (EIS),
which is also called TwineBall. This EIS is included in the RAR package,
twineball.jar. The TwineBall EIS uses the Derby database to store table data in a
file on the file system TWINE.

v The KiteString sample is similar to TwineBall, but is based directly on the JCA

1.5 resource adapter interface specification. The KiteString sample is located in
the adapter/kitestring directory of the install location you selected.

12 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

This documentation describes how to run the Twine Ball sample only. However,
you can apply the instructions for running and testing the Twine Ball sample to
the Kite String sample.

The sample instructions accommodate creating an adapter for the Twine Ball
sample using WebSphere Integration Developer, for deployment to a WebSphere
Process Server runtime environment, as well as instructions for creating the
adapter for the Twine Ball sample using Rational Application Developer, for
deployment to WebSphere Application Server runtime environment.

In order to test the functionality of the adapter used in the sample, the adapter
must include both outbound and inbound processing capabilities. In the
instructions for the sample, you will first select an outbound processing direction
for the adapter. The outbound processing performed by the adapter in the Twine
Ball sample creates a customer. As a result of creating a customer, an event is
created in a database table. When you test the adapter in the sample, the adapter
uses its inbound processing capabilities to retrieve that event.

Both Twineball and KiteString include the following:

v Implementation of a resource adapter and enterprise metadata discovery

v Resource adapter deployment descriptor and source code in Project Interchange

Format suitable for importing into WebSphere Integration Developer

v RAR file suitable for deployment to WebSphere Process Server.

Running the Twine Ball sample using WebSphere Integration
Developer

Use WebSphere Integration Developer to access and run the Twine Ball sample.

Import the samples code

Before you can run the sample, you must first import it into your workspace.

Make sure you have installed WebSphere Adapter Toolkit.

For information on known issues with regard to running the sample code, see
Known issues in Troubleshooting the samples.

Importing the sample code involves bringing sample code and artifacts into your
environment so that you can run a sample application.

The following instructions describe how to use WebSphere Integration Developer
to import a deployable RAR file for use in the Twine Ball sample.

Optionally, you can import the Twine Ball sample by importing the source code.

1. Import the deployable RAR file for the Twine Ball sample from the WebSphere

Integration Developer samples.

a. Launch WebSphere Integration Developer

Click Start → Programs → IBM WebSphere → Integration Developer 6.2.

b. From the menu, select Help → Samples

WebSphere Adapter development overview 13

This launches the Samples.

c. From the Samples navigation pane, select Technology samples and expand

Java and WebSphere Adapters so that the Twine Ball and Kite String

samples display.

d. Click Twine Ball to display a description of the Twine Ball sample in the

viewing pane of the Technology Samples.

2. From the viewing pane of the Technology samples window, select Import the

sample deployable rar. This launches the Connector Import window.

Note: You can also import the sample deployable RAR from the setup

instructions window.

3. Enter values on the Connector Import window:

a. Accept the default values for the Connector file and the Connector module

fields.

b. Select WebSphere Process Server v6.2 for the Target runtime field.

14 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

c. Optional: Deselect the Add project to an EAR check box.

4. Click Finish.

A dialog prompts you to open the J2EE perspective. Click Ye s to finish the
process of importing the deployable RAR file for the Twine Ball sample into
your workspace.

Now you can perform external service discovery for the Twine Ball sample.

Run external service discovery for outbound processing

The external service wizard is a tool you use to create services. The external service
wizard establishes a connection to the EIS, discovers services (based on search
criteria you provide), and generates business objects, interfaces, and import or
export files, based on the services discovered.

Import the deployable RAR file for the sample.

For the Twine Ball sample you need to create an adapter service for outbound
processing and inbound processing. This task describes the how to use the External
Service wizard to create and adapter service for outbound processing.

1. If not already there, go to the Business Integration perspective.

2. Place your cursor in the Business Integration navigation pane, right-click and

select New → Other to launch the Select a wizard window.

3. From the list of available wizards, expand Business Integration and select the

External Service wizard:

WebSphere Adapter development overview 15

4. Click Next to launch the New External Service window.

5. From the New External Service window, make sure that Unlisted Adapter is

selected and click Next.

6. From the Select an Adapter window, expand TwineBallConnector (IBM:6.2),

select CWYAT_TwineBall and click Next.

16 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

7. From the Processing Direction window, select Outbound and click Next.

8. From the Discovery Configuration window, click Next. No connection

properties are required.

9. From the Object Discovery and Selection window, select CUSTOMER from the

Discovered objects pane and add it to the Selected objects portion of the
window then click Next.

WebSphere Adapter development overview 17

10. From the Configure Composite Properties window, select Next.

11. From the Service Generation and Deployment Configuration window, deselect

Specify a Java Authentication and Authorization Services (JASS) alias
security credential and click Next.

18 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

12. From the Service Location Properties window, click New. This launches the

New Integration Project window.

13. From the New Integration Project window, select Create a module project and

click Next.

14. Enter values in the New Module window and click Finish.

Your module displays in the Project explorer view:

WebSphere Adapter development overview 19

15. Click Finish from the Service Location Properties window to add the

outbound interface to the module.

16. You are prompted on whether you want to update the model, select Yes.

Run the external service discovery process again to add the inbound interface to
the module.

Run external service discovery for inbound processing

The external service wizard is a tool you use to create services. The external service
wizard establishes a connection to the EIS, discovers services (based on search
criteria you provide), and generates business objects, interfaces, and import or
export files, based on the services discovered.

Make sure you have done the following:

v Import the deployable RAR file for the sample into your workspace.

v Run external service discovery for outbound processing.

For the Twine Ball sample you need to create an adapter service for outbound
processing and inbound processing. This task describes the how to use the External
Service wizard to create an adapter service for inbound processing.

1. Go to the Business Integration perspective.

2. Place your cursor in the Business Integration navigation pane, right-click and

select New → Other to launch the Select a wizard window.

3. From the list of available wizards, expand Business Integration and select the

External Service wizard:

20 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

4. Click Next to launch the New External Service window.

5. From the New External Service window, make sure that Unlisted Adapter is

selected and click Next.

6. From the Select an Adapter window, expand TwineBallConnector (IBM:6.2),

select CWYAT_TwineBall and click Next.

WebSphere Adapter development overview 21

7. From the Processing Direction window, select Inbound and click Next.

8. From the Discovery Configuration window, click Next. No connection

properties are required.

9. From the Object Discovery and Selection window, select CUSTOMER and add

it to the Selected objects portion of the window then click Next.

22 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

10. From the Configure Composite Properties window select Next.

11. From the Service Generation and Deployment Configuration window, deselect

Specify a Java Authentication and Authorization Services (JASS) alias
security credential.

WebSphere Adapter development overview 23

12. From the Service Location Properties window, click Finish to add the inbound

interface to the module.

13. You are prompted on whether you want to update the model, select Yes.

You should see the inbound and outbound interfaces in the viewing area of
the assembly diagram editor:

Modify the module.

Modify the module

Modify the sample module by adding a Java component to link to the inbound
service.

You must have created the service before modifying it.

By adding a Java component to link the service you will be able to access and
implement the emit <Create/Delete/Update>Customer() method to insert a print
statement.

1. Add a Java component to link to the InboundService.

24 WebSphere Adapters: WebSphere Adapter Toolkit User Guide