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.
Contents WebSphere Adapter Toolkit . . . . . . 1 IBM WebSphere Adapter Toolkit technology overviews . . . . . . . . . . . . . . . 2 IBM WebSphere Adapters . . . . . . . . . 2 Architectural overview . . . . . . . . . . 4 How metadata is used at build time and run time 7 Using Enterprise Metadata Discovery to build services . . . . . . . . . . . . . . . 7 IBM WebSphere Adapter Toolkit overview . . . . 8 New Connector Project wizard overview . . . . 9 Resource Adapter Deployment Descriptor Editor overview . .
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.
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.
Inbound event notification complements outbound request processing, enabling adapters to provide bidirectional communication between business processes and EIS applications. WebSphere Process Server WebSphere Adapter J2E component Enterprise information system Business 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.
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.
processing performed by each component (and subcomponent) in the model is described in sections that follow the illustration. Application interface SCA J2EE CC Application Data Component Exchange Programming Model Proprietary. . SDO DAAPI Record Other Metadata Common Client Interface (CCI) Common Services Connections Security Transactions DESPI Records Metadata JCA Connector Monitoring Connectivity Problem Determination Adapter Foundation Classes Data exchange Figure 3.
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.
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.
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.
– 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
/** * 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 element of the ra.xml file.
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.
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 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.
Add Connection Definition dialog A Connection Definition requires the following information: v ConnectionFactory Interface v ConnecitonFactory Implementaion Class v Connection Interface v v Connection Implementation Class 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.
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 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 element of the ra.
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.
Add Required 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. Modifying deployment descriptor properties When you modify configuration properties, the Resource Adapter Deployment Descriptor automatically updates source code with corresponding JavaBean properties.
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.
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.
2. 3. 4. 5. 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.
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.
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.
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.
Outbound Operation Signatures applyChanges create update delete Notes 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Method Description ArrayList getEvents(int quantity, int eventStatus, String[] typeFilter) 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.
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.
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.
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.
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.
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.
public EndpointPair(MessageEndpointFactory mef, ActivationSpec activationSpec) { this.mef = mef; this.activationSpec = activationSpec; } public boolean equals(Object o) { if (!(o instanceof EndpointPair)) { return false; } EndpointPair other = (EndpointPair) o; 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 {...
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.
When the adapter signals that it has completed delivery, the transaction manager will then call ″end″, ″prepare″, and ″commit″ to complete the requirements outlined in the XA transaction protocol. When the ″prepare″ call is made, the XA implementation will call ″setTransactionID″ on the eventPersistance implementation; the eventPersistance implementation will store the transaction XID in the event table.
Callback event processing for event recovery When there is a failure in the event processing as part of system recovery, the adapter is able to recover the unprocessed events by implementing the once-one-only delivery mechanism. During real time event processing if any component of the business integration system fails then the adapter must process the events that are not completed, and not process the events that are completed.
When the container starts, it calls the getXAResources() method on the adapter to get all the associated XA resources. The adapter then instantiates the appropriate XA resource and returns it back to the container. The JCA container now calls the recover() method on the returned XAResourceImpl to get all the pending transactions from the configured event persistence using the getPendingTransanctions() method.
Application sign-on The Adapter Foundation Classes can use either container-managed or component-managed authentication or sign-on. The process of connecting to a back-end application, such an EIS, usually requires some type of authentication. In a JCA environment, application authentication is known as sign-on. It can be performed in one of two ways: v When using container-managed sign-on, the JCA container is responsible for providing sign-on credentials.
7. The ConnectionManager may call getConnection(Subject, ConnectionRequestInfo) on a ManagedConnection where the passed ConnectionRequestInfo does not match the ConnectionRequestInfo already associated with the ManagedConnection. The default implementation of this method performs a property-for-property comparison between the two ConnectionRequestInfo instances. It returns true if an exact match is found, otherwise false.
public Object createConnectionFactory(ConnectionManager connMgr) throws ResourceException { return new TwineBallConnectionFactory(connMgr, this); } 2. ManagedConnection createManagedConnection(Subject, ConnectionRequestInfo) This method is used by the JCA container to acquire a physical connection to the EIS instance. Subclass implementation should return a EIS-specific ManagedConnection instance which is a subclass of WBIManagedConnection. public javax.resource.spi.
Best practices v Each ManagedConnection instance should encapsulate at most one connection to the EIS. v Since there may be more than one Connection instance for each ManagedConnection instance, resource adapter developers should implement private contracts between their WBIManagedConnection subclass and their WBIConnection/WBIInteractionsubclasses to ensure that access to the underlying EIS connection or API is performed in a thread-safe manner.
public Interaction createInteraction() throws ResourceException { return new TwineBallInteraction(this); } Note: If you want to provide your own implementation of ConnectionMetadata, you must override method WBIConnection#getMetadata. javax.resource.cci.ConnectionSpec: Clients use a javax.resource.cci.ConnectionSpec instance to pass request-specific connection properties to the getConnection method of the ConnectionFactory.
this.connection.getResourceAdapter(); ObjectNaming objectNaming = new ObjectNaming(resourceAdapter); factory = new TwineBallCommandFactory(objectNaming); commandManager = new CommandManager(factory, this.connection.getEISConnection(), this.getLogUtils()); } public Record execute(InteractionSpec ispec, Record inRecord) throws ResourceException { WBIRecord wbiRecord = (WBIRecord) inRecord; String functionName = ((WBIInteractionSpec) ispec).
properties should not change the configuration of the EIS. javax.resource.cci.ConnectionMetadata: A javax.resource.cci.ConnectionMetadata instance provides information to the client components about the underlying EIS of a resource adapter. Client components can use the javax.resource.cci.Connection.getMetadata() interface to retrieve connection-specific EIS metadata.
3. Override method WBIManagedConnection.getLocalTransaction() and, if XA support is provided, method WBIManagedConnection.getXAResource(). Wrap either or both of the LocalTransaction or XAResource instances returned by these methods with a WBILocalTransactionWrapper or WBIXATransacxtionWrapper instance, respectively. These wrappers provide extended diagnostics for troubleshooting and also help adapters determine whether or not to autocommit requests. According to the JCA 1.
Adapters are responsible for creating, updating, retrieving, and deleting (CRUD) records in the EIS system based on the structure described by the incoming metadata and the content in the incoming cursor. The command pattern approach is recommended for handling the generic processing of CRUD operations for After-Image as well as Delta scenarios.
Consider the following scenario: Child B1 is in the EIS, but is not in the incoming structure. Child B1, then, must be deleted. The Command Manager will execute a Retrieve command to build the structure as it appears in the EIS, then compare this structure to the incoming object tree. The comparison finds that child B1 is deleted. Accordingly, the resulting command structure has a Delete command in that position.
Command Manager Delete Delta objects Delta processing is only relevant for service data objects (SDO). The Command Manager functions in a similar way when processing delta objects. Instead of retrieving and comparing, the command manager reads the change summary for the intended changes.
Suppose, as in the example below, that child B1 is created and is part of the change summary. The resulting command structure will contain a Create command for child B1, and will have NO-OPERATION parents linking it back to the top level parent.
Command Manager Create When it processes this structure, the interpreter will execute the No-op commands as well as the Create command. In general, the no-op commands should not modify data in the EIS system. After-image processing: The Command Manager, based on the CommandManager API, implements the command pattern capability. This utility simplifies the work of comparing beforeand after-image data. The Command Manager is based on the CommandManager API of the Adapter Foundation Classes.
Command Manager simplifies before and after comparisons As shown in the upper portion of the figure, the input to the Command Manager is a before image and an after image. The Command Manager creates a top-level command representing the operation for the top-level incoming cursor. As processing continues, sub-commands are added at the child object level and so on to the top-level incoming cursor, as shown in the lower portion of the figure.
The Command Manager processes delta structures in a manner analogous to that of after-image data. The difference is that, for delta objects, comparative data is extracted from service data object change summaries. When the input service data object (SDO) represents an Update operation with a delta structure, the Command Manager will look up the BOChangeSummary to find the respective operations on each child SDO.
You will need to implement the following: 1. Command implementations for each command type (″Retrieve″, ″RetrieveAll″, ″Create″, ″Update″, ″Delete″, and ″NoOperation″). 2. A command factory implementation that will create instances of these EIS-specific commands. 3. An implementation of Interaction.execute() that calls the Command Manager. Command implementations: You use an execute() method to implement commands.
if (functionName.equals(NodeLevelOperations.CREATE_NODE)) { command = new TwineBallCreateCommand(); } else if (functionName.equals(NodeLevelOperations.DELETE_NODE)) { command = new TwineBallDeleteCommand(); } else if (functionName.equals(NodeLevelOperations.UPDATE_NODE)) { command = new TwineBallUpdateCommand(); } else if (functionName.equals(NodeLevelOperations.RETRIEVE_STRUCTURE)) { command = new TwineBallRetrieveCommand(); } else if (functionName.equals(NodeLevelOperations.
Data and metadata Adapter Foundation Classes (AFC) implement DESPI APIs and support two data formats, service data objects (SDO) and JavaBeans. The data format-specific implementations are provided in the AFC and are abstracted from the adapters which use the DESPI APIs to process data in a format-independent way. XSD and JavaBean structure relationship to DESPI SDO Structure: JavaBeanRecord Structure: The JavaBeanRecord data structure is derived from the XML Schema defining the SDO.
Table 2.
The notion of whether or not a property is set is critical to processing null values or values that have not been set in the adapter. If a property has been explicitly set to null, the adapter must be able to detect this and set the associated property to null in the EIS. If the property has not been set, it might still have a null value, but the adapter will ignore the value and not set it in the EIS system.
As defined in the sapBAPIBusinessObjectTypeMetadata schema ″Operation″ is an n-cardinality complex type.
objectAnnotationsMap ObjectName WBI_CUSTOMER_CI Operation operationsList createOperationsMap Name Create MethodName operationList MethodNameList methodNameList updateOperationMap createOperationMap wbiCustomerCreate The Metadata API Advanced implementations of adapters are metadata-driven.
These interfaces may contain more helper methods than are listed here, please see the Javadoc for the additional helpers. Factory classes Class TypeFactory: TypeFactory creates an instance of an implementation of Type. The TypeFactory is also capable of detecting whether SDO version 2, SDO version 1, or neither is present in the classpath, allowing it to make decisions about what implementation to use. v Type getType(Object object) Gets a Type object from existing metadata.
Property getProperty(String propertyName) Returns the property object for this property name. Map getAnnotations(String source) Returns the object-level annotations for this type. You must pass in the "source" of the annotations, which corresponds to the "source" attribute of the "appinfo" tag of the XML Schema representing this object. Annotations will be returned as a Map, and this Map may contain other maps if the annotation structure is nested.
boolean isContainment() Returns whether or not the property contains a Type (complex object). boolean isMany() Returns whether or not the property contains a List or Array. int getMaxLength() Returns the max length of the property. Map getAnnotations(String source) Returns the annotations for this property. boolean isKey(String source) Returns true if this property is a key, and false if not. Type getType() If the property is containment, this method will return the contained type.
Support for GeneratedRecords artifact type: WebSphere adapters may support JavaBeanRecord data representation along with SDO 1.0 and SDO 2.0 data objects. As part of the support for JavaBean data representation, the adapter foundation classes provides a JavaBeans record generator class that can generate DataBindingDescriptions for the object types discovered and selected through the enterprise metadata discovery (EMD) process.
The enterprise metadata discovery component is analogous to the Object Discovery Agent of WebSphere Business Integration Adapters. In addition to generating business object definitions, however, the enterprise metadata discovery also generates service component architecture artifacts such as an Import/Export file and WSDL. An explicit goal of enterprise metadata discovery is to enable existing JCA resource adapter extensions to provide metadata discovery and import in a simple, straightforward way.
Business Object Structures These are the business objects used by JCA adapters. They describe the structure and content of arguments to functions on the EIS client interface or the business objects accessed through the EIS client interface. Communication Configuration The communications configuration is represented by a collection of properties also referred to as PropertyGroup. The properties include properties required for both inbound and outbound communication.
Service metadata Enterprise metadata discovery architecture The enterprise metadata discovery tooling includes runtime, discovery, and service generation interfaces and metadata edit capabilities. Enterprise metadata discovery architecture Note: The solid arrows represent the enterprise metadata discovery implementation in the above diagram.
These interfaces extend the CCI interfaces defined in the JCA specification to support invocation of services discovered with enterprise metadata discovery. These interface implementations are provided by the resource adapter provider or a third party discovery service provider. These are the data binding interfaces that are used to integrate with service data objects. v Discovery These interfaces constitute the bulk of the contracts defined in this specification.
for multiple back-end EIS assets. IBM WebSphere recommends a single adapterType for each enterprise metadata discovery implementation. The following information must be provided for this class by a discovery service implementation. v ID (for example, PeopleSoft) v Description (for example, PeopleSoft JCA Adapter) v Display name (for example, PeopleSoft Adapter) v Vendor (for example, IBM) v Version (for example, 6.
copy matching properties from metadata connection to runtime connection. For more information, see the WBIOutboundConnectionTypeImpl in the Javadocs. The following information must be provided for this class by a discovery service implementation: v ID (for example, PeopleSoft) v Display name (for example, PeopleSoft) v Description (for example, PeopleSoft Component Interface) v ResourceAdapterBean class (for example, ″com.ibm.j2ca.peoplesoft.
MetadataConnection The MetadataConnection object represents the connection to EIS or EIS repository. This interface is implemented by the Adapter Foundation Classes only and does not require any implementation from discovery service instances. MetadataConnection uses the managed connection factory to create the connection to the EIS. The configuration properties specified by the user are mapped to the managed connection factory. AgetConnection() call is placed to obtain an EIS connection.
In addition to object selection, MetadataSelection also holds properties that are applicable for the selected objects. Such properties include the following: v Specification of service type: inbound or outbound v Namespace for use by business object definitions v ConnectionType that for use at run time. This step is required if the ConnectionType at run time differs from that for metadata discovery. Regardless, IBM WebSphere recommends a different connectionType for metadata than for run time.
the import. The Adapter Foundation Classes provide an implementation for ServiceDescription as abstract classes. Discovery service implementations should extend these classes and implement the abstract methods Inbound service descriptions Enterprise metadata discovery service implementations should provide the following information for an inbound service description.
You must provide EIS connection descriptions for the enterprise metadata discovery service. Adapter Foundation Classes contain interface implementations to help you get started. Like ServiceDescription, ConnectionDescription can be either inbound or outbound service. Adapter Foundation Classes provide implementation for ConnectionDescription interfaces. Discovery service implementations need not implement these interfaces.
Outbound Function Description The following information has to be filled in by the discovery service implementations: v Name - e.g. createCustomer, applyChangesCustomer v InteractionSpec - Instance of interaction spec which has function name specified that represents this method description. E.g. for createCustomer the function name would be ’Create’.
Note: To limit confusion, custom operation names should not conflict with the standard operation names mentioned above. Note: In cases where the mapping of EIS operations to Create, Retrieve, Update and Delete is equivalent except for naming conventions–for example, PeopleSoft has a Find operation that is functionally equivalent to a Retrieve–the EIS-specific operation should not be exposed since it adds no value.
Name – For example, VENDORID Type – For example, string Cardinality – 1 or N Required – Boolean ObjectTypeName – For cases where an attribute maps to an object for example, porecord:PORECORD. v Max Length v Metadata – the MetadataObject representing attribute-level application-specific information. v v v v v ImportedNamespace: ImportedNamespace describes the names that must be imported into the business object definition. This class represents the import statement in the XML schema definition.
BootStrap: WebSphere Integration Developer performs a bootstrap step to identify a resource adapter that has been enabled for enterprise metadata discovery service. To identify a resource adapter that is enabled for metadata discovery service, WebSphere Integration Developer launches a bootstrap step to find a discovery-service.xml file. This file should be located in the META-INF folder for the resource adapter. An example of this file is found in the sample delivered with the WebSphere Adapter Toolkit.
v PropertyGroup – A collection of properties including single and multi types and PropertyGroup itself. For example, OutboundConnectionConfiguration allows three property groups in one Main property group: UserConfiguration that includes Username and Password; MachineConfiguration that includes Hostname and PortNo; and Miscellaneous that includes other properties such as Prefix and DirectoryName. v PropertyChangeListener – Used when a property change affects some other property or property group.
A propertyChange() method should be implemented if a property needs to listen for changes on some other property. Check the TwineBall sample for ServiceTypeSingleProperty. To enable the function of both vetoableChange and propertyChange, the instance of the property should be added to the propertyChangeListener list.
public TwineBallMetadataDiscovery() throws MetadataException { super("com.ibm.j2ca.sample.twineball.emd"); } The WBIAdapterTypeImpl constructor requires the following parameters: 1. The name of the class representing the ResourceAdapter class. This is used to create property groups for ResourceAdapter in enterprise metadata discovery. 2. Number of outbound connections 3.
discovery and the one that used for run time. The copy is based on names. For example, if a property name Username exists in the configuration used for discovery and that used for run time, the Username value is copied. public ServiceDescription createServiceDescription (MetadataSelection importSelection) throws MetadataException { ServiceDescription description = null; WBIMetadataSelectionImpl selection = (WBIMetadataSelectionImpl) importSelection; MetadataImportConfiguration[] confArray = selection.
public TwineBallAdapterType()throws MetadataException{ super(Constants.RESOURCE_ADAPTER_BEAN_NAME, 2, 1); setId(Constants.ADAPTER_NAME); setDisplayName(Constants.ADAPTER_NAME); setDescription(WBIMetadataDiscoveryImpl.getPropertyDescription (ADAPTERTYPE_PROPERTY)); setVendor(VENDOR); setVersion(VERSION); setOutboundConnections(); setInboundConnections(); } setInboundConnections The setInboundConnections() method sets the inbound connections on the adapter type.
the managed connection factory types that are supported by the adapter. Each managed connection factory maps to an instance of outbound connection types. Each enterprise metadata discovery implementation should extend WBIOutboundConnectionTypeImpl and implement the methods described below. Constructor The constructor takes the adapterType argument, and then sets the ID, and the description and display names.
setDescription(WBIMetadataDiscoveryImpl.getPropertyDescription ("ConnectionType")); setId("TwineBall"); setDisplayName(WBIMetadataDiscoveryImpl.getPropertyName ("ConnectionType")); } createInboundConnectionConfiguration The createInboundConnectionConfiguration() method returns an instance of InboundConnectionConfiguration. Each enterprise metadata discovery implementation extends WBIInboundConnectionConfugurationImpl and an instance of that class is returned in this method.
TwineBallConfigurationProperties.getTwineBallConfigurationProperties(); TwineBallResourceAdapter ra = new TwineBallResourceAdapter(); WBIPropertyGroupImpl adapterProp = (WBIPropertyGroupImpl) EMDUtil.getPropertyGroup(ra); propGroup.addProperty(adapterProp); if (getAppliedProperties() != null) EMDUtil.
This class is similar to WBIOutboundConnectionConfigurationImpl except instead of ManagedConnectionFactory, WBIInboundConnectionConfigurationImpl handles the ActivationSpecWithXid bean class. You must extend the methods described below. public PropertyGroup createActivationSpecProperties() { WBIPropertyGroupImpl connProp = null; try { connProp = (WBIPropertyGroupImpl) EMDUtil.
Constructor The constructor takes MetadataConnection as an argument. The constructor can also return properties from MetadataConnection that were used to start the discovery service; for example, prefix, directory name, and those properties that populate the MetadataObject nodes in the tree. public TwineBallMetadataTree(WBIMetadataConnectionImpl connection, LogUtils logUtils) throws MetadataException { super(connection); this.connection = connection; this.
(Constants.SERVICETYPE)); propertyGroup.addProperty(typeProp); WBISingleValuedPropertyImpl nameSpaceProp = new WBISingleValuedPropertyImpl (Constants.NAMESPACE, String.class); nameSpaceProp.setDefaultValue(Constants.TB_DEFAULT_NAMESPACE); propertyGroup.addProperty(nameSpaceProp); nameSpaceProp.setDisplayName (WBIMetadataDiscoveryImpl.getPropertyName (Constants.NAMESPACE)); nameSpaceProp.setDescription (WBIMetadataDiscoveryImpl.getPropertyDescription (Constants.
ArrayList objects = getTopLevelObjects(); response.setObjects(objects); return response; } WBIMetadataObjectImpl samples: WBIMetadataObjectImpl represents the nodes of the tree that WebSphere Integration Developer displays during enterprise metadata discovery. In most cases these nodes map to objects in the EIS that the user selects to import a service description. WBIMetadataObjectImpl should be extended and the following methods must be implemented.
createSelectionProperties The createSelectionProperties() method returns a property group that is used to capture inputs from users. These inputs include business object namespace, supported operations, and the relative path in the module project where XML schema definitions should be saved. public PropertyGroup createSelectionProperties() { WBIPropertyGroupImpl propertyGroup = null; try { propertyGroup = new WBIPropertyGroupImpl (Constants.SELECTION_PROPERTIES); propertyGroup.
The enterprise metadata discovery service uses WBIMetadataEditImpl to acquire connectionTypes, which contains editable properties forResourceAdapter, ManagedConnectionFactory, or ActivationSpecWithXid. The enterprise metadata discovery tooling creates an instance of WBIMetadataEditImpl during the boot strap process. Along with the name of the MetadataDiscovery class, WBIMetadataEditImpl is specified in the discovery-service.xml file.
dataDesc.prepareChildSchemaFiles(); WBIMetadataDiscoveryImpl.getLogUtils().trace(Level.FINER, CLASSNAME, "preparingChildSchemaFiles", "Preparing SchemaFile for " + bo.getDisplayName()); dataDesc.prepareSchemaFiles(); SchemaDefinition[] schemaFiles = dataDesc.getSchemaDefinitions(); for (int j = 0; j < schemaFiles.length; j++) { SchemaDefinition definition = schemaFiles[j]; put(definition.getNamespace(), definition.getLocation(), definition.getContent()); } } WBIMetadataDiscoveryImpl.getLogUtils().
bometadata.setNameSpace(namespace); bometadata.setObjectNameSpace(Constants.BUS_OBJ_APPINFO_ASI_TYPE_TAG); bometadata.setASI(Constants.ASI_OBJECTNAME, this.getMetadataObject().getDisplayName()); WBIMetadataDiscoveryImpl.getLogUtils().traceMethodExit (CLASSNAME, "getMetadataForBusinessObject"); return bometadata; } // End of BO level metadata isContainer The isContainer() method returns true when the complexType definition requires a Container definition with the graph definition.
WBIMetadataDiscoveryImpl.getLogUtils().traceMethodExit (CLASSNAME, "getImportNameSpaces"); return list; } getNameSpaces The getNameSpaces() method returns the NameSpaces listed in the XML schema definition. Typically these are application specific information schema definition namespaces. Note that this list is for outside namespaces only; child object namespaces are included by the Adapter Foundation Classes. public List getNameSpaces() { WBIMetadataDiscoveryImpl.getLogUtils().
getChildList The getChildList() method returns the Iterator for the child objects of the DataDescription. public Iterator getChildList() throws MetadataException { return (this.getMetadataObject().getChildren(null)).getObjectIterator(); } WBIInboundServiceDescriptionImpl samples: WBIInboundServiceDescriptionImpl represents the object that populates function descriptions for inbound service descriptions. Implement the method shown in the section below.
FunctionDescription[] funcArray = new FunctionDescription[functionDescriptions.size()]; functionDescriptions.toArray(funcArray); super.setFunctionDescriptions(funcArray); } WBIOutboundServiceDescriptionImpl samples: WBIOutboundServiceDescriptionImpl represents the object that populates function descriptions for outbound service descriptions. Implement the method shown in the section below.
dataDescription.setMetadataObject(metadataObj); dataDescription.populateSchemaDefinitions(); dataDescription.setRelativePath(location); dataDescription.setName(getNameSpace() + "/" + metadataObj.getBOName().toLowerCase() + "container", metadataObj.getBOName() + "Container"); outboundFunctionDescription.setOutputDataDescription(dataDescription); } interactionSpec = new WBIInteractionSpec(); if (operation.equals(WBIInteractionSpec.
Creating services that use technology-style adapters relies on being able to implement the interfaces in the commonj.connector.metadata.build.* package or by extending the adapter foundation classes in com.ibm.j2ca.extension.emd.build.* package, or a combination thereof.
processed. A custom function selector can use the information in the InboundInteractionSpec to generate a native function. For a custom adapter, you can create either a smart function selector that utilizes the data or metadata to perform function selection, with or without configuration; or you can implement a simple function selector that always returns a static function name. Implementing a simple function selector restricts your inbound service to a single function.
To access the binding configuration, do context.get(BindingContext.BINDING_CONFIGURATION) To access the expected type, do context.get (BindingContext.EXPECTED_TYPE) Function selectors, data handlers, and data bindings are all configurable. This configuration can be quite rich, providing single and multi-valued properties, drop-downs, and user-editable tables and trees. Every configurable artifact needs to have a Properties bean.
v WBIMetadataBuild v WBIFunctionBuilder v WBIMetadataType (optional) When you extend WBIMetadataBuild, you will need to implement the following methods: v FunctionBuilder createFunctionBuilder(String functionSelector) CreateFunctionBuilder returns your FunctionBuilder instance. v String[] getConnectionSpecClassName(); getConnectionSpecClassName returns the class name of your J2CA connection spec.
Extend WBIMetadataType if your adapter needs a simple wrapper object around a payload object, similar to the IBM WebSphere Adapter for Flat Files and the IBM WebSphere Adapter for FTP. The WBIMetadataType interface allows you to select a payload type, and optionally generate a business graph structure in addition to a plain wrapper. Implement MetadataType interface directly if you need to deal with a more complex object structure.
Initialize input method This method resolves the type of the metadata if it’s a JavaBean or SDO type and initializes the metadata interfaces appropriately. public void initializeInput(DataExchangeFactory dataBinding, Object metadata) throws DESPIException . Purpose of the initialize input method Implement the initializeInput method only if the metadata contains information to be used to initialize the back-end connection for processing the request.
Set managed connection method This method passes the ManagedConnection handle to the record implementation, allowing the record to get access to the physical connection to the backend application to perform processing.public void setManagedConnection( ManagedConnection managedConnection) throws ResourceException Purpose of the set managed connection method This method is called after initializeInput().
the retriveAll operation could return ″N″ records from the backend application, for each call to the getNext() method the implementation should fill in data of one record from the backend application into OutputCursors/Accessors. It should keep track of which record it needs to do next so in subsequent call to getNext() it can fill in next record.
The method should first extract the value from backend object representation defined through Xpath and use OutputCursor and OutputAccessor interfaces to populate values in runtime data structure. Sample Data binding implementation Adapters must provide implementations for DataBinding interface in order to work with WebSphere Process Server. The marshalling of data from SDO to CCI record and from CCI record to SDO occurs through DataBinding implementation.
For operations where getNext() should be invoked multiple times like RetrieveAll, the databinding should call getNext() multiple times add the built BusinessObject to the list of BusinessObjects within the Container BO. getRecord public Record getRecord() throws DataBindingException This method should return the instance of record being build in setDataObject() call or passed through setRecord() call.
v When WBIStructuredRecord is initialized with data that contains Bidi annotations, Cursors and accessors that are associated with that structured record will automatically translate the content into or from the Bidi format specified in the annotations, via special cursors and accessors that wrap the versions provided by the data exchange factory . Problem determination You can implement messages to accompany a range events.
How to support fault handling: Understand the following concepts for implementing fault handling into your adapter. Before you define faults, review adapter processing to determine which error conditions can be categorized as faults, rather than as exceptions. You will likely be able to apply at least one of the faults provided in the Adapter Foundation Classes.
//Added for Faults funcDesc.setName(operation.toLowerCase() + queryDataDesc.getBOName()); getLogUtils().trace(LogLevel.FINEST, CLASSNAME, "getXMLListFunctions", "Setting input data description to: " + queryDataDesc.getName().toString() + " for function: " + funcDesc.getName()); //$NON-NLS-1$ funcDesc.setInputDataDescription(queryDataDesc); funcDesc.
public class JDEXMLListFaultDataDescription implements FaultDataDescription { public JDEXMLListFaultDataDescription() { super(); // TODO Auto-generated constructor stub } private String faultName = null; public String getFaultName() { // TODO Auto-generated method stub return faultName; } public void setFaultName(String faultName) { this.
fdesc2.setGenericDataBindingClassName("com.ibm.j2ca.extension.emd.runtime.WBIFaultDataBindingImpl"); fdesc2.setFaultName(FaultBOUtil.MATCHES_EXCEEDED_LIMIT_NAME); FaultDataDescription desc[] = new FaultDataDescription[] {fdesc1, fdesc2}; funcDesc.setFaultSelectorClassname("com.ibm.j2ca.extension.emd.runtime.WBIFaultSelectorImpl"); funcDesc.setFaultDataDescriptions(desc); } catch (Exception e) { throw new MetadataException( "Unable to create fault BO definitions " + e.
Table 4. Fault name and configured fault binding (continued) Fault Name Configured Fault Binding INVALID_REQUEST com.ibm.j2ca.extension.emd.runtime.WBIFaultDataBindingImpl When input to the operation does not have the required characteristics, the adapter throws this fault.
You can use the FaultBOUtil to define the fault business object, as long as either no attributes or only simple attributes are added. This should amount to a few lines of code, See Implementing Faults for an example. Note: The model for fault classes and fault business objects is a 1-to-1 relationship, the base fault business object cannot be used even if no additional attributes are needed. This is because SCA does not pass back the fault name to the client / server runtime.
– They provide information on the state of the adapter for use by monitor tooling – Represented as common base event data at run time, event messages can be included in the extended LogUtils.log method signatures Support for protecting sensitive user data in log and trace files WebSphere Adapter Toolkit provides support for confidential tracing of properties.
Writing a trace message You use the trace method of the LogUtils class to generate a trace message. This method has two signatures. One of them is informational. The other is associated with an exception.
"getRecordForEvent()", "test"); return null; } } Example of trace message for the outbound scenario with confidential tracing property enabled public HelloWorldConnectionFactory(ConnectionManager connMgr, WBIManagedConnectionFactory mcf) { super(connMgr, mcf); getLogUtils().traceConfidential(Level.FINE, "com.ibm.helloworld.outbound.
Tracing assists developers and troubleshooters. Due to the significant performance cost incurred by tracing, however, many customers disable it in production environments. When developing or troubleshooting, it is good practice to check whether tracing is enabled before building to generate trace messages. You can do this by checking method LogUtils.isTraceEnabled(java.util.logging.Level) before building the adapter. The following is an example: if(logUtils.isTraceEnabled(Level.Fine) { getLogUtils().trace(.
Message types There are two message types for adapters, ADAPTER_RBUNDLE. The BASE_RBUNDLE is reserved for the Adapter Foundation Classes. The message types are used to distinguish between the adapter and the base classes message file. The default value of Message Type field is ADAPTER_RBUNDLE. You use only the ADAPTER_RBUNDLE message type because you should only access adapter message file. Log levels Log Levels and indicators Level Indicator Significance Fatal F Task cannot continue.
translated text. Values that are language-independent, such as key values or object names, are appropriate as log message parameters. Similarly to trace messages, parameters in a log message can contain data from the customer’s EIS.
Example of log message for the inbound scenario with confidential tracing property enabled public javax.resource.cci.Record getRecordForEvent(com.ibm.j2ca.extension.eventmanagement.Event event) throws javax.resource.ResourceException, javax.resource.spi.CommException { logger.logConfidential(Level.INFO, LogUtilConstants.ADAPTER_RBUNDLE, "com.ibm.helloworld.inbound.
public interface EventSourceContext { /** * Returns an event source for a monitored element. * @param elementKind an artifact kind that can be monitored e.g ResourceAdapter. * @param elementName the name of the monitored element * @return the event source object that encapsulates the element to be monitored */ EventSource getEventSource(String elementKind, String elementName); /** * Creates an event source for a monitored element. The usage is similar to * java.util.logging.Logger.
* The client of an event point needs to know the payload of the */ public interface EventPoint { /** *return the name of the event point */ fired events. String getName(); /** * Checks if an event needs to be fired for this event point. This method minimizes the * overhead of inactive monitoring * points. returns: true if this event point fires monitoring events. */ boolean isEnabled(); /** * Fires a monitoring event. * @param name the name of the payload data element.
CEI PAGE 191targetNamespace="http://www.ibm.com/xmlns/prod/websphere/scdl/eis/6.0.0:JCAAdapter" xmlns:er="http://www.ibm.com/xmlns/prod/websphere/recovery/6.0.0/es/eventpayloads" > 3.
Purpose 1. Monitorable Element Schema (.mes) file changes Defines the element type within an adapter where monitoring can be attached. The element type is specified using the Qname of the element type from the schema, which defines the structure of the artifact itself. It also defines the natures (ENTRY, EXIT, FAILURE) that are available for that type of element. The sample below declares how the monitors can be attached to myOutbound.
d. If eventPoint is enabled, then fire event for Entry, Exit and Failure is invoked. Entry event is fired in the beginning of the method call, exit event is fired in the end of the method call and failure event is fired in case of exception. For example we can invoke failure event by following API call. if(ep.isEnabled()) { ep.fire(new String[]{"FailureReason"}, new Object[]{ex.
v v v v Is a transaction (and the application) hung, or are transactions failing? What is the response time? Are service level commitments being met? Who uses the application and how many of each transaction are used? The resource adapters are instrumented with the Application Response Measurement API, an API that allows adapters to collect and manage transaction end-to-end response time and volumetric information.
statistics and data for each ManagedConnection, which can be used to assess and troubleshoot performance related problems. In order for resource adapters to participate in various WebSphere RequestMetric tools for outbound, diagnostic tools, etc, you will need to follow these steps: 1. Import com.ibm.websphere.j2c.*; 2. Get interaction metrics listener by using WBIManagedConnection classes’ getInteractionListener() method or by calling WBIInteraction classes’ getInteractionListener() method. 3.
FFDC processing overview Instead of explicitly instrumenting catch blocks by calling FFDC directly, either manually or by using a tool, you can write a simple aspect using the AspectJ language, which encapsulates the FFDC policy for your code. The FFDCSupport aspect is abstract. Like an abstract class, FFDCSupport cannot be instantiated and defers some of its implementation to a sub-aspect.
import com.ibm.websphere.ffdc.FFDCSupport; public aspect Example_3 extends FFDCSupport { protected pointcut ffdcScope () : within(com.foo.*) && !within(com.foo.Goo); } In Figure 3 aspect Example_3 has the same effect as Example_1 except it excludes FFDC for class com.foo.Goo by using the && and ! operators to form a pointcut expression. Figure 9. Add FFDC to all classes in the com.foo package excluding com.foo.Goo import com.ibm.websphere.ffdc.
import com.ibm.websphere.ffdc.FFDCSupport; public aspect Example_6 extends FFDCSupport { protected pointcut ffdcScope () : within(com.foo.*); public pointcut ffdcCall () : call(* com.ibm.websphere.ffdc..*(..)); declare warning : ffdcCall() && ffdcScope() : "Don't call FFDC directly. Use FFDCSupport aspect."; public pointcut dumpException () : call(void Throwable.printStackTrace(..)); declare warning : dumpException() && ffdcScope() : "Don't dump exceptions to console. Use FFDCSupport aspect."; } Figure 12.
Exception messages Exception messages, like trace messages, convey information about problems. The difference is that exception messages are tailored more directly to support teams familiar with adapter source code, and therefore need not be translated. Treat text included in exception messages as you would text for trace messages. In general, exception messages are not directed at general users but rather at support teams who have the ability to investigate adapter source code.
To test the enterprise metadata discovery (EMD) implementation for the developed resource adapter, complete the following steps: 1. From the IBM WebSphere Adapters Foundation Classes library, copy the following three dependent jars into the connectorModule connector project: v commonj.connector.jar v CWYBS_AdapterFoundation.jar v DESPI.jar Displaying the dependent jars Note: Alternatively, if you want to export the jars as RAR, you can use the AFCUtility tool to place these three jars into the RAR.
JUnit: an open source framework for unit testing JUnit is becoming the standard tool for unit testing in Java development environments. JUnit allows you to quickly and easily integrate automated regression testing into your coding and build processes. With JUnit, an open source unit test framework, you can write and run tests for your adapter implementation. You use a simple setup() method to prepare each component for testing. Each test method can contain one or more assertions.
Your adapter may or may not be dependant on ″live″ data inside the EIS. If so, you must either return the data to a known state after every test, or create a mock implementation of the EIS API so that EIS data remains untouched. setUp() In the setup method for outbound, perform the following step: 1. Load any schemas (if necessary) Test When you have completed the steps for setting up the test, you are ready to call the CCI interaction and validate the result.
setUp() The setUp() method for inbound is very similar to that for outbound. You may, however, not need an outbound connection through the adapter. Accordingly, you need only perform the following tasks: 1. Create an adapter instance and set its properties 2. Start the resource adapter. Test The test methods for inbound must do the following: 1. Prepare the data inside the EIS. In a polling adapter, this would cause the triggers to fire, populating the event table. 2.
For information on testing the adapter in managed mode in WebSphere Application Server, see Validating code with Rational Application Developer / Websphere Application Server. Installing the test client To test your adapter in a runtime environment, you must first install a test client on the target WebSphere Process Server. 1. Install the test client, TestController.ear, on the target WebSphere Process Server. Locate the file \eclipse\plugins\ com.ibm.wbit.comptest.
Test module configuration 3. Select the testing mode and click Finish to start the test. On the Deployment Location screen, select a WebSphere Process Server to test in managed mode (optionally you can select Eclipse to test in unmanaged mode). In addition, you select Run or Debug mode. If you select Debug mode, you can set breakpoints in your code; when the test reaches a breakpoint, WebSphere Integration Developer displays the Debug perspective. A screen informs you that the test is running.
Adding a value to the Datapool This adds the data to Datapool. When you want to use this input data again, select Use Value from Pool. Using an execution trace The test client you installed provides you with a trace of the execution and the data path of the test. You can optionally load any previously saved execution trace into the test client. This enables you to renew a test session at the point where you saved the execution. The procedures below describe how to load and save an execution trace file. 1.
After you have created and exported an adapter EAR file with the service type set to Inbound, you can test inbound functionality. 1. Edit your module using the Assembly Editor, connecting the export to a Java component. a. Double-click on the module to start the Assembly Editor. b. Create a new Component by selecting the Component with no implementation from the first option. c. Add a wire by clicking the export and dragging it to the component. Wiring a component d. Click OK in the next window. e.
Selecting the Java package g. Save the module. 2. Publish the application to WebSphere Process Server. 3. Open the administration console for the WebSphere Process Server and configure the application’s activation specifications so that it can process inbound requests. 4. Restart the inbound application and ensure that it is polling. 5. To start testing, select the module from the Navigation window, right-click and select Test → Attach . The test client displays the Events window. 6.
Validating code with Rational Application Developer and WebSphere Application Server To test the adapter in the Websphere Application Server environment, use the javabean generation capability of EMD to generate records and a java proxy interface to the adapter. Then generate a session bean that will call this interface, and use the Websphere universal test client (UTC) to send data to the adapter. 1.
4. In the Resource Adapter deployment panel, choose how to deploy the adapter. You can deploy the adapter with the EAR or you can deploy the adapter as a stand-alone component. 5. Click Finish to generate the code. Once the EJB is generated you can send data to the adapter and examine the return values using the UTC. 6. Use the UTC to validate that the adapter can process data Publish your EAR project to the server using the Add and Remove projects option.
7. Start UTC using the Run universal test client option.
8. Once the UTC comes up, use the JNDI explorer to find your EJB. Look for your session EJB under EJB Beans. Now, you can test your adapter via the EJB interface. You can create a session bean using the home interface (create), then invoke business methods on the remote interface, providing the appropriate data. This works the same way as testing any session bean.
Note: External service discovery is equivalent to enterprise metadata discovery. f. Select the appropriate external service. g. Specify the connection properties, metadata, and service functions. h. On the Saving Properties pane, save the properties to the module you created in Step d. i. Save the file. 2. Add the target server to WebSphere Integration Developer. Note: If you have not done so, you must add the target server–WebSphere Process Server–to WebSphere Integration Developer.
Reference Terminology The terminology presented are of terms that are used frequently in the documentation. Adapter foundation classes (AFC) Sometimes referred to as base classes, the adapter foundation classes are a common set of services for all IBM WebSphere resource adapters. The Adapter Foundation Classes conform to, and extend, the Java 2 Connector Architecture JCA 1.5 specification.
Eclipse An open source infrastructure for building tools such as an Integrated Development Environment (IDE). The toolkit’s wizard and editor are Eclipse plug-ins. Eclipse Plug-in A module that extends the functionality of the Eclipse Platform Editor A component in Eclipse that allows data to be edited. Editors may perform syntax validation. Enterprise information system (EIS) The applications that comprise an enterprise’s existing system for handling company-wide information.
Outbound Outbound is a description of the direction in which data and messages pass from a J2EE client application to the EIS. Adapters support both inbound and outbound data flow. Performance monitoring infrastructure (PMI) A set of packages and libraries assigned to gather, deliver, process, and display performance data. PMI is the underlying framework in WebSphere Application Server that gathers performance data from various runtime resources such as adapters.
Notices This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used.
Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact: IBM Corporation Department 2Z4A/SOM1 294 Route 100 Somers, NY 10589-0100 U.S.A. Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.
this code are derived from IBM Corp. Sample Programs. (c) Copyright IBM Corp. _enter the year or years_. All rights reserved. If you are viewing this information softcopy, the photographs and color illustrations may not appear. Programming interface information Programming interface information, if provided, is intended to help you create application software using this program. General-use programming interfaces allow you to write application software that obtain the services of this program’s tools.
214 WebSphere Adapters: WebSphere Adapter Toolkit User Guide
Index Special characters C .
G M generation options 35 H hardware requirements 12 I implementation overview 68 Inbound callback event notification 90, 91, 92, 94 callback event sender 91 callback event sender constructors 92 event notification 79 one way callback events 90 operations 72 request and response callback events 90 standard 72 using adapter foundation classes 91 with XA transaction 94 inbound adapter classes 37 Connection pooling 37 Event polling 38 inbound callback event 38 properties 37, 38 inbound JCA adapter classe
V verbs usage business graph 71 W WBIActivationSpec 37 WBIAdapterTypeImpl 39, 141 WBIConnection 35, 102 WBIConnectionFactory 35, 101 WBIConnectionRequestInfo 104 WBIDataBindingGenerator 38 WBIDataDescriptionImpl 39, 151 WBIInboundConnectionConfigurationImpl 39, 146 WBIInboundConnectionTypeImpl 39, 143 WBIInboundServiceDescriptionImpl 39, 155 WBIInteraction 35, 102 WBIInteractionSpec 35, 103 WBILocalTransaction 35 WBIManagedConnection 35, 100 WBIManagedConnectionFactory 35, 99 WBIMetadataDiscoveryImpl 39,
218 WebSphere Adapters: WebSphere Adapter Toolkit User Guide
Printed in USA
