IBM WebSphere Adapters manual

WebSphere ® Adapters WebSphere Adapter T oolkit User Guide Version 6 Release 2 Version 6 Release 2 [...]

[...]

WebSphere ® Adapters WebSphere Adapter T oolkit User Guide Version 6 Release 2 Version 6 Release 2 [...]

Note Before using this information and the pr oduct it supports, read the information in “Notices” on page 21 1. December 2008 This edition applies to version 6, release 2, modification 0 of and to all subsequent r eleases and modifications until otherwise indicated in new editions. T o send us your comments about this document, email mailto://[...]

Contents WebSphere Adapter T oolkit ...... 1 IBM W ebSpher e Adapter T oolkit technology overviews ............... 2 IBM W ebSpher e 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 W ebSpher e Adapter T oolkit overv[...]

iv W ebSpher e Adapters: W ebSphere Adapter T oolkit User Guide[...]

W ebSphere Adapter T oolkit The IBM ® W ebSphere ® Adapter T oolkit provides the development tools, libraries and sample code to assist you in creating JCA resour ce adapters. W ith 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 p[...]

The development process using the IBM W ebSphere Adapter T oolkit includes the following as shown in the illustration: 1. Run the New JCA Resource Adapter Project wizard. The wizard generates a r esource adapter deployment descriptor and code. The code can include sequence of calls, log and trace messages and comments. 2. Use the Resource Adapter D[...]

Inbound event notification complements outbound request pr ocessing, enabling adapters to provide bidir ectional communication between business processes and EIS applications. The IBM W ebSphere Adapter portfolio of adapters is based on the Java 2 Platform, Enterprise Edition (J2EE) standard. JCA is a standard ar chitecture for integrating J2EE app[...]

W ebSphere adapters utilize a format-independent data model for repr esenting data objects. In a W ebSphere Process Server or W ebSphere Enterprise Service Bus runtime envir onment, W ebSphere adapters use an extension of the service data objects (SDO) for repr esenting data objects. Architectural overview In conjunction with the appropriate EIS-sp[...]

processing performed by each component (and subcomponent) in the model is described in sections that follow the illustration. The component model allows for a single architectur e for adapter development and evolution. It uses recognized standar ds but extends them as necessary , for example with high performance, runtime-independent data exchange [...]

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 standar d JCA CCI interfaces, which include Connection, ConnectionFactory , Interaction and InteractionSpec for outbound processing and Resour ceA[...]

the appropriate pr ogramming 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 pr ogramming model, delivers the application component. The application[...]

V ersion 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 inter[...]

– The New Connector Project W izard - Prompts you to specify information about the resour ce 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-pa[...]

v Generate a resource adapter deployment descriptor Y ou 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 r esource adapter deployment descriptor generated by the wiz[...]

IBM W ebSphere Adapter T oolkit tasks The tasks range from installing the toolkit, samples, and Adapter Foundation Classes (using the Eclipse Update Manager in W ebSphere Integration Developer) to implementing and validating your code. T able 1. W ebSphere Adapter T oolkit tasks T ask T ask description V alidate W ebSphere Adapter T oolkit installa[...]

Operating system V ersions W indows 2000 W indows 2000 Professional (SP4) W indows 2000 Server (SP4) W indows 2000 Advanced Server (SP 4) W indows XP W indows XP SP 2 W indows 2003 W indows Server 2003 Standard W indows Server 2003 Enterprise Hardware requirements The table shows the hardwar e requirements for supported operating systems. Operating[...]

This documentation describes how to run the T wine Ball sample only . However , you can apply the instructions for running and testing the T wine Ball sample to the Kite String sample. The sample instructions accommodate cr eating an adapter for the T wine Ball sample using W ebSphere Integration Developer , for deployment to a W ebSphere Process S[...]

This launches the Samples. c. From the Samples navigation pane, select T echnology samples and expand Java and W ebSphere Adapters so that the T wine Ball and Kite String samples display . d. Click T wine Ball to display a description of the T wine Ball sample in the viewing pane of the T echnology Samples. 2. From the viewing pane of the T echnolo[...]

c. Optional: Deselect the Add project to an EAR check box. 4. Click Finish . A dialog prompts you to open the J2EE perspective. Click Ye s to finish the process of importing the deployable RAR file for the T wine Ball sample into your workspace. Now you can perform external service discovery for the T wine Ball sample. Run external service discover[...]

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 T wineBallConnector (IBM:6.2) , select CWY A T_T wineBall and click Next . 16 W ebSphere Adapters: W ebSphere Adapter T oolkit User Guide[...]

7. From the Pr ocessing Direction window , select Outbound and click Next . 8. From the Discovery Configuration window , click Next . No connection properties ar e required. 9. From the Object Discovery and Selection window , select CUSTOMER fr om the Discovered objects pane and add it to the Selected objects portion of the window then click Next .[...]

10. From the Configur e 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 W ebSphere Adapters: W ebSphere Adapter T oolkit User Guide[...]

12. From the Service Location Pr operties window , click New . This launches the New Integration Project window . 13. From the New Integration Pr oject window , select Create a module project and click Next . 14. Enter values in the New Module window and click Finish . Y our module displays in the Project explorer view: W ebSphere Adapter developme[...]

15. Click Finish from the Service Location Pr operties window to add the outbound interface to the module. 16. Y ou are prompted on whether you want to update the model, select Ye s . Run the external service discovery process again to add the inbound interface to the module. Run external service discovery for inbound processing The external servic[...]

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 T wineBallConnector (IBM:6.2) , select CWY A T_T wineBall and click Next . W ebSphere Adapter development overview 21[...]

7. From the Pr ocessing Direction window , select Inbound and click Next . 8. From the Discovery Configuration window , click Next . No connection properties ar e 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 W ebSphere Adapters: W ebSphere[...]

10. From the Configur e 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 . W ebSphere Adapter development overview 23[...]

12. From the Service Location Pr operties window , click Finish to add the inbound interface to the module. 13. Y ou are prompted on whether you want to update the model, select Ye s . Y ou 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[...]

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 fr om 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 sele[...]

4. Run the administrative console and verify the module is installed and running. 5. T est the module by performing the following steps: a. Change to the Business Integration perspective b. Right click on the module and select T est → T est Module c. Populate the customer object fields with data. d. Click the continue button. e. Look for this mes[...]

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 [...]

6. On left side select EJBSessionBean1 and click Customer createCustomer(Customer) Enter input customer parameters T roubleshooting the samples Y ou may need to troubleshoot issues that arise when creating or r unning the samples. Errors The following errors may r esult when working with the sample code: v A com.ibm.adapter .framework.BaseException[...]

Launching the New Connector Project wizard Y ou launch the wizard from IBM W ebSphere Integration Developer . Make sure you have met all of the installation r equirements and that you have successfully installed W ebSphere Integration Developer and the W ebSphere Adapter T oolkit plug-ins. Launch the New Connector Project wizar d when you are ready[...]

Select a wizard dialog 5. Start the wizard. Expand the Java EE folder , choose Connector Project , and click Next . This starts the New Connector Project wizar d and displays the Connector Project dialog. Connector Project dialog Y ou are ready to describe your pr oject and resource adapter pr operties. 30 W ebSphere Adapters: W ebSphere Adapter T [...]

Specify project properties Y ou name your connector project, optionally adding it to an Enterprise Application project. Y ou also specify the configuration used for developing the resource adapter . Y ou perform all of these tasks from the Connector Project dialog. Connector Project dialog 1. Name your Connector Project. Enter a project name in the[...]

Specify project facets As part of the process of cr eating a project, you specify project facets . A project facet repr esents a unit of functionality in the project. Project facets define characteristics and requir ements for projects. When you add a facet to a project, that pr oject is configured to perform a certain task, fulfill certain r equir[...]

2. Click Next to advance to the Resource adapter pr operties page. Now you are r eady to set the properties for the resour ce adapter . Specify resource adapter properties Resource adapter pr operties are the descriptive properties that you assign to both the adapter and the adapter class. Y ou name the adapter and qualify its Java class with a pac[...]

1. In Adapter Name , type the name of the adapter . 2. In Adapter ShortName , type a one- to four-character short name for the adapter . The short name is used to create the component name that is used in the log and trace files as follows: ShortName + the characters “RA” + the value of the adapter ID property , which the user specifies when co[...]

For information on the characteristics of an IBM W ebSphere Resource Adapter and a J2C Resource Adapter , see Introduction to JCA. Generation Options dialog From the Adapter Specification dr op-down, choose the type of adapter you want to create: v Choose IBM W ebSphere Resource Adapter in the Adapter Specification list to generate code that extend[...]

Y ou 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. LocalT ransaction indicates the IBM W ebSphere adapter supports local transactions. Local transaction suppor[...]

/** * 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 th[...]

When you choose the connection pooling component property the wizar d 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 po[...]

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 ar e no properties associated with Enterprise Metadata Discovery classes. Generating enterprise metadata discovery classes creates code for the methods n[...]

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 fr [...]

Generating outbound local transaction support methods: W ith local transaction support, the transaction is managed and performed by the EIS. LocalT ransaction indicates the IBM W ebSphere adapter supports local transactions. Local transaction support methods provide a LocalT ransaction implementation and return the wrapper . Consider your strategy [...]

Generating outbound XA transaction support methods: W ith 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 consider ed a global transaction. Review the section on XA transaction support in Generating an I[...]

Review the section on command pattern classes in Generating an IBM W ebSphere Resource Adapter . The command pattern classes allow you to break down a hierar chical update into a series of nodes and then generate a collection of sub-commands to manage the nodes. An interpreter pr ocesses the sub-commands, retrieving and executing the corresponding [...]

2. Review the available component property options associated with inbound adapter classes. Each of the component property options ar e described in the sections that follow . Generate the inbound adapter classes for the component property selected. Note: Before deploying your adapter to W ebSphere Pr ocess Server version 6.2, you must populate all[...]

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 r ecords from the event store at r egular intervals. In each poll call, a number of events are processed by the adapter . Review the information on inbound adapter clas[...]

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 notif[...]

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 W ebSphere Integration Developer to introspect an EIS to cr eate business objec[...]

2. When you are finished choosing generation options, click Finish . Generate data binding classes. Generating data binding classes Y ou can generate data binding classes separate from the data binding classes that are generated fr om enterprise metadata discovery . Review the section on data binding classes in Generating an IBM W ebSphere Resource[...]

2. When you are finished choosing generation options, click Finish . Learn how to generate a JCA resource adapter . Generating a JCA resource adapter Y ou use the wizard to generate adapter classes that correspond to the pr operties and options you specify . The following sections describe the J2EE resour ce adapter classes. Outbound JCA resource a[...]

v ManagedConnectionFactory implements javax.resour ce.spi.ResourceAdapterAssociation, javax.V alidatingManagedConnectionFactory , ManagedConnectionFactory v MangedConnection implements javax.resour ce.spi.DissasociatableManagedConnection, ManagedConnection v ManagedConnectionMetaData implements ManagedConnectionMetaData For information on how to ge[...]

v EditableT ype implements commonj.connector .discoveryEditableT ype v MetadataDiscovery implements commonj.connector .discovery .MetadataDiscovery v MetadataEdit implements commonj.connector .discovery .MetadataEdit v MetadataImportConfiguration implements commonj.connector .discovery .MetadataImportConfiguration v MetadataObject implements common[...]

implements javax.resour ce.runtime.SingleT ypedProperty and javax.resour ce.runtime.PropertyDescriptor v SingleV aluedProperty implements javax.resour ce.runtime.SingleV aledProperty and javax.resour ce.runtime.PropertyDescriptor v PropertyGroup implements javax.resour ce.runtime.PropertyGroup and javax.resour ce.runtime.PropertyDescriptor v MultiV[...]

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 r esponsible 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 resour ce ada[...]

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 W ebSphere Integration Developer to introspect an EIS to cr eate business objects a[...]

2. When you are finished choosing generation options, click Finish . Generated code and deployment descriptor The generated artifacts reflect the adapter classes with the pr operties and options you specified. After you specify options for your resour ce adapter , the wizard generates code and a deployment descriptor in a Connector Project and then[...]

Using the Resource Adapter Deployment Descriptor editor The Resource Adapter Deployment Descriptor editor provides an easy and convenient way to configure your r esource adapter . Resource Adapter Deployment Descriptor editor Y ou configure the resour ce adapter by using a deployment descriptor . The deployment descriptor—the ra.xml file— is ge[...]

Deployment descriptor Overview pane Alternatively , you can view the deployment descriptor in the editor by highlighting the file in the Project Explor er and selecting Open With → Deployment Descriptor Editor from the context menu. Displaying the descriptor editor from the context menu Y ou can display each of the four views by using the tabs at[...]

Using the Overview pane The Overview pane provides access to general information about your r esource adapter . Y ou 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 r esource adapter , you can generate components that you may not have originally specified wh[...]

Add component dialog The Icons section of the overview pane allows you to associate icons with the resour ce adapter . Y ou can specify a large or small icon in jpg or gif format. T o fit into the allotted area, the lar ge icons must be 32 x 32 pixels and the small icon 16 x 16 pixels. W ebSphere Process Server does not make use of these icons. Usi[...]

Resource adapter pane The General Information section allows you to specify deployment descriptor values for the entire r esource adapter . This section displays the name of the ResourceAdapter class with which this deployment descriptor is associated. This class must directly or indir ectly implement the javax.resource.spi.Resour ceAdapter interfa[...]

Add Config property dialog When you add, modify , or delete user-defined pr operties in this section, the editor creates (or r emoves) the corresponding Java bean properties in your code. For more information, see Modifying pr operties. The Admin Objects section allows you to specify administered objects for this resour ce adapter and configure the[...]

The sections of the Outbound Adapter pane are described below . Outbound resour ce adapter pane The General Information section allows you to specify deployment descriptor values associated with the outbound resour ce adapter . Y ou can specify the level of transaction support, if any , and whether reauthentication is supported. The Connection Defi[...]

Add Connection Definition dialog A Connection Definition requir es the following information: v ConnectionFactory Interface v ConnecitonFactory Implementaion Class v Connection Interface v Connection Implementation Class v ConnectionRequestInfo Class v ManagedConnectionFactory Class Once a connection definition is defined all properties inherited b[...]

Add Config property dialog When you add, modify , or delete user-defined pr operties in this section, the editor creates (or r emoves) the corresponding Java bean properties in your code. For more information, see Modifying pr operties. The Authentication Mechanisms section allows you to specify the authentication mechanism(s) supported by the reso[...]

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 ActivationSpecW ithXid are shown in the pr operties list directly under the ActivationSpecW ithXid Class. Y ou c[...]

Add Required Config Pr operty dialog When you add, modify , or delete user-defined pr operties in this section, the editor creates (or r emoves) the corresponding Java bean properties in your code. For more information, see Modifying pr operties. Modifying deployment descriptor properties When you modify configuration properties, the Resour ce Adap[...]

Generated bean properties The editor maps resour ce adapter properties to class code. When you modify the resour ce adapter , the editor performs automatic source code updates. The table shows the generated code affected when you add, delete, or modify a configuration property: Class code affected by configuration property change Configuration prop[...]

Y ou can now view or modify the raw ra.xml file using the default editor provided by W ebSphere 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 ar e displayed in the Problems pane. Important: When using the Resource [...]

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 pr ocessing in general–this will probably be a combination of those you’ve defined in 1a and 1b for outbound. d. Establish a list of rem[...]

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 ef ficiency in processing and reduced bandwidth requir ements for exchanging data. v The b[...]

changes. For outbound requests, the adapter must interpr et 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. V erbs A verb i[...]

Convert business object names from EIS-assigned formats to a camel case format (remove separators such as spaces or underscor es and capitalize first letter of each word). For example, convert the EIS name, ORDER_LINE_ITEM, to Or derLineItem. As described in the W ebSphere business object specification, name the parent business object graph for the[...]

Outbound Operation Signatures Notes applyChanges<BOType> create<BOType> update<BOType> delete<BOType> 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 requir ed by the business object struc[...]

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: W ebSphere business objects support an isSet property . isSet property The isSet() AP[...]

2. If the EIS does not generate its own primary key (or keys), insert the key values from the input business object into the appr opriate key column (or columns) of the EIS entity . 3. Update the output business object to reflect the values of the newly cr eated EIS entity; this includes any EIS-generated key values or properties marked as having p[...]

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 thr own by create and delete operations plus the following: RecordNotFoundException is thrown if the EIS does not contain an entity wit[...]

The InvalidRequestException exception is thrown if input to the operation is not supported. The EISSystemException exception is thrown if the EIS r eports any unrecoverable errors. Retrieve: This operation rebuilds the complete business object hierar chy . The adapter ensures that the returned hierar chical business object matches exactly the datab[...]

CCI clients of resour ce adapters that support batch results must be capable of recognizing a top-level container and iterating thr ough the child objects that repr esent 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 r esult set regardless of how many (if any) matches are found. Processing overview RetrieveAll processing is as follows: RetrieveAll should make the adapter ready to r eturn multiple objects. For each of the objects that will be returned, the ″ getNext() ″ method will be called. Each call to ″ [...]

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 fr om 10 to 100, to a complete document or binary payload such as an insurance claim form submitted in XML. Although each EIS ap[...]

Event Store Requirements 1. Event data must be persistent. Once detected in the event store, an event should remain available ther e 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 recor ds in the event store. Adapter Requirements[...]

During recovery , W ebSphere Application Server calls the resource adapter , queries it for XAResources, and then performs transaction r ecovery as follows: v T ransactions that the J2EE container rolls back have not been delivered and ar e marked NEW . v T ransactions that the J2EE container commits have been delivered; these are deleted. Implemen[...]

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 r etrieve the full entity in the EIS for which this event was originally recor ded. The structure and content of this key [...]

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 fr om those in process or ineligible. The adapter must support five differ ent event status values as described in the table below . All events generated by the event detection mechanism in the EIS should be in t[...]

Field Description eventT ype Corresponds to the Business Object Name field of the event recor d timeStamp Corresponds to the T imestamp field of the event recor d eventStatus Corresponds to the Status field of the event recor d Event detection: Events detection mechanisms reflect the sour ces that trigger them: user actions in the application, batc[...]

5. Set the name of the W ebSphere business object complexT ype 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 r etrieval in the adapter uses two Foundation Classes interfaces. The goals are setting up event polling and a safe, reliable c[...]

Method Description ArrayList getEvents(int quantity, int eventStatus, String[] typeFilter) This method enables the adapter to determine if there ar e any new events available or old events that need re-sending. Implement this method to query the event store and r eturn a list of event instances (up to the limit specified by the quantity parameter )[...]

EventStore transaction contr ol 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 requir ed only if transactions are supported. void rollbackWork() This method should rollback any uncommitted work. [...]

Function selector: Function selectors map resour ce adapter events to corresponding SCA export function names. The W ebSphere Adapter component that exposes resour ce adapters as SCA components requir es what is known as a function selector . This selector maps events generated by resour ce adapters to a SCA export function name. For example, an ad[...]

When you enable inbound callback event notification, business processes ar e 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 pr ocesses of a change, as opposed to the polling mechanism used in event notification. Callback event notificati[...]

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 assur e once-and-only-once event[...]

The sendWithReturn methods invoke onMessage on the InboundListener . This method delivers the Record it r eceived from the listener thread. Her e the differ ence is the onMessage method will be invoked on the InboundListener to deliver the Record to the endpoint. The method would r eturn ″ Record ″ as returned by onMessage method. The sendWithN[...]

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.activation[...]

Callback event processing for event delivery with XA transaction T o provide data integrity and to make sure events ar e not delivered more than once, which would cause errors in the downstr eam 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 the adapter signals that it has completed delivery , the transaction manager will then call ″ end ″ , ″ prepar e ″ , and ″ commit ″ to complete the requirements outlined in the XA transaction protocol. When the ″ prepar e ″ call is made, the XA implementation will call ″ setT ransactionID ″ on the eventPersistance implement[...]

Callback event processing for event recovery When there is a failur e in the event processing as part of system recovery , the adapter is able to recover the unpr ocessed events by implementing the once-one-only delivery mechanism. During real time event pr ocessing if any component of the business integration system fails then the adapter must pro[...]

When the container starts, it calls the getXAResources() method on the adapter to get all the associated XA resources. The adapter then instantiates the appr opriate XA resource and r eturns it back to the container . The JCA container now calls the recover() method on the returned XAResourceImpl to get all the pending transactions fr om the config[...]

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 r equires some type of authentication. In a JCA environment, application authentication is known as sign-on . It can be performed in one of two [...]

7. The ConnectionManager may call getConnection(Subject, ConnectionRequestInfo) o na 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 ConnectionReques[...]

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[...]

Best practices v Each ManagedConnection instance should encapsulate at most one connection to the EIS. v Since there may be mor e than one Connection instance for each ManagedConnection instance, resour ce adapter developers should implement private contracts between their WBIManagedConnection subclass and their WBIConnection/WBIInteractionsubclass[...]

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.resour ce.cci.ConnectionSpec instance to pass request-spec[...]

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 { WBI[...]

properties should not change the configuration of the EIS. javax.resource.cci.ConnectionMetadata: A javax.resource.cci.ConnectionMetadata instance pr ovides information to the client components about the underlying EIS of a resour ce adapter . Client components can use the javax.resour ce.cci.Connection.getMetadata() interface to retrieve connectio[...]

3. Override method WBIManagedConnection.getLocalT ransaction() and, if XA support is provided, method WBIManagedConnection.getXAResour ce(). W rap either or both of the LocalT ransaction or XAResource instances r eturned by these methods with a WBILocalT ransactionW rapper or WBIXA T ransacxtionW rapper instance, respectively . These wrappers provi[...]

Adapters are r esponsible for creating, updating, retrieving, and deleting (CRUD) recor ds 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 pr ocessing 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 structur e. Child B1, then, must be deleted. The Command Manager will execute a Retrieve command to build the structur e as it appears in the EIS, then compare this structur e to the incoming object tree. The comparison finds that child B1 is deleted. Accordingly , [...]

Command Manager Delete Delta objects Delta processing is only r elevant 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 r eads the change summary for the intended changes. Note that since a child object might be changed without any[...]

Suppose, as in the example below , that child B1 is created and is part of the change summary . The resulting command str ucture will contain a Cr eate command for child B1, and will have NO-OPERA TION parents linking it back to the top level parent. W ebSphere Adapter development overview 109[...]

Command Manager Create When it processes this str ucture, the interpr eter 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 sim[...]

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 cr eates a top-level command repr esenting the operation for the top-level incoming cursor . As processing continues, sub-commands ar e added at the child obj[...]

The Command Manager processes delta str uctures in a manner analogous to that of after-image data. The dif ference is that, for delta objects, comparative data is extracted from service data object change summaries. When the input service data object (SDO) repr esents an Update operation with a delta structur e, the Command Manager will look up the[...]

Y ou 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.execut[...]

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(NodeL[...]

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 pr ovided in the AFC and ar e abstracted from the adapters which use the DESPI APIs to process data in a format-independent way . XSD and JavaBean structure rela[...]

T able 2. Mapping between built-in XSD schema and JavaBean properties (continued) Header Header anySimpleT ype String Any String There ar e cases in which a simple XML data type must be mapped to the corresponding Java wrapper class for the Java primitive type: v an element declaration with the nillable attribute set to True v an element declaratio[...]

The notion of whether or not a property is set is critical to pr ocessing 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[...]

As defined in the sapBAPIBusinessObjectT ypeMetadata schema ″ Operation ″ is an n-cardinality complex type. The ″ MethodName ″ element of the operation type is a simple type with multiple cardinality: <complexType name="sapBAPIBusinessObjectTypeMetadata"> <sequence> <element name="Type" type="string&q[...]

objectAnnotationsMap ObjectName WBI_CUSTOMER_CI Operation operationsList createOperationsMap Name Create MethodName MethodNameList operationList updateOperationMap createOperationMap methodNameList wbiCustomerCreate The Metadata API Advanced implementations of adapters are metadata-driven. This implies that the adapter is not hard coded for each ob[...]

These interfaces may contain more helper methods than ar e listed here, please see the Javadoc for the additional helpers. Factory classes Class T ypeFactory: T ypeFactory creates an instance of an implementation of T ype. The T ypeFactory is also capable of detecting whether SDO version 2, SDO version 1, or neither is present in the classpath, all[...]

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 represe[...]

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[...]

Support for GeneratedRecords artifact type: W ebSphere adapters may support JavaBeanRecord data r epresentation along with SDO 1.0 and SDO 2.0 data objects. As part of the support for JavaBean data repr esentation, the adapter foundation classes provides a JavaBeans r ecord generator class that can generate DataBindingDescriptions for the object ty[...]

The enterprise metadata discovery component is analogous to the Object Discovery Agent of W ebSphere Business Integration Adapters. In addition to generating business object definitions, however , the enterprise metadata discovery also generates service component architectur e artifacts such as an Import/Export file and WSDL. An explicit goal of en[...]

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 repr esented by a collection of properties al[...]

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 architectur e Note: The solid arrows r epresent the enterprise metadata discovery implementation in the above diagram. The[...]

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 pr ovided by the resource adapter pr ovider or a third party discovery service pr ovider . These are the data binding interfaces that are used to integrate [...]

for multiple back-end EIS assets. IBM W ebSphere 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, Peopl[...]

copy matching properties fr om 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, Pe[...]

MetadataConnection The MetadataConnection object repr esents the connection to EIS or EIS repository . This interface is implemented by the Adapter Foundation Classes only and does not requir e any implementation from discovery service instances. MetadataConnection uses the managed connection factory to create the connection to the EIS. The configu[...]

In addition to object selection, MetadataSelection also holds properties that ar e 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 requir ed if the ConnectionType[...]

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 s[...]

Y ou 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 inte[...]

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 repr esents this method description. E.g. for createCustomer the function name would be ’C[...]

Note: T o 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 Cr eate, Retrieve, Update and Delete is equivalent except for naming conventions–for example, PeopleSoft has a Find operation that is functionally equivalent to a Retrieve?[...]

v Name – For example, VENDORID v Type – For example, string v Cardinality – 1 or N v Required – Boolean v ObjectTypeName – For cases where an attribute maps to an object for example, porecor d:PORECORD. v Max Length v Metadata – the MetadataObject repr esenting attribute-level application-specific information. ImportedNamespace: Importe[...]

BootStrap: W ebSphere Integration Developer performs a bootstrap step to identify a resour ce adapter that has been enabled for enterprise metadata discovery service. T o identify a resource adapter that is enabled for metadata discovery service, W ebSphere Integration Developer launches a bootstrap step to find a discovery-service.xml file. This f[...]

v PropertyGroup – A collection of properties including single and multi types and PropertyGroup itself. For example, OutboundConnectionConfiguration allows three pr operty groups in one Main property gr oup: UserConfiguration that includes Username and Password ; MachineConfiguration that includes Hostname and PortNo ; and Miscellaneous that incl[...]

A propertyChange() method should be implemented if a property needs to listen for changes on some other property . Check the T wineBall sample for ServiceTypeSingleProperty . T o enable the function of both vetoableChange and propertyChange , the instance of the property should be added to the propertyChangeListener list. In the TwineBallMetadataSe[...]

public TwineBallMetadataDiscovery() throws MetadataException { super("com.ibm.j2ca.sample.twineball.emd"); } The WBIAdapterTypeImpl constructor r equires the following parameters: 1. The name of the class repr esenting the ResourceAdapter class. This is used to create pr operty groups for ResourceAdapter in enterprise metadata discovery .[...]

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 { ServiceDescripti[...]

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(); setInboundConnectio[...]

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 ar gume[...]

setDescription(WBIMetadataDiscoveryImpl.getPropertyDescription ("ConnectionType")); setId("TwineBall"); setDisplayName(WBIMetadataDiscoveryImpl.getPropertyName ("ConnectionType")); } createInboundConnectionConfiguration The createInboundConnectionConfiguration() method returns an instance of InboundConnectionConfigurat[...]

TwineBallConfigurationProperties.getTwineBallConfigurationProperties(); TwineBallResourceAdapter ra = new TwineBallResourceAdapter(); WBIPropertyGroupImpl adapterProp = (WBIPropertyGroupImpl) EMDUtil.getPropertyGroup(ra); propGroup.addProperty(adapterProp); if (getAppliedProperties() != null) EMDUtil.copyValues(getAppliedProperties(), propGroup); }[...]

This class is similar to WBIOutboundConnectionConfigurationImpl except instead of ManagedConnectionFactory , WBIInboundConnectionConfigurationImpl handles the ActivationSpecWithXid bean class. Y ou must extend the methods described below . public PropertyGroup createActivationSpecProperties() { WBIPropertyGroupImpl connProp = null; try { connProp =[...]

Constructor The constructor takes MetadataConnection as an ar gument. The constructor can also return pr operties from MetadataConnection that were used to start the discovery service; for example, prefix, dir ectory name, and those properties that populate the MetadataObject nodes in the tree. public TwineBallMetadataTree(WBIMetadataConnectionImpl[...]

(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.getPropertyNam[...]

ArrayList objects = getTopLevelObjects(); response.setObjects(objects); return response; } WBIMetadataObjectImpl samples: WBIMetadataObjectImpl repr esents the nodes of the tree that W ebSphere 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 [...]

createSelectionProperties The createSelectionProperties() method returns a pr operty group that is used to capture inputs fr om users. These inputs include business object namespace, supported operations, and the relative path in the module pr oject where XML schema definitions should be saved. public PropertyGroup createSelectionProperties() { WBI[...]

The enterprise metadata discovery service uses WBIMetadataEditImpl to acquire connectionTypes , which contains editable properties for ResourceAdapter , ManagedConnectionFactory ,o r ActivationSpecWithXid . The enterprise metadata discovery tooling creates an instance of WBIMetadataEditImpl during the boot strap process. Along with the name of the [...]

dataDesc.prepareChildSchemaFiles(); WBIMetadataDiscoveryImpl.getLogUtils().trace(Level.FINER, CLASSNAME, "preparingChildSchemaFiles", "Preparing SchemaFile for " + bo.getDisplayName()); dataDesc.prepareSchemaFiles(); SchemaDefinition[] schemaFiles = dataDesc.getSchemaDefinitions(); f o r( i n tj=0 ;j< schemaFiles.length; j++)[...]

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 metad[...]

WBIMetadataDiscoveryImpl.getLogUtils().traceMethodExit (CLASSNAME, "getImportNameSpaces"); return list; } getNameSpaces The getNameSpaces() method returns the NameSpaces listed in the XML schema definition. T ypically these are application specific information schema definition namespaces. Note that this list is for outside namespaces onl[...]

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 repr esents the object that populat[...]

FunctionDescription[] funcArray = new FunctionDescription[functionDescriptions.size()]; functionDescriptions.toArray(funcArray); super.setFunctionDescriptions(funcArray); } WBIOutboundServiceDescriptionImpl samples: WBIOutboundServiceDescriptionImpl repr esents the object that populates function descriptions for outbound service descriptions. Imple[...]

dataDescription.setMetadataObject(metadataObj); dataDescription.populateSchemaDefinitions(); dataDescription.setRelativePath(location); dataDescription.setName(getNameSpace() + "/" + metadataObj.getBOName().toLowerCase() + "container", metadataObj.getBOName() + "Container"); outboundFunctionDescription.setOutputDataDes[...]

Creating services that use technology-style adapters r elies 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. Building configurable artifacts (data bindings, data handlers, and function s[...]

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[...]

T o access the binding configuration, do context.get(BindingContext.BINDING_CONFIGURATION) T o 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 pr operties, drop-downs, and user -e[...]

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 re[...]

Extend WBIMetadataType if your adapter needs a simple wrapper object around a payload object, similar to the IBM W ebSphere Adapter for Flat Files and the IBM W ebSphere Adapter for FTP . The WBIMetadataType interface allows you to select a payload type, and optionally generate a business graph structur e in addition to a plain wrapper . Implement [...]

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 m[...]

Set managed connection method This method passes the ManagedConnection handle to the recor d implementation, allowing the recor d 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 connec[...]

the retriveAll operation could return ″ N ″ r ecords from the backend application, for each call to the getNext() method the implementation should fill in data of one recor d from the backend application into OutputCursors/Accessors. It should keep track of which recor d it needs to do next so in subsequent call to getNext() it can fill in next[...]

The method should first extract the value from backend object r epresentation defined through Xpath and use OutputCursor and OutputAccessor interfaces to populate values in runtime data structur e. Sample Data binding implementation Adapters must provide implementations for DataBinding interface in or der to work with W ebSphere Process Server . Th[...]

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 r ecord being build in s[...]

v When WBIStructur edRecord is initialized with data that contains Bidi annotations, Cursors and accessors that are associated with that str uctured recor d 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 factor[...]

How to support fault handling: Understand the following concepts for implementing fault handling into your adapter . Before you define faults, r eview adapter processing to determine which error conditions can be categorized as faults, rather than as exceptions. Y ou will likely be able to apply at least one of the faults provided in the Adapter Fo[...]

//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.setInputDataDescri[...]

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.faultName [...]

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"[...]

T able 4. Fault name and configured fault binding (continued) Fault Name Configured Fault Binding INV ALID_REQUEST com.ibm.j2ca.extension.emd.runtime.WBIFaultDataBindingImpl When input to the operation does not have the requir ed characteristics, the adapter throws this fault. Specific err ors that can result include the following: v For a Create o[...]

Y ou 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[...]

– 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 W ebSphere Adapter T oolkit provides support for confidential traci[...]

W riting a trace message Y ou 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. void trace (Level l, String classname, String method, String msg) void trace (Level l, String classname, String method, String msg, Exception e[...]

"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.[...]

T racing assists developers and troubleshooters. Due to the significant performance cost incurred by tracing, however , many customers disable it in production environments. When developing or tr oubleshooting, it is good practice to check whether tracing is enabled before building to generate trace messages. Y ou can do this by checking method Log[...]

Message types There ar e 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 T ype field is ADAPTER_RBUNDLE . Y ou use only the ADAPTER_RBUNDLE message type beca[...]

translated text. V alues that are language-independent, such as key values or object names, are appr opriate as log message parameters. Similarly to trace messages, parameters in a log message can contain data from the customer’s EIS. Because a customer might be unwilling to send a log file that contains sensitive data to a support specialist for[...]

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.i[...]

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 elem[...]

* The client of an event point needs to know the payload of the fired events. */ public interface EventPoint { /** *return the name of the event point */ 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 mon[...]

<?xml version="1.0" encoding="UTF-8"?> <EventNaturesSpec name="EventNatures" targetNamespace="http://www.ibm.com/xmlns/prod/websphere/scdl/eis/6.0.0:JCAAdapter" xmlns="http://www.ibm.com/xmlns/prod/websphere/monitoring/6.1/mes" xmlns:eis="http://www.ibm.com/xmlns/prod/websphere/scdl/ei[...]

targetNamespace="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" > <Event name="ResourceAdapter.Polling.STARTED" situationType= "STATUS" situationCategory="ReportSituation" reasoningScope=&quo[...]

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 structur e of the artifact itself. It also defines the natures (ENTR Y , EXIT , F AILURE) that are available for t[...]

d. If eventPoint is enabled, then fire event for Entry , Exit and Failur e is invoked. Entry event is fired in the beginning of the method call, exit event is fir ed in the end of the method call and failure event is fir ed in case of exception. For example we can invoke failure event by following API call. if(ep.isEnabled()) { ep.fire(new String[][...]

v Is a transaction (and the application) hung, or are transactions failing? v What is the response time? v Are service level commitments being met? v Who uses the application and how many of each transaction are used? The resour ce adapters are instrumented with the Application Response Measurement API, an API that allows adapters to collect and ma[...]

statistics and data for each ManagedConnection , which can be used to assess and troubleshoot performance r elated problems. In order for r esource adapters to participate in various W ebSphere RequestMetric tools for outbound, diagnostic tools, etc, you will need to follow these steps: 1. Import com.ibm.websphere.j2c.*; 2. Get interaction metrics [...]

FFDC processing overview Instead of explicitly instrumenting catch blocks by calling FFDC dir ectly , 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 defer[...]

If you use the FFDCSupport aspect, you can ensure a consistent FFDC policy for your application by adding declare warning or err or advice to your aspects While this capability is not explicitly provided by the FFDCSupport aspect, you can leverage the use of AspectJ and follow a standard pattern of enfor cing a policy implemented using an aspect wi[...]

When using FFDCSupport aspect you can control the data gather ed. T wo template methods getSourceId and getProbeId are pr ovided to you for this purpose. For example, you may want to limit the length of the source ID strings. In Figur e 7, aspect Example_7 illustrates how to override the getSourceId method and return a short name. Y ou can use FFDC[...]

Exception messages Exception messages, like trace messages, convey information about problems. The differ ence is that exception messages are tailored mor e directly to support teams familiar with adapter source code, and ther efore need not be translated. T reat text included in exception messages as you would text for trace messages. In general, [...]

T o test the enterprise metadata discovery (EMD) implementation for the developed resour ce adapter , complete the following steps: 1. From the IBM W ebSphere Adapters Foundation Classes library , copy the following three dependent jars into the connectorModule connector pr oject: v commonj.connector .jar v CWYBS_AdapterFoundation.jar v DESPI.jar D[...]

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 regr ession testing into your coding and build processes. W ith JUnit, an open source unit test framework, you can write and run tests for your adapter imp[...]

Y our 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 cr eate 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) T est Wh[...]

setUp() The setUp() method for inbound is very similar to that for outbound. Y ou 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 pr operties 2. Start the resour ce adapter . T est The test methods for inbound must do the followi[...]

For information on testing the adapter in managed mode in W ebSphere Application Server , see V alidating code with Rational Application Developer / W ebsphere Application Server . Installing the test client T o test your adapter in a runtime environment, you must first install a test client on the target W ebSphere Pr ocess Server . 1. Install the[...]

T est module configuration 3. Select the testing mode and click Finish to start the test. On the Deployment Location screen, select a W ebSphere Pr ocess 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 c[...]

Adding a value to the Datapool This adds the data to Datapool. When you want to use this input data again, select Use V alue 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. Y ou can optionally load any previously saved execution trace into the test client. T[...]

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 implem[...]

Selecting the Java package g. Save the module. 2. Publish the application to W ebSphere Process Server . 3. Open the administration console for the W ebSphere Process Server and configure the application’s activation specifications so that it can pr ocess inbound requests. 4. Restart the inbound application and ensure that it is polling. 5. T o s[...]

V alidating code with Rational Application Developer and W ebSphere Application Server T o test the adapter in the W ebsphere Application Server environment, use the javabean generation capability of EMD to generate recor ds and a java proxy interface to the adapter . Then generate a session bean that will call this interface, and use the W ebspher[...]

4. In the Resource Adapter deployment panel, choose how to deploy the adapter . Y ou 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 th[...]

7. Start UTC using the Run universal test client option. W ebSphere Adapter development overview 205[...]

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. Y ou can create a session bean using the home interface (create), then invoke business methods on the remote interface, pr oviding the appropriate data. This works the same way as testin[...]

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 W ebSphere Integ[...]

Reference T erminology The terminology presented ar e of terms that are used frequently in the documentation. Adapter foundation classes (AFC) Sometimes referr ed to as base classes, the adapter foundation classes are a common set of services for all IBM W ebSphere resour ce adapters. The Adapter Foundation Classes conform to, and extend, the Java [...]

Eclipse An open source infrastr ucture for building tools such as an Integrated Development Environment (IDE). The toolkit’s wizar d 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. En[...]

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 [...]

Notices This information was developed for products and services of fered in the U.S.A. IBM may not offer the pr oducts, services, or features discussed in this document in other countries. Consult your local IBM repr esentative for information on the products and services curr ently available in your area. Any refer ence to an IBM product, pr ogra[...]

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 pr ograms (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, N[...]

this code are derived fr om 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 pr ovided, is intended to help you create appli[...]

214 W ebSphere Adapters: W ebSphere Adapter T oolkit User Guide[...]

Index Special characters .WBIOutboundServiceDescriptionImpl 39 (CCI), Common Client Interface 4 (EAR) project, Enterprise Application Archive 31 (EAR), enterprise application archive 2 (RAR), resour ce adapter archive 2 Numerics 1.5 specification, Java 2 Connector Architectur e JCA 10 2 Connector Architecture JCA 1.5 specification, Java 10 A Activa[...]

G generation options 35 H hardwar e requir ements 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 r esponse callback events 90 standard 72 using adapter foundation classes 91 wi[...]

V verbs usage business graph 71 W WBIActivationSpec 37 WBIAdapterT ypeImpl 39, 141 WBIConnection 35, 102 WBIConnectionFactory 35, 101 WBIConnectionRequestInfo 104 WBIDataBindingGenerator 38 WBIDataDescriptionImpl 39, 151 WBIInboundConnectionConfigurationImpl 39, 146 WBIInboundConnectionT ypeImpl 39, 143 WBIInboundServiceDescriptionImpl 39, 155 WBII[...]

218 W ebSphere Adapters: W ebSphere Adapter T oolkit User Guide[...]

[...]

 Printed in USA[...]