Page 1 WebSphere Adapters ® Version 6 Release 2 WebSphere Adapter Toolkit User Guide Version 6 Release 2...
Page 3 WebSphere Adapters ® Version 6 Release 2 WebSphere Adapter Toolkit User Guide Version 6 Release 2...
Page 4 To send us your comments about this document, email mailto://doc-comments@us.ibm.com. We look forward to hearing from you. When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any way it believes appropriate without incurring any obligation to you.
Page 5: Table Of Contents
Specify project facets . Specify connector project module settings . Specify resource adapter properties . Specify generation options . Generating an IBM WebSphere Resource Adapter 35 Generating a JCA resource adapter Generated code and deployment descriptor. Using the Resource Adapter Deployment Descriptor editor .
Page 6 WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 7: Websphere Adapter Toolkit
WebSphere Process Server and that exhibits the common functionality and extended qualities of service offered specifically by WebSphere Adapters. WebSphere Adapters are based on the JCA 1.5 specification. These adapters are supported on multiple runtime environments and brokers. Implementing a WebSphere adapter allows you to take advantage of the quality of...
Page 8: Ibm Websphere Adapter Toolkit Technology Overviews
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.
Page 9 J2E component Figure 1. A WebSphere Adapter The IBM WebSphere Adapter portfolio of adapters is based on the Java 2 Platform, Enterprise Edition (J2EE) standard. JCA is a standard architecture for integrating J2EE applications with enterprise information systems. Each of these systems provides native APIs for identifying a function to call, specifying its input data, and processing its output data.
Page 10: Architectural Overview
WebSphere adapters utilize a format-independent data model for representing data objects. In a WebSphere Process Server or WebSphere Enterprise Service Bus runtime environment, WebSphere adapters use an extension of the service data objects (SDO) for representing data objects. Architectural overview...
Page 11 processing performed by each component (and subcomponent) in the model is described in sections that follow the illustration. Application Component JCA Connector JCA Connector Common Services Monitoring Problem Determination Figure 3. Runtime architecture component model The component model allows for a single architecture for adapter development and evolution.
Page 12 “Monitoring and measuring performance” on page 181. Application interface component The application interface component bridges the runtime environment and the connector component. It enables invocation of the connector from the clients, using WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 13: How Metadata Is Used At Build Time And Run Time
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.
Page 14: Ibm Websphere Adapter Toolkit Overview
The enterprise metadata discovery-compliant tools are based on the Eclipse platform and include IBM WebSphere Integration Developer and IBM Rational Application Developer. The current tools support generation of SCA and J2EE programming model artifacts, and is extensible to also support generation of artifacts for other programming models and server runtimes.
Page 15: New Connector Project Wizard Overview
As changes are made to configuration properties using the editor, the appropriate Java bean properties are added to your code. v Adapter Foundation Classes - A common set of services for all IBM WebSphere resource adapters. v Samples - To assist you in creating custom WebSphere resource adapters.
Page 16: Resource Adapter Deployment Descriptor Editor Overview
Data exchange service provider interface (DESPI) and the Javadoc for Enterprise Metadata Discovery, are included as part of the WebSphere Adapter Toolkit installation. For more information, see “IBM WebSphere Adapter Toolkit tasks” on page 11. WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 17: Ibm Websphere Adapter Toolkit Tasks
Descriptor editor Implementing code stubs Validating code Exporting the resource adapter IBM WebSphere Adapter Toolkit installation requirements The WebSphere Adapter Toolkit installation has operating system requirements and hardware requirements. Among the requirements are a Windows or Linux operating system and successful installation of WebSphere Integration Developer.
Page 18: Samples Overview
IBM WebSphere Adapter Toolkit software plug-ins. Samples overview When you installed the IBM WebSphere Adapter Toolkit, two sample resource adapters were placed on your system. The samples installed with WebSphere Adapter Toolkit are a reference for the creation of custom JCA resource adapters.
Page 19: Running The Twine Ball Sample Using Websphere Integration Developer
1. Import the deployable RAR file for the Twine Ball sample from the WebSphere Integration Developer samples. a. Launch WebSphere Integration Developer Click Start → Programs → IBM WebSphere → Integration Developer 6.2. b. From the menu, select Help → Samples WebSphere Adapter development overview...
Page 20 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.
Page 21 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.
Page 22 4. Click Next to launch the New External Service window. 5. From the New External Service window, make sure that Unlisted Adapter is selected and click Next. 6. From the Select an Adapter window, expand TwineBallConnector (IBM:6.2), select CWYAT_TwineBall and click Next. WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 23 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.
Page 24 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. WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 25 12. From the Service Location Properties window, click New. This launches the New Integration Project window. 13. From the New Integration Project window, select Create a module project and click Next. 14. Enter values in the New Module window and click Finish. Your module displays in the Project explorer view: WebSphere Adapter development overview...
Page 26 2. Place your cursor in the Business Integration navigation pane, right-click and select New → Other to launch the Select a wizard window. 3. From the list of available wizards, expand Business Integration and select the External Service wizard: WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 27 4. Click Next to launch the New External Service window. 5. From the New External Service window, make sure that Unlisted Adapter is selected and click Next. 6. From the Select an Adapter window, expand TwineBallConnector (IBM:6.2), select CWYAT_TwineBall and click Next. WebSphere Adapter development overview...
Page 28 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. WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 29 10. From the Configure Composite Properties window select Next. 11. From the Service Generation and Deployment Configuration window, deselect Specify a Java Authentication and Authorization Services (JASS) alias security credential. WebSphere Adapter development overview...
Page 30 By adding a Java component to link the service you will be able to access and implement the emit <Create/Delete/Update>Customer() method to insert a print statement. 1. Add a Java component to link to the InboundService. WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 31 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.
Page 32: Running The Twine Ball Sample Using Rational Application Developer
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.
Page 33 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.
Page 34: Troubleshooting The Samples
Using the New Connector Project wizard You use the wizard create a Connector Project which contains a deployment descriptor and classes. The classes either extend the WebSphere Adapter Foundation Classes or implement the JCA 1.5 Interface specification. WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 35: Launching The New Connector Project Wizard
Launch the New Connector Project wizard when you are ready to create a new adapter project. 1. Start IBM WebSphere Integration Developer. Choose Start → IBM WebSphere → WebSphere Integration Developer V6.x → WebSphere Integration Developer V6.x. This displays the Workspace Launcher dialog.
Page 36 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. WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 37: Specify Project Properties
Enter a project name in the Project name field. The name is automatically appended to the workspace location. 2. Set Target Runtime to <None> and select IBM Websphere Adapter for the Configurations The IBM Websphere Adapter configuration contains the IBM WebSphere Adapter Foundation Classes 6.2, J2C Module 1.5 and Java 5.0 Project Facets.
Page 38: Specify Project Facets
1. From the New Connector Project screen, make sure IBM WebSphere Adapter displays in the Configurations field and do not change the configuration or deselect any of the project facets. The project facets that are preselected are the facets you need to run the WebSphere Adapter Toolkit.
Page 39: Specify Resource Adapter Properties
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.
Page 40: Specify Generation Options
You specify adapter components in the Generation Options dialog. You must choose which kind of adapter specification you want to implement: an IBM WebSphere Resource Adapter, or a J2C Resource Adapter. The adapter specification that you choose determines the generation options available.
Page 41: Generating An Ibm Websphere Resource 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.
Page 42 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.
Page 43 The list of Adapter Foundation Classes that are extended in your Connector Project when you choose to generate inbound adapter classes is as follows: v ActivationSpecWithXid extends com.ibm.j2ca.base.WBIActivationSpecWithXid v EventStoreWithXid extends com.ibm.j2ca.extension.eventmanagement.EventStoreWithXid You can select the following properties when generating outbound adapter classes:...
Page 44 SDO to CCI record and from CCI record to SDO. The list of Adapter Foundation Classes that are extended in your Connector Project when you choose to generate data binding classes is as follows: v DataBinding implements commonj.connector.runtime.RecordHolderDataBinding v DataBindingGenerator extends WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 45 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.
Page 46 2. Review the available component property options associated with outbound adapter classes. Each of the component property options are described in the sections that follow. Generate the outbound adapter classes for the component property selected. WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 47 XA transactional behavior to the adapter if you click Finish to generate the code for this task. Review the section on local transaction support in Generating an IBM WebSphere Resource Adapter. For more information on transaction support, see Implementing transaction support.
Page 48 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.
Page 49 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.
Page 50 1. Click the Generate Inbound Adapter classes check box and then click on the Connection Pooling check box in the right pane. Note: The Event Polling Support property is selected automatically when you select Connection Pooling . Connection pooling is not supported for Callback Events. WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 51 In each poll call, a number of events are processed by the adapter. Review the information on inbound adapter classes and the information on inbound event polling support in Generating an IBM WebSphere Resource Adapter. When you choose to generate inbound adapter classes for event polling support, the wizard creates code for the methods that must be implemented to produce a resource adapter that can send polling events from an EIS to a business process.
Page 52 EIS to a business process. 1. Click the Generate Inbound Adapter classes check box and then click on the Callback Event Support check box in the right pane. WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 53 Review the information on enterprise metadata discovery classes in Generating an IBM WebSphere Resource Adapter. When you choose to generate enterprise metadata discovery classes, the wizard generates code for the methods needed to produce a service that you can use to glean business object structure and other data from an EIS.
Page 54 You can generate data binding classes separate from the data binding classes that are generated from enterprise metadata discovery. Review the section on data binding classes in Generating an IBM WebSphere Resource Adapter. When you choose to generate data binding classes, the wizard generates code for the methods needed to marshall data from SDO to CCI record and from CCI record to SDO.
Page 55: Generating A Jca 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.
Page 56 InboundFunctionDescription implements commonj.connector.description.InboundFunctionDescription v InboundServiceDescription implements commonj.connector.description.InboundServiceDescription v OutboundFunctionDescription implements commonj.connector.description.OutboundFunctionDescription v OutboundServiceDescription implements commonj.connector.description.OutboundServiceDescription v SchemaDefinition implements commonj.connector.SchemaDefinition v ServiceDescription implements commonj.connector.description.ServiceDescription v AdapterType implements commonj.connector.discovery.AdapterType v AdapterTypeSummary implements commonj.connector.discovery.AdapterTypeSummary WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 57 v EditableType implements commonj.connector.discoveryEditableType v MetadataDiscovery implements commonj.connector.discovery.MetadataDiscovery v MetadataEdit implements commonj.connector.discovery.MetadataEdit v MetadataImportConfiguration implements commonj.connector.discovery.MetadataImportConfiguration v MetadataObject implements commonj.connector.discovery.MetadataObject v MetadataObjectIterator implements commonj.connector.discovery.MetadataObjectIterator v MetadataObjectResponse implements commonj.connector.discovery.MetadataObjectResponse v MetadataSelection implements commonj.connector.discovery.MetadataSelection v MetadataTree implements commonj.connector.discovery.MetadataTree v ConnectionConfiguration implements commonj.connector.discovery.ConnectionConfiguration v ConnectionPersistence implements commonj.connector.discovery.ConnectionPersistence v ConnectionType implements commonj.connector.discovery.ConnectionType...
Page 58 For information on how to generate Enterprise Metadata Discovery classes, see Generating JCA Enterprise Metadata Discovery classes. Note: If you select the IBM WebSphere Adapter Foundation Classes Support feature check box in the Project Facets screen, then the created J2EE resource adapter project automatically includes the IBM WebSphere Adapter Foundation Classes library in the project libraries list of the Java Build path.
Page 59 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.
Page 60 The prefix is the Class Name Prefix that you entered when specifying properties on the Resource adapter properties page of the wizard. 1. Click the Generate Enterprise Metadata Discovery classes check box. WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 61: Generated Code And Deployment Descriptor
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.
Page 62: Using The Resource Adapter Deployment Descriptor Editor
Once you complete the New Connector Project wizard your workspace is switched to the J2EE perspective and your deployment descriptor displays using the Resource Adapter Deployment Descriptor editor. Displaying the deployment descriptor in the editor provides you with several different views. WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 63 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.
Page 64 Add Component dialog box. Only those options not previously generated will be enabled for you to select. Note: To display the Add button for Add Component, maximize the Overview pane. The Add button does not display when this pane is minimized. WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 65 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.
Page 66 In addition, you can add or delete your own user-defined configuration properties using the Add and Remove buttons on the left side of the editor. You can also edit these properties using the widgets on the right side of the editor. WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 67 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.
Page 68 EIS. Clicking the Add button under the Connection Definitions list on the left side of the editor displays the following dialog box, which allows you to specify all required connection definition information. WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 69 Add Connection Definition dialog A Connection Definition requires the following information: ConnectionFactory Interface ConnecitonFactory Implementaion Class v Connection Interface Connection Implementation Class ConnectionRequestInfo Class 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.
Page 70 The Inbound Adapter pane contains a Message Listeners section. Inbound Resource Adapter pane The Message Listeners section allows you to specify message listeners for inbound event processing. You must specify a MessageListener type and an Activation Spec WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 71 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.
Page 72: Modifying Deployment Descriptor Properties
When you modify the type of a property, the editor adjusts the field and accessor methods accordingly. Note: Removing or modifying properties may cause compile errors in your code that you must resolve. WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 73: Editing Deployment Descriptor Source
Generated bean properties The editor maps resource adapter properties to class code. When you modify the resource adapter, the editor performs automatic source code updates. The table shows the generated code affected when you add, delete, or modify a configuration property: Class code affected by configuration property change Configuration property Config Property (Resource adapter panel)
Page 74: Implementing Code From The Ibm Websphere Adapter Toolkit
Resource Adapter Deployment Descriptor editor. Implementing code from the IBM WebSphere Adapter Toolkit Foundation Classes implementation overview To develop a WebSphere resource adapter, you identify the JCA classes for your project, generate subclasses of all the corresponding Foundation Classes, and then modify or override methods as described in the individual class subsections.
Page 75: Data Model
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.
Page 76 The business object data model is based upon the open-standard service data object (SDO) model that is supported by IBM and others (visit www.eclipse.org for more information). v The business object data model aligns well with the larger WebSphere service-oriented architecture (SOA) strategy which, going forward, will better enable interpretability with other WebSphere-based applications.
Page 77 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.
Page 78 Supported standard top-level operations Inbound Operation Signatures emitCreateAfterImage<BOType> emitUpdateAfterImage<BOType> emitDeleteAfterImage<BOType> emitDelta<BOType> WebSphere Adapters: WebSphere Adapter Toolkit User Guide Notes These operations should generate after-image business objects with verbs that match the operation signature; for example, emitCreateAfterImageCustomer should generate a Customer object with verb Create.
Page 79 Outbound Operation Signatures applyChanges<BOType> create<BOType> update<BOType> delete<BOType> retrieve<BOType> retrieveAll<BOType> Standard processing logic: Each adapter should enable operations that are supported by the EIS. General guidelines for operations with adapters include the following v All operations should be atomic: if an operation fails for any reason, the adapter should roll back any partial changes made to the EIS as part of the request.
Page 80 EIS with the given key values, the adapter should fail immediately. Some WebSphere Adapters have historically made a best effort and defaulted to an update in such cases. Such adapters attempted to interpret the request and make every effort to complete it.
Page 81 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;...
Page 82 Error handling The RecordNotFoundException exception is thrown if the EIS does not contain an entity with the same key values as the business object to be deleted. WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 83 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.
Page 84 WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 85: Inbound Event Notification
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″...
Page 86 Using the IBM WebSphere Foundation Classes for inbound event notification Although not required, use of the IBM WebSphere Foundation Classes is strongly recommended for adapters that need to provide event notification. Using the Foundation Classes can dramatically simplify the often complicated implementation of event retrieval and publication.
Page 87 To manage application-specific events, the Foundation Classes require that you provide application-specific logic, if any. To do this, you must: 1. Ensure that any subclass of com.ibm.j2ca.base.WBIResourceAdapter implements interface com.ibm.j2ca.WBIPollableResourceAdapter. This interface allows the Foundation Classes to acquire an EventStore implementation that specifically reflects the EIS application.
Page 88 The event might generate a sequential identifier, such as 00123, to which the adapter adds its name. In such an event ID numbering scheme, the resulting object event ID is MyAdapterName_00123. Another technique might WebSphere Adapters: WebSphere Adapter Toolkit User Guide Description A unique identifier for the event...
Page 89 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.
Page 90 Implementing the EventStore Interface section. Event object fields Field eventID eventKeys WebSphere Adapters: WebSphere Adapter Toolkit User Guide Description Foundation Class Constant The event is ready to be NEWEVENT processed. The adapter is processing INPROGRESS this event.
Page 91 Field eventType timeStamp eventStatus Event detection: Events detection mechanisms reflect the sources that trigger them: user actions in the application, batch processes that add or modify application data, or database administrator actions. When an event detection mechanism is set up in an application and an application event associated with a business object occurs, the application must detect the event and write it to the event store.
Page 92 Xid[] getPendingTransactions() throws ResourceException, CommException public Event getEventForXid(XidImpl xid) throws ResourceException, CommException WebSphere Adapters: WebSphere Adapter Toolkit User Guide Description This method should store the xid in the Event table in the same row specified by event. xid.toString() will serialize the Xid for easy storage.
Page 93 Method ArrayList getEvents(int quantity, int eventStatus, String[] typeFilter) boolean implementsFiltering() Event getSpecificEvent(String eventId) Object getObjectForEvent(Event event) void deleteEvent(Event event) void updateEventStatus(Event event, int newstatus) Transaction Support Methods If the implementation of the event store supports transactions, the EventStore implementation should provide access to that transaction control using the following methods: Description This method enables the adapter to...
Page 94 The EventStore implementation would need to employ the available database APIs to gain access to the contents of the event table. Event store implementation WebSphere Adapters: WebSphere Adapter Toolkit User Guide Description Is the event store transactional? If so, this method should return true.
Page 95: Inbound Callback Event Notification
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.
Page 96 The following is an illustration of asynchronous callback event processing. WebSphere Adapters: WebSphere Adapter Toolkit User Guide Callback From EIS...
Page 97 This allows developers to provide greater quality of service (QoS) in less time and also ensure that behavior across adapters is consistent. Although not required, it is a recommended practice that you use IBM WebSphere adapter foundation classes (AFC) for adapters that have to provide callback event notification.
Page 98 MessageEndpointFactory arguments. Here is a snippet of EndPointManager class showing how the callback mechanism is implemented. public class EndpointManager { * inner class which maintains pairs of mef and activationspec public static class EndpointPair { public MessageEndpointFactory mef; public ActivationSpec activationSpec; WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 99 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 {...} The adapter listener gets all MessageEndpointFactories for the current...
Page 100 If problems occur within this transaction scope, a proper rollback mechanism will ensure data integrity is maintained. XA transaction will be active and supported only when the adapter is configured with one EndpointFactory. WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 101 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;...
Page 102 This ensures that once-one-only delivery mechanism is implemented when the system recovers from a failure. WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 103: Outbound Support
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.
Page 104 By default, this method returns false. If you can support changing some connection parameters without destroying the connection (for example, language), override and return true. 6. If you override isConnectionInfoOverwritable, consider overriding the boolean matchConnectionRequestInfo (WBIConnectionRequestInfo) WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 105 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.
Page 106 TwineBallConnection(this); 4. destroy() This method should close this connection to the EIS and release any resources. WebSphere Adapters: WebSphere Adapter Toolkit User Guide (WBIConnectionRequestInfo) connectionRequestInfo, this.getResourceAdapter()); throws ResourceException boolean reauthenticate)
Page 107 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.
Page 108 TwineBallInteraction extends WBIInteraction { private CommandManager commandManager; private Interpreter interpreter; private TwineBallConnection connection; private TwineBallCommandFactory factory; public TwineBallInteraction(WBIConnection connection) throws ResourceException { super(connection); this.connection = (TwineBallConnection) connection; interpreter = new Interpreter(this.getLogUtils()); TwineBallResourceAdapter resourceAdapter = WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 109 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).getFunctionName(); WBIInteractionSpec interactionSpec = (WBIInteractionSpec)ispec; factory.setMaxRecords(interactionSpec.getMaxRecords()); Command topLevelCommand = commandManager.produceCommands((WBIRecord) inRecord, topLevelCommand.getClass().getName());...
Page 110 (The JCA specification prescribes that any adapter supporting XA should also support local transactions.) 2. Update your adapter-specific construction of WBIResourceAdapterMetadata to reflect support for local transactions. ResourceAdapterMetadata#supportsLocalTransactionDemarcation should return true. WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 111 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.
Page 112 With a snapshot Update, the Command Manager must retrieve the object from the EIS, compare it to the incoming structure and create a command structure that can change the data in the EIS to match the incoming structure. WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 113 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.
Page 114 EIS systems require a parent pointer in order to process children, the command manager generates NO_OPERATION commands for the untouched parents of changed child objects. WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 115 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.
Page 116 The order of execution for Create and Update is top-to-bottom; for Delete the order is bottom-to-top. As shown in the following figure, the Command Manager relieves you of the task of developing and testing comparison routines. WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 117 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.
Page 118 Update. Implementing Command Manager: You implement commands for each type of operation supported by the adapter, a command factory to support instances of each operation, and calls to the Command Manager. WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 119 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.
Page 120 WBIStructuredRecord outRecord = new WBIStructuredRecord(); outRecord.setOperationName(functionName); outRecord.setTwineBallConnection(connection.getEISConnection()); outRecord.setEISRepresentation(topLevelCommand.getEisRepresentation()); return outRecord; Notice that you need not ″walk″ the incoming object structure, or the command structure– the command manager and interpreter perform this function. WebSphere Adapters: WebSphere Adapter Toolkit User Guide throws ResourceException;...
Page 121: Data And Metadata
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.
Page 122 ContainedType The class of the object that this property contains v PrimaryKey: Whether this property is key v DefaultValue: The default value v MaxLength: The maximum length of this property. WebSphere Adapters: WebSphere Adapter Toolkit User Guide Header String String...
Page 123 The List would contain one or more Map entries where each Map contains the mapping for the elements of the child complex type. Here is an example of how the object level metadata annotation would look like in an SDO schema: <annotation> <appinfo source="http://www.ibm.com/xmlns/prod/websphere/j2ca/sap/metadata"> <sapasi:sapBAPIBusinessObjectTypeMetadata xmlns:sapasi="http://www.ibm.com/xmlns/prod/websphere/j2ca/sap/metadata"> <sapasi:Type>BAPI</sapasi:Type> <sapasi:Operation> <sapasi:MethodName>BAPI_CUSTOMER_CREATEFROMDATA1</sapasi:MethodName>...
Page 124 LinkedHashMap updateOperationMap = new LinkedHashMap(); updateOperationMap.put("Name", "Update"); methodnameList = new LinkedList(); methodnameList.add("wbiCustomerUpdate)"; updateOperationMap.put("MethodName", methodnameList); operationAnnotation.add(updateOperationMap); objectAnnotations.put("Operation",operationAnnotation); ObjectAnnotations:Object level metadata in the annotations is read and stored in the ’objectAnnotations’ Map. Following diagram shows the structure of objectAnnotations. WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 125 objectAnnotationsMap ObjectName WBI_CUSTOMER_CI Operation operationsList operationList updateOperationMap createOperationMap The Metadata API Advanced implementations of adapters are metadata-driven. This implies that the adapter is not hard coded for each object type in the system, but rather has a form of discovery in which a representation of the object (the metadata) in the EIS is constructed at build time, then at runtime the adapter uses this metadata, along with the data, to process the object.
Page 126 String getName() Retuns the name of the type. Iterator getPropertyIterator() Returns an iterator to allow iteraton over the properties in this type. List getProperties() Returns a list of properties for this type. WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 127 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.
Page 128 Enterprise metadata implementation Selection of artifact types WebSphere adapters can run against multiple brokers (server runtimes). Each broker might require different types of artifacts. The adapter foundation classes can generate artifacts in support of multiple brokers. The following artifact types are supported by adapter foundation classes: 1.
Page 129: Enterprise Metadata Discovery General Interfaces And Implementation For Application Adapters
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.
Page 130 The metadata generated by the discovery service must comply with the restrictions on interaction mode mentioned above: for Outbound the metadata must support Request/Response and for Inbound, one-way. WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 131 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.
Page 132 Enterprise metadata discovery architecture Note: The solid arrows represent the enterprise metadata discovery implementation in the above diagram. The components of the enterprise metadata discovery implementation, described below, are: v Runtime WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 133 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.
Page 134 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)
Page 135 ResourceAdapterBean class (for example, ″com.ibm.j2ca.peoplesoft.PeopleSoftResourceAdapter″) v ManagedConnectionFactory bean class (for example, ″com.ibm.j2ca.peoplesoft.PeopleSoftManagedConnectionFactory″ ) v OutboundConnectionConfiguration - Represents properties needed to connect to the EIS for discovery and to create service descriptions. For connection types that are used only at runtime this represents managed connection factor and resource adapter properties.
Page 136 MetadataTree model. Another implementation might display function parameters as nodes in the MetadataTree model. IBM WebSphere recommends displaying the leaf-level properties in the model only if there is an advantage to doing so. In most cases, simple properties or function parameters should not be added as nodes in the tree.
Page 137 The MetadataObject represents the node of the MetadataTree. You define properties and filters in this object that help guide enterprise metadata discovery. IBM WebSphere recommends that you specify objectProperties that suggest the EIS objects you are defining. You should also define filter properties in MetadataObject that might make fetching of child objects more efficient and usable.
Page 138 Activation Spec beans v Function list - These represent the methods and functions that can be called by the client. An Outbound Function Description describes the interface for each of these methods. Connection descriptions: WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 139 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.
Page 140 Each DataDescription instance should have a unique namespace. The convention followed by IBM is to use a base namespace concatenated by the name of the corresponding object.
Page 141 Note: Function-based adapters occasionally may be required to perform multiple individual EIS operations to achieve the equivalent of a single Create, Retrieve, Update, or Delete operation. IBM WebSphere recommends that these low-level EIS operations also be exposed so that users are free to compose equivalent operations.
Page 142 For example, pasi:Getter value getObjectName. Namespace definition The namespace http://www.ibm.com/xmlns/prod/websphere/j2ca is reserved for XML artifacts produced by or employed by WebSphere Adapters. Adapters should use http://www.ibm.com/xmlns/prod/websphere/j2ca/ <adapter_name> for any adapter-specific artifacts generated during the metadata import process; for example, http://www.ibm.com/xmlns/prod/websphere/j2ca/ peoplesoft.
Page 143 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.
Page 144 To enable validation of specific properties, extend the WBISingleValuedPropertyImpl or WBIMultiValuedPropertyImpl and then implement the vetableChange() method. Any validation can be performed in this code. In case of failures, PropertyVetoException must be thrown. WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 145 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. In the TwineBallMetadataSelection class in the TwineBall sample, the property representing operations listens on the property for serviceType: propertyGroup = new WBIPropertyGroupImpl(Constants.SELECTION_PROPERTIES);...
Page 146 The instance of ServiceDescription created should be filled in with name, namespace, function description and configurations as shown below. The method copyPropertyValues(), defined on connection configurations, copies the properties that match between the connection configuration that was used to perform WebSphere Adapters: WebSphere Adapter Toolkit User Guide throws MetadataException {...
Page 147 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;...
Page 148 WBIOutboundConnectionTypeImpl samples: WBIOutboundConnectionTypeImpl represents the outbound connection types supported by the adapter. The mapping of these connection types corresponds to WebSphere Adapters: WebSphere Adapter Toolkit User Guide (ADAPTERTYPE_PROPERTY)); new TwineBallInboundConnectionType(this); (Constants.RESOURCE_ADAPTER_BEAN_NAME); (Constants.ACTIVATION_SPEC); new TwineBallOutboundConnectionType(this); new TwineBallOutboundConnectionType(this);...
Page 149 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.
Page 150 WebSphere Integration Developer uses this method to display the first connection configuration screen for enterprise metadata discovery. public PropertyGroup createUnifiedProperties() { WBIPropertyGroupImpl propGroup = null; try { propGroup = WebSphere Adapters: WebSphere Adapter Toolkit User Guide ("ConnectionType")); ("ConnectionType")); EMDUtil.copyValues(getAppliedProperties(), adapterProp);...
Page 151 TwineBallConfigurationProperties.getTwineBallConfigurationProperties(); TwineBallResourceAdapter ra = new TwineBallResourceAdapter(); WBIPropertyGroupImpl adapterProp = (WBIPropertyGroupImpl) EMDUtil.getPropertyGroup(ra); propGroup.addProperty(adapterProp); if (getAppliedProperties() != null) EMDUtil.copyValues(getAppliedProperties(), propGroup); } catch (MetadataException e) { throw new RuntimeException(e); return propGroup; createResourceAdapterProperties The createResourceAdapterProperties method returns an instance of PropertyGroup that represents properties you can configure for the ResourceAdapter bean.
Page 152 WBIMetadataTreeImpl represents the object that holds the metadataObject nodes of the tree that WebSphere Integration Developer displays for enterprise metadata discovery. Extend the WBIMetadataTreeImpl class and implement the methods described below. WebSphere Adapters: WebSphere Adapter Toolkit User Guide (new TwineBallActivationSpec()); ("UserCredentials"); ("UserName", String.class);...
Page 153 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 {...
Page 154 Any metadataObjects that can be selected for import should be set as true with the setIsSelectableForImport() method. public MetadataObjectResponse listMetadataObjects(PropertyGroup filterParameters) WBIMetadataObjectResponseImpl response = new WBIMetadataObjectResponseImpl(); WebSphere Adapters: WebSphere Adapter Toolkit User Guide throws MetadataException {...
Page 155 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.
Page 156 Those inputs might include operations that are supported for each MetadataObject instance, or additional information required to process the object at run time. WBIMetadataEditImpl samples: WebSphere Adapters: WebSphere Adapter Toolkit User Guide propertyGroup = new WBIPropertyGroupImpl (Constants.SELECTION_PROPERTIES); propertyGroup.setDisplayName (WBIMetadataDiscoveryImpl.getPropertyName...
Page 157 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.
Page 158 WBIMetadata getMetadataForBusinessObject() { WBIMetadataDiscoveryImpl.getLogUtils().traceMethodEntrance WBIMetadata bometadata = new WBIMetadata(); bometadata.setSource(Constants.ASI_TARGET_NAMESPACE); QName namespace = new QName(Constants.ASI_TARGET_NAMESPACE, Constants.ASI); WebSphere Adapters: WebSphere Adapter Toolkit User Guide dataDesc.prepareChildSchemaFiles(); WBIMetadataDiscoveryImpl.getLogUtils().trace(Level.FINER, dataDesc.prepareSchemaFiles(); SchemaDefinition[] schemaFiles = dataDesc.getSchemaDefinitions(); for (int j = 0; j < schemaFiles.length; j++) { SchemaDefinition definition = schemaFiles[j];...
Page 159 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. The Container definition is used when the adapter supports a RetrieveAll operation. public boolean isContainer() { WBIMetadataDiscoveryImpl.getLogUtils().traceMethodEntrance boolean retValue = false;...
Page 160 The getRequired() method returns true if the element is marked as required in the XML schema definition. Otherwise, this method returns false. public boolean getRequired(String attrName) { return false; } WebSphere Adapters: WebSphere Adapter Toolkit User Guide (CLASSNAME, "getImportNameSpaces"); (CLASSNAME, "getNameSpaces");...
Page 161 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. setFunctionDescriptions The setFunctionDescriptions() method populates function descriptions based on objects and properties selected in MetadataSelection .
Page 162 "/" + metadataObj.getBOName().toLowerCase() + "bg", metadataObj.getBOName() + "BG"); traceFiner("type of input object" + dataDescription.getName().getNamespaceURI() + "\\" + dataDescription.getName().getLocalPart()); if (operation != WBIInteractionSpec.RETRIEVE_ALL_OP) outboundFunctionDescription.setOutputDataDescription(dataDescription); else { dataDescription = new TwineBallDataDescription(); dataDescription.setName(getNameSpace(), metadataObj.getDisplayName() + "Container"); WebSphere Adapters: WebSphere Adapter Toolkit User Guide + metadataObj.getDisplayName());...
Page 163: Enterprise Metadata Discovery Interfaces And Implementation For Technology Adapters
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.RETRIEVE_ALL_OP)) { MaxRecordSingleProperty maxCount = (MaxRecordSingleProperty) selectionProperties.getProperty (TwineBallMetadataSelection.MAXRECORDS); if (maxCount.getValue() == null) interactionSpec.setMaxRecords(((Integer) maxCount.getPropertyType().getDefaultValue()).intValue()); else interactionSpec.setMaxRecords(((Integer) maxCount.getValue()).intValue()); interactionSpec.setFunctionName(operation); outboundFunctionDescription.setInteractionSpec(interactionSpec); outboundFunctionDescription.setImportConfiguration(importConfiguration); functionDescriptions.add(outboundFunctionDescription); FunctionDescription[] functionArray = new FunctionDescription[functionDescriptions.size()];...
Page 164 When implementing a data handler, code it to handle both byte array and string formats, if possible. Note: Existing Websphere adapters, as of version 6.1.x and version 6.2, use InputStream for accessing raw data and data object for the transformed version exclusively.
Page 165 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.
Page 166 Implementing Enterprise Metadata Discovery to build an interface The com.ibm.j2ca.extension.emd.build.* package allows a simpler way to build services with an adapter from existing types. Instead of the EMD process generating types, it will import them and use them in a service.
Page 167 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.
Page 168: Structured Record Implementation
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.
Page 169 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.
Page 170 Xpath expression. This method can be called multiple times by the client application if the operation can return multiple records from the backend application. For example, if WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 171 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.
Page 172: Data Binding Implementation
To perform this task the adapter should use DESPI APIs. Initialize the record with initializeOutput(), then call getNext() to build data in SDO. This method should take care of building an instance of BG is the methods getNamespaceURI()and getBusinessObjectName() return a type BG. WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 173: Bidirectional Language Support
DataBinding generator To enable the right business object type being made available to DataBinding implementations adapters should implement DataBindingGenerator interface. Adapters should implement com.ibm.j2ca.extension.databinding, WBIDataBindingGenerator and implement provide a default constructor implementation. Call the super class constructor and pass in the name of the adapter and the absolute classname of the base DataBinding implementation.
Page 174: Problem Determination
In addition to the fault classes, the following fault selector class and base fault binding class are provided: v WBIFaultSelectorImpl v WBIFaultDataBindingImpl A utility class named FaultBOUtil can help you define simple custom fault business objects. WebSphere Adapters: WebSphere Adapter Toolkit User Guide Corresponding Fault Name DUPLICATE_RECORD INVALID_REQUEST MATCHES_EXCEEDED_LIMIT MISSING_DATA...
Page 175 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.
Page 176 } catch (Exception e) { throw new MetadataException( "Unable to create fault BO definitions " + e.getMessage(), e); //$NON-NLS-1$ The following example shows code for implementing FaultDataDescription in the JDEXMLListFaultDataDescription class: WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 177 JDEBFFaultDataDescription fdesc1 = new JDEBFFaultDataDescription(); JDEBFFaultDataDescription fdesc2 = new JDEBFFaultDataDescription(); BusinessObjectDefinition bo = FaultBOUtil.createDuplicateRecordBO(); URI uri = new URI("./" + FaultBOUtil.DUPLICATE_RECORD_NAME //$NON-NLS-1$ + EMDConstants.XSD); fdesc1.put(FaultBOUtil.FAULT_TARGET_NS, uri, bo.serialize()); fdesc1.setGenericDataBindingClassName("com.ibm.j2ca.extension.emd.runtime.WBIFaultDataBindingImpl"); fdesc1.setFaultName(FaultBOUtil.DUPLICATE_RECORD_NAME); bo = FaultBOUtil.createMatchesExceededLimitBO(); uri = new URI("./" + FaultBOUtil.MATCHES_EXCEEDED_LIMIT_NAME //$NON-NLS-1$ + EMDConstants.XSD); fdesc2.put(FaultBOUtil.FAULT_TARGET_NS, uri, bo.serialize());...
Page 178 These are examples only. Table 4. Fault name and configured fault binding Fault Name DUPLICATE_RECORD WebSphere Adapters: WebSphere Adapter Toolkit User Guide Configured Fault Binding com.ibm.j2ca.extension.emd.runtime.WBIFaultDataBindingImpl The adapter throws this fault when processing an outbound Create operation when an error occurs because the specified file already exists in the specified directory path.
Page 179 Only required if you have defined additional attributes for your fault. v Define the fault business object Configured Fault Binding com.ibm.j2ca.extension.emd.runtime.WBIFaultDataBindingImpl When input to the operation does not have the required characteristics, the adapter throws this fault. Specific errors that can result include the...
Page 180 – Rather than hard-code log messages in the adapter, place them in a separate log message file to facilitate translation into localized languages – They feature multiple levels that users can employ to filter log messages v The following guidelines apply to event messages: WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 181 JCA resource adapter. You will not be able to manually add logging and tracing to the generated JCA adapter code. You can insert log and/or trace statements into your generated IBM WebSphere adapter code using a dialog box that collects information about the log or trace statement to be generated and insert the appropriate code at the cursor position.
Page 182 Example of trace message for the outbound scenario public HelloWorldConnectionFactory(ConnectionManager connMgr, WBIManagedConnectionFactory mcf) super(connMgr, mcf); getLogUtils().trace(Level.FINE,"com.ibm.helloworld.outbound.HelloWorldConnectionFactory", "HelloWorldConnectionFactory()", "test"); Example of trace message for the inbound scenario public javax.resource.cci.Record getRecordForEvent(com.ibm.j2ca.extension.eventmanagement.Event event) throws javax.resource.ResourceException, javax.resource.spi.CommException { logger.trace(Level.FINE, "com.ibm.helloworld.inbound.HelloWorldEventStoreWithXid", WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 183 Set the trace level on the package that you want to trace to all in the Change Log Detail Levels field: For example, if the adapter package name is com.ibm.myadapter, modify the Change Log Detail Levels pane and add com.ibm.myadapter.* = all.″...
Page 184 The message type E tells you this is an error message. The component identifier must be registered with IBM to avoid conflicts between products. The type identifier should conform to one of the values specified in the Log Level table shown below.
Page 185 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.
Page 186 Example of log message for the outbound scenario with confidential tracing property enabled public HelloWorldConnectionFactory(ConnectionManager connMgr, WBIManagedConnectionFactory mcf) { super(connMgr, mcf); getLogUtils().logConfidential(Level.INFO, LogUtilConstants.ADAPTER_RBUNDLE, "com.ibm.helloworld.outbound.HelloWorldConnectionFactory", "HelloWorldConnectionFactory()", "10", new Object[] { "str" }); WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 187 WebSphere Process Server includes the Common Event Infrastructure technology, which adapters use to create, transmit, persist and distribute events. Note: If an adapter is running on a broker that does not use the IBM CEI technology but instead uses its own event monitoring technology; that broker can...
Page 188 * Every monitorable component needs to defines the event points. Each event point * defines an event and the data/payload associated with that event. The EventPoint * is used to fire monitoring events. WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 189 * 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.
Page 190 The following is an example of xsd event schema content:: <?xml version="1.0" encoding="UTF-8"?>" <EventSpec xmlns="http://www.ibm.com/xmlns/prod/websphere/monitoring/6.0.0/es" name="Events" WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 191 <Data name="PollFrequency" type="int" minOccurs="0" maxOccurs="1"/> <Data name="PollQuantity" type="int" minOccurs="0" maxOccurs="1"/> </Payload> </Event> 3. Invoke Events import com.ibm.j2ca.extension.logging.internal.cbe.EngineData; CBEEngineData engineData = CBEEngineDataFactory.getEngineDataForEventType("Polling"); //This will instantiate the EngineData class for user defined event e.g "Polling". engineData.setValue("EventAction","STARTED"); //This will set the user defined action e.g. "Started"...
Page 192 Import com.ibm.j2ca.extension.monitoring.CEI.EventPoint; Define a unique PMI event point name. For example String eventName = uniqueAdapterID + “##” + ″myOutbound″; Get an instance of EventPoint: for each eventAction ENTRY, EXIT, FAILURE. EventPoint ep = (EventPoint)(EventPoints.INSTANCE.getEventPoints(eventName,eventAction)) WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 193 Note: The steps below describe how to invoke PMI statistics around a method named myOutbound. 1. Import com.ibm.j2ca.extension.monitoring.CEI.EventPoint; 2. Define a unique PMI event point name. For example String eventName = uniqueAdapterID + "##" + "myOutbound";...
Page 194 Measurement API, an API that allows adapters to collect and manage transaction end-to-end response time and volumetric information. The adapters can participate in IBM Tivoli Monitoring for Transaction Performance, by allowing collection and review of data concerning transaction metrics. The resource adapters using ARM define transactions at following three points: v InboundEventRetrieval: Will measure response time of retrieving events from the EIS.
Page 195 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’...
Page 196 Figure 2 illustrates aspect Example_2, which differs from Example_1 . Notice line 13, where the wildcard includes ″double dots″ (..) in the within() PCD, which means the includes all classes in the com.foo package and sub-packages. For example, com.foo.impl.Bar. Figure 8. Add FFDC to com.foo package and all sub-packages WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 197 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.
Page 198 String[] introspectSelf () { String[] self = { "userid=" + userid, "password=XXXXXXXX" }; return self; Hide password field of Person class from introspection. Figure 14. How to hide a sensitive field in this case a password WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 199: Validating The Code
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.
Page 200: Testing The Adapter In Unmanaged Mode
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...
Page 201 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.
Page 202 MessageEndpointFactory – To create endpoints v WorkManager – To create work instances v Work – To map to threads For a detailed and coded example of these contracts, see the TwineBall sample. WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 203: Testing The Adapter In Managed Mode
1. Import in the Twineball, or KiteString source code from the samples gallery. 2. Find the testcase you want to run. For example, choose AllTest.java in the com.ibm.j2ca.sample.twineball package in the tests folder. 3. Right-click on the class and choose Run As → JUnit Test.
Page 204 Configure the adapter instance. The Test Client displays a panel in which you select the Configuration, Module, Component, Interface and Operation you want to test. Make these selections, including the verb and the value(s) you want sent to the adapter and click Continue. WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 205 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.
Page 206 To test inbound functionality, you configure an inbound instance of your adapter with an export monitor. You then run an outbound adapter instance to generate an event of interest for your inbound adapter. WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 207 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.
Page 208 9. Create an event in your application’s event table. You can do this by running the test client on the Outbound application. When an event is received on the monitored component, an entry will appear in the Events window. WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 209: Validating Code With Rational Application Developer And Websphere Application Server
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.
Page 210 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. WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 211 7. Start UTC using the Run universal test client option. WebSphere Adapter development overview...
Page 212: Creating And Exporting A Resource Adapter
WebSphere Process Server. Here is a summary of the steps needed to create and export an enterprise application archive (EAR) file for your custom adapter. These steps are defined in adapter-specific detail in IBM WebSphere Adapter user guide documents. a. Launch IBM WebSphere Integration Developer.
Page 213 Select Export → EAR file from the pop-up menu. c. When prompted, specify the filename where the EAR is to be saved. 4. Start the target IBM WebSphere Process Server. 5. Start the administration console on that server. 6. Install the adapter EAR file on the target WebSphere Process Server.
Page 214: Reference
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. The foundation classes include generic contracts and methods to develop a working resource adapter and are included as a component to the WebSphere Adapter Toolkit.
Page 215 Events generally result from user-defined triggers set on objects in the IBM Rational Application Developer An IBM application that provides a set of extensions to the base Eclipse platform. IBM WebSphere Adapter A J2C Resource Adapter that is based on the Adapter Foundation Classes.
Page 216 A sequence of dialogue pages which collect user input to perform a task such as creating a New Java Project in the workspace or creating a New Java Class within a selected project. WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 217: Notices
Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.
Page 218 The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us.
Page 219: Programming Interface Information
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.
Page 220 WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 221: Index
4, 5, 6, 7 Archive (EAR) project, Enterprise Application 31 archive (EAR), enterprise application 2 archive (RAR), resource adapter 2 © Copyright IBM Corp. 2006, 2008 Callback event sender constructors 92 CCI Record 70 Classes Adapter Foundation...
Page 222 50 KiteString sample 12 LocalTransaction 49 log messages 178 Logging Common Event Infrastructure 184 events 184 WebSphere Adapters: WebSphere Adapter Toolkit User Guide ManagedConnectionFactory 50, 67 ManagedConnectionMetaData 50 MangedConnection 50 Message Listener Property 67 Metadata API 119 application-specific information 7...
Page 223 verbs usage business graph 71 WBIActivationSpec 37 WBIAdapterTypeImpl 39, 141 WBIConnection 35, 102 WBIConnectionFactory 35, 101 WBIConnectionRequestInfo 104 WBIDataBindingGenerator 38 WBIDataDescriptionImpl 39, 151 WBIInboundConnectionConfigurationImpl 39, WBIInboundConnectionTypeImpl 39, WBIInboundServiceDescriptionImpl 39, WBIInteraction 35, 102 WBIInteractionSpec 35, 103 WBILocalTransaction 35 WBIManagedConnection 35, 100 WBIManagedConnectionFactory 35, 99 WBIMetadataDiscoveryImpl 39, 139 WBIMetadataEditImpl 39, 151...
Page 224 WebSphere Adapters: WebSphere Adapter Toolkit User Guide...
Page 226 Printed in USA...

This manual is also suitable for:

Websphere adapter toolkit

IBM WebSphere Adapters User Manual

Websphere Adapter Toolkit

Notices

Quick Links

Related Manuals for IBM WebSphere Adapters

Summary of Contents for IBM WebSphere Adapters

This manual is also suitable for:

Table of Contents