IBMメーカーWebSphere Adaptersの使用説明書/サービス説明書
ページ先へ移動 of 226
WebSphere ® Adapters WebSphere Adapter T oolkit User Guide Version 6 Release 2 Version 6 Release 2 .
.
WebSphere ® Adapters WebSphere Adapter T oolkit User Guide Version 6 Release 2 Version 6 Release 2 .
Note Before using this information and the pr oduct it supports, read the information in “Notices” on page 21 1. December 2008 This edition applies to version 6, release 2, modification 0 of and to all subsequent r eleases and modifications until otherwise indicated in new editions.
Contents WebSphere Adapter T oolkit ...... 1 IBM W ebSpher e Adapter T oolkit technology overviews ............... 2 IBM W ebSpher e Adapters ......... 2 Architectural overview .......... 4 How metadata is used at build time and run time 7 Using Enterprise Metadata Discovery to build services .
iv W ebSpher e Adapters: W ebSphere Adapter T oolkit User Guide.
W ebSphere Adapter T oolkit The IBM ® W ebSphere ® Adapter T oolkit provides the development tools, libraries and sample code to assist you in creating JCA resour ce adapters. W ith the toolkit you may create either of the following: v A resource adapter based on the interfaces defined by the JCA Resource Adapter 1.
The development process using the IBM W ebSphere Adapter T oolkit includes the following as shown in the illustration: 1. Run the New JCA Resource Adapter Project wizard. The wizard generates a r esource adapter deployment descriptor and code. The code can include sequence of calls, log and trace messages and comments.
Inbound event notification complements outbound request pr ocessing, enabling adapters to provide bidir ectional communication between business processes and EIS applications. The IBM W ebSphere Adapter portfolio of adapters is based on the Java 2 Platform, Enterprise Edition (J2EE) standard.
W ebSphere adapters utilize a format-independent data model for repr esenting data objects. In a W ebSphere Process Server or W ebSphere Enterprise Service Bus runtime envir onment, W ebSphere adapters use an extension of the service data objects (SDO) for repr esenting data objects.
processing performed by each component (and subcomponent) in the model is described in sections that follow the illustration. The component model allows for a single architectur e for adapter development and evolution.
The connectivity subcomponent interacts with the target enterprise information system’s specific libraries and functionality . The subcomponent is exposed to the application interface component thro.
the appropriate pr ogramming model. It is responsible for mapping the specific invocation to the invocation of the connector component through the JCA common client interface (CCI). The component developer who has knowledge of the connector invocation interfaces and the runtime pr ogramming model, delivers the application component.
V ersion 1.1 of Enterprise Metadata Discovery includes enhancements for configurable data handlers, function selectors, and data bindings, and a way to build service descriptions using these configured artifacts and existing schemas.
– The New Connector Project W izard - Prompts you to specify information about the resour ce adapter you wish to develop, and then generates code and a deployment descriptor . The code generated by the wizard can include sequence of calls, log and trace messages and comments.
v Generate a resource adapter deployment descriptor Y ou can view and edit this deployment descriptor using the Resource Adapter Deployment Descriptor Editor .
IBM W ebSphere Adapter T oolkit tasks The tasks range from installing the toolkit, samples, and Adapter Foundation Classes (using the Eclipse Update Manager in W ebSphere Integration Developer) to implementing and validating your code.
Operating system V ersions W indows 2000 W indows 2000 Professional (SP4) W indows 2000 Server (SP4) W indows 2000 Advanced Server (SP 4) W indows XP W indows XP SP 2 W indows 2003 W indows Server 2003 Standard W indows Server 2003 Enterprise Hardware requirements The table shows the hardwar e requirements for supported operating systems.
This documentation describes how to run the T wine Ball sample only . However , you can apply the instructions for running and testing the T wine Ball sample to the Kite String sample.
This launches the Samples. c. From the Samples navigation pane, select T echnology samples and expand Java and W ebSphere Adapters so that the T wine Ball and Kite String samples display . d. Click T wine Ball to display a description of the T wine Ball sample in the viewing pane of the T echnology Samples.
c. Optional: Deselect the Add project to an EAR check box. 4. Click Finish . A dialog prompts you to open the J2EE perspective. Click Ye s to finish the process of importing the deployable RAR file for the T wine Ball sample into your workspace. Now you can perform external service discovery for the T wine Ball sample.
4. Click Next to launch the New External Service window . 5. From the New External Service window , make sure that Unlisted Adapter is selected and click Next . 6. From the Select an Adapter window , expand T wineBallConnector (IBM:6.2) , select CWY A T_T wineBall and click Next .
7. From the Pr ocessing Direction window , select Outbound and click Next . 8. From the Discovery Configuration window , click Next . No connection properties ar e required. 9. From the Object Discovery and Selection window , select CUSTOMER fr om the Discovered objects pane and add it to the Selected objects portion of the window then click Next .
10. From the Configur e Composite Properties window , select Next . 11 . From the Service Generation and Deployment Configuration window , deselect Specify a Java Authentication and Authorization Services (JASS) alias security credential and click Next .
12. From the Service Location Pr operties window , click New . This launches the New Integration Project window . 13. From the New Integration Pr oject window , select Create a module project and click Next . 14. Enter values in the New Module window and click Finish .
15. Click Finish from the Service Location Pr operties window to add the outbound interface to the module. 16. Y ou are prompted on whether you want to update the model, select Ye s . Run the external service discovery process again to add the inbound interface to the module.
4. Click Next to launch the New External Service window . 5. From the New External Service window , make sure that Unlisted Adapter is selected and click Next . 6. From the Select an Adapter window , expand T wineBallConnector (IBM:6.2) , select CWY A T_T wineBall and click Next .
7. From the Pr ocessing Direction window , select Inbound and click Next . 8. From the Discovery Configuration window , click Next . No connection properties ar e required. 9. From the Object Discovery and Selection window , select CUSTOMER and add it to the Selected objects portion of the window then click Next .
10. From the Configur e Composite Properties window select Next . 11 . From the Service Generation and Deployment Configuration window , deselect Specify a Java Authentication and Authorization Services (JASS) alias security credential .
12. From the Service Location Pr operties window , click Finish to add the inbound interface to the module. 13. Y ou are prompted on whether you want to update the model, select Ye s . Y ou should see the inbound and outbound interfaces in the viewing area of the assembly diagram editor: Modify the module.
a. In the viewing pane of the Assembly diagram, right click and select Add → Java to add a Java component to the diagram 2. Add a wire fr om the inbound interface to the new Java component. A window displays to inform you that your actions will allow the service to be used in other modules.
4. Run the administrative console and verify the module is installed and running. 5. T est the module by performing the following steps: a. Change to the Business Integration perspective b. Right click on the module and select T est → T est Module c.
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 .
6. On left side select EJBSessionBean1 and click Customer createCustomer(Customer) Enter input customer parameters T roubleshooting the samples Y ou may need to troubleshoot issues that arise when creating or r unning the samples. Errors The following errors may r esult when working with the sample code: v A com.
Launching the New Connector Project wizard Y ou launch the wizard from IBM W ebSphere Integration Developer . Make sure you have met all of the installation r equirements and that you have successfully installed W ebSphere Integration Developer and the W ebSphere Adapter T oolkit plug-ins.
Select a wizard dialog 5. Start the wizard. Expand the Java EE folder , choose Connector Project , and click Next . This starts the New Connector Project wizar d and displays the Connector Project dialog. Connector Project dialog Y ou are ready to describe your pr oject and resource adapter pr operties.
Specify project properties Y ou name your connector project, optionally adding it to an Enterprise Application project. Y ou also specify the configuration used for developing the resource adapter . Y ou perform all of these tasks from the Connector Project dialog.
Specify project facets As part of the process of cr eating a project, you specify project facets . A project facet repr esents a unit of functionality in the project.
2. Click Next to advance to the Resource adapter pr operties page. Now you are r eady to set the properties for the resour ce adapter . Specify resource adapter properties Resource adapter pr operties are the descriptive properties that you assign to both the adapter and the adapter class.
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 use.
For information on the characteristics of an IBM W ebSphere Resource Adapter and a J2C Resource Adapter , see Introduction to JCA. Generation Options dialog From the Adapter Specification dr op-down, .
Y ou can select the following properties when generating outbound adapter classes: v Local transaction support Generating outbound adapter classes with local transaction support means that the transaction is managed and performed by the EIS. LocalT ransaction indicates the IBM W ebSphere adapter supports local transactions.
/** * Does the EIS support XA transaction? * Get the XAResource from your EIS and return the wrapper. * * @return new instance of WBIXAResourceWrapper * @see javax.
When you choose the connection pooling component property the wizar d will create the ActivationSpecWithXid class that extends WBIActivationSpecForPooling . For information on how to generate inbound connection pooling support, see Generating inbound connection pooling support.
com.ibm.j2ca.extension.databinding.WBIDataBindingGenerator For information on how to generate data binding classes, see Generating Data Binding Classes. Enterprise Metadata Discovery classes There ar e no properties associated with Enterprise Metadata Discovery classes.
v StringCaseChanger This is a utility that you can use format the business object or attribute name properly . For information on how to generate Enterprise Metadata Discovery classes, see Generating Enterprise Metadata Discovery classes .
Generating outbound local transaction support methods: W ith local transaction support, the transaction is managed and performed by the EIS. LocalT ransaction indicates the IBM W ebSphere adapter supports local transactions. Local transaction support methods provide a LocalT ransaction implementation and return the wrapper .
Generating outbound XA transaction support methods: W ith XA transaction support, the transaction spans multiple heterogeneous systems. It uses global or two-phase-commit protocol. If a transaction manager coordinates a transaction, that transaction is consider ed a global transaction.
Review the section on command pattern classes in Generating an IBM W ebSphere Resource Adapter . The command pattern classes allow you to break down a hierar chical update into a series of nodes and then generate a collection of sub-commands to manage the nodes.
2. Review the available component property options associated with inbound adapter classes. Each of the component property options ar e described in the sections that follow . Generate the inbound adapter classes for the component property selected. Note: Before deploying your adapter to W ebSphere Pr ocess Server version 6.
2. Click Finish . Now , you can generate inbound event polling support. Generating inbound event polling support: Event polling refers to an adapter’s capability to poll the event r ecords from the event store at r egular intervals. In each poll call, a number of events are processed by the adapter .
2. When you are finished choosing generation options, click Finish . Now , you can generate inbound callback event classes. Generating inbound callback event support: Inbound callback event support alerts business processes to changes in, or new information about, an EIS.
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 metadat.
2. When you are finished choosing generation options, click Finish . Generate data binding classes. Generating data binding classes Y ou can generate data binding classes separate from the data binding classes that are generated fr om enterprise metadata discovery .
2. When you are finished choosing generation options, click Finish . Learn how to generate a JCA resource adapter . Generating a JCA resource adapter Y ou use the wizard to generate adapter classes that correspond to the pr operties and options you specify .
v ManagedConnectionFactory implements javax.resour ce.spi.ResourceAdapterAssociation, javax.V alidatingManagedConnectionFactory , ManagedConnectionFactory v MangedConnection implements javax.
v EditableT ype implements commonj.connector .discoveryEditableT ype v MetadataDiscovery implements commonj.connector .discovery .MetadataDiscovery v MetadataEdit implements commonj.connector .discovery .MetadataEdit v MetadataImportConfiguration implements commonj.
implements javax.resour ce.runtime.SingleT ypedProperty and javax.resour ce.runtime.PropertyDescriptor v SingleV aluedProperty implements javax.resour ce.runtime.SingleV aledProperty and javax.resour ce.runtime.PropertyDescriptor v PropertyGroup implements javax.
2. When you are finished choosing generation options, click Finish . Generate inbound JCA adapter classes. Generating inbound JCA adapter classes The inbound adapter classes are r esponsible for notifying a business process of an inbound event from the EIS.
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 di.
2. When you are finished choosing generation options, click Finish . Generated code and deployment descriptor The generated artifacts reflect the adapter classes with the pr operties and options you specified.
Using the Resource Adapter Deployment Descriptor editor The Resource Adapter Deployment Descriptor editor provides an easy and convenient way to configure your r esource adapter . Resource Adapter Deployment Descriptor editor Y ou configure the resour ce adapter by using a deployment descriptor .
Deployment descriptor Overview pane Alternatively , you can view the deployment descriptor in the editor by highlighting the file in the Project Explor er and selecting Open With → Deployment Descriptor Editor from the context menu.
Using the Overview pane The Overview pane provides access to general information about your r esource adapter . Y ou can display it at any time by clicking the Overview tab at the bottom of this pane.
Add component dialog The Icons section of the overview pane allows you to associate icons with the resour ce adapter . Y ou can specify a large or small icon in jpg or gif format. T o fit into the allotted area, the lar ge icons must be 32 x 32 pixels and the small icon 16 x 16 pixels.
Resource adapter pane The General Information section allows you to specify deployment descriptor values for the entire r esource adapter . This section displays the name of the ResourceAdapter class with which this deployment descriptor is associated.
Add Config property dialog When you add, modify , or delete user-defined pr operties in this section, the editor creates (or r emoves) the corresponding Java bean properties in your code.
The sections of the Outbound Adapter pane are described below . Outbound resour ce adapter pane The General Information section allows you to specify deployment descriptor values associated with the outbound resour ce adapter . Y ou can specify the level of transaction support, if any , and whether reauthentication is supported.
Add Connection Definition dialog A Connection Definition requir es the following information: v ConnectionFactory Interface v ConnecitonFactory Implementaion Class v Connection Interface v Connection .
Add Config property dialog When you add, modify , or delete user-defined pr operties in this section, the editor creates (or r emoves) the corresponding Java bean properties in your code.
class. Clicking the Add button under the list of Message Listeners on the left side of the editor displays the following dialog box. Add Message Listener dialog Once a message listener is defined all properties inherited by the specified ActivationSpecW ithXid are shown in the pr operties list directly under the ActivationSpecW ithXid Class.
Add Required Config Pr operty dialog When you add, modify , or delete user-defined pr operties in this section, the editor creates (or r emoves) the corresponding Java bean properties in your code.
Generated bean properties The editor maps resour ce adapter properties to class code. When you modify the resour ce adapter , the editor performs automatic source code updates.
Y ou can now view or modify the raw ra.xml file using the default editor provided by W ebSphere Integration Developer . When you use this editor to save this file, the file is automatically validated against the Resource Adapter XML Schema Definition (or .
b. Identify configuration properties suitable for use by a client for a specific outbound connection instance (for example, username, password, language). c. Identify configuration properties for inbound event pr ocessing in general–this will probably be a combination of those you’ve defined in 1a and 1b for outbound.
v A full, working implementation, as opposed to the CCI Record model that simply defines interfaces that must be implemented by the adapter developer . v A built-in support for tracking changes at both the object and property levels, which allows for improved ef ficiency in processing and reduced bandwidth requir ements for exchanging data.
changes. For outbound requests, the adapter must interpr et the change summary , making all applicable changes to the data. For example, if an ORDER_LINE has been added to an ORDER object, the ORDER_LINE will appear as Created in the change summary . The adapter is responsible for finding that ORDER, and adding the ORDER_LINE to it.
Convert business object names from EIS-assigned formats to a camel case format (remove separators such as spaces or underscor es and capitalize first letter of each word).
Outbound Operation Signatures Notes applyChanges<BOType> create<BOType> update<BOType> delete<BOType> These operations can handle delta or after-image business objects.
v Adapters should follow strict conventions in processing business objects. This includes failing if an entity is marked as updated in the input business object but does not exist in the EIS (rather than attempting to create the entity in the EIS). isSet property: W ebSphere business objects support an isSet property .
2. If the EIS does not generate its own primary key (or keys), insert the key values from the input business object into the appr opriate key column (or columns) of the EIS entity .
Operation return value Note: When writing the output values to the output cursor , be sure to include any generated keys or other side effects. Error handling Error handling behavior includes any and .
The InvalidRequestException exception is thrown if input to the operation is not supported. The EISSystemException exception is thrown if the EIS r eports any unrecoverable errors. Retrieve: This operation rebuilds the complete business object hierar chy .
CCI clients of resour ce adapters that support batch results must be capable of recognizing a top-level container and iterating thr ough the child objects that repr esent the results of the query . The client can then extract any individual business object in the container and deliver it to the rest of the system as with any single business object.
Note: The RetrieveAll operation always returns a r esult set regardless of how many (if any) matches are found. Processing overview RetrieveAll processing is as follows: RetrieveAll should make the adapter ready to r eturn multiple objects. For each of the objects that will be returned, the ″ getNext() ″ method will be called.
EIS applications. Depending on the underlying EIS, the business events an adapter generates may span the set of changes that have occurred to a given entity in the EIS, such a customer changing the quantity in their order fr om 10 to 100, to a complete document or binary payload such as an insurance claim form submitted in XML.
Event Store Requirements 1. Event data must be persistent. Once detected in the event store, an event should remain available ther e until deleted by the adapter regardless of connection failure or time elapsed. 2. The event store must allow the adapter to both identify and change the state of event recor ds in the event store.
During recovery , W ebSphere Application Server calls the resource adapter , queries it for XAResources, and then performs transaction r ecovery as follows: v T ransactions that the J2EE container rolls back have not been delivered and ar e marked NEW .
generate a timestamp to identify an event, producing an identifier such as MyAdapterName _06139833001005. Object Key Each event should contain enough key information to enable the adapter event-retrieval mechanism to locate and r etrieve the full entity in the EIS for which this event was originally recor ded.
Status The event status is used to track the state of an event. It allows the Foundation Classes to distinguish among events that are new fr om those in process or ineligible. The adapter must support five differ ent event status values as described in the table below .
Field Description eventT ype Corresponds to the Business Object Name field of the event recor d timeStamp Corresponds to the T imestamp field of the event recor d eventStatus Corresponds to the Status.
5. Set the name of the W ebSphere business object complexT ype that corresponds to this application entity 6. Set the event status to New . Implementing event retrieval in the adapter The careful work of implementing event r etrieval in the adapter uses two Foundation Classes interfaces.
Method Description ArrayList getEvents(int quantity, int eventStatus, String[] typeFilter) This method enables the adapter to determine if there ar e any new events available or old events that need re-sending.
EventStore transaction contr ol methods Method Description boolean isTransactional() Is the event store transactional? If so, this method should return true . void commitWork() This method should commit the pending transaction. It is requir ed only if transactions are supported.
Function selector: Function selectors map resour ce adapter events to corresponding SCA export function names. The W ebSphere Adapter component that exposes resour ce adapters as SCA components requir es what is known as a function selector . This selector maps events generated by resour ce adapters to a SCA export function name.
When you enable inbound callback event notification, business processes ar e alerted to changes in, or new information about, an EIS. The phrase callback refers to the ability of the EIS system to directly notify the adapter or business pr ocesses of a change, as opposed to the polling mechanism used in event notification.
Using the IBM WebSphere adapter foundation classes for inbound callback event processing The adapter foundation classes can automatically track endpoints (the consumers of events) for the adapter , co.
The sendWithReturn methods invoke onMessage on the InboundListener . This method delivers the Record it r eceived from the listener thread. Her e the differ ence is the onMessage method will be invoked on the InboundListener to deliver the Record to the endpoint.
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.
Callback event processing for event delivery with XA transaction T o provide data integrity and to make sure events ar e not delivered more than once, which would cause errors in the downstr eam system in the integration scenario, the invention provides a mechanism to achieve once-and-only delivery and the same is accomplished using XA transaction.
When the adapter signals that it has completed delivery , the transaction manager will then call ″ end ″ , ″ prepar e ″ , and ″ commit ″ to complete the requirements outlined in the XA transaction protocol.
Callback event processing for event recovery When there is a failur e in the event processing as part of system recovery , the adapter is able to recover the unpr ocessed events by implementing the once-one-only delivery mechanism.
When the container starts, it calls the getXAResources() method on the adapter to get all the associated XA resources. The adapter then instantiates the appr opriate XA resource and r eturns it back to the container .
Application sign-on The Adapter Foundation Classes can use either container-managed or component-managed authentication or sign-on. The process of connecting to a back-end application, such an EIS, usually r equires some type of authentication. In a JCA environment, application authentication is known as sign-on .
7. The ConnectionManager may call getConnection(Subject, ConnectionRequestInfo) o na ManagedConnection where the passed ConnectionRequestInfo does not match the ConnectionRequestInfo already associated with the ManagedConnection .
public Object createConnectionFactory(ConnectionManager connMgr) throws ResourceException { return new TwineBallConnectionFactory(connMgr, this); } 2. ManagedConnection createManagedConnection(Subject, ConnectionRequestInfo) This method is used by the JCA container to acquire a physical connection to the EIS instance.
Best practices v Each ManagedConnection instance should encapsulate at most one connection to the EIS. v Since there may be mor e than one Connection instance for each ManagedConnection instance, reso.
public Interaction createInteraction() throws ResourceException { return new TwineBallInteraction(this); } Note: If you want to provide your own implementation of ConnectionMetadata , you must override method WBIConnection#getMetadata . javax.resource.
this.connection.getResourceAdapter(); ObjectNaming objectNaming = new ObjectNaming(resourceAdapter); factory = new TwineBallCommandFactory(objectNaming); commandManager = new CommandManager(factory, this.
properties should not change the configuration of the EIS. javax.resource.cci.ConnectionMetadata: A javax.resource.cci.ConnectionMetadata instance pr ovides information to the client components about the underlying EIS of a resour ce adapter . Client components can use the javax.
3. Override method WBIManagedConnection.getLocalT ransaction() and, if XA support is provided, method WBIManagedConnection.getXAResour ce(). W rap either or both of the LocalT ransaction or XAResource instances r eturned by these methods with a WBILocalT ransactionW rapper or WBIXA T ransacxtionW rapper instance, respectively .
Adapters are r esponsible for creating, updating, retrieving, and deleting (CRUD) recor ds in the EIS system based on the structure described by the incoming metadata and the content in the incoming cursor .
Consider the following scenario: Child B1 is in the EIS, but is not in the incoming structur e. Child B1, then, must be deleted. The Command Manager will execute a Retrieve command to build the structur e as it appears in the EIS, then compare this structur e to the incoming object tree.
Command Manager Delete Delta objects Delta processing is only r elevant for service data objects (SDO). The Command Manager functions in a similar way when processing delta objects. Instead of retrieving and comparing, the command manager r eads the change summary for the intended changes.
Suppose, as in the example below , that child B1 is created and is part of the change summary . The resulting command str ucture will contain a Cr eate command for child B1, and will have NO-OPERA TION parents linking it back to the top level parent.
Command Manager Create When it processes this str ucture, the interpr eter will execute the No-op commands as well as the Create command. In general, the no-op commands should not modify data in the EIS system. After-image processing: The Command Manager , based on the CommandManager API, implements the command pattern capability .
Command Manager simplifies before and after comparisons As shown in the upper portion of the figure, the input to the Command Manager is a before image and an after image. The Command Manager cr eates a top-level command repr esenting the operation for the top-level incoming cursor .
The Command Manager processes delta str uctures in a manner analogous to that of after-image data. The dif ference is that, for delta objects, comparative data is extracted from service data object change summaries.
Y ou will need to implement the following: 1. Command implementations for each command type ( ″ Retrieve ″ , ″ RetrieveAll ″ , ″ Create ″ , ″ Update ″ , ″ Delete ″ , and ″ NoOperation ″ ). 2. A command factory implementation that will create instances of these EIS-specific commands.
if (functionName.equals(NodeLevelOperations.CREATE_NODE)) { command = new TwineBallCreateCommand(); } else if (functionName.equals(NodeLevelOperations.DELETE_NODE)) { command = new TwineBallDeleteCommand(); } else if (functionName.equals(NodeLevelOperations.
Data and metadata Adapter Foundation Classes (AFC) implement DESPI APIs and support two data formats, service data objects (SDO) and JavaBeans. The data format-specific implementations are pr ovided in the AFC and ar e abstracted from the adapters which use the DESPI APIs to process data in a format-independent way .
T able 2. Mapping between built-in XSD schema and JavaBean properties (continued) Header Header anySimpleT ype String Any String There ar e cases in which a simple XML data type must be mapped to the .
The notion of whether or not a property is set is critical to pr ocessing null values or values that have not been set in the adapter . If a property has been explicitly set to null, the adapter must be able to detect this and set the associated property to null in the EIS.
As defined in the sapBAPIBusinessObjectT ypeMetadata schema ″ Operation ″ is an n-cardinality complex type. The ″ MethodName ″ element of the operation type is a simple type with multiple card.
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.
These interfaces may contain more helper methods than ar e listed here, please see the Javadoc for the additional helpers. Factory classes Class T ypeFactory: T ypeFactory creates an instance of an implementation of T ype.
Property getProperty(String propertyName) Returns the property object for this property name. Map getAnnotations(String source) Returns the object-level annotations for this type.
boolean isContainment() Returns whether or not the property contains a Type (complex object). boolean isMany() Returns whether or not the property contains a List or Array. int getMaxLength() Returns the max length of the property. Map getAnnotations(String source) Returns the annotations for this property.
Support for GeneratedRecords artifact type: W ebSphere adapters may support JavaBeanRecord data r epresentation along with SDO 1.0 and SDO 2.0 data objects.
The enterprise metadata discovery component is analogous to the Object Discovery Agent of W ebSphere Business Integration Adapters. In addition to generating business object definitions, however , the enterprise metadata discovery also generates service component architectur e artifacts such as an Import/Export file and WSDL.
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.
Service metadata Enterprise metadata discovery architecture The enterprise metadata discovery tooling includes runtime, discovery , and service generation interfaces and metadata edit capabilities. Enterprise metadata discovery architectur e Note: The solid arrows r epresent the enterprise metadata discovery implementation in the above diagram.
These interfaces extend the CCI interfaces defined in the JCA specification to support invocation of services discovered with enterprise metadata discovery . These interface implementations are pr ovided by the resource adapter pr ovider or a third party discovery service pr ovider .
for multiple back-end EIS assets. IBM W ebSphere recommends a single adapterType for each enterprise metadata discovery implementation. The following information must be provided for this class by a discovery service implementation.
copy matching properties fr om metadata connection to runtime connection. For more information, see the WBIOutboundConnectionTypeImpl in the Javadocs. The following information must be provided for th.
MetadataConnection The MetadataConnection object repr esents the connection to EIS or EIS repository . This interface is implemented by the Adapter Foundation Classes only and does not requir e any implementation from discovery service instances. MetadataConnection uses the managed connection factory to create the connection to the EIS.
In addition to object selection, MetadataSelection also holds properties that ar e applicable for the selected objects. Such properties include the following: v Specification of service type: inbound or outbound v Namespace for use by business object definitions v ConnectionType that for use at run time.
the import. The Adapter Foundation Classes provide an implementation for ServiceDescription as abstract classes. Discovery service implementations should extend these classes and implement the abstrac.
Y ou must provide EIS connection descriptions for the enterprise metadata discovery service. Adapter Foundation Classes contain interface implementations to help you get started. Like ServiceDescription , ConnectionDescription can be either inbound or outbound service.
Outbound Function Description The following information has to be filled in by the discovery service implementations: v Name - e.g. createCustomer , applyChangesCustomer v InteractionSpec - Instance of interaction spec which has function name specified that repr esents this method description.
Note: T o limit confusion, custom operation names should not conflict with the standard operation names mentioned above. Note: In cases where the mapping of EIS operations to Cr eate, Retrieve, Update.
v Name – For example, VENDORID v Type – For example, string v Cardinality – 1 or N v Required – Boolean v ObjectTypeName – For cases where an attribute maps to an object for example, porecor d:PORECORD. v Max Length v Metadata – the MetadataObject repr esenting attribute-level application-specific information.
BootStrap: W ebSphere Integration Developer performs a bootstrap step to identify a resour ce adapter that has been enabled for enterprise metadata discovery service. T o identify a resource adapter that is enabled for metadata discovery service, W ebSphere Integration Developer launches a bootstrap step to find a discovery-service.
v PropertyGroup – A collection of properties including single and multi types and PropertyGroup itself. For example, OutboundConnectionConfiguration allows three pr operty groups in one Main propert.
A propertyChange() method should be implemented if a property needs to listen for changes on some other property . Check the T wineBall sample for ServiceTypeSingleProperty . T o enable the function of both vetoableChange and propertyChange , the instance of the property should be added to the propertyChangeListener list.
public TwineBallMetadataDiscovery() throws MetadataException { super("com.ibm.j2ca.sample.twineball.emd"); } The WBIAdapterTypeImpl constructor r equires the following parameters: 1. The name of the class repr esenting the ResourceAdapter class.
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 TwineBallAdapterType()throws MetadataException{ super(Constants.RESOURCE_ADAPTER_BEAN_NAME, 2, 1); setId(Constants.ADAPTER_NAME); setDisplayName(Constants.
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 .
setDescription(WBIMetadataDiscoveryImpl.getPropertyDescription ("ConnectionType")); setId("TwineBall"); setDisplayName(WBIMetadataDiscoveryImpl.
TwineBallConfigurationProperties.getTwineBallConfigurationProperties(); TwineBallResourceAdapter ra = new TwineBallResourceAdapter(); WBIPropertyGroupImpl adapterProp = (WBIPropertyGroupImpl) EMDUtil.getPropertyGroup(ra); propGroup.addProperty(adapterProp); if (getAppliedProperties() != null) EMDUtil.
This class is similar to WBIOutboundConnectionConfigurationImpl except instead of ManagedConnectionFactory , WBIInboundConnectionConfigurationImpl handles the ActivationSpecWithXid bean class.
Constructor The constructor takes MetadataConnection as an ar gument. The constructor can also return pr operties from MetadataConnection that were used to start the discovery service; for example, prefix, dir ectory name, and those properties that populate the MetadataObject nodes in the tree.
(Constants.SERVICETYPE)); propertyGroup.addProperty(typeProp); WBISingleValuedPropertyImpl nameSpaceProp = new WBISingleValuedPropertyImpl (Constants.NAMESPACE, String.class); nameSpaceProp.setDefaultValue(Constants.TB_DEFAULT_NAMESPACE); propertyGroup.
ArrayList objects = getTopLevelObjects(); response.setObjects(objects); return response; } WBIMetadataObjectImpl samples: WBIMetadataObjectImpl repr esents the nodes of the tree that W ebSphere Integration Developer displays during enterprise metadata discovery .
createSelectionProperties The createSelectionProperties() method returns a pr operty group that is used to capture inputs fr om users. These inputs include business object namespace, supported operations, and the relative path in the module pr oject where XML schema definitions should be saved.
The enterprise metadata discovery service uses WBIMetadataEditImpl to acquire connectionTypes , which contains editable properties for ResourceAdapter , ManagedConnectionFactory ,o r ActivationSpecWithXid . The enterprise metadata discovery tooling creates an instance of WBIMetadataEditImpl during the boot strap process.
dataDesc.prepareChildSchemaFiles(); WBIMetadataDiscoveryImpl.getLogUtils().trace(Level.FINER, CLASSNAME, "preparingChildSchemaFiles", "Preparing SchemaFile for " + bo.getDisplayName()); dataDesc.prepareSchemaFiles(); SchemaDefinition[] schemaFiles = dataDesc.
bometadata.setNameSpace(namespace); bometadata.setObjectNameSpace(Constants.BUS_OBJ_APPINFO_ASI_TYPE_TAG); bometadata.setASI(Constants.ASI_OBJECTNAME, this.
WBIMetadataDiscoveryImpl.getLogUtils().traceMethodExit (CLASSNAME, "getImportNameSpaces"); return list; } getNameSpaces The getNameSpaces() method returns the NameSpaces listed in the XML schema definition. T ypically these are application specific information schema definition namespaces.
getChildList The getChildList() method returns the Iterator for the child objects of the DataDescription . public Iterator getChildList() throws MetadataException { return (this.
FunctionDescription[] funcArray = new FunctionDescription[functionDescriptions.size()]; functionDescriptions.toArray(funcArray); super.setFunctionDescriptions(funcArray); } WBIOutboundServiceDescriptionImpl samples: WBIOutboundServiceDescriptionImpl repr esents the object that populates function descriptions for outbound service descriptions.
dataDescription.setMetadataObject(metadataObj); dataDescription.populateSchemaDefinitions(); dataDescription.setRelativePath(location); dataDescription.setName(getNameSpace() + "/" + metadataObj.getBOName().toLowerCase() + "container", metadataObj.
Creating services that use technology-style adapters r elies on being able to implement the interfaces in the commonj.connector.metadata.build.* package or by extending the adapter foundation classes in com.ibm.j2ca.extension.emd.build.* package, or a combination thereof.
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 u.
T o access the binding configuration, do context.get(BindingContext.BINDING_CONFIGURATION) T o access the expected type, do context.get (BindingContext.
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.
Extend WBIMetadataType if your adapter needs a simple wrapper object around a payload object, similar to the IBM W ebSphere Adapter for Flat Files and the IBM W ebSphere Adapter for FTP . The WBIMetadataType interface allows you to select a payload type, and optionally generate a business graph structur e in addition to a plain wrapper .
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 .
Set managed connection method This method passes the ManagedConnection handle to the recor d implementation, allowing the recor d to get access to the physical connection to the backend application to perform processing.
the retriveAll operation could return ″ N ″ r ecords from the backend application, for each call to the getNext() method the implementation should fill in data of one recor d from the backend application into OutputCursors/Accessors.
The method should first extract the value from backend object r epresentation defined through Xpath and use OutputCursor and OutputAccessor interfaces to populate values in runtime data structur e. Sample Data binding implementation Adapters must provide implementations for DataBinding interface in or der to work with W ebSphere Process Server .
For operations where getNext() should be invoked multiple times like RetrieveAll, the databinding should call getNext() multiple times add the built BusinessObject to the list of BusinessObjects within the Container BO.
v When WBIStructur edRecord is initialized with data that contains Bidi annotations, Cursors and accessors that are associated with that str uctured recor d will automatically translate the content in.
How to support fault handling: Understand the following concepts for implementing fault handling into your adapter . Before you define faults, r eview adapter processing to determine which error conditions can be categorized as faults, rather than as exceptions.
//Added for Faults funcDesc.setName(operation.toLowerCase() + queryDataDesc.getBOName()); getLogUtils().trace(LogLevel.FINEST, CLASSNAME, "getXMLListFunctions", "Setting input data description to: " + queryDataDesc.getName().toString() + " for function: " + funcDesc.
public class JDEXMLListFaultDataDescription implements FaultDataDescription { public JDEXMLListFaultDataDescription() { super(); // TODO Auto-generated constructor stub } private String faultName = null; public String getFaultName() { // TODO Auto-generated method stub return faultName; } public void setFaultName(String faultName) { this.
fdesc2.setGenericDataBindingClassName("com.ibm.j2ca.extension.emd.runtime.WBIFaultDataBindingImpl"); fdesc2.setFaultName(FaultBOUtil.MATCHES_EXCEEDED_LIMIT_NAME); FaultDataDescription desc[] = new FaultDataDescription[] {fdesc1, fdesc2}; funcDesc.
T able 4. Fault name and configured fault binding (continued) Fault Name Configured Fault Binding INV ALID_REQUEST com.ibm.j2ca.extension.emd.runtime.WBIFaultDataBindingImpl When input to the operation does not have the requir ed characteristics, the adapter throws this fault.
Y ou can use the FaultBOUtil to define the fault business object, as long as either no attributes or only simple attributes are added. This should amount to a few lines of code, See Implementing Faults for an example.
– 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.
W riting a trace message Y ou use the trace method of the LogUtils class to generate a trace message. This method has two signatures. One of them is informational.
"getRecordForEvent()", "test"); return null; } } Example of trace message for the outbound scenario with confidential tracing property enabled public HelloWorldConnectionFactory(ConnectionManager connMgr, WBIManagedConnectionFactory mcf) { super(connMgr, mcf); getLogUtils().
T racing assists developers and troubleshooters. Due to the significant performance cost incurred by tracing, however , many customers disable it in production environments. When developing or tr oubleshooting, it is good practice to check whether tracing is enabled before building to generate trace messages.
Message types There ar e two message types for adapters, ADAPTER_RBUNDLE . The BASE_RBUNDLE is reserved for the Adapter Foundation Classes. The message types are used to distinguish between the adapter and the base classes message file. The default value of Message T ype field is ADAPTER_RBUNDLE .
translated text. V alues that are language-independent, such as key values or object names, are appr opriate as log message parameters. Similarly to trace messages, parameters in a log message can contain data from the customer’s EIS.
Example of log message for the inbound scenario with confidential tracing property enabled public javax.resource.cci.Record getRecordForEvent(com.ibm.j2ca.extension.eventmanagement.Event event) throws javax.resource.ResourceException, javax.resource.spi.
public interface EventSourceContext { /** * Returns an event source for a monitored element. * @param elementKind an artifact kind that can be monitored e.
* 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.
<?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.
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.
Purpose 1. Monitorable Element Schema (.mes) file changes Defines the element type within an adapter where monitoring can be attached. The element type is specified using the Qname of the element type from the schema, which defines the structur e of the artifact itself.
d. If eventPoint is enabled, then fire event for Entry , Exit and Failur e is invoked. Entry event is fired in the beginning of the method call, exit event is fir ed in the end of the method call and failure event is fir ed in case of exception. For example we can invoke failure event by following API call.
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 tran.
statistics and data for each ManagedConnection , which can be used to assess and troubleshoot performance r elated problems. In order for r esource adapters to participate in various W ebSphere RequestMetric tools for outbound, diagnostic tools, etc, you will need to follow these steps: 1.
FFDC processing overview Instead of explicitly instrumenting catch blocks by calling FFDC dir ectly , either manually or by using a tool, you can write a simple aspect using the AspectJ language, which encapsulates the FFDC policy for your code. The FFDCSupport aspect is abstract.
If you use the FFDCSupport aspect, you can ensure a consistent FFDC policy for your application by adding declare warning or err or advice to your aspects While this capability is not explicitly provi.
When using FFDCSupport aspect you can control the data gather ed. T wo template methods getSourceId and getProbeId are pr ovided to you for this purpose. For example, you may want to limit the length of the source ID strings. In Figur e 7, aspect Example_7 illustrates how to override the getSourceId method and return a short name.
Exception messages Exception messages, like trace messages, convey information about problems. The differ ence is that exception messages are tailored mor e directly to support teams familiar with adapter source code, and ther efore need not be translated.
T o test the enterprise metadata discovery (EMD) implementation for the developed resour ce adapter , complete the following steps: 1. From the IBM W ebSphere Adapters Foundation Classes library , copy the following three dependent jars into the connectorModule connector pr oject: v commonj.
JUnit: an open source framework for unit testing JUnit is becoming the standard tool for unit testing in Java development environments. JUnit allows you to quickly and easily integrate automated regr ession testing into your coding and build processes.
Y our adapter may or may not be dependant on ″ live ″ data inside the EIS. If so, you must either return the data to a known state after every test, or cr eate a mock implementation of the EIS API so that EIS data remains untouched. setUp() In the setup method for outbound, perform the following step: 1.
setUp() The setUp() method for inbound is very similar to that for outbound. Y ou may , however , not need an outbound connection through the adapter . Accordingly , you need only perform the following tasks: 1. Create an adapter instance and set its pr operties 2.
For information on testing the adapter in managed mode in W ebSphere Application Server , see V alidating code with Rational Application Developer / W ebsphere Application Server . Installing the test client T o test your adapter in a runtime environment, you must first install a test client on the target W ebSphere Pr ocess Server .
T est module configuration 3. Select the testing mode and click Finish to start the test. On the Deployment Location screen, select a W ebSphere Pr ocess Server to test in managed mode (optionally you can select Eclipse to test in unmanaged mode). In addition, you select Run or Debug mode.
Adding a value to the Datapool This adds the data to Datapool. When you want to use this input data again, select Use V alue from Pool. Using an execution trace The test client you installed provides you with a trace of the execution and the data path of the test.
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 .
Selecting the Java package g. Save the module. 2. Publish the application to W ebSphere Process Server . 3. Open the administration console for the W ebSphere Process Server and configure the application’s activation specifications so that it can pr ocess inbound requests.
V alidating code with Rational Application Developer and W ebSphere Application Server T o test the adapter in the W ebsphere Application Server environment, use the javabean generation capability of EMD to generate recor ds and a java proxy interface to the adapter .
4. In the Resource Adapter deployment panel, choose how to deploy the adapter . Y ou can deploy the adapter with the EAR or you can deploy the adapter as a stand-alone component. 5. Click Finish to generate the code. Once the EJB is generated you can send data to the adapter and examine the return values using the UTC.
7. Start UTC using the Run universal test client option. W ebSphere Adapter development overview 205.
8. Once the UTC comes up, use the JNDI explorer to find your EJB. Look for your session EJB under EJB Beans. Now , you can test your adapter via the EJB interface. Y ou can create a session bean using the home interface (create), then invoke business methods on the remote interface, pr oviding the appropriate data.
Note: External service discovery is equivalent to enterprise metadata discovery . f. Select the appropriate external service. g. Specify the connection properties, metadata, and service functions. h. On the Saving Properties pane, save the properties to the module you created in Step d.
Reference T erminology The terminology presented ar e of terms that are used frequently in the documentation. Adapter foundation classes (AFC) Sometimes referr ed to as base classes, the adapter foundation classes are a common set of services for all IBM W ebSphere resour ce adapters.
Eclipse An open source infrastr ucture for building tools such as an Integrated Development Environment (IDE). The toolkit’s wizar d and editor are Eclipse plug-ins. Eclipse Plug-in A module that extends the functionality of the Eclipse Platform Editor A component in Eclipse that allows data to be edited.
Outbound Outbound is a description of the direction in which data and messages pass from a J2EE client application to the EIS. Adapters support both inbound and outbound data flow . Performance monitoring infrastructure (PMI) A set of packages and libraries assigned to gather , deliver , process, and display performance data.
Notices This information was developed for products and services of fered in the U.S.A. IBM may not offer the pr oducts, services, or features discussed in this document in other countries. Consult your local IBM repr esentative for information on the products and services curr ently available in your area.
Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other pr ograms (including this .
this code are derived fr om IBM Corp. Sample Programs. (c) Copyright IBM Corp. _enter the year or years_. All rights reserved. If you are viewing this information softcopy , the photographs and color illustrations may not appear .
214 W ebSphere Adapters: W ebSphere Adapter T oolkit User Guide.
Index Special characters .WBIOutboundServiceDescriptionImpl 39 (CCI), Common Client Interface 4 (EAR) project, Enterprise Application Archive 31 (EAR), enterprise application archive 2 (RAR), resour ce adapter archive 2 Numerics 1.5 specification, Java 2 Connector Architectur e JCA 10 2 Connector Architecture JCA 1.
G generation options 35 H hardwar e requir ements 12 I implementation overview 68 Inbound callback event notification 90, 91, 92, 94 callback event sender 91 callback event sender constructors 92 even.
V verbs usage business graph 71 W WBIActivationSpec 37 WBIAdapterT ypeImpl 39, 141 WBIConnection 35, 102 WBIConnectionFactory 35, 101 WBIConnectionRequestInfo 104 WBIDataBindingGenerator 38 WBIDataDes.
218 W ebSphere Adapters: W ebSphere Adapter T oolkit User Guide.
.
Printed in USA.
デバイスIBM WebSphere Adaptersの購入後に（又は購入する前であっても）重要なポイントは、説明書をよく読むことです。その単純な理由はいくつかあります：
IBM WebSphere Adaptersをまだ購入していないなら、この製品の基本情報を理解する良い機会です。まずは上にある説明書の最初のページをご覧ください。そこにはIBM WebSphere Adaptersの技術情報の概要が記載されているはずです。デバイスがあなたのニーズを満たすかどうかは、ここで確認しましょう。IBM WebSphere Adaptersの取扱説明書の次のページをよく読むことにより、製品の全機能やその取り扱いに関する情報を知ることができます。IBM WebSphere Adaptersで得られた情報は、きっとあなたの購入の決断を手助けしてくれることでしょう。
IBM WebSphere Adaptersを既にお持ちだが、まだ読んでいない場合は、上記の理由によりそれを行うべきです。そうすることにより機能を適切に使用しているか、又はIBM WebSphere Adaptersの不適切な取り扱いによりその寿命を短くする危険を犯していないかどうかを知ることができます。
ですが、ユーザガイドが果たす重要な役割の一つは、IBM WebSphere Adaptersに関する問題の解決を支援することです。そこにはほとんどの場合、トラブルシューティング、すなわちIBM WebSphere Adaptersデバイスで最もよく起こりうる故障・不良とそれらの対処法についてのアドバイスを見つけることができるはずです。たとえ問題を解決できなかった場合でも、説明書にはカスタマー・サービスセンター又は最寄りのサービスセンターへの問い合わせ先等、次の対処法についての指示があるはずです。
