IBM WebSphere Adapters - Manuals

WebSphere Adapter Toolkit The IBM ® WebSphere ® Adapter Toolkit provides the development tools, libraries and sample code to assist you in creating JCA resource adapters. With the toolkit you may create either of the following: v A resource adapter based on the interfaces defined by the JCA Resource...

The development process using the IBM WebSphere Adapter Toolkit includes thefollowing as shown in the illustration: 1. Run the New JCA Resource Adapter Project wizard.The wizard generates a resource adapter deployment descriptor and code. Thecode can include sequence of calls, log and trace messages...

Inbound event notification complements outbound request processing, enablingadapters to provide bidirectional communication between business processes andEIS applications. The IBM WebSphere Adapter portfolio of adapters is based on the Java 2 Platform,Enterprise Edition (J2EE) standard. JCA is a sta...

WebSphere adapters utilize a format-independent data model for representing dataobjects. In a WebSphere Process Server or WebSphere Enterprise Service Busruntime environment, WebSphere adapters use an extension of the service dataobjects (SDO) for representing data objects. Architectural overview In...

processing performed by each component (and subcomponent) in the model isdescribed in sections that follow the illustration. The component model allows for a single architecture for adapter developmentand evolution. It uses recognized standards but extends them as necessary, forexample with high per...

the appropriate programming model. It is responsible for mapping the specificinvocation to the invocation of the connector component through the JCA commonclient interface (CCI). The component developer who has knowledge of the connector invocationinterfaces and the runtime programming model, delive...

Version 1.1 of Enterprise Metadata Discovery includes enhancements forconfigurable 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 adap...

– The New Connector Project Wizard - Prompts you to specify information about the resource adapter you wish to develop, and then generates code anda deployment descriptor.The code generated by the wizard can include sequence of calls, log and tracemessages and comments. – Resource Adapter Deployment...

v Generate a resource adapter deployment descriptor You can view and edit this deployment descriptor using the Resource AdapterDeployment Descriptor Editor. Resource Adapter Deployment Descriptor Editor overview This multi-page editor allows you to display, configure, and validate the resourceadapte...

IBM WebSphere Adapter Toolkit tasks The tasks range from installing the toolkit, samples, and Adapter FoundationClasses (using the Eclipse Update Manager in WebSphere Integration Developer) toimplementing and validating your code. Table 1. WebSphere Adapter Toolkit tasks Task Task description Valida...

Operating system Versions Windows 2000 Windows 2000 Professional (SP4)Windows 2000 Server (SP4)Windows 2000 Advanced Server (SP 4) Windows XP Windows XP SP 2 Windows 2003 Windows Server 2003 StandardWindows Server 2003 Enterprise Hardware requirements The table shows the hardware requirements for su...

This documentation describes how to run the Twine Ball sample only. However,you can apply the instructions for running and testing the Twine Ball sample tothe Kite String sample. The sample instructions accommodate creating an adapter for the Twine Ballsample using WebSphere Integration Developer, f...

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

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 intoyour workspace. Now you can perform external service discovery for the Tw...

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 theDiscovered objects pane and add it to the Selected obje...

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) aliassecurity credential and click Next . 18 WebSphere Adapters: WebSphere Adapter Toolkit U...

15. Click Finish from the Service Location Properties window to add the outbound interface to the module. 16. You are prompted on whether you want to update the model, select Yes . Run the external service discovery process again to add the inbound interface tothe module. Run external service discov...

7. From the Processing Direction window, select Inbound and click Next . 8. From the Discovery Configuration window, click Next . No connection properties are required. 9. From the Object Discovery and Selection window, select CUSTOMER and addit to the Selected objects portion of the window then cli...

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) aliassecurity credential . WebSphere Adapter development overview 23

12. From the Service Location Properties window, click Finish to add the inbound interface to the module. 13. You are prompted on whether you want to update the model, select Yes . You should see the inbound and outbound interfaces in the viewing area ofthe assembly diagram editor: Modify the 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 from the inbound interface to the new Java component. A windowdisplays to inform you that your actions will allow the service to be used inother modules. Click OK . ...

6. In Java Creation and Deployment Configuration, make the followingselections: 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 ex...

6. On left side select EJBSessionBean1 and click Customer createCustomer(Customer) Enter input customer parameters Troubleshooting the samples You may need to troubleshoot issues that arise when creating or running thesamples. Errors The following errors may result when working with the sample code:...

Launching the New Connector Project wizard You launch the wizard from IBM WebSphere Integration Developer. Make sure you have met all of the installation requirements and that you havesuccessfully installed WebSphere Integration Developer and the WebSphereAdapter Toolkit plug-ins. Launch the New Con...

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 wizard and displays the Connector Project dialog. Connector Project dialog You are ready to describe your project and resource adapter properties. 3...

Specify project properties You name your connector project, optionally adding it to an Enterprise Applicationproject. You also specify the configuration used for developing the resourceadapter. You perform all of these tasks from the Connector Project dialog. Connector Project dialog 1. Name your Co...

Specify project facets As part of the process of creating a project, you specify project facets . A project facet represents a unit of functionality in the project. Project facets define characteristicsand requirements for projects. When you add a facet to a project, that project isconfigured to per...

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 boththe adapter and the adapter class. You name the ad...

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 inthe log and trace files as follows: ShortName + the characters “RA” + the value of the adapter ID ...

For information on the characteristics of an IBM WebSphere Resource Adapter anda 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 Sp...

You can select the following properties when generating outbound adapter classes: v Local transaction support Generating outbound adapter classes with local transaction support means thatthe transaction is managed and performed by the EIS. LocalTransaction indicates the IBM WebSphere adapter support...

/** * 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 WBIXAResourceWra...

When you choose the connection pooling component property the wizard willcreate the ActivationSpecWithXid class that extends WBIActivationSpecForPooling . For information on how to generate inbound connection pooling support, seeGenerating inbound connection pooling support. v Event polling support ...

com.ibm.j2ca.extension.databinding.WBIDataBindingGenerator For information on how to generate data binding classes, see Generating DataBinding Classes. Enterprise Metadata Discovery classes There are no properties associated with Enterprise Metadata Discovery classes. Generating enterprise metadata ...

v StringCaseChanger This is a utility that you can use format the business object or attribute nameproperly. For information on how to generate Enterprise Metadata Discovery classes, seeGenerating Enterprise Metadata Discovery classes . Generating outbound adapter classes Generate outbound adapter c...

Review the section on command pattern classes in Generating an IBM WebSphereResource Adapter. The command pattern classes allow you to break down a hierarchical update into aseries of nodes and then generate a collection of sub-commands to manage thenodes. An interpreter processes the sub-commands, ...

2. Review the available component property options associated with inboundadapter classes.Each of the component property options are described in the sections thatfollow. Generate the inbound adapter classes for the component property selected. Note: Before deploying your adapter to WebSphere Proces...

2. Click Finish . Now, you can generate inbound event polling support. Generating inbound event polling support: Event polling refers to an adapter’s capability to poll the event records from theevent store at regular intervals. In each poll call, a number of events are processedby the adapter. Revi...

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 newinformation about, an EIS. The phrase callback refers to...

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 servicediscovery tool in WebSphere Integration Develope...

2. When you are finished choosing generation options, click Finish . Generate data binding classes. Generating data binding classes You can generate data binding classes separate from the data binding classes thatare generated from enterprise metadata discovery. Review the section on data binding cl...

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 propertiesand options you specify. The following sections describe the J2EE resou...

implements javax.resource.runtime.SingleTypedProperty andjavax.resource.runtime.PropertyDescriptor v SingleValuedProperty implements javax.resource.runtime.SingleValedProperty and javax.resource.runtime.PropertyDescriptor v PropertyGroup implements javax.resource.runtime.PropertyGroup and javax.reso...

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 aninbound event from the EIS. Review the section on inbound JCA resource a...

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 servicediscovery tool in WebSphere Integration Developer to...

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 optionsyou specified. After you specify options for your resource adapter, the wizard generates code anda deployme...

Using the Resource Adapter Deployment Descriptor editor The Resource Adapter Deployment Descriptor editor provides an easy andconvenient way to configure your resource adapter. Resource Adapter Deployment Descriptor editor You configure the resource adapter by using a deployment descriptor. Thedeplo...

Deployment descriptor Overview pane Alternatively, you can view the deployment descriptor in the editor byhighlighting 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...

Using the Overview pane The Overview pane provides access to general information about your resourceadapter. You can display it at any time by clicking the Overview tab at the bottom of this pane. In addition to providing general information about your resource adapter, you cangenerate components th...

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 fitinto the allotted area, the large icons must be 32 x 32 pixels and the small icon 16 x16 pixels. WebSphere Process Se...

Resource adapter pane The General Information section allows you to specify deployment descriptor values for the entire resource adapter. This section displays the name of theResourceAdapter class with which this deployment descriptor is associated. Thisclass must directly or indirectly implement th...

Add Config property dialog When you add, modify, or delete user-defined properties in this section, the editorcreates (or removes) the corresponding Java bean properties in your code. Formore information, see Modifying properties. The Admin Objects section allows you to specify administered objects ...

The sections of the Outbound Adapter pane are described below. Outbound resource adapter pane The General Information section allows you to specify deployment descriptor values associated with the outbound resource adapter. You can specify the level oftransaction support, if any, and whether reauthe...

Add Connection Definition dialog A Connection Definition requires the following information: v ConnectionFactory Interface v ConnecitonFactory Implementaion Class v Connection Interface v Connection Implementation Class v ConnectionRequestInfo Class v ManagedConnectionFactory Class Once a connection...

Add Config property dialog When you add, modify, or delete user-defined properties in this section, the editorcreates (or removes) the corresponding Java bean properties in your code. Formore information, see Modifying properties. The Authentication Mechanisms section allows you to specify the authe...

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 specifiedActivationSpecWithXid are shown in the properties list directly...

Add Required Config Property dialog When you add, modify, or delete user-defined properties in this section, the editorcreates (or removes) the corresponding Java bean properties in your code. Formore information, see Modifying properties. Modifying deployment descriptor properties When you modify c...

Generated bean properties The editor maps resource adapter properties to class code. When you modify theresource adapter, the editor performs automatic source code updates. The table shows the generated code affected when you add, delete, or modify aconfiguration property: Class code affected by con...

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

b. Identify configuration properties suitable for use by a client for a specificoutbound connection instance (for example, username, password, language). c. Identify configuration properties for inbound event processing ingeneral–this will probably be a combination of those you’ve defined in 1aand 1...

v A full, working implementation, as opposed to the CCI Record model thatsimply defines interfaces that must be implemented by the adapter developer. v A built-in support for tracking changes at both the object and property levels,which allows for improved efficiency in processing and reduced bandwi...

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

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

Outbound Operation Signatures Notes applyChanges<BOType>create<BOType>update<BOType>delete<BOType> These operations can handle delta orafter-image business objects. The assumptionis that the adapter can consume either typeof object or, if not, can convert after-imageand delta...

v Adapters should follow strict conventions in processing business objects. Thisincludes failing if an entity is marked as updated in the input business objectbut does not exist in the EIS (rather than attempting to create the entity in theEIS). isSet property: WebSphere business objects support an ...

2. If the EIS does not generate its own primary key (or keys), insert the keyvalues from the input business object into the appropriate key column (orcolumns) of the EIS entity. 3. Update the output business object to reflect the values of the newly created EISentity; this includes any EIS-generated...

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 ensuresthat the returned hierarchi...

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 ofthe objects that will be returned, the ″ getNext()...

Event Store Requirements 1. Event data must be persistent. Once detected in the event store, an eventshould remain available there until deleted by the adapter regardless ofconnection failure or time elapsed. 2. The event store must allow the adapter to both identify and change the state ofevent rec...

During recovery, WebSphere Application Server calls the resource adapter, queriesit for XAResources, and then performs transaction recovery as follows: v Transactions that the J2EE container rolls back have not been delivered and aremarked NEW. v Transactions that the J2EE container commits have bee...

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 adapterevent-retrieval mechanism to locate and retrieve the full entity in the EIS for whichthis event was originally re...

Status The event status is used to track the state of an event. It allows the FoundationClasses to distinguish among events that are new from those in process orineligible. The adapter must support five different event status values as described in thetable below. All events generated by the event d...

Field Description eventType Corresponds to the Business Object Namefield of the event record timeStamp Corresponds to the Timestamp field of theevent record eventStatus Corresponds to the Status field of the eventrecord Event detection: Events detection mechanisms reflect the sources that trigger th...

5. Set the name of the WebSphere business object complexType that correspondsto this application entity 6. Set the event status to New. Implementing event retrieval in the adapter The careful work of implementing event retrieval in the adapter uses twoFoundation Classes interfaces. The goals are set...

Method Description ArrayList getEvents(int quantity, inteventStatus, String[] typeFilter) This method enables the adapter todetermine if there are any new eventsavailable or old events that need re-sending.Implement this method to query the eventstore and return a list of event instances (upto the l...

EventStore transaction control methods Method Description boolean isTransactional() Is the event store transactional? If so, thismethod should return true . void commitWork() This method should commit the pendingtransaction. It is required only if transactionsare supported. void rollbackWork() This ...

Function selector: Function selectors map resource adapter events to corresponding SCA exportfunction names. The WebSphere Adapter component that exposes resource adapters as SCAcomponents requires what is known as a function selector. This selector mapsevents generated by resource adapters to a SCA...

When you enable inbound callback event notification, business processes arealerted 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 processesof a change, as opposed to the polling mechanism used in...

Using the IBM WebSphere adapter foundation classes forinbound callback event processing The adapter foundation classes can automatically track endpoints (the consumersof events) for the adapter, control the event pick up and delivery of events, handlerecovery of events if the adapter unexpectedly te...

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

Callback event processing for event recovery When there is a failure in the event processing as part of system recovery, theadapter is able to recover the unprocessed events by implementing theonce-one-only delivery mechanism. During real time event processing if any component of the business integr...

When the container starts, it calls the getXAResources() method on the adapter toget all the associated XA resources. The adapter then instantiates the appropriateXA resource and returns it back to the container. The JCA container now calls the recover() method on the returnedXAResourceImpl to get a...

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-pro...

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

Best practices v Each ManagedConnection instance should encapsulate at most one connection tothe EIS. v Since there may be more than one Connection instance for eachManagedConnection instance, resource adapter developers should implementprivate contracts between their WBIManagedConnection subclass a...

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

properties should not change the configuration of the EIS. javax.resource.cci.ConnectionMetadata: A javax.resource.cci.ConnectionMetadata instance provides information to the clientcomponents about the underlying EIS of a resource adapter. Client components canuse the javax.resource.cci.Connection.g...

3. Override method WBIManagedConnection.getLocalTransaction() and, if XAsupport is provided, method WBIManagedConnection.getXAResource(). Wrap either or both of the LocalTransaction or XAResource instances returned bythese methods with a WBILocalTransactionWrapper orWBIXATransacxtionWrapper instance...

Adapters are responsible for creating, updating, retrieving, and deleting (CRUD)records in the EIS system based on the structure described by the incomingmetadata and the content in the incoming cursor. The command pattern approachis recommended for handling the generic processing of CRUD operations...

Consider the following scenario: Child B1 is in the EIS, but is not in the incomingstructure. Child B1, then, must be deleted. The Command Manager will execute aRetrieve command to build the structure as it appears in the EIS, then comparethis structure to the incoming object tree. The comparison fi...

Command Manager Delete Delta objects Delta processing is only relevant for service data objects (SDO). The Command Manager functions in a similar way when processing delta objects.Instead of retrieving and comparing, the command manager reads the changesummary for the intended changes. Note that sin...

Command Manager Create When it processes this structure, the interpreter will execute the No-op commandsas well as the Create command. In general, the no-op commands should notmodify data in the EIS system. After-image processing: The Command Manager, based on the CommandManager API, implements thec...

The Command Manager processes delta structures in a manner analogous to thatof after-image data. The difference is that, for delta objects, comparative data isextracted from service data object change summaries. When the input service data object (SDO) represents an Update operation with adelta stru...

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 TwineBallUpdateCo...

Data and metadata Adapter Foundation Classes (AFC) implement DESPI APIs and support two dataformats, service data objects (SDO) and JavaBeans. The data format-specific implementations are provided in the AFC and areabstracted from the adapters which use the DESPI APIs to process data in aformat-inde...

Table 2. Mapping between built-in XSD schema and JavaBean properties (continued) Header Header anySimpleType String Any String There are cases in which a simple XML data type must be mapped to thecorresponding Java wrapper class for the Java primitive type: v an element declaration with the nillable...

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 impl...

These interfaces may contain more helper methods than are listed here, please seethe Javadoc for the additional helpers. Factory classes Class TypeFactory: TypeFactory creates an instance of an implementation of Type. The TypeFactory isalso capable of detecting whether SDO version 2, SDO version 1, ...

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 proper...

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 foundationclasses provides a JavaBeans record generator class that can genera...

The enterprise metadata discovery component is analogous to the Object DiscoveryAgent of WebSphere Business Integration Adapters. In addition to generatingbusiness object definitions, however, the enterprise metadata discovery alsogenerates service component architecture artifacts such as an Import/...

Service metadata Enterprise metadata discovery architecture The enterprise metadata discovery tooling includes runtime, discovery, and servicegeneration interfaces and metadata edit capabilities. Enterprise metadata discovery architecture Note: The solid arrows represent the enterprise metadata disc...

These interfaces extend the CCI interfaces defined in the JCA specification tosupport invocation of services discovered with enterprise metadata discovery.These interface implementations are provided by the resource adapter provideror a third party discovery service provider. These are the data bind...

for multiple back-end EIS assets. IBM WebSphere recommends a single adapterType for each enterprise metadata discovery implementation. The following information must be provided for this class by a discovery serviceimplementation. v ID (for example, PeopleSoft) v Description (for example, PeopleSoft...

copy matching properties from metadata connection to runtime connection. Formore information, see the WBIOutboundConnectionTypeImpl in the Javadocs. The following information must be provided for this class by a discovery serviceimplementation: v ID (for example, PeopleSoft) v Display name (for exam...

MetadataConnection The MetadataConnection object represents the connection to EIS or EIS repository. This interface is implemented by the Adapter Foundation Classes only and doesnot require any implementation from discovery service instances. MetadataConnection uses the managed connection factory to...

In addition to object selection, MetadataSelection also holds properties that are applicable for the selected objects. Such properties include the following: v Specification of service type: inbound or outbound v Namespace for use by business object definitions v ConnectionType that for use at run t...

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

Outbound Function Description The following information has to be filled in by the discovery serviceimplementations: v Name - e.g. createCustomer, applyChangesCustomer v InteractionSpec - Instance of interaction spec which has function name specifiedthat represents this method description. E.g. for ...

Note: To limit confusion, custom operation names should not conflict with the standard operation names mentioned above. Note: In cases where the mapping of EIS operations to Create, Retrieve, Update and Delete is equivalent except for naming conventions–for example, PeopleSofthas a Find operation th...

v PropertyGroup – A collection of properties including single and multi types and PropertyGroup itself. For example, OutboundConnectionConfiguration allows three property groups in one Main property group: UserConfiguration that includes Username and Password ; MachineConfiguration that includes Hos...

public TwineBallMetadataDiscovery() throws MetadataException { super("com.ibm.j2ca.sample.twineball.emd"); } The WBIAdapterTypeImpl constructor requires the following parameters: 1. The name of the class representing the ResourceAdapter class. This is used to create property groups for Resou...

discovery and the one that used for run time. The copy is based on names. Forexample, 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 importSelec...

the managed connection factory types that are supported by the adapter. Eachmanaged connection factory maps to an instance of outbound connection types. Each enterprise metadata discovery implementation should extend WBIOutboundConnectionTypeImpl and implement the methods described below. Constructo...

setDescription(WBIMetadataDiscoveryImpl.getPropertyDescription ("ConnectionType")); setId("TwineBall");setDisplayName(WBIMetadataDiscoveryImpl.getPropertyName ("ConnectionType")); } createInboundConnectionConfiguration The createInboundConnectionConfiguration() method returns...

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

This class is similar to WBIOutboundConnectionConfigurationImpl except insteadof ManagedConnectionFactory , WBIInboundConnectionConfigurationImpl handles the ActivationSpecWithXid bean class. You must extend the methods described below. public PropertyGroup createActivationSpecProperties() { WBIProp...

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 thatpopulate the MetadataObject nodes in the tree. public T...

(Constants.SERVICETYPE)); propertyGroup.addProperty(typeProp);WBISingleValuedPropertyImpl nameSpaceProp = new WBISingleValuedPropertyImpl(Constants.NAMESPACE, String.class); nameSpaceProp.setDefaultValue(Constants.TB_DEFAULT_NAMESPACE);propertyGroup.addProperty(nameSpaceProp);nameSpaceProp.setDispla...

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 thesenodes map to objects i...

createSelectionProperties The createSelectionProperties() method returns a property group that is used to capture inputs from users. These inputs include business object namespace,supported operations, and the relative path in the module project where XMLschema definitions should be saved. public Pr...

The enterprise metadata discovery service uses WBIMetadataEditImpl to acquire connectionTypes , which contains editable properties for ResourceAdapter , ManagedConnectionFactory , or ActivationSpecWithXid . The enterprise metadata discovery tooling creates an instance of WBIMetadataEditImpl during t...

dataDesc.prepareChildSchemaFiles(); WBIMetadataDiscoveryImpl.getLogUtils().trace(Level.FINER, CLASSNAME, "preparingChildSchemaFiles","Preparing SchemaFile for " + bo.getDisplayName()); dataDesc.prepareSchemaFiles();SchemaDefinition[] schemaFiles = dataDesc.getSchemaDefinitions();for ...

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");...

WBIMetadataDiscoveryImpl.getLogUtils().traceMethodExit (CLASSNAME, "getImportNameSpaces"); return list; } getNameSpaces The getNameSpaces() method returns the NameSpaces listed in the XML schema definition. Typically these are application specific information schema definitionnamespaces. Not...

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: WBIInboundServiceDe...

FunctionDescription[] funcArray = new FunctionDescription[functionDescriptions.size()]; functionDescriptions.toArray(funcArray);super.setFunctionDescriptions(funcArray); } WBIOutboundServiceDescriptionImpl samples: WBIOutboundServiceDescriptionImpl represents the object that populates function descr...

Creating services that use technology-style adapters relies on being able toimplement 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 artifac...

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

To access the binding configuration, do context.get(BindingContext.BINDING_CONFIGURATION) To access the expected type, do context.get (BindingContext.EXPECTED_TYPE) Function selectors, data handlers, and data bindings are all configurable. Thisconfiguration can be quite rich, providing single and mu...

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

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 IBMWebSphere Adapter for FTP. The WBIMetadataType interface allows you to select a payload type, and optionally generate a business graph structur...

Initialize input method This method resolves the type of the metadata if it’s a JavaBean or SDO type andinitializes the metadata interfaces appropriately. public void initializeInput(DataExchangeFactory dataBinding, Object metadata) throwsDESPIException . Purpose of the initialize input method Imple...

Set managed connection method This method passes the ManagedConnection handle to the record implementation, allowing the record to get access to the physical connection to the backendapplication to perform processing. public void setManagedConnection( ManagedConnection managedConnection) throws Reso...

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 onerecord from the backend application into OutputCursors/Accessors. It should keeptrack of which record it needs to do next so in subsequ...

The method should first extract the value from backend object representationdefined through Xpath and use OutputCursor and OutputAccessor interfaces topopulate values in runtime data structure. Sample Data binding implementation Adapters must provide implementations for DataBinding interface in orde...

For operations where getNext() should be invoked multiple times like RetrieveAll,the databinding should call getNext() multiple times add the built BusinessObjectto the list of BusinessObjects within the Container BO. getRecord public Record getRecord() throws DataBindingException This method should...

v When WBIStructuredRecord is initialized with data that contains Bidiannotations, Cursors and accessors that are associated with that structuredrecord will automatically translate the content into or from the Bidi formatspecified in the annotations, via special cursors and accessors that wrap theve...

How to support fault handling: Understand the following concepts for implementing fault handling into youradapter. Before you define faults, review adapter processing to determine which errorconditions can be categorized as faults, rather than as exceptions. You will likely beable to apply at least ...

public class JDEXMLListFaultDataDescription implements FaultDataDescription { public JDEXMLListFaultDataDescription() { super();// TODO Auto-generated constructor stub } private String faultName = null; public String getFaultName() { // TODO Auto-generated method stubreturn faultName; } public void ...

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.ex...

Table 4. Fault name and configured fault binding (continued) Fault Name Configured Fault Binding INVALID_REQUEST com.ibm.j2ca.extension.emd.runtime.WBIFaultDataBindingImpl When input to the operation does not have the required characteristics, theadapter throws this fault. Specific errors that can r...

You can use the FaultBOUtil to define the fault business object, as long as eitherno attributes or only simple attributes are added. This should amount to a fewlines of code, See Implementing Faults for an example. Note: The model for fault classes and fault business objects is a 1-to-1 relationship...

– They provide information on the state of the adapter for use by monitor tooling – Represented as common base event data at run time, event messages can be included in the extended LogUtils.log method signatures Support for protecting sensitive user data in log and trace files WebSphere Adapter Too...

Writing a trace message You use the trace method of the LogUtils class to generate a trace message. This method has two signatures. One of them is informational. The other is associatedwith an exception. void trace (Level l, String classname, String method, String msg) void trace (Level l, String cl...

"getRecordForEvent()", "test"); return null; }} Example of trace message for the outbound scenario with confidential tracingproperty enabled public HelloWorldConnectionFactory(ConnectionManager connMgr, WBIManagedConnectionFactory mcf) { super(connMgr, mcf); getLogUtils().traceConfid...

Tracing assists developers and troubleshooters. Due to the significant performancecost incurred by tracing, however, many customers disable it in productionenvironments. When developing or troubleshooting, it is good practice to checkwhether tracing is enabled before building to generate trace messa...

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 todistinguish between the adapter and the base classes message file. The defaultvalue of Message Type field is ADAPTER_RBUNDLE . You u...

translated text. Values that are language-independent, such as key values or objectnames, are appropriate as log message parameters. Similarly to trace messages, parameters in a log message can contain data from thecustomer’s EIS. Because a customer might be unwilling to send a log file thatcontains...

Example of log message for the inbound scenario with confidential tracingproperty 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.INF...

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 monit...

<?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...

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="Re...

Purpose 1. Monitorable Element Schema (.mes) file changesDefines the element type within an adapter where monitoring can be attached.The element type is specified using the Qname of the element type from theschema, which defines the structure of the artifact itself. It also defines thenatures (ENTRY...

d. If eventPoint is enabled, then fire event for Entry, Exit and Failure is invoked.Entry event is fired in the beginning of the method call, exit event is fired inthe end of the method call and failure event is fired in case of exception.For example we can invoke failure event by following API call...

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 resource adapters are instrumented with the Application ResponseMeasurement AP...

statistics and data for each ManagedConnection , which can be used to assess and troubleshoot performance related problems. In order for resource adapters to participate in various WebSphere RequestMetrictools for outbound, diagnostic tools, etc, you will need to follow these steps: 1. Import com.ib...

FFDC processing overview Instead of explicitly instrumenting catch blocks by calling FFDC directly, eithermanually or by using a tool, you can write a simple aspect using the AspectJlanguage, which encapsulates the FFDC policy for your code. The FFDCSupport aspect is abstract. Like an abstract class...

Exception messages Exception messages, like trace messages, convey information about problems. Thedifference is that exception messages are tailored more directly to support teamsfamiliar with adapter source code, and therefore need not be translated. Treat text included in exception messages as you...

To test the enterprise metadata discovery (EMD) implementation for the developedresource adapter, complete the following steps: 1. From the IBM WebSphere Adapters Foundation Classes library, copy thefollowing three dependent jars into the connectorModule connector project: v commonj.connector.jar v ...

JUnit: an open source framework for unit testing JUnit is becoming the standard tool for unit testing in Java developmentenvironments. JUnit allows you to quickly and easily integrate automatedregression testing into your coding and build processes. With JUnit, an open source unit test framework, yo...

Your adapter may or may not be dependant on ″ live ″ data inside the EIS. If so, you must either return the data to a known state after every test, or create a mockimplementation of the EIS API so that EIS data remains untouched. setUp() In the setup method for outbound, perform the following step: ...

setUp() The setUp() method for inbound is very similar to that for outbound. You may, however, not need an outbound connection through the adapter. Accordingly, youneed only perform the following tasks: 1. Create an adapter instance and set its properties 2. Start the resource adapter. Test The test...

For information on testing the adapter in managed mode in WebSphereApplication Server, see Validating code with Rational Application Developer /Websphere Application Server. Installing the test client To test your adapter in a runtime environment, you must first install a test clienton the target We...

Test module configuration 3. Select the testing mode and click Finish to start the test. On the Deployment Location screen, select a WebSphere Process Server to test in managed mode(optionally you can select Eclipse to test in unmanaged mode). In addition, you select Run or Debug mode. If you select...

Adding a value to the Datapool This adds the data to Datapool. When you want to use this input data again, select Use Value from Pool. Using an execution trace The test client you installed provides you with a trace of the execution and thedata path of the test. You can optionally load any previousl...

After you have created and exported an adapter EAR file with the service type setto Inbound, you can test inbound functionality. 1. Edit your module using the Assembly Editor, connecting the export to a Javacomponent. a. Double-click on the module to start the Assembly Editor. b. Create a new Compon...

Selecting the Java package g. Save the module. 2. Publish the application to WebSphere Process Server. 3. Open the administration console for the WebSphere Process Server andconfigure the application’s activation specifications so that it can processinbound requests. 4. Restart the inbound applicati...

4. In the Resource Adapter deployment panel, choose how to deploy the adapter.You can deploy the adapter with the EAR or you can deploy the adapter as astand-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 value...

7. Start UTC using the Run universal test client option. WebSphere Adapter development overview 205

8. Once the UTC comes up, use the JNDI explorer to find your EJB. Look for yoursession EJB under EJB Beans. Now, you can test your adapter via the EJB interface. You can create a session bean using the home interface (create), then invokebusiness methods on the remote interface, providing the approp...

Reference Terminology The terminology presented are of terms that are used frequently in thedocumentation. Adapter foundation classes (AFC) Sometimes referred to as base classes, the adapter foundation classes are acommon set of services for all IBM WebSphere resource adapters. The AdapterFoundation...

Eclipse An open source infrastructure for building tools such as an IntegratedDevelopment Environment (IDE). The toolkit’s wizard and editor are Eclipseplug-ins. Eclipse Plug-in A module that extends the functionality of the Eclipse Platform Editor A component in Eclipse that allows data to be edite...

Notices This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document inother countries. Consult your local IBM representative for information on theproducts and services currently available in your are...

this code are derived from IBM Corp. Sample Programs. (c) Copyright IBM Corp._enter the year or years_. All rights reserved. If you are viewing this information softcopy, the photographs and colorillustrations may not appear. Programming interface information Programming interface information, if pr...