Loading...
|
|
|
||
|
WebSphere® |
Adapters |
||
Version 6 Release 2 |
||||
|
||||
|
||||
WebSphere Adapter Toolkit User Guide
Version 6 Release 2
|
|
|
||
|
WebSphere® |
Adapters |
||
Version 6 Release 2 |
||||
|
||||
|
||||
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.
©Copyright International Business Machines Corporation 2006, 2008.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
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:
vA 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.
vA resource adapter that extends the WebSphere Adapter Foundation Classes library. Choose this path if your goal is to create a resource adapter implementation that can run in a managed server runtime environment like WebSphere Process Server and that exhibits the common functionality and extended qualities of service offered specifically by WebSphere Adapters. WebSphere Adapters are based on the JCA 1.5 specification. These adapters are supported on multiple runtime environments and brokers.
Implementing a WebSphere adapter allows you to take advantage of the quality of services offered in the WebSphere Adapter foundation classes (AFC) and the flexibility of being able to run the adapter on runtime environments other than WebSphere Process Server.
In either case, the toolkit provides a project creation wizard that generates the code that you then implement. In addition, the toolkit provides a specialized editor that facilitates the task of creating and configuring a resource adapter deployment descriptor.
This document focuses primarily on development of resource adapters and artifacts that extend the WebSphere Adapter Foundation Class library.
The following figure illustrates the process of developing a JCA resource adapter using the WebSphere Adapter Toolkit.
Using the WebSphere Adapter Toolkit
© Copyright IBM Corp. 2006, 2008 |
1 |
The development process using the IBM WebSphere Adapter Toolkit includes the following as shown in the illustration:
1.Run the New JCA Resource Adapter Project wizard.
The wizard generates a resource adapter deployment descriptor and code. The code can include sequence of calls, log and trace messages and comments.
2.Use the Resource Adapter Deployment Descriptor Editor to configure your deployment descriptor.
3.Implement the code to correctly interface with your enterprise information system (EIS).
4.Export the resource adapter as a resource adapter archive (RAR) or enterprise application archive (EAR) file.
The purpose of this documentation
Adapter development requires a great deal of software engineering, which varies from customer to customer. The process of integrating adapter functionality into your business processes will require you to design, build and test the solution that utilizes the adapter. The purpose of the WebSphere Adapter Toolkit documentation is to lay out the requirements of the architecture and provide guidance on how and when to implement the various facets of it, so that you can apply your engineering discipline to the adapter-specific requirements, capabilities and architecture.
IBM WebSphere Adapter Toolkit technology overviews
The IBM WebSphere Adapter Toolkit helps developers implement the Adapter Foundation Classes, which establish a WebSphere Adapter standard for building resource adapters that conform to the Java 2 Connector Architecture (JCA) 1.5 specification.
IBM WebSphere Adapters
An IBM WebSphere Adapter implements the Java 2 Enterprise Edition (J2EE) Connector architecture (JCA), version 1.5. Also known as resource adapters or JCA adapters, WebSphere Adapters enable managed, bidirectional connectivity between enterprise information systems (EIS) and J2EE components supported by multiple server runtime environments, including WebSphere Process Server and WebSphere Application Server.
IBM WebSphere adapters support outbound request processing and inbound event processing.
Note: IBM WebSphere adapters support outbound and inbound processing for WebSphere Process Server and outbound processing only for WebSphere Application Server.
Outbound processing refers to a process in which request data flows from a client application to the EIS. In an outbound processing scenario, the adapter acts as the connector between the application component and the EIS. The adapter provides a set of standard operations, which process either after-image or delta style business objects. An outbound request can read data from or write data to the EIS.
Inbound event processing refers to a process that is initiated by an event on the EIS. In inbound event processing the adapter converts events generated from the EIS into business objects and sends the business object to the client application.
2 WebSphere Adapters: WebSphere Adapter Toolkit User Guide
Inbound event notification complements outbound request processing, enabling adapters to provide bidirectional communication between business processes and EIS applications.
WebSphere Process Server |
Enterprise information |
|||||||||
|
|
|
|
|
|
|
|
system |
||
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
WebSphere |
|
|
|
|
|
|
|
|
|
|
|
|
|
Business |
|
|||
J2E component |
|
|
Adapter |
|
|
|
|
|
||
|
|
|
|
|
|
function |
|
|||
|
|
|
|
|
|
|||||
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Files
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.
Fully compliant with the JCA standard, WebSphere Adapters have been developed to run on multiple server runtimes. A WebSphere Adapter does the following:
vIntegrates with multiple server runtimes, including WebSphere Process Server, WebSphere Enterprise Service Bus, and WebSphere Application Server.
vConnects an application running on WebSphere Process Server with an EIS.
vEnables data exchange between the application and the EIS.
Each WebSphere Adapter is made up of the following:
vAn implementation of the (J2EE) Connector Architecture (JCA), version 1.5, which supports WebSphere Process Server and WebSphere Application Server.
vAn 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. . |
Programming |
|
|
|
|
|
|
Model |
|
Application |
Data |
SDO |
DAAPI |
Metadata |
|
Component |
Exchange |
|
|
|
|
|
|
Record |
Other |
|
|
|
|
|
|
Common Client |
|
|
|
|
|
Interface (CCI) |
Common |
JCA Connector |
|
|
Connections |
|
|
|
Security |
|||
Services |
|
|
|
|
|
|
|
|
|
Transactions |
|
|
|
|
|
|
DESPI Records |
Monitoring |
|
|
|
|
Metadata |
|
|
Connectivity |
Adapter |
||
|
|
|
|||
Problem |
|
|
|
|
Foundation |
|
|
Data exchange |
Classes |
||
Determination |
|
|
|||
|
|
|
|
|
|
Figure 3. Runtime architecture component model
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:
vAn 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:
vGenerate 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
vGenerate 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:
vDisplay and configure the resource adapter deployment descriptor without having to modify the XML file directly
vAutomatically generate Java bean properties in the generated source code that correspond to the configuration properties you add using the editor
vValidate 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 |
See the developerWorks site for WebSphere Adapter Toolkit for |
requirements |
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. |
|
|
Installing WebSphere Adapter Toolkit |
You do not run an installer program for the toolkit. Instead, you |
|
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. |
|
|
Access the Javadoc for the Adapter Foundation |
To access the Javadoc, perform the following steps: |
Classes, EMD 1.1 and DESPI. |
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. |
|
|
Using the New J2C Resource Adapter Project |
How to launch it, specify properties, choose generation options, |
wizard |
and generate classes. |
|
|
Using the Resource Adapter Deployment |
How to launch it, display features, change and add properties, |
Descriptor editor |
and edit source. |
|
|
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) |
|
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® |
v Intel® Pentium® III 800 MHZ processor or faster |
|||
Windows® 2000 |
v 1024 x 768 display or higher resolution monitor |
|||
Windows 2003 |
||||
v |
Memory: requirements |
|||
Windows XP |
||||
|
|
– |
768 MB minimum |
|
|
|
– |
1 GB recommended |
|
|
v |
Disk space requirements: |
||
|
|
– 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:
vThe 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.
vThe 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:
vImplementation of a resource adapter and enterprise metadata discovery
vResource adapter deployment descriptor and source code in Project Interchange Format suitable for importing into WebSphere Integration Developer
vRAR 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 Yes to finish the process of importing the deployable RAR file for the Twine Ball sample into your workspace.
Now you can perform external service discovery for the Twine Ball sample.
Run external service discovery for outbound processing
The external service wizard is a tool you use to create services. The external service wizard establishes a connection to the EIS, discovers services (based on search criteria you provide), and generates business objects, interfaces, and import or export files, based on the services discovered.
Import the deployable RAR file for the sample.
For the Twine Ball sample you need to create an adapter service for outbound processing and inbound processing. This task describes the how to use the External Service wizard to create and adapter service for outbound processing.
1.If not already there, go to the Business Integration perspective.
2.Place your cursor in the Business Integration navigation pane, right-click and select New → Other to launch the Select a wizard window.
3.From the list of available wizards, expand Business Integration and select the
External Service wizard:
WebSphere Adapter development overview 15
4.Click Next to launch the New External Service window.
5.From the New External Service window, make sure that Unlisted Adapter is selected and click Next.
6.From the Select an Adapter window, expand TwineBallConnector (IBM:6.2), select CWYAT_TwineBall and click Next.
16 WebSphere Adapters: WebSphere Adapter Toolkit User Guide
7. From the Processing Direction window, select Outbound and click Next.
8.From the Discovery Configuration window, click Next. No connection properties are required.
9.From the Object Discovery and Selection window, select CUSTOMER from the Discovered objects pane and add it to the Selected objects portion of the window then click Next.
WebSphere Adapter development overview 17
10. From the Configure Composite Properties window, select Next.
11.From the Service Generation and Deployment Configuration window, deselect
Specify a Java Authentication and Authorization Services (JASS) alias security credential and click Next.
18 WebSphere Adapters: WebSphere Adapter Toolkit User Guide
12.From the Service Location Properties window, click New. This launches the New Integration Project window.
13.From the New Integration Project window, select Create a module project and click Next.
14.Enter values in the New Module window and click Finish.
Your module displays in the Project explorer view:
WebSphere Adapter development overview 19
15.Click Finish from the Service Location Properties window to add the outbound interface to the module.
16.You are prompted on whether you want to update the model, select Yes.
Run the external service discovery process again to add the inbound interface to the module.
Run external service discovery for inbound processing
The external service wizard is a tool you use to create services. The external service wizard establishes a connection to the EIS, discovers services (based on search criteria you provide), and generates business objects, interfaces, and import or export files, based on the services discovered.
Make sure you have done the following:
vImport the deployable RAR file for the sample into your workspace.
vRun external service discovery for outbound processing.
For the Twine Ball sample you need to create an adapter service for outbound processing and inbound processing. This task describes the how to use the External Service wizard to create an adapter service for inbound processing.
1.Go to the Business Integration perspective.
2.Place your cursor in the Business Integration navigation pane, right-click and select New → Other to launch the Select a wizard window.
3.From the list of available wizards, expand Business Integration and select the
External Service wizard:
20 WebSphere Adapters: WebSphere Adapter Toolkit User Guide
4.Click Next to launch the New External Service window.
5.From the New External Service window, make sure that Unlisted Adapter is selected and click Next.
6.From the Select an Adapter window, expand TwineBallConnector (IBM:6.2), select CWYAT_TwineBall and click Next.
WebSphere Adapter development overview 21
7. From the Processing Direction window, select Inbound and click Next.
8.From the Discovery Configuration window, click Next. No connection properties are required.
9.From the Object Discovery and Selection window, select CUSTOMER and add it to the Selected objects portion of the window then click Next.
22 WebSphere Adapters: WebSphere Adapter Toolkit User Guide
10. From the Configure Composite Properties window select Next.
11.From the Service Generation and Deployment Configuration window, deselect
Specify a Java Authentication and Authorization Services (JASS) alias security credential.
WebSphere Adapter development overview 23
12.From the Service Location Properties window, click Finish to add the inbound interface to the module.
13.You are prompted on whether you want to update the model, select Yes.
You should see the inbound and outbound interfaces in the viewing area of the assembly diagram editor:
Modify the module.
Modify the module
Modify the sample module by adding a Java component to link to the inbound service.
You must have created the service before modifying it.
By adding a Java component to link the service you will be able to access and implement the emit <Create/Delete/Update>Customer() method to insert a print statement.
1. Add a Java component to link to the InboundService.
24 WebSphere Adapters: WebSphere Adapter Toolkit User Guide
Loading...