IBM WebSphere Adapters User Manual

Download

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://doc-comments@us.ibm.com. 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.

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

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

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

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

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

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.

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

a. In the viewing pane of the Assembly diagram, right click and select Add →

Java to add a Java component to the diagram

2. Add a wire from the inbound interface to the new Java component. A window

displays to inform you that your actions will allow the service to be used in other modules. Click OK.

3. Right click on the Java component and select Generate → Implementation. and

click OK on the Generate Implementation window.

4. Add a system.out.println to the emitCreateAfterImageCustomer

emitCreateAfterImageCustomer()/emitCustomer() method

public void emitCreateAfterImageCustomer(

DataObject emitCreateAfterImageCustomerInput) { System.out.println("Got the event!"); //TODO Needs to be implemented.

}

5. Save the module.

Now you are ready to test the module.

Test the sample

Use the administrative console and test client to test your sample.

Before you test the sample module make sure you have completed all of the previous tasks for creating and modifying the sample module.

1. Start WebSphere Process Server

2. Add the module project to the server

3. Verify the adapter is running (and polling if you selected the inbound service).

Check the console, log and trace file for more information.

WebSphere Adapter development overview 25

4. Run the administrative console and verify the module is installed and running.

5. Test the module by performing the following steps:

a. Change to the Business Integration perspective b. Right click on the module and select Test → Test Module

c. Populate the customer object fields with data.

d. Click the continue button.

e. Look for this message in the console:

Got the Event!

This is the message that you implemented in the emitCreateAfterImageCustomer() method.

Running the Twine Ball sample using Rational Application Developer

Use Rational Application Developer access and run the Twine Ball sample.

Import the samples code into Rational Application Developer and modify the sample for use

Before you can run the sample, you must first import it into your workspace and modify various values.

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 Rational Application 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 Rational

Developer samples.

a. Launch Rational Application Developer

Click Start → Programs → IBM Rational → Application Developer 7.5.1.

b. From the menu, select Help → Samples

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.

3. Right click on CWYAT_TwineBall and select New → Other → J2C → J2C Java

Bean

4. Click CWYAT_TwineBall → Next → Next

5. In the Object Discovery and Selection window use the arrow-right to add the

CUSTOMER object to the Objects to be imported area of the window and click Next.

26 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

6. In Java Creation and Deployment Configuration, make the following

selections:

v Select create new project Name and enter a name for the project, for

example, Demo.

v Enter a name in the Create New Package Name field, for example pckg v Provide an interface name in the Interface Name field, for example Sample

v Choose Non-managed Connection and click Finish.

7. Right click on Demo → New → Other → J2C and select one of the following:

v Web Page

v Web Service

v EJB from J2C Java Bean

Select Next.

8. Choose Java Project and enter a name for the project.

9. In J2C Java bean selection, choose the correct J2C bean implementation and

click Next. For example, using the values documented in this sample, you would choose:\Demo\src\pckg\SampleImpl.java

10. Select EJB and click Next

11. Create the EJB project name and the EJB package.

12. For example, DemoEJB for the project name and ejbpkg for the EJB package

name.

13. Right click DemoEJB → Properties and add the following to the Java Build

path:

v twine.jar

v aspectjrt.jar

v ffdc.jar

v ffdcsupport.jar

14. Right click DemoEJB → Java EE → Prepare for deployment

15. Right click on Server and add project If you used values from this example,

you would add the project DEMOEJBEAR.

Use the universal test client to test the adapter in the Twine Ball sample.

Test the sample using the universal test client

Use the universal test client to verify that the adapter in the Twine Ball sample functions as intended.

Before you test the sample module make sure you have completed all of the previous tasks for creating and modifying the sample module.

The test validates that the adapter performs it’s intended functions within the context of the Twine Ball sample.

1. Run universal test client.

2. Click on JNDI Explorer

3. Click on ejb and click on your package, for example ejbpkg and select correct

SessionBeanHome

4. On the left side of Universal test client, choose correct SessionBeanHome and

Invoke create method. If you used the values from the sample documentation, you would select EJBSessionBeanHome.

5. Click the work with object radio button.

WebSphere Adapter development overview 27

6. On left side select EJBSessionBean1 and click Customer

createCustomer(Customer) Enter input customer parameters

Troubleshooting the samples

You may need to troubleshoot issues that arise when creating or running the samples.

Errors

The following errors may result when working with the sample code:

v A com.ibm.adapter.framework.BaseException error

This error can result when using the sample source code to run external service discovery or because the Twine Ball database is locked by a prior run of the external service discovery process. The error message displays as follows:

To fix this error perform the following steps:

1. Go to the WebSphere Integration Developer installation directory and delete

the twine folder.

2. Restart WebSphere Integration Developer and try to run the external service

discovery process again.

Known issues

The following issues regarding working with the Kite String and Twine Ball samples are known issues to development:

v If you create the module using the sample code instead of the deployable RAR

file, you cannot publish to the module successfully to WebSphere Process Server. When you run the samples you should do so using the deployable sample RAR file instead of the source code.

v The Kite String sample works in WebSphere Application Server with custom

clients, but it does not work with the Rational Application Developer J2C tooling.

Using the New Connector Project wizard

You use the wizard create a Connector Project which contains a deployment descriptor and classes. The classes either extend the WebSphere Adapter Foundation Classes or implement the JCA 1.5 Interface specification.

28 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

Launching the New Connector Project wizard

You launch the wizard from IBM WebSphere Integration Developer.

Make sure you have met all of the installation requirements and that you have successfully installed WebSphere Integration Developer and the WebSphere Adapter Toolkit plug-ins.

Launch the New Connector Project wizard when you are ready to create a new adapter project.

1. Start IBM WebSphere Integration Developer.

Choose Start → IBM WebSphere → WebSphere Integration Developer V6.x → WebSphere Integration Developer V6.x. This displays the Workspace Launcher dialog.

Workspace Launcher dialog

2. Enter a workspace directory for your project, or click Browse to select a

location for your project in the Workspace field.

The workspace is a directory where WebSphere Integration Developer stores your project.

Optional: Select the Use this location as the default check box to always use this workspace for new projects. You can change workspaces by choosing File → Switch Workspace.

3. Make sure you are in either the Business Integration or Java EE perspective.

4. Select the wizard.

Choose File → New → Other. This displays the Select a wizard dialog.

WebSphere Adapter development overview 29

Select a wizard dialog

5. Start the wizard.

Expand theJava EE folder, choose Connector Project, and click Next. This starts the New Connector Project wizard and displays the Connector Project dialog.

Connector Project dialog

You are ready to describe your project and resource adapter properties.

30 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

Specify project properties

You name your connector project, optionally adding it to an Enterprise Application project. You also specify the configuration used for developing the resource adapter.

You perform all of these tasks from the Connector Project dialog.

Connector Project dialog

1. Name your Connector Project.

Enter a project name in the Project name field. The name is automatically appended to the workspace location.

2. Set Target Runtime to <None> and select IBM Websphere Adapter for the

Configurations

The IBM Websphere Adapter configuration contains the IBM WebSphere Adapter Foundation Classes 6.2, J2C Module 1.5 and Java 5.0 Project Facets. You can modify these facets by clicking the Modify button.

3. Optional: Specify an Enterprise Application Archive (EAR) project name.

a. In the EAR Membership section, click the Add project to an EAR check

box. Enter or select a name in the EAR project Name field or click New and then name the new EAR project.

Note: You can generate an EAR file later, after building and testing the adapter.

4. Click Next. This displays the Project facets dialog.

You are ready to specify project facet properties.

WebSphere Adapter development overview 31

Specify project facets

As part of the process of creating a project, you specify project facets. A project facet represents a unit of functionality in the project. Project facets define characteristics and requirements for projects. When you add a facet to a project, that project is configured to perform a certain task, fulfill certain requirements, or have certain characteristics.

1. From the New Connector Project screen, make sure IBM WebSphere Adapter

displays in the Configurations field and do not change the configuration or deselect any of the project facets. The project facets that are preselected are the facets you need to run the WebSphere Adapter Toolkit.

2. Select Next to go to the Connector Project module settings panel.

Now you can configure the Connector Project Module settings.

Specify connector project module settings

Specify connector project module settings for your adapter.

1. From the Configure Connector Module setting page, accept the name assigned

to the connector project.

32 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

2. Click Next to advance to the Resource adapter properties page.

Now you are ready to set the properties for the resource adapter.

Specify resource adapter properties

Resource adapter properties are the descriptive properties that you assign to both the adapter and the adapter class.

You name the adapter and qualify its Java class with a package name and class prefix.

You perform these tasks in the J2C Resource Adapter Properties window.

WebSphere Adapter development overview 33

Figure 6. J2C Resource Adapter Properties window

1. In Adapter Name, type the name of the adapter.

2. In Adapter ShortName, type a one- to four-character short name for the

adapter. The short name is used to create the component name that is used in the log and trace files as follows:

ShortName + the characters “RA” + the value of the adapter ID property, which the user specifies when configuring the adapter

For example, if you specify the short name BO and the user specifies the adapter ID of 001, then the component name used in log and trace files is BORA001.

3. In Package Name, type the package name.

4. In Class Name Prefix, type the prefix to be used in adapter class names. Class

Name displays the resulting fully qualified ResourceAdapter class name.

5. Click Next. This displays the Generation Options window.

You can now specify generation options for your resource adapter.

Specify generation options

Generation options are the types of components for which you can generate classes.

You specify adapter components in the Generation Options dialog.

You must choose which kind of adapter specification you want to implement: an IBM WebSphere Resource Adapter, or a J2C Resource Adapter. The adapter specification that you choose determines the generation options available.

34 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

For information on the characteristics of an IBM WebSphere Resource Adapter and a J2C Resource Adapter, see Introduction to JCA.

Generation Options dialog

From the Adapter Specification drop-down, choose the type of adapter you want to create:

v Choose IBM WebSphere Resource Adapter in the Adapter Specification list to

generate code that extends the Adapter Foundation Classes.

v Choose J2EE J2CA Resource Adapter in the Adapter Specification list to

generate code that implements the JCA 1.5 interface specification.

The wizard displays the generation options that correspond to your adapter.

What to do next

You are ready to specify generation options that match your adapter requirements.

Generating an IBM WebSphere Resource Adapter

You use the wizard to generate adapter classes that correspond to the adapter capabilities you require. This involves choosing the types of adapter classes (outbound, inbound, data binding, or enterprise metadata discovery) you want to generate and then choosing the component properties associated with the adapter classes.

The following sections describe the adapter classes and their associated component properties.

Outbound adapter classes and associated properties

Generating outbound adapter classes creates code (and in some cases sequence of calls, log and trace messages and comments) for the methods that must be implemented to produce a resource adapter that can send business events to an EIS. The list of Adapter Foundation Classes that are extended in your Connector Project when you choose to generate outbound adapter classes is as follows:

v Connection extends com.ibm.j2ca.base.WBIConnection

v ConnectionFactory extends com.ibm.j2ca.base.WBIConnectionFactory

v ConnectionRequestInfo extends com.ibm.j2ca.base.WBIConnectionRequestInfo

v Interaction extends com.ibm.j2ca.base.WBIInteraction

v InteractionSpec extends com.ibm.j2ca.base.WBIInteractionSpec

v ManagedConnection extends com.ibm.j2ca.base.WBIManagedConnection

v ManagedConnectionFactory extends

com.ibm.j2ca.base.WBIManagedConnectionFactory

In addition the following are generated directly from the JCA 1.5 interface specification:

v ConnectionSpec implements javax.resource.cci.ConnectionSpec

v ConnectionMetaDataImpl implements javax.resource.cci.ConnectionMetaData

v LocalTransaction implements javax.resource.spi.LocalTransaction

WebSphere Adapter development overview 35

You can select the following properties when generating outbound adapter classes:

v Local transaction support

Generating outbound adapter classes with local transaction support means that the transaction is managed and performed by the EIS. LocalTransaction indicates the IBM WebSphere adapter supports local transactions. Local transaction support methods provide a LocalTransaction implementation and return the wrapper.

Using the WBILocalTransaction covers the following requirements:

– Notifies the JCA container

– Updates the state of transactions on the WBIManagedConnection When you choose the Local Transaction Support component property from the

list of outbound adapter component properties, the wizard will create the following method in the ManagedConnection class:

/** * Does the EIS support local transaction? Provide a LocalTransaction * implementation and return the wrapper.

* * @return new instance of WBILocalResourceWrapper

* @see javax.resource.spi.ManagedConnection#getLocalTransaction() */ public LocalTransaction getLocalTransaction() throws ResourceException {

FooLocalTransaction transaction = new FooLocalTransaction(this);

return new WBILocalTransactionWrapper(transaction, this);

}

For information on how to generate an outbound adapter with local transaction support, see Generating outbound local transaction support methods.

v XA transaction support

Generating outbound adapter classes with XA transaction support means the transaction spans multiple heterogeneous systems. It uses global or two-phase-commit protocol. If a transaction manager coordinates a transaction, that transaction is considered a global transaction.

Using the WBILocalTransaction covers the following requirements:

– Notifies the JCA container

– Updates the state of transactions on the WBIManagedConnection

The getXAResource() method should get the XAResource from your EIS and return the wrapper. The WBIXAResourceWrapper acts as a thin layer delegating all calls to the underlying EIS XAResource instance, while at the same time tracking the sequence of calls to monitor and determine when the connection is involved in a transaction and when it is not.

The wizard will create the getXAResource() and getLocaltransaction() method as follows:

Local method

/** * Does the EIS support local transaction? * * @return new instance of WBIXAResourceWrapper * @see javax.resource.spi.ManagedConnection#getLocalTransaction() */ public LocalTransaction getLocalTransaction() throws ResourceException { FooLocalTransaction transaction = new FooLocalTransaction(this); return new WBILocalTransactionWrapper(transaction, this); }

XA method

36 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

/**

* Does the EIS support XA transaction? * Get the XAResource from your EIS and return the wrapper. *

* @return new instance of WBIXAResourceWrapper * @see javax.resource.spi.ManagedConnection#getXAResource()

public XAResource getXAResource() throws ResourceException {

return new WBIXAResourceWrapper(null, this);

}

Further implementation of these methods are needed to support XA transactions.

For information on how to generate XA Transaction support methods, see Generating XA Transaction support methods.

v Command pattern

Generating command pattern classes allows you to break down a hierarchical update into a series of nodes and then generate a collection of sub-commands to manage the nodes. An interpreter processes the sub-commands, retrieving and executing the corresponding code. If you choose this option, the wizard generates code for the following classes:

– BaseCommand extends

com.ibm.j2ca.extension.commandpattern.CommandForCursor

– CommandFactory implements

com.ibm.j2ca.extension.commandpattern.CommandFactoryForCursor

– CreateCommand extends <your package

name>.outbound.commandpattern.<your class prefix>BaseCommand

– DeleteCommand extends <your package

name>.outbound.commandpattern.<your class prefix>BaseCommand

– NoOperationCommand extends <your package

name>.outbound.commandpattern.<your class prefix>BaseCommand

– RetrieveCommand extends <your package

name>.outbound.commandpattern.<your class prefix>BaseCommand

– RetrieveAllCommand extends <your package

name>.outbound.commandpattern.<your class prefix>BaseCommand

– UpdateCommand extends <your package

name>.outbound.commandpattern.<your class prefix>BaseCommand

For information on how to generate command pattern classes, see Generating command pattern classes.

Inbound adapter classes and associated methods

Generating inbound adapter classes creates code for the methods that must be implemented to produce a resource adapter that can send events from an EIS to a business process. The list of Adapter Foundation Classes that are extended in your Connector Project when you choose to generate inbound adapter classes is as follows:

v ActivationSpecWithXid extends com.ibm.j2ca.base.WBIActivationSpecWithXid

v EventStoreWithXid extends

com.ibm.j2ca.extension.eventmanagement.EventStoreWithXid

You can select the following properties when generating outbound adapter classes:

v Connection pooling

WebSphere Adapter development overview 37

When you choose the connection pooling component property the wizard will create the ActivationSpecWithXid class that extends WBIActivationSpecForPooling.

For information on how to generate inbound connection pooling support, see Generating inbound connection pooling support.

v Event polling support

Generating inbound adapter classes for event polling support creates code for the methods that must be implemented to produce a resource adapter that can send polling events from an EIS to a business process.

The list of Adapter Foundation Classes that are extended in your Connector Project when you choose to generate inbound adapter classes for event polling support is as follows:

– ActivationSpecWithXid extends com.ibm.j2ca.base.WBIActivationSpecWithXid

– EventStoreWithXid extends

com.ibm.j2ca.extension.eventmanagement.EventStoreWithXid

When the CommException exception is logged during adapter startup because the EIS is down, stopped, or unreachable, the adapter automatically retries the connection if the RetryConnectionOnStartup activation specification property is enabled. If the property is not enabled, the adapter immediately reports the failure. This support is provided by the Adapter Foundation Classes. An adapter user enables this property in the external service wizard by selecting Retry EIS connection on startup on the Service Generation and Deployment Configuration window. The RetryConnectionOnStartup property works with the RetryLimit and RetryInterval properties, which specify the number of times the adapter retries the connection and the length of time it waits before retrying.

For information on how to generate event polling support, see Generating inbound event polling support.

v Generating inbound callback event support

Generating inbound adapter classes for callback event support creates code for the methods that must be implemented to produce a resource adapter that can send callback events from an EIS to a business process.

The list of Adapter Foundation Classes that are extended in your Connector Project when you choose to generate inbound adapter classes for callback event support is as follows:

– ActivationSpecWithXid extends com.ibm.j2ca.base.WBIActivationSpecWithXid

– InboundListener that imports in

com.ibm.j2ca.extension.eventmanagment.external.CallbackEventSender

For information on how to generate inbound callback event support, see Generating inbound callback event support.

Data Binding classes

There are no properties associated with data binding classes.

Generating data binding classes creates code for the methods needed to marshall data from SDO to CCI record and from CCI record to SDO.

The list of Adapter Foundation Classes that are extended in your Connector Project when you choose to generate data binding classes is as follows:

v DataBinding implements

commonj.connector.runtime.RecordHolderDataBinding

v DataBindingGenerator extends

38 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

com.ibm.j2ca.extension.databinding.WBIDataBindingGenerator

For information on how to generate data binding classes, see Generating Data Binding Classes.

Enterprise Metadata Discovery classes

There are no properties associated with Enterprise Metadata Discovery classes.

Generating enterprise metadata discovery classes creates code for the methods needed to produce a service that you can use to glean business object structure and other data from an EIS.

The list of Adapter Foundation Classes that are extended in your Connector Project when you choose to generate enterprise metadata discovery classes is as follows:

v AdapterType extends

com.ibm.j2ca.extension.emd.discovery.WBIAdapterTypeImpl

v DataDescription extends

com.ibm.j2ca.extension.emd.description.WBIDataDescriptionImpl

v InboundConnectionConfiguration extends

com.ibm.j2ca.extension.emd.discovery.connection.WBIInboundConnectionConfigurationImpl

v InboundConnectionType extends

com.ibm.j2ca.extension.emd.discovery.connection.WBIInboundConnectionTypeImpl

v InboundServiceDescription extends

com.ibm.j2ca.extension.emd.description.WBIInboundServiceDescriptionImpl

v MetadataDiscovery extends

com.ibm.j2ca.extension.emd.discovery.WBIMetadataDiscoveryImpl

v MetadataEdit extends

com.ibm.j2ca.extension.emd.discovery.WBIMetadataEditImpl

v MetadataImportConfiguration extends

com.ibm.j2ca.extension.emd.discovery.WBIMetadataImportConfigurationImpl

v MetadataObject extends

com.ibm.j2ca.extension.emd.discovery.WBIMetadataObjectImpl

v MetadataSelection extends

com.ibm.j2ca.extension.emd.discovery.WBIMetadataSelectionImpl

v MetadataTree extends

com.ibm.j2ca.extension.emd.discovery.WBIMetadataTreeImpl

v OutboundConnectionConfiguration extends

com.ibm.j2ca.extension.emd.discovery.connection.WBIOutboundConnectionConfiguration

v OutboundConnectionType extends

com.ibm.j2ca.extension.emd.discovery.connection.WBIOutboundConnectionTypeImpl

v OutboundServiceDescription extends

com.ibm.j2ca.extension.emd.description.WBIOutboundServiceDescriptionImpl

In addition to the Adapter Foundation Classes listed above, the following classes are also generated to assist you:

v Constants

Contains enterprise metadata discovery constant variables.

WebSphere Adapter development overview 39

v StringCaseChanger

This is a utility that you can use format the business object or attribute name properly.

For information on how to generate Enterprise Metadata Discovery classes, see Generating Enterprise Metadata Discovery classes .

Generating outbound adapter classes

Generate outbound adapter classes for adapters that will send requests from a client application to the EIS.

Review the section on outbound adapter classes and associated properties in Generating an IBM WebSphere Resource Adapter.

When you choose to generate outbound adapter classes, the wizard creates code (and in some cases sequence of calls, log and trace messages and comments) for the methods that must be implemented to produce a resource adapter that can send business events to an EIS.

1. From the Available components portion of the Generation Options window,

click the Generate Outbound Adapter Classes check box .

2. Review the available component property options associated with outbound

adapter classes.

Each of the component property options are described in the sections that follow.

Generate the outbound adapter classes for the component property selected.

40 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

Generating outbound local transaction support methods:

With local transaction support, the transaction is managed and performed by the EIS. LocalTransaction indicates the IBM WebSphere adapter supports local transactions. Local transaction support methods provide a LocalTransaction implementation and return the wrapper.

Consider your strategy for implementing transaction behavior in the adapter before generating outbound classes. You will not be allowed to regenerate code to add XA transactional behavior to the adapter if you click Finish to generate the code for this task.

Review the section on local transaction support in Generating an IBM WebSphere Resource Adapter.

For more information on transaction support, see Implementing transaction support.

1. Click the Generate outbound adapter classes check box and then click on the

Local Transaction Support check box in the right pane.

Note: Before clicking Finish be aware that when you generate transactional

support for the outbound classes you will not be able to modify the transaction support automatically after generating the classes.

2. Click Finish.

Now, you can generate outbound XA transaction support methods.

WebSphere Adapter development overview 41

Generating outbound XA transaction support methods:

With XA transaction support, the transaction spans multiple heterogeneous systems. It uses global or two-phase-commit protocol. If a transaction manager coordinates a transaction, that transaction is considered a global transaction.

Review the section on XA transaction support in Generating an IBM WebSphere Resource Adapter.

The getLocalTransaction() method provides a LocalTransaction implementation and returns the wrapper.

For more information on transaction support, see Implementing transaction support.

1. Click the Generate Outbound Adapter classes check box and then click on the

XATransaction Transaction Support check box in the right pane.

When you choose XATransaction Transaction Support, Local Transaction Support is selected automatically.

2. Click Finish.

Now, you can generate command pattern classes.

Generating command pattern classes:

Command pattern classes help reduce the complexity associated with comparing and managing dynamic object hierarchies.

42 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

Review the section on command pattern classes in Generating an IBM WebSphere Resource Adapter.

The command pattern classes allow you to break down a hierarchical update into a series of nodes and then generate a collection of sub-commands to manage the nodes. An interpreter processes the sub-commands, retrieving and executing the corresponding code.

1. Click Generate Outbound Adapter Classes and then click Command Pattern

component property on the right pane.

2. Click Finish.

Generating inbound adapter classes

Generate inbound adapter classes for notifying a business process of an inbound event from the EIS.

Review the section on inbound adapter classes and associated properties in Generating an IBM WebSphere Resource Adapter.

When you choose to generate inbound adapter classes, the wizard creates code for the methods that must be implemented to produce a resource adapter that can send events from an EIS to a business process.

1. From the Available components portion of the Generation Options window,

click the Generate Inbound Adapter classes check box.

WebSphere Adapter development overview 43

2. Review the available component property options associated with inbound

adapter classes.

Each of the component property options are described in the sections that follow.

Generate the inbound adapter classes for the component property selected.

Note: Before deploying your adapter to WebSphere Process Server version 6.2, you must populate all inbound properties with default values. You can also assign dummy values to properties that are generated but not implemented by your adapter.

Generating inbound connection pooling support:

Generate inbound connection pooling support.

When you choose the connection pooling component property the wizard will create the ActivationSpecWithXid class that extends WBIActivationSpecForPooling.

Further implementation of this method is needed to support XA transactions.

1. Click the Generate Inbound Adapter classes check box and then click on the

Connection Pooling check box in the right pane.

Note: The Event Polling Support property is selected automatically when you

select Connection Pooling . Connection pooling is not supported for Callback Events.

44 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

2. Click Finish.

Now, you can generate inbound event polling support.

Generating inbound event polling support:

Event polling refers to an adapter’s capability to poll the event records from the event store at regular intervals. In each poll call, a number of events are processed by the adapter.

Review the information on inbound adapter classes and the information on inbound event polling support in Generating an IBM WebSphere Resource Adapter.

When you choose to generate inbound adapter classes for event polling support, the wizard creates code for the methods that must be implemented to produce a resource adapter that can send polling events from an EIS to a business process.

1. Click the Generate Inbound Adapter check box and then click on the Event

Polling Support check box in the right pane.

WebSphere Adapter development overview 45

2. When you are finished choosing generation options, click Finish.

Now, you can generate inbound callback event classes.

Generating inbound callback event support:

Inbound callback event support alerts business processes to changes in, or new information about, an EIS. The phrase callback refers to the ability of the EIS system to directly notify the adapter or business processes of a change, as opposed to the polling mechanism used in event notification.

Review the information on inbound adapter classes and the information on inbound callback event support in Inbound callback event notification.

When you choose to generate inbound adapter classes for callback event support, the wizard creates code for the methods that must be implemented to produce a resource adapter that can send callback events from an EIS to a business process.

1. Click the Generate Inbound Adapter classes check box and then click on the

Callback Event Support check box in the right pane.

46 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

2. When you are finished choosing generation options, click Finish.

Now you can generate enterprise metadata discovery classes.

Generating enterprise metadata discovery classes

The enterprise metadata discovery classes are used by the external service discovery tool in WebSphere Integration Developer to introspect an EIS to create business objects and other artifacts.

Review the information on enterprise metadata discovery classes in Generating an IBM WebSphere Resource Adapter.

When you choose to generate enterprise metadata discovery classes, the wizard generates code for the methods needed to produce a service that you can use to glean business object structure and other data from an EIS.

1. Click the Generate Enterprise Metadata Discovery classes check box.

WebSphere Adapter development overview 47

2. When you are finished choosing generation options, click Finish.

Generate data binding classes.

Generating data binding classes

You can generate data binding classes separate from the data binding classes that are generated from enterprise metadata discovery.

Review the section on data binding classes in Generating an IBM WebSphere Resource Adapter.

When you choose to generate data binding classes, the wizard generates code for the methods needed to marshall data from SDO to CCI record and from CCI record to SDO.

1. Click the Generate Data Binding classes for SCA check box.

48 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

2. When you are finished choosing generation options, click Finish.

Learn how to generate a JCA resource adapter.

Generating a JCA resource adapter

You use the wizard to generate adapter classes that correspond to the properties and options you specify.

The following sections describe the J2EE resource adapter classes.

Outbound JCA resource adapter classes

Generating outbound JCA resource adapter classes creates code for the methods that must be implemented to produce a JCA resource adapter that can send business events to an EIS. The list of JCA 1.5 interfaces that are implemented in your Connector Project when you choose to generate outbound adapter classes is as follows outbound JCA adapter classes:

v ConnectionFactory implements javax.resource.cci.ConnectionFactory

v Connection implements javax.resource.cci.Connection

v ConnectionMetaData implements javax.resource.cci.ConnectionMetaData

v ConnectionRequestInfo implements javax.resource.cci.ConnectionRequestInfo

v ConnectionSpec implements javax.resource.cci.ConnectionSpec

v Interaction implements javax.resource.cci.Interaction

v InteractionSpec implements javax.resource.cci.InteractionSpec

v LocalTransaction implements javax.resource.cci.LocalTransaction

WebSphere Adapter development overview 49

v ManagedConnectionFactory implements

javax.resource.spi.ResourceAdapterAssociation, javax.ValidatingManagedConnectionFactory, ManagedConnectionFactory

v MangedConnection implements

javax.resource.spi.DissasociatableManagedConnection, ManagedConnection

v ManagedConnectionMetaData implements ManagedConnectionMetaData

For information on how to generate outbound JCA resource adapter classes, see Generating outbound JCA adapter classes.

Inbound JCA resource adapter classes

Generating inbound JCA resource adapter classes creates code for the methods that must be implemented to produce a resource adapter that can send events from an EIS to a business process. The list of JCA 1.5 interface classes that are implemented in your Connector Project when you choose to generate inbound adapter classes is as follows:

v ActivationSpec Implements javax.resource.spi.ActivationSpec

For information on how to generate inbound JCA resource adapter classes, see Generating inbound JCA adapter classes.

JCA Enterprise Metadata Discovery classes

Generating enterprise metadata discovery classes creates code for the methods needed to produce a service that you can use to glean business object structure and other data from an EIS. The wizard also generates a discovery-service.xml file.

The list of JCA interfaces that are implemented in your Connector Project when you choose to generate enterprise metadata discovery classes is as follows:

v DataBindingDescription implements

commonj.connector.description.DataBindingDescription

v DataBindingGenerator implements

commonj.connector.description.DataBindingGenerator

v DataDescription implements commonj.connector.description.DataDescription

v DataFile implements commonj.connector.description.DataFile

v FunctionDescription implements

commonj.connector.description.FunctionDescription

v InboundFunctionDescription implements

commonj.connector.description.InboundFunctionDescription

v InboundServiceDescription implements

commonj.connector.description.InboundServiceDescription

v OutboundFunctionDescription implements

commonj.connector.description.OutboundFunctionDescription

v OutboundServiceDescription implements

commonj.connector.description.OutboundServiceDescription

v SchemaDefinition implements commonj.connector.SchemaDefinition

v ServiceDescription implements

commonj.connector.description.ServiceDescription

v AdapterType implements commonj.connector.discovery.AdapterType

v AdapterTypeSummary implements

commonj.connector.discovery.AdapterTypeSummary

50 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

v EditableType implements commonj.connector.discoveryEditableType

v MetadataDiscovery implements

commonj.connector.discovery.MetadataDiscovery

v MetadataEdit implements commonj.connector.discovery.MetadataEdit

v MetadataImportConfiguration implements

commonj.connector.discovery.MetadataImportConfiguration

v MetadataObject implements commonj.connector.discovery.MetadataObject

v MetadataObjectIterator implements

commonj.connector.discovery.MetadataObjectIterator

v MetadataObjectResponse implements

commonj.connector.discovery.MetadataObjectResponse

v MetadataSelection implements commonj.connector.discovery.MetadataSelection

v MetadataTree implements commonj.connector.discovery.MetadataTree

v ConnectionConfiguration implements

commonj.connector.discovery.ConnectionConfiguration

v ConnectionPersistence implements

commonj.connector.discovery.ConnectionPersistence

v ConnectionType implements commonj.connector.discovery.ConnectionType

v InboundConnectionConfiguration implements

commonj.connector.discovery.InboundConnectionConfiguration

v InboundConnectionType implements

javax.resource.emd.discovery.InboundConnectionType

v MetadataConnection implements

commonj.connector.discovery.MetadataConnection

v OutboundConnectionConfiguration implements

commonj.connector.discovery.OutboundConnectionConfiguration

v OutboundConnectionType implements

commonj.connector.discovery.OutboundConnectionType

v Action implements commonj.connector.discovery.Action

v ObjectWizard implements commonj.connector.discovery.ObjectWizard

v ObjectWizardStatus implements

commonj.connector.discovery.ObjectWizardStatus

v ObjectWizardStep implements commonj.connector.discovery.ObjectWizardStep

v Operation implements commonj.connector.discovery.Operation

v OperationType implements commonj.connector.discovery.OperationType

v DataBinding implements javax.resource.runtime.DataBinding

v FunctionSelector implements javax.resource.runtime.FunctionSelector

v InboundListener implements javax.resource.runtime.InboundListener

v InboundNativeDataRecord implements

javax.resource.runtime.InboundNativeDataRecord

v RecordDataBindingImpl implements javax.resource.runtime.RecordDataBinding

v RecordHolderDataBinding implements

javax.resource.runtime.RecordHolderDataBinding

v PropertyDescriptor implements javax.resource.runtime.PropertyDescriptor

v PropertyType implements javax.resource.runtime.PropertyType

v Property implements javax.resource.runtime.Property and

javax.resource.runtime.PropertyDescriptor

v SingleTypedProperty

WebSphere Adapter development overview 51

implements javax.resource.runtime.SingleTypedProperty and javax.resource.runtime.PropertyDescriptor

v SingleValuedProperty implements javax.resource.runtime.SingleValedProperty

and javax.resource.runtime.PropertyDescriptor

v PropertyGroup implements javax.resource.runtime.PropertyGroup and

javax.resource.runtime.PropertyDescriptor

v MultiValuedProperty implements

javax.resource.runtime.MultiValuedPropertyProperty and javax.resource.runtime.PropertyDescriptor

v BoundedMultiValuedProperty implements

javax.resource.runtime.BoundedMultiValuedProperty and javax.resource.runtime.PropertyDescriptor

v NodeProperty implements javax.resource.runtime.NodeProperty and

javax.resource.runtime.PropertyDescriptor

v TreeProperty implements javax.resource.runtime.TreeProperty and

javax.resource.runtime.PropertyDescriptor

v TableProperty implements javax.resource.runtime.TableProperty and

javax.resource.runtime.PropertyDescriptor

For information on how to generate Enterprise Metadata Discovery classes, see Generating JCA Enterprise Metadata Discovery classes.

Note: If you select the IBM WebSphere Adapter Foundation Classes Support feature check box in the Project Facets screen, then the created J2EE resource adapter project automatically includes the IBM WebSphere Adapter Foundation Classes library in the project libraries list of the Java Build path.

Generating outbound JCA adapter classes

The outbound adapter classes are responsible for notifying an EIS of outbound events from a business process.

Review the section on outbound JCA resource adapter classes in Generating a JCA resource adapter.

When you choose to generate outbound adapter classes, the wizard creates code for the methods that must be implemented to produce a resource adapter that can send business events to an EIS.

1. Click the Generate Outbound Adapter Classes check box.

52 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

2. When you are finished choosing generation options, click Finish.

Generate inbound JCA adapter classes.

Generating inbound JCA adapter classes

The inbound adapter classes are responsible for notifying a business process of an inbound event from the EIS.

Review the section on inbound JCA resource adapter classes in Generating a JCA resource adapter.

1. Click the Generate Inbound Adapter classes check box.

WebSphere Adapter development overview 53

2. When you are finished choosing generation options, click Finish.

Generate JCA enterprise metadata discovery classes.

Generating JCA enterprise metadata discovery classes

The enterprise metadata discovery classes are used by the external service discovery tool in WebSphere Integration Developer to introspect an EIS to create business objects and other artifacts.

Review the section on JCA enterprise metadata discovery classes in Generating a JCA resource adapter

Note: When you generate JCA enterprise metadata discovery classes, the wizard adds a prefix to each. The prefix is the Class Name Prefix that you entered when specifying properties on the Resource adapter properties page of the wizard.

1. Click the Generate Enterprise Metadata Discovery classes check box.

54 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

2. When you are finished choosing generation options, click Finish.

Generated code and deployment descriptor

The generated artifacts reflect the adapter classes with the properties and options you specified.

After you specify options for your resource adapter, the wizard generates code and a deployment descriptor in a Connector Project and then switches to the J2EE perspective in the workspace. The wizard then automatically launches the Resource Adapter Deployment Descriptor editor.

For a complete description of the editor, see the “Resource Adapter Deployment Descriptor Editor overview” on page 10.

WebSphere Adapter development overview 55

Using the Resource Adapter Deployment Descriptor editor

The Resource Adapter Deployment Descriptor editor provides an easy and convenient way to configure your resource adapter.

Resource Adapter Deployment Descriptor editor

You configure the resource adapter by using a deployment descriptor. The deployment descriptor—the ra.xml file— is generated by the wizard and included in your Java Connector Project.

The editor is made up multiple pages each of which represents a major section of the ra.xml file. Changes made in the editor are saved directly to the ra.xml file in your Java Connector Project.

The editor allows you to display and modify all elements of the ra.xml file. You can also add properties. After each modification this file is validated against its schema definition to ensure its validity.

Any validation problems with the ra.xml file are displayed in the Problems view of the development environment.

Displaying the deployment descriptor

Once you complete the New Connector Project wizard your workspace is switched to the J2EE perspective and your deployment descriptor displays using the Resource Adapter Deployment Descriptor editor.

Displaying the deployment descriptor in the editor provides you with several different views.

56 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

Deployment descriptor Overview pane

Alternatively, you can view the deployment descriptor in the editor by highlighting the file in the Project Explorer and selecting Open With → Deployment Descriptor Editor from the context menu.

Displaying the descriptor editor from the context menu

You can display each of the four views by using the tabs at the bottom of the Overview pane, which is the default view.

Descriptor editor tabs

WebSphere Adapter development overview 57

Using the Overview pane

The Overview pane provides access to general information about your resource adapter. You can display it at any time by clicking the Overview tab at the bottom of this pane.

In addition to providing general information about your resource adapter, you can generate components that you may not have originally specified when working with the wizard.

Overview pane

The General Information section summarizes general information about the resource adapter.

The License Information section allows you to specify and display license descriptions and requirements, if any, for the resource adapter.

The Components section provides navigation links to other panes of the editor.

The Component Addition section allows you to generate components that you may not have originally specified when working with the wizard. Click the Add to display the Add Component dialog box. Only those options not previously generated will be enabled for you to select.

Note: To display the Add button for Add Component, maximize the Overview pane. The Add button does not display when this pane is minimized.

58 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

Add component dialog

The Icons section of the overview pane allows you to associate icons with the resource adapter. You can specify a large or small icon in jpg or gif format. To fit into the allotted area, the large icons must be 32 x 32 pixels and the small icon 16 x 16 pixels. WebSphere Process Server does not make use of these icons.

Using the Resource Adapter pane

The Resource Adapter pane displays information that is stored in the <resourceadapter> element of the ra.xml file.

You can navigate to this pane by clicking ResourceAdapter in the Components section of the Overview pane or by clicking the ResourceAdapter tab at the bottom of the pane.

The sections of the Resource Adapter pane are described below.

WebSphere Adapter development overview 59

Resource adapter pane

The General Information section allows you to specify deployment descriptor values for the entire resource adapter. This section displays the name of the ResourceAdapter class with which this deployment descriptor is associated. This class must directly or indirectly implement the javax.resource.spi.ResourceAdapter interface.

The Components section provides navigation links to other parts of the editor. The Resource Adapter pane displays links to the Outbound Adapter and Inbound Adapter panes.

The Config Properties section allows you to specify resource-adapter-level configuration properties. By default, all configuration properties inherited by the class specified in the Resource Adapter Classname field in the General Information section are shown here. You can specify default values for these inherited properties. In addition, you can add or delete your own user-defined configuration properties using the Add and Remove buttons on the left side of the editor. You can also edit these properties using the widgets on the right side of the editor.

60 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

Add Config property dialog

When you add, modify, or delete user-defined properties in this section, the editor creates (or removes) the corresponding Java bean properties in your code. For more information, see Modifying properties.

The Admin Objects section allows you to specify administered objects for this resource adapter and configure their properties. You can add, update, or delete administered objects and specify properties for each object. The information you specify here will be stored at the resource adapter level of the deployment descriptor.

The Security Permissions section allows you to specify application server permissions. These are the permissions required by the resource adapter to execute within the application server. You can add, update, or delete security permissions. The information you specify here will be stored at the resource adapter level of the deployment descriptor.

Using the Outbound Adapter pane

The Outbound Adapter pane displays information that is stored in the <outboundresourceadapter> element of the ra.xml.

You can navigate to this pane by clicking OutboundResourceAdapter in the Components section of the Overview pane or by clicking the Outbound Adapter tab at the bottom of the pane.

WebSphere Adapter development overview 61

The sections of the Outbound Adapter pane are described below.

Outbound resource adapter pane

The General Information section allows you to specify deployment descriptor values associated with the outbound resource adapter. You can specify the level of transaction support, if any, and whether reauthentication is supported.

The Connection Definitions section allows you to specify an outbound connection definition. This connection definition is used by the application server to obtain a physical connection to the EIS. Clicking the Add button under the Connection Definitions list on the left side of the editor displays the following dialog box, which allows you to specify all required connection definition information.

62 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

Add Connection Definition dialog

A Connection Definition requires the following information:

v ConnectionFactory Interface

v ConnecitonFactory Implementaion Class

v Connection Interface

v Connection Implementation Class

v ConnectionRequestInfo Class

v ManagedConnectionFactory Class

Once a connection definition is defined all properties inherited by the specified ManangedConnectionFactory are shown in the properties list directly under the ManagedConnectionFactory Class. You can specify default values and descriptions for these inherited properties. In addition, you can add, update or delete your own user-defined configuration properties using the Add, Edit, and Remove buttons on the right side of the editor.

WebSphere Adapter development overview 63

Add Config property dialog

The Authentication Mechanisms section allows you to specify the authentication mechanism(s) supported by the resource adapter.

Using the Inbound Adapter pane

The Inbound Adapter pane displays information that is stored in the <inbound-resourceadapter> element of the ra.xml file.

You can navigate to this pane by clicking InboundResourceAdapter in the Components section of the Overview pane or by clicking the Inbound Adapter tab at the bottom of the pane.

The Inbound Adapter pane contains a Message Listeners section.

Inbound Resource Adapter pane

The Message Listeners section allows you to specify message listeners for inbound event processing. You must specify a MessageListener type and an Activation Spec

64 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

class. Clicking the Add button under the list of Message Listeners on the left side of the editor displays the following dialog box.

Add Message Listener dialog

Once a message listener is defined all properties inherited by the specified ActivationSpecWithXid are shown in the properties list directly under the ActivationSpecWithXid Class.

You can specify default values and descriptions for these inherited properties. In addition, you can add, update, or delete your own user-defined configuration properties using the Add, Edit,orRemove buttons on the right side of the editor.

WebSphere Adapter development overview 65

Add Required Config Property dialog

Modifying deployment descriptor properties

When you modify configuration properties, the Resource Adapter Deployment Descriptor automatically updates source code with corresponding JavaBean properties.

When you define configuration properties, you typically must also add them to the source code as JavaBean properties. The Resource Adapter Deployment Descriptor performs this and other tasks automatically:

v When you add a property using the editor, the editor adds the appropriate field

and accessor methods to the Java code for you.

v When you delete a property, the editor removes the field and accessor methods

for you.

v When you modify the type of a property, the editor adjusts the field and

accessor methods accordingly.

Note: Removing or modifying properties may cause compile errors in your code that you must resolve.

66 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

Generated bean properties

The editor maps resource adapter properties to class code. When you modify the resource adapter, the editor performs automatic source code updates.

The table shows the generated code affected when you add, delete, or modify a configuration property:

Class code affected by configuration property change

Configuration property Affected class code

Config Property (Resource adapter panel) ResourceAdapter

Connection Definition Property (Outbound adapter panel)

Message Listener Property (Inbound adapter panel)

ManagedConnectionFactory ConnectionRequestInfo

ActivationSpecWithXid

Editing deployment descriptor source

You can view and edit your adapter’s deployment descriptor directly.

Although the Resource Adapter Deployment Descriptor editor provides a fully functional and convenient method for viewing and editing the deployment descriptor, you may find it useful to view or edit the ra.xml file directly. The steps to do this are as follows:

1. Make sure that the ra.xml file is not currently displayed in the editor.

You cannot open the file if it is already open in the editor.

2. From the Project Explorer pane, select the Deployment Descriptor: Connector

<your connector name> file.

3. Right click and choose Open With → XML Source Page Editor

The XML Source Page Editor displays the ra.xml file.

WebSphere Adapter development overview 67

You can now view or modify the raw ra.xml file using the default editor provided by WebSphere Integration Developer. When you use this editor to save this file, the file is automatically validated against the Resource Adapter XML Schema Definition (or .xsd) file. Any errors are displayed in the Problems pane.

Important: When using the Resource Adapter Deployment Descriptor editor provided by the WebSphere Adapter Toolkit, you can open valid deployment descriptors only. If you attempt to open a deployment descriptor that is not valid (as defined by the schema), the XML Source Page Editor displays the file so that you can fix the problem before attempting to open it in the Resource Adapter Deployment Descriptor editor.

Implementing code from the IBM WebSphere Adapter Toolkit

Foundation Classes implementation overview

To develop a WebSphere resource adapter, you identify the JCA classes for your project, generate subclasses of all the corresponding Foundation Classes, and then modify or override methods as described in the individual class subsections. Subclasses that override methods in the Foundation Classes should invoke the super method so that generic logic is still invoked (unless explicitly indicated otherwise).

The steps shown below provide an overview of how to build an adapter from the Foundation Classes. Note that these steps focus on the major classes to extend. In some cases, you must provide yet another JCA interface implementation to extend a class; when this occurs, locate the appropriate Adapter Foundation class and extend it for your purposes. Typically this requires minor changes only.

1. Decide which configuration properties you need for the resource adapter to

support the enterprise information system (EIS):

a. Identify configuration properties for connecting to the EIS instance for

outbound processing (for example, hostname, port).

68 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

b. Identify configuration properties suitable for use by a client for a specific

outbound connection instance (for example, username, password, language).

c. Identify configuration properties for inbound event processing in

general–this will probably be a combination of those you’ve defined in 1a and 1b for outbound.

d. Establish a list of remaining adapter configuration properties–those not

related or relevant to inbound or outbound configurations.

2. Extend class WBIResourceAdapter and provide accessor methods for

configuration properties defined in 1d. Add these same properties to the resource adapter deployment descriptor.

3. If the resource adapter supports inbound event processing through the event

manager Quality of Service (QoS) as described later in this user guide, modify your WBIResourceAdapter subclass to implement interface WBIPollableResourceAdapterWithXid and provide an implementation of interface EventStore. If you defined additional inbound properties in 1c, beyond what is already defined for class WBIActivationSpec, extend WBIActivationSpecWithXid and update your deployment descriptor to reflect this new subclass class under the supported activation specs.

4. Extend class WBIManagedConnectionFactory and add accessor methods for any

properties defined in 1A. Add these same properties to the resource adapter deployment descriptor.

5. Extend classes WBIConnection and WBIInteraction. In your WBIInteraction

subclass, provide logic for processing requests (create, retrieve, update, and delete operations). In your WBIConnection subclass, simply provide the ability to generate a new WBIInteraction instance.

6. Extend WBIStructuredRecord and implement the getNext() and extract()

methods. If the adapter is intended to be used in an SCA environment, implement data bindings.

7. Extend class WBIManagedConnection and provide logic to physically connect and

disconnect to the EIS. In the getConnection methods, simply return the WBIConnection subclass created above.

8. If you defined additional connection-specific properties in 1b beyond what is

already defined in classes WBIConnectionRequestInfo and WBIConnectionRequest extend both and add these properties.

See the Adapter Foundation Classes Javadoc for the complete descriptions of the classes.

Data model

In any system where heterogeneous components exchange data, a common data model or object format is crucial. With a common data model, system components know what to send and what to expect in return.

For Websphere Process Server and Websphere Enterprise Service Bus, this data model is called a business object. The adapters handle data internally, in a format-independent manner, using the Data Exchange Service Provider Interface (DESPI). In the WebSphere Process Server and WebSphere Enterprise Service Bus environment, a data binding produces and consumes the business objects, and communicates with the adapter using the Data Exchange SPI.

The JCA 1.5 specification defines an optional CCI Record model.

The business object data model provides for the following:

WebSphere Adapter development overview 69

v A full, working implementation, as opposed to the CCI Record model that

simply defines interfaces that must be implemented by the adapter developer.

v A built-in support for tracking changes at both the object and property levels,

which allows for improved efficiency in processing and reduced bandwidth requirements for exchanging data.

v The business object data model is based upon the open-standard service data

object (SDO) model that is supported by IBM and others (visit www.eclipse.org for more information).

v The business object data model aligns well with the larger WebSphere

service-oriented architecture (SOA) strategy which, going forward, will better enable interpretability with other WebSphere-based applications.

Relationship of business objects to service data objects

At the technical level, the WebSphere business object model maps directly to the service data object (SDO) model: a WebSphere business graph and business object correspond to an SDO data graph and data object.

A business graph is a top-level structure that defines a single child business object which can itself contain zero or more child business objects.

Using a business graph optional. Use it to provide a change summary for applying a delta updates to hold metadata about its child business objects.

Business graph

After-images versus deltas

Two distinct types of business objects, after-image and delta, are used to convey different kinds of information.

After-Image business objects can be thought of as a snapshot of the data in time; they reflect how the EIS entity looks (for inbound events) or is expected to look (for outbound requests). An after-image business object should represent the entire entity structure in the EIS. For example, if an ORDER object with UPDATE verb is sent to the adapter, and the order has two ORDER_LINE children, the object in the EIS should be modified to reflect the input; if the EIS’s representation of that object had only one ORDER_LINE, it will have two after the processing has completed.

Delta business objects reflect the specific changes that have occurred (for inbound events) or that the user wants affected (for outbound requests) in the EIS. Each business object contains a changeSummary structure that can store all the pending

70 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

changes. For outbound requests, the adapter must interpret the change summary, making all applicable changes to the data. For example, if an ORDER_LINE has been added to an ORDER object, the ORDER_LINE will appear as Created in the change summary. The adapter is responsible for finding that ORDER, and adding the ORDER_LINE to it.

Verbs

A verb is a property of a business graph.

If the data object being processed by the adapter has no business graph, there will be no verb.

The AppplyChanges function, when passed a business graph, can perform either an afterimage function or a delta update. If the verb is populated, the adapter will perform the operation indicated by the verb. If no verb is present, the change summary will be used to perform a delta update.

When encountering a delta business object, a component can introspect the change summary to determine what actually occurred.

Verbs versus operations

Verbs and operations are similar conceptually but serve different purposes. Operations reflect the functions that an adapter can perform. An operation is directly related to the adapter performing it. By contrast, a verb is directly related to the business object in which it is specified. In general, the verb defined for a business object should match the operation but not always; some operations are unrelated to the verb.

An example helps illustrate the difference between verbs and operations. If you wanted to create a new entity in the EIS using an after-image business object, you would specify an object verb of Create. Accordingly, a Create operation would invoke the adapter. If you invoke an adapter Delete operation with an object that had a Create verb, the adapter would report an error.

However, some operations, specifically those that do not fall under Create, Update, or Delete, do not require verbs. For example, the Retrieve operation of adapters, which has the adapter query the EIS to find an entity that matches the business object, does not expect a verb. This Retrieve operation is unconcerned with what action lead to the business object being created (the information reflected by the verb); rather it is concerned only with retrieving an EIS entity that is reflected by the object.

Note: The only time verbs are part of adapter processing is when the object has a business graph, and the function used is applyChanges. In that case, and only that case, the verb dictates the processing to be performed by adapter.

Business object standards

Business object naming:

EIS object names are extracted during the metadata import process. These names often must be modified for use with a resource adapter. Business object names, such as Customer or Address, must reflect the data structures they represent and follow a camel case initial capitalization format.

WebSphere Adapter development overview 71

Convert business object names from EIS-assigned formats to a camel case format (remove separators such as spaces or underscores and capitalize first letter of each word). For example, convert the EIS name, ORDER_LINE_ITEM, to OrderLineItem.

As described in the WebSphere business object specification, name the parent business object graph for the contained business object followed by BG. For example, CustomerBG is the parent object graph for a Customer business object.

Business objects names as well as property names should have no semantic value to the adapter. When you develop your adapter logic, be sure that it is based on metadata as opposed to naming conventions.

Standard operations:

As described by the JCA specification, a resource adapter is generally intended to expose low-level, EIS-specific operations. These EIS-specific operations range from create, retrieve, update, and delete (for database-type applications) to those that are unique to customer EIS instances (for function-based adapters such as SAP).

The WebSphere business object model and a variety of WebSphere components (such as the relationship management service) assume that most adapters support a set of standard create, retrieve, update, and delete operations. This leaves a gap for most adapters where the supported low-level operations do not natively meet the expectations of other WebSphere components. To fill this gap, all adapters should support higher-level create, retrieve, update, and delete operations, depending on what is provided by the EIS. With such support, a Create operation for one adapter follows the same naming conventions and behavior as a Create operation for another adapter. The result is better tooling and consistency in terms of user experience.

The following are the supported, standard top-level operations:

Supported standard top-level operations

Inbound Operation Signatures Notes

emitCreateAfterImage<BOType> emitUpdateAfterImage<BOType> emitDeleteAfterImage<BOType>

emitDelta<BOType> This operation should generate a delta

These operations should generate after-image business objects with verbs that match the operation signature; for example, emitCreateAfterImageCustomer should generate a Customer object with verb Create.

business object with a summary depicting the changes that occurred in the EIS.

72 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

Outbound Operation Signatures Notes

applyChanges<BOType> create<BOType> update<BOType> delete<BOType>

retrieve<BOType> Retrieve one object based on key values.

retrieveAll<BOType> Retrieve multiple objects that match some

These operations can handle delta or after-image business objects. The assumption is that the adapter can consume either type of object or, if not, can convert after-image and delta as required by the business object structure.

For applyChanges, the adapter determines the operation (create, update, or delete) based on the top-level verb or the change summary.

applyChanges allows users to easily pass any create, update, or delete business objects.

The create, applyUpdate and delete operations are specific to one operation. Note that applyChanges, for after-images, should invoke the appropriate <x> operation.

Exceptions: If the adapter cannot support delta for a given business object type (because it lacks retrieve capability to convert), a signature of applyAfterImage<BOType> may be substituted.

user-defined predicate; this is a query option intended to replace RetrieveByContent.

RetrieveAll should always return a top-level container with 0..n matching child business objects. It should never return a single top-level matching business object as with the Retrieve operation.

Standard processing logic:

Each adapter should enable operations that are supported by the EIS.

General guidelines for operations with adapters include the following

v All operations should be atomic: if an operation fails for any reason, the adapter

should roll back any partial changes made to the EIS as part of the request.

v For all operations, adapters should never modify the input business object

passed by the client (per JCA standards). Instead, if the operation requires the same object passed as input to be returned as output, use WebSphere Business Integration utilities to create, modify, and return a deep copy of the input object.

v If child objects are included in the input business object, the order of child

objects should be maintained in the output business object. Doing so enables relationship management service support.

v If an after-image is passed to the adapter as input, an after-image should be

returned as output. The same applies for deltas.

WebSphere Adapter development overview 73

v Adapters should follow strict conventions in processing business objects. This

includes failing if an entity is marked as updated in the input business object but does not exist in the EIS (rather than attempting to create the entity in the EIS).

isSet property:

WebSphere business objects support an isSet property.

isSet property

The isSet() API of the DESPI InputAccessor determines if a given business object property has been set. When isSet() is false the adapters should ignore the specific attribute while processing the request.

Strict interpretation of requests:

An adapter should always fail if the user provides data that is inconsistent with either the behavior of the adapter or the state of the EIS. This requires more effort from maps or users to ensure that data is appropriate before exposing it to an adapter. That effort also reduces the chance of miscommunication (that is, that the adapter will do something unintended).

If an adapter receives a request in which a business object is marked as created but, in fact, an entity already exists in the EIS with the given key values, the adapter should fail immediately.

Some WebSphere Adapters have historically made a best effort and defaulted to an update in such cases. Such adapters attempted to interpret the request and make every effort to complete it.

ApplyChanges operation:

The applyChanges operation is a catch-all operation that enables users to send any create, update, or delete business object to the resource adapter for processing based on the verb.

The applyChanges operation saves effort and simplifies mapping with simple logic: for after-image business objects, the applyChanges operation should look at top-level verb in the business object and then call create, update or delete as appropriate; when applyChanges is invoked without a verb, this is a delta operation. The adapter should read the SDO change summary and perform all the changes indicated in the change summary.

After-image Create operation:

The after-image Create operation generates a new entity in the EIS that matches the data and structure of the input business object. The business object returned by this operation should accurately reflect the newly created entity in the EIS.

Processing overview

The processing of the after-image create operation, which starts at the top-level business object, is as follows:

1. Create an entity in the EIS corresponding to the type of the input business

object

74 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

2. If the EIS does not generate its own primary key (or keys), insert the key

values from the input business object into the appropriate key column (or columns) of the EIS entity.

3. Update the output business object to reflect the values of the newly created EIS

entity; this includes any EIS-generated key values or properties marked as having potential side-effects (see property-level metadata).

4. Recursively create the EIS entities corresponding to the first-level child business

objects, and continue recursively creating all child business objects at all subsequent levels in the business object hierarchy.

Operation return value

The output written to the output cursor should contain any newly-created key values and other side effects.

Error handling

The DuplicateRecordException exception is thrown if the EIS already contains an entity with the same key values as a business object to be created.

The InvalidRequestException exception is thrown if any of the following inputs to the operation ate not supported:

v If key values are specified in the input business object but the EIS supports

auto-creation only

v If key values are not specified in the input business object but the EIS requires

them

v If the top-level verb, if provided, is not Create (assertion optional)

The EISSystemException exception is thrown if the EIS reports any unrecoverable errors.

After-image Update operation:

The after-image update operation modifies an EIS entity so that it and its child objects match the data and structure of the input business object. It requires an explicit comparison of the input business object to the EIS system.

Processing overview

After-image update processing is as follows:after-image Update

v Compare the existing business object in the EIS with the input business object

and create, update, or delete entities to match the input as follows:

– If child entities exist in the application, they are modified as needed.

– Any child business objects contained in the hierarchical business object that

do not have corresponding entities in the EIS are added to the EIS.

– Any child entities that exist in the EIS but are not contained in the business

object are deleted from the application.

v Update the output business object to reflect the modified EIS entities; this

includes any EIS-generated key values or properties marked as having potential side-effects (see property-level metadata).

WebSphere Adapter development overview 75

Operation return value

Note: When writing the output values to the output cursor, be sure to include any

generated keys or other side effects.

Error handling

Error handling behavior includes any and all exceptions thrown by create and delete operations plus the following:

RecordNotFoundException is thrown if the EIS does not contain an entity with the same key values as the business object to be updated.

EISSystemException is thrown if the EIS reports any unrecoverable errors.

MissingDataException is thrown during adapter operations to indicate that not all

the necessary information has been provided as required.

InvalidRequestException is thrown during adapter operations during adapter operations to indicate poorly formatted data was provided.

After-image Delete operation:

The after-image Delete operation removes an existing entity and any contained child entities from the EIS.

Processing overview

The after-image Delete operation is processed as follows:

1. Perform a recursive retrieve on the input business object to obtain all data in

the EIS that is associated with the top-level business object.

2. Perform a recursive delete on the entities represented by the input business

object, starting from the lowest-level entities and ascending to the top-level entity; non-contained entities should be left intact although any relationships to deleted objects should be removed if explicitly defined in the EIS.

Note: Adapters should also delete any and all contained children whether or not they are reflected in the input business object. For example, if just a top-level business object is provided with keys and no children, the adapter should still check for contained children in the EIS and delete them.

Operation return value

Since the deletion of an entity in the EIS only requires a return that indicates the success (or failure) of the operation, the goal is to convey this with as little overhead as possible. The Delete operation might or might not return anything. The adapter should handle the case where the output record is initialized with the same metadata as the input cursor. In this case, it is not necessary to populate the output data on getNext, apart from the key information.

Error handling

The RecordNotFoundException exception is thrown if the EIS does not contain an entity with the same key values as the business object to be deleted.

76 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

The InvalidRequestException exception is thrown if input to the operation is not supported.

The EISSystemException exception is thrown if the EIS reports any unrecoverable errors.

Retrieve:

This operation rebuilds the complete business object hierarchy. The adapter ensures that the returned hierarchical business object matches exactly the database state of the application entity.

The Retrieve operation accepts either an after-image or delta business object. The comparison in either case will be by equality only. Non-key values are allowed as match criteria.

The request business object can contain any of the following:

v A top-level business object but no child objects, even though the business object

definition includes children.

v A business object that contains the top-level business object and some of its

defined children.

v A complete hierarchical business object containing all child business objects.

The difference between Retrieve and RetrieveAll is that Retrieve is intended to return a single, unique business object that meets user-defined criteria whereas RetrieveAll returns multiple matching business objects. For example, use Retrieve to find Customer where id=″abc123″ and RetrieveAll to find all Customers where state=″NY″.

Processing overview

Retrieve processing is as follows:

When the retrieve operation is invoked, it is preferable to retrieve the record information from the EIS and put it into the output structured record, where getNext() will populate that information into the output cursor. If it is not possible to retrieve the information from the EIS until getNext() is called, it is acceptable to perform the entire retrieve operation inside of the getNext() method.

Error handling

RecordNotFoundException is thrown if any populated properties in the input business object does not exist in the EIS.

MultipleMatchingRecordsException is thrown if more than one record match input criteria.

EISSystemException is thrown if the EIS reports any unrecoverable errors.

RetrieveAll:

RetrieveAll returns a batch of records that match the values provided in the request business object. The records are returned as a collection of business objects through a top-level container business object.

WebSphere Adapter development overview 77

CCI clients of resource adapters that support batch results must be capable of recognizing a top-level container and iterating through the child objects that represent the results of the query. The client can then extract any individual business object in the container and deliver it to the rest of the system as with any single business object. This obviously requires the creation of additional business object container structure definitions by the user or during metadata import for each business object type that the user intends to query in batch. The business object container is shown in the illustration.

Customer container BO

Customer

Business Object

Address

Business Object

Customer

Business Object

Address

Business Object

Business object container

This approach is favored over that of the JDBC-style ResultSet support as described in the JCA specification. However, if an EIS provides native ResultSet support or if it makes sense then adapter developers are encouraged to implement the CCI ResultSet interfaces to provide customers with a high-performance alternative to the generic batch retrieval approach described in this document.

The container object is produced by the data binding for use in the Websphere Process Server or Websphere Enterprise Service Bus environment. Internally, the adapter will model the multiple retrieved records as a list of top-level records that can be iterated over using the getNext() method of the output Record.

Note: The use of the operation name RetrieveAll rather than RetrieveByContent (as used by the WebSphere Business Integration adapters) distinguishes this operation as a new and clear standard. Support for RetrieveByContent was inconsistent across previous adapters: some would retrieve a single object and return special error codes if there were more objects that matched while other adapters would create special containers to return multiple values.

78 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

Note: The RetrieveAll operation always returns a result set regardless of how

many (if any) matches are found.

Processing overview

RetrieveAll processing is as follows:

RetrieveAll should make the adapter ready to return multiple objects. For each of the objects that will be returned, the ″getNext()″ method will be called. Each call to ″getNext″ should advance the cursor to the next top-level record.

Note: Adapters should check the property MaxRecords in the WBIInteractionSpec instance to determine the maximum number of records to return in order to avoid out-of-memory issues.

Operation return value

The adapter performs a query and retrieves a result set of all objects that match a given set of values. The output object is a container that holds an 0..n objects of the same type as the input object.

Error handling

RecordNotFoundException is thrown if any populated properties in the input business object do not exist in the EIS.

MatchesExceededLimitException is thrown if the number of hits in the EIS exceeds the value of MaxRecords as defined in the interaction specification. The property MatchCount will contain the actual number of hits that the adapter had in the EIS so that users can either increase their limit or refine their search appropriately.

EISSystemException is thrown if the EIS reports any unrecoverable errors.

Custom operations:

Adapters support custom operations that enable more robust means of interrogating or modifying the EIS. Custom operations include Execute (to execute a stored procedure or script) or Lock (to lock an entity in the EIS).

For custom operations, implementations should accept both after-image and delta business objects and simply use the values provided in the data portion of the business graph. For example, if a delta is provided without enough information to perform a custom request operation, the adapter should attempt to retrieve the necessary information from the EIS application when possible or throw an InvalidRequestException that expands missing data.

For custom operations, implementations can interpret the data coming in the input cursor in any way that is desirable. Be sure to throw the appropriate exceptions if the input data is insufficient.

Inbound event notification

When you enable inbound event-notification, business processes are alerted to changes in, or new information about, an EIS.

Inbound event notification complements outbound request processing, enabling adapters to provide bi-directional communication between business processes and

WebSphere Adapter development overview 79

EIS applications. Depending on the underlying EIS, the business events an adapter generates may span the set of changes that have occurred to a given entity in the EIS, such a customer changing the quantity in their order from 10 to 100, to a complete document or binary payload such as an insurance claim form submitted in XML.

Although each EIS application is unique, most adapters implement inbound event-notification in similar ways:

1. Create an event store in the target EIS to persist changes or other relevant event

data that is published by the adapter.

2. Implement an event detection mechanism in the EIS. This mechanism is

responsible for detecting any changes of interest (to the adapter) in the EIS and recording them in the event store.

3. Implement an event retrieval mechanism in the adapter that can detect and

retrieve events from the event store described in (1) above.

4. Implement a data transformation mechanism in the adapter to convert EIS

events to WebSphere business objects for use by target business processes.

Inbound event notification

Using the IBM WebSphere Foundation Classes for inbound event notification

Although not required, use of the IBM WebSphere Foundation Classes is strongly recommended for adapters that need to provide event notification.

Using the Foundation Classes can dramatically simplify the often complicated implementation of event retrieval and publication. The Foundation Classes can automatically track endpoints (the consumers of events) for the adapter, control the polling for and delivery of events, handle recovery of events if the adapter unexpectedly terminates, and assure once-and-only-once event delivery. This allows developers to provide greater quality of service (QoS) in less time and also ensure that behavior across adapters is consistent.

In order to employ the Foundation Classes for event-notification, the adapter and EIS application must meet requirements described in the following sections.

80 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

Event Store Requirements

1. Event data must be persistent. Once detected in the event store, an event

should remain available there until deleted by the adapter regardless of connection failure or time elapsed.

2. The event store must allow the adapter to both identify and change the state of

event records in the event store.

Adapter Requirements

To manage application-specific events, the Foundation Classes require that you provide application-specific logic, if any. To do this, you must:

1. Ensure that any subclass of com.ibm.j2ca.base.WBIResourceAdapter implements

interface com.ibm.j2ca.WBIPollableResourceAdapter. This interface allows the Foundation Classes to acquire an EventStore implementation that specifically reflects the EIS application.

2. Provide an implementation of the

com.ibm.j2ca.extensions.eventmanagement.EventStore interface. This interface allows the Foundation Classes to manage events in the store without requiring specific knowledge of how and where the event store is implemented.

3. Extend WBIActivationSpecForXid to include the base polling properties. There is an alternate ActivationSpec, called WBIActivationSpecForPooling, that

contains two additional properties; Minimum connections, and MaximumConnections. These properties are used by the event manager to establish a connection pool of EventStoreWithXid instances. Each instance of EventStoreWithXid is treated as a ″connection″.

If the user sets MaximumConnections to a value greater than 1, and the delivery type is set to a value other than ″ORDERED″, multiple threads will be used in delivery, and each delivery thread can potentially be assigned a discrete connection.

If you decide to use WBIActivationSpecForPooling, keep in mind that ″createEventStore″ can be called multiple times on your adapter, so be sure to handle this appropriately.

Application Requirements

In many cases–and even when your adapter does not implement the Foundation Classes–an application must also be configured or modified before the adapter can use the event-notification mechanism.

Modifications to the application might include setting up a user account in the application, creating an event store and event table in the application database, inserting stored procedures in the database, or setting up an inbox. If the application generates event records, you might need to configure their text. You might also need to configure the adapter to use the event-notification mechanism. For example, a system administrator might need to set adapter-specific configuration properties to the names of the event store and event table.

Assured once-and-once-only event delivery

XA transactions support once-and only-once event delivery.

Assured once-and only-once delivery is implemented with an XAResource. The XAResource keeps track of transaction IDs in the event table. The event table contains an XID (string) field. The adapter queries and updates that XID field.

WebSphere Adapter development overview 81

During recovery, WebSphere Application Server calls the resource adapter, queries it for XAResources, and then performs transaction recovery as follows:

v Transactions that the J2EE container rolls back have not been delivered and are

marked NEW.

v Transactions that the J2EE container commits have been delivered; these are

deleted.

Implementing an event store in the EIS

An event store is a persistent storage area in the EIS application where event records are saved until the adapter can process them. The event store might be a database table, application event queue, email inbox, or any type of persistent store. A persistent event store enables the application to detect and save event records for the adapter even when the adapter is not operational.

Note: Always consider performance implications and scalability when choosing where and how to implement an event store. For example, if you are building an adapter for a database application, an event store represented as a table in the database will most likely perform more efficiently than an event store implemented in an external event inbox.

Event records:

There are no hard and fast rules governing the structure or content of an event record in the event store. The goal is to provide enough information for the EventStore interface implementation to successfully generate a business object that represents the event.

Common event record fields

Field Description

Event Identifier (ID) A unique identifier for the event

Object Key The application-specific data that uniquely

identifies the entity that occasioned the event.

Business Object Name The type of the business object that maps to

the entity.

Verb The operation that triggered this event:

create, update, delete, and so on.

Timestamp The time at which the application generated

the event.

Status The status of the event. This is used by the

Foundation Classes to track which events are new, in process, or processed.

XID The transaction ID.

Event Identifier (ID)

Each event requires a unique identifier for tracking purposes. This identifier can be a number generated by the application or a number generated by a scheme that your adapter uses. The event might generate a sequential identifier, such as 00123, to which the adapter adds its name. In such an event ID numbering scheme, the resulting object event ID is MyAdapterName_00123. Another technique might

82 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

generate a timestamp to identify an event, producing an identifier such as MyAdapterName_06139833001005.

Object Key

Each event should contain enough key information to enable the adapter event-retrieval mechanism to locate and retrieve the full entity in the EIS for which this event was originally recorded. The structure and content of this key is up to you.

For reference, a key is typically comprised of easily-parsed values such as name-value pairs. For example, Customer_ID=123 or, for a composite key, Model=Widget;Color=CanaryYellow.

Business Object Name

Since the EIS entity identified in each event is converted to a business object instance, the type of the business object must either be specified or derivable at run time by the event-retrieval mechanism.

The most straightforward approach is to include the business object name value in the event record. Specifically, the business object graph type should be included; for example, CustomerBG or OrderBG.

Note: The namespace, which is also required for business object creation, need not be included in the event; the namespace is user-defined and should be retrieved by the adapter from the adapter ActivationSpecWithXid instance.

If, as an adapter developer, you choose to derive the business object graph type, you are strongly advised against mandating any specific EIS entity name to business object type mapping schemes. Business object properties and names are unreliable because they can be modified by users. To avoid such problems, adapters should always process business objects using metadata.

Verb

The verb should reflect the operation that this event represents. For example, if this event reflects the creation of an entity in the application, the verb would be Create. This value should be one of the standard verbs used by adapters (including Create, Retrieve, Update, Delete) and specified in the business object generated for the event. When properly specified in the business object, the verb allows consumers of the business object event to determine what action to take on the event.

Note: The default function selector implementation (WBIFunctionSelector) uses the verb passed in the event business object to determine the appropriate SCA EIS import operation. Be sure that verbs used here correspond to the operations defined by your adapter enterprise metatdata discovery implementation.

Timestamp

The Foundation classes use the timestamp to ensure proper ordering of events. For example, use of a timestamp prevents an event describing the deletion of an Order from being published before an event describing the creation of that same Order. The timestamp should provide detail sufficient to distinguish events occurring close in time.

WebSphere Adapter development overview 83

Status

The event status is used to track the state of an event. It allows the Foundation Classes to distinguish among events that are new from those in process or ineligible.

The adapter must support five different event status values as described in the table below. All events generated by the event detection mechanism in the EIS should be in the initial state of New. Only the Foundation Classes, through the EventStore.updateEventStatus method, change event status.

Possible Event Statuses

Event Status Description Foundation Class Constant

New The event is ready to be

processed.

In Progress The adapter is processing

this event. Note that an event in this state may or may not yet be delivered.

Processed The adapter successfully

processed and delivered the event.

Failed The adapter was unable to

process this event due to one or more problems.

Unsubscribed The adapter processed the

event but found no interested subscribers

NEWEVENT

INPROGRESS

PROCESSED

FAILED

UNSUBSCRIBED

XID

The XAResource uses this string field to track transaction IDs in the event table. The adapter queries and updates that XID field. During recovery, WebSphere Application Server calls the resource adapter, queries it for XAResources, and then performs transaction recovery based on the XID.

Event object:

An event object is an instance of the com.ibm.j2ca.extensions.eventmanagement.Event class as defined in the Foundation Classes. An event object is the common representation of an event in the Adapter Foundation Classes and it is populated from an event record in the getSpecificEvent(String eventId) method described in the Implementing the EventStore Interface section.

Event object fields

Field Description

eventID Corresponds to the Event Identifier field of

the event record

eventKeys Corresponds to the Object Key field of the

event record

84 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

Field Description

eventType Corresponds to the Business Object Name

field of the event record

timeStamp Corresponds to the Timestamp field of the

event record

eventStatus Corresponds to the Status field of the event

record

Event detection:

Events detection mechanisms reflect the sources that trigger them: user actions in the application, batch processes that add or modify application data, or database administrator actions.

When an event detection mechanism is set up in an application and an application event associated with a business object occurs, the application must detect the event and write it to the event store.

Event detection mechanisms are application dependent. Some applications provide an event detection mechanism for use by clients such as adapters. The event detection mechanism may include an event store and a prescribed way of inserting information about application changes into the event store. For example, one type of implementation uses an event message box that receives messages from the application when it processes an event of interest to the adapter. The adapter application-specific component periodically polls the message box for new event messages.

Other applications have no built-in event detection mechanism but have other ways of providing information when application entities change. If an application does not provide an event detection mechanism, you must use whatever mechanism is available to extract information on entity changes for the adapter. Among those mechanisms are database triggers, exit calls to programs that write to event stores, or extracting information from flat files that aggregate application changes.

In all cases, the event detection mechanism should ensure data integrity between an application event and the event record written to the event store. For example, the generation of an event record should not occur until all required data transactions for the event have completed successfully.

Steps Involved

In general, an application event detection mechanism should take the following steps:

1. Detect an event on an application entity.

2. Create an event record.

To create the record, the event detection mechanism should:

1. Generate a unique event identifier (ID).

2. Set the object key to the primary key of the application entity.

3. Set the verb to the action that occurred in the database.

4. Set the event timestamp.

WebSphere Adapter development overview 85

5. Set the name of the WebSphere business object complexType that corresponds

to this application entity

6. Set the event status to New.

Implementing event retrieval in the adapter

The careful work of implementing event retrieval in the adapter uses two Foundation Classes interfaces. The goals are setting up event polling and a safe, reliable connection to the event store.

Adapters that employ the Foundation Classes for event retrieval must meet the following requirements:

1. Implementing interface com.ibm.j2ca.base.WBIPollableResourceAdapterWithXid

in any WBIResourceAdapter subclass.

2. Implementing interface

com.ibm.j2ca.extensions.eventmanagement.EventStoreWithXid

The first requirement identifies (for the Foundation Classes) the adapter for event polling. If this interface is implemented, the Foundation Classes automatically begin checking for and publishing events as dictated by polling-related configuration properties such as PollPeriod and PollQuantity and as specified by active adapter endpoints.

The second requirement, implementation of the EventStoreWithXid interface, typically requires the most (adapter) development effort. As the location and structure of each event store is application-specific, the EventStoreWithXid interface provides the Foundation Classes with a common means of querying and modifying an event store.

Implementing an EventStore Interface

An EventStore implementation is responsible for establishing and managing a connection, if necessary, to the underlying EIS application. The EventStore implementation should be thread-safe because it will be accessed on multiple threads in Unordered delivery mode.

The table below describes the methods that each EventStore implementation must provide:

EventStore methods

Method Description

public void setEventTransactionID(Event event, XidImpl xid) throws ResourceException, CommException

public Xid[] getPendingTransactions() throws ResourceException, CommException

public Event getEventForXid(XidImpl xid) throws ResourceException, CommException

This method should store the xid in the Event table in the same row specified by event. xid.toString() will serialize the Xid for easy storage.

This method should return the XIDs for events that have an associated XID, but are still in NEWEVENT status.

This method should return the event associated with the given Xid.

86 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

Method Description

ArrayList getEvents(int quantity, int eventStatus, String[] typeFilter)

boolean implementsFiltering() This method provides the Foundation

Event getSpecificEvent(String eventId) This method should reconstruct a complete

Object getObjectForEvent(Event event) The EventStore implementation should

void deleteEvent(Event event) The EventStore implementation should

void updateEventStatus(Event event, int newstatus)

This method enables the adapter to determine if there are any new events available or old events that need re-sending. Implement this method to query the event store and return a list of event instances (up to the limit specified by thequantity parameter ) that have a status matching the value of parameter eventStatus. The order of events returned in ArrayList should reflect the sequence of events as intended for publication.

If this EventStore implementation supports filtering as specified by method implementsFiltering, this method should inspect the value of parameter typeFilter.If typeFilter is not null, the method should return events that match the type(s) specified only. If typeFilter is null (or filtering is not supported), the method should simply return events of all types.

Classes with information on the capability of the EventStore implementation. If it can filter events by type in method getEvents, the implementation should return true; otherwise it should return false.

event object for the event identifier. This will most likely require that the EventStore implementation query to retrieve the missing information from the event record in the EIS (for example, object type, status, and so on).

inspect the event passed and return a business object instance reflecting the changed entity in the EIS application. For example, if the event specifies an object type of CustomerBG and a key value of CustomerID=123, this method might be expected to return a CustomerBG instance populated with the values from customer 123 in the EIS.

delete the event record identified from the underlying EIS event store.

The EventStore implementation should modify the event record identified with the provided status code.

Transaction Support Methods

If the implementation of the event store supports transactions, the EventStore implementation should provide access to that transaction control using the following methods:

WebSphere Adapter development overview 87

EventStore transaction control methods

Method Description

boolean isTransactional() Is the event store transactional? If so, this

method should return true.

void commitWork() This method should commit the pending

transaction. It is required only if transactions are supported.

void rollbackWork() This method should rollback any

uncommitted work. It is required only if transactions are supported.

Possible event store implementations

An event store is usually implemented in a database, however, any structured persistence mechanism could be used

Implementing the event store with a database:

If an EIS application incorporates a database, you can use the database to store event information.

Where to store events

To locate the event store in the EIS application database, you must create a new, separate WebSphere event table there. The table then functions as the event store for event records. Each column of the table would reflect one of the fields mentioned in Table 1; each row would reflect a unique event.

Implementing event detection

If the application has no built-in method for detecting events and the database that the application is running on provides database triggers, you could implement row-level triggers to detect changes to application tables. When changes occur in one of these tables, the triggers would write new event records to the event table.

Note: If possible, avoid full table scans of existing application tables as a way of determining whether application tables have changed.

Retrieving events

The EventStore implementation would need to employ the available database APIs to gain access to the contents of the event table.

Event store implementation

88 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

Function selector:

Function selectors map resource adapter events to corresponding SCA export function names.

The WebSphere Adapter component that exposes resource adapters as SCA components requires what is known as a function selector. This selector maps events generated by resource adapters to a SCA export function name. For example, an adapter may generate an after-image Customer event with top-level verb Update, which the user expects to be published using the function emitCreateAfterImageCustomer.

public interface FunctionSelector {

public String generateFunctionName(Object[] argObjects) throws MetadataException;

}

The StructuredDataFunctionSelector class looks at metadata within the StructuredRecord to generate a function name. It will create a function name as follows ″emit[OperationName]AfterImage[RecordName]″, where OperationName is an operation stored in the record as the operationName property, and RecordName is the value stored in the recordName property.

For more information on the FunctionSelector interface, see the Metadata Discovery Specification.

For example, if the StructuredDataFunctionSelector received an event such as CustomerBG with TopLevelVerb Create and containing a business object of type Customer, the WBIFunctionSelector class would generate a function name such as emitCreateAfterImageCustomer. For the same business graph with no TopLevelVerb, the function name emitted might be emitDeltaCustomer.

Error handling for events:

Event error handling depends on the delivery type and the kind of endpoint involved.

If the endpoint throws an exception during delivery, the event manager will stop delivering events to that endpoint, and the timer task for polling stops. If the delivery type is ORDERED, the remaining events polled in that cycle are not delivered until the event with the error is processed. If the delivery type is UNORDERED, the event manager attempts to deliver the remaining events in the current poll cycle. When the endpoint is taken offline and reactivated, the event(s) in which the error occurred is re-delivered, and normal delivery of subsequent events resumes. If the endpoint is transactional and the transaction rolls back, the event manager responds as if the endpoint threw an exception.

If the implementation throws an exception during the getObjectForEvent call (for retrieval of the full event), the event manager marks the status of that event in the event table asERROR_PROCESSING_EVENT. If the delivery type is ORDERED, the polling task stops until the endpoint is reactivated. If the delivery type is UNORDERED, the polling task continues.

Inbound callback event notification

An EIS application’s capability to call the adapter directly, by registering a listener, is known as a callback. If your application supports the callback capability, you can make use of callback event notification support in the adapter foundation classes.

WebSphere Adapter development overview 89

When you enable inbound callback event notification, business processes are alerted to changes in, or new information about, an EIS. The phrase callback refers to the ability of the EIS system to directly notify the adapter or business processes of a change, as opposed to the polling mechanism used in event notification.

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

Generally, in a callback scenario, the adapter will need to setup event listeners to receive callback events from the EIS. Callback event processing could be either synchronous (REQUEST-RESPONSE) or asynchronous (ONE-WAY).

Request and response callback events

A request and response callback event is a synchronous operation in which the EIS sends a callback call to the adapter and waits for the adapter to respond to the call.

Since the EIS expects a response from the adapter, event delivery to multiple endpoints cannot be supported.

The following is an illustration of synchronous callback event processing.

EIS

Callback From EIS

Adapter

Response

Request

Endpoint

Application

Response

One way callback events

One way callback events are asynchronous operations in which the EIS sends an event to the adapter and then goes on with its processing, not waiting for the adapter to send a response back.

The following is an illustration of asynchronous callback event processing.

EIS

Callback From EIS

Response

Adapter

Message

Delivery

Response

Endpoint

Application

90 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

Using the IBM WebSphere adapter foundation classes for inbound callback event processing

The adapter foundation classes can automatically track endpoints (the consumers of events) for the adapter, control the event pick up and delivery of events, handle recovery of events if the adapter unexpectedly terminates, and assure once-and-only-once event delivery.

This allows developers to provide greater quality of service (QoS) in less time and also ensure that behavior across adapters is consistent.

Although not required, it is a recommended practice that you use IBM WebSphere adapter foundation classes (AFC) for adapters that have to provide callback event notification.

Adapter foundation classes make the process of callback event delivery in an assured manner easier for the developer creating the adapter, by providing the event delivery API called the CallBackEventSender.

The following diagram depicts the usage of adapter foundation classes (common component). The CallbackEventSender API is integral to the adapter foundation classes.

Adapter

EIS

Callback From EIS

Response

Message

Delivery (with

optional return)

Response

Client

system

Callback event sender

CallbackEventSender in com.ibm.j2ca.extension.eventmanagement.external package provides four public methods.

CallbackEventSender in com.ibm.j2ca.extension.eventmanagement.external package provides following four public methods.

v public void sendEventWithNoReturn(Record, InteractionSpec) throws

WBISendFailedException

v public Record sendEventWithReturn(Record, InteractionSpec) throws

WBISendFailedException

v public void sendEventWithNoReturn(GenericEvent, Record, InteractionSpec)

throws WBISendFailedException

v public Record sendEventWithReturn(GenericEvent, Record, InteractionSpec)

throws WBISendFailedException

These methods end up invoking different methods in the message-driven bean (MDB). The MDB will implement several interfaces, including InboundListener, and MessageListener.

WebSphere Adapter development overview 91

The sendWithReturn methods invoke onMessage on the InboundListener. This method delivers the Record it received from the listener thread. Here the difference is the onMessage method will be invoked on the InboundListener to deliver the Record to the endpoint. The method would return ″Record″ as returned by onMessage method.

The sendWithNoReturn method invokes onNotification on the InboundListener. The sendEventWithReturn() method is not supported incase of multiple endpoint factories configured, hence will throw an appropriate exception. Also, if there are failures during the sending event when multiple endpoint factories configured, a consolidated exception stack trace will be thrown with details like which endpointfactory failed and for what reason.

Callback event sender constructors:

CallbackEventSender provides four different constructors to facilitate different types of client invocation.

The following information describes the usage of the four constructors:

v CallbackEventSender(ArrayList, EventPersistence, XAResource,

ActivationSpecWithXid, LogUtils)

The complete constructor which takes an array of endpoint factories and supports XA transaction with event persistence updates. If the input ActivationSpecWithXid is valid and not null, event would be delivered by calling target method on the inbound listener with ActivationSpecWithXid as additional argument.

v CallbackEventSender(ArrayList, ActivationSpecWithXid, LogUtils)

Constructor used for event delivery without XA transaction and event persistence support.

v CallbackEventSender(MessageEndpointFactory, EventPersistence, XAResource,

ActivationSpecWithXid, LogUtils)

This constructor does take the same arguments as (1) except that it takes one MessageEndpointFactory instead of an array.

v CallbackEventSender(MessageEndpointFactory, ActivationSpecWithXid, LogUtils)

A slight variation for constructor (2) with just one MessageEndpointFactory argument instead of an array.

Callback event processing for basic delivery

When the event is created at the EIS end, configured adapterListener gets notified and it in turn instantiates CallbackEventSender. Here adapterListener decides which method to invoke out of the four defined.

To implement callback mechanism, adapter must have an EndPointManager class. The class needs to maintain the relationship between the activationSpec and MessageEndpointFactory arguments. Here is a snippet of EndPointManager class showing how the callback mechanism is implemented.

public class EndpointManager {

/** * inner class which maintains pairs of mef and activationspec */

public static class EndpointPair {

public MessageEndpointFactory mef;

public ActivationSpec activationSpec;

92 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

public EndpointPair(MessageEndpointFactory mef, ActivationSpec activationSpec) {

this.mef = mef; this.activationSpec = activationSpec;

}

public boolean equals(Object o) {

if (!(o instanceof EndpointPair)) {

return false;

}

return other.mef.equals(this.mef) && other.activationSpec.equals(this.activationSpec);

// adds new endpointPair to the list public void addEndpoint(MessageEndpointFactory mef, ActivationSpec activationSpec) throws ResourceException {...} }

EndpointPair other = (EndpointPair) o;

}

The adapter listener gets all MessageEndpointFactories for the current activationSpec and registers that with the CallbackEventSender instance.

EndpointManager epManager = ((ResourceAdapter)aSpec.getResourceAdapter()).getEndpointManager(); EndpointPair[] endpoints = epManager.getEndpoints(this.aSpec);

if (!isSynchronous && aSpec.getAssuredOnceDelivery().booleanValue()) {// XA Delivery

callbackEventSender = new CallbackEventSender(endPointList,

eventRecMngr.getEventPersistance(), XAres, aSpec, logger.getLogUtils());

} else {// Non XA delivery

callbackEventSender = new CallbackEventSender(endPointList, aSpec, logger.getLogUtils());

}

/* Refer to the Callback event sender constructors section for more information. Note: The adapter listener creates the worker threads to take care of calling and getting responses from the callBackEventSender method. */

Once the program control gets into CallbackEventSender, it checks how many EndpointFactories are configured for the current instance of adapter. If there is more than one, then it delivers the event by creating endpoints for each of them and invoking either onNotification or onMessage method on the endpoint with out any XA transaction. Finally, it would call the release() method on the end point to free the endpoint hence the application server can add it to endpoint pool. Finally it would call release() method on the end point to free the endpoint hence the application server can add it to endpoint pool.

Also it invokes beforeDelivery() and afterDelivery() methods on the endpoint as defined by the JCA functional specification.

XA transaction will come into picture only when the adapter is configured with ONE EndpointFactory. The following sequence diagram depicts the callback event processing for basic delivery.

WebSphere Adapter development overview 93

Callback event processing for event delivery with XA transaction

To provide data integrity and to make sure events are not delivered more than once, which would cause errors in the downstream system in the integration scenario, the invention provides a mechanism to achieve once-and-only delivery and the same is accomplished using XA transaction.

When assured delivery is required, the basic flow described in Callback event processing for basic delivery becomes more complex. For more complex scenarios, CallbackEventSender creates an instance of XA to bring the delivery under a new transaction. The beforeDevliery() call to endpoint is the starting point of XA transaction and it will last till afterDelivery(). If problems occur within this transaction scope, a proper rollback mechanism will ensure data integrity is maintained.

XA transaction will be active and supported only when the adapter is configured with one EndpointFactory.

94 WebSphere Adapters: WebSphere Adapter Toolkit User Guide

IBM WebSphere Adapters User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

Contents

WebSphere Adapter Toolkit

IBM WebSphere Adapter Toolkit technology overviews

IBM WebSphere Adapters

Architectural overview

How metadata is used at build time and run time

Using Enterprise Metadata Discovery to build services

IBM WebSphere Adapter Toolkit overview

New Connector Project wizard overview

Resource Adapter Deployment Descriptor Editor overview

Adapter Foundation Classes overview

IBM WebSphere Adapter Toolkit tasks

IBM WebSphere Adapter Toolkit installation requirements

Samples overview

Running the Twine Ball sample using WebSphere Integration Developer

Import the samples code

Run external service discovery for outbound processing

Run external service discovery for inbound processing

Modify the module

Test the sample

Running the Twine Ball sample using Rational Application Developer

Import the samples code into Rational Application Developer and modify the sample for use

Test the sample using the universal test client

Troubleshooting the samples

Using the New Connector Project wizard

Launching the New Connector Project wizard

Specify project properties

Specify project facets

Specify connector project module settings

Specify resource adapter properties

Specify generation options

Generating an IBM WebSphere Resource Adapter

Generating outbound adapter classes

Generating inbound adapter classes

Generating enterprise metadata discovery classes

Generating data binding classes

Generating a JCA resource adapter

Generating outbound JCA adapter classes

Generating inbound JCA adapter classes

Generating JCA enterprise metadata discovery classes

Generated code and deployment descriptor

Using the Resource Adapter Deployment Descriptor editor

Displaying the deployment descriptor

Using the Overview pane

Using the Resource Adapter pane

Using the Outbound Adapter pane

Using the Inbound Adapter pane

Modifying deployment descriptor properties

Generated bean properties

Editing deployment descriptor source

Implementing code from the IBM WebSphere Adapter Toolkit

Foundation Classes implementation overview

Data model

Relationship of business objects to service data objects

After-images versus deltas

Verbs

Verbs versus operations

Business object standards

Inbound event notification

Using the IBM WebSphere Foundation Classes for inbound event notification

Assured once-and-once-only event delivery

Implementing an event store in the EIS

Implementing event retrieval in the adapter

Possible event store implementations

Inbound callback event notification

Request and response callback events

One way callback events

Using the IBM WebSphere adapter foundation classes for inbound callback event processing

Callback event sender

Callback event processing for basic delivery

Callback event processing for event delivery with XA transaction