IBM BPM, V8.0.1, All platforms > Authoring services in Integration Designer > Services and service-related functions > Access external services with adapters

Considerations when refactoring

The external service wizard and the assembly editor that simplify the development of applications through generating artifacts, also create references to the generated artifacts. When you refactor the artifacts, either through the refactoring user interface or manually moving, renaming and deleting objects yourself, these references sometimes will require revisions, which are listed in this section.

We will restrict ourselves to only the refactoring functions in IBM Integration Designer. These refactoring functions are available in the Business Integration view or in an artifact editor such as the business object editor or interface editor.

Refactoring considerations can be examined from these views:

• Using refactoring on an EIS import or export
• Using refactoring on a JMS or generic JMS import or export
• Using refactoring on an MQ JMS import or export
• Using refactoring on an HTTP import or export
• Using refactoring to move operations and merge interfaces
• Refactoring artifacts manually without using the refactoring wizard

In these sections, the refactoring steps are shown by selecting items from the Business Integration navigation, though the same items could have also been selected from the assembly editor.

In the following sections where the updates are performed by the refactoring operation, the results can be viewed in the refactoring wizard's Details view on the Preview page.

Use refactoring on an EIS import or export

Description: Renaming an interface operation with the following steps:

1. In the interface editor, right-click the operation that you want to change.

2. From the menu, select Refactor > Rename Operation.

Problem: The method attribute in the method binding will not match the operation name on the interface.

Correction: The necessary updates will be performed by the refactoring operation and the results can be viewed in the refactoring wizard's Details view on the Preview page.

Description: Renaming a module that contains an import or export with an EIS binding by following these steps:

1. In the Business Integration view, right-click the module that you want to rename.

2. From the menu, select Refactor > Rename.

Problem: One of the properties exposed in an EIS import or export binding is the resource adapter JavaBeans name. In the case of JCA 1.5 resource adapters deployed with the module (that is, you checked Deploy connector with module on the Generate Artifacts page of the external service wizard), the resource adapter JavaBeans name will contain the concatenated name of the module (Application EAR) and the resource adapter name as specified in the ra.xml deployment descriptor. This specific name is required to perform the correct deployment of the resource adapter instance to the server. A resource adapter instance may provide bi-directional connectivity to multiple EIS instances. ManagedConnectionFactory JavaBeans can be used to provide outbound connectivity to a single EIS instance. ActivationSpec JavaBeans can be used to provide inbound connectivity from an EIS instance. When the module is renamed, the currently deployed server resources (such as ManagedConnectionFactory JavaBeans or ActivationSpec JavaBeans) that have been created using the old module name become invalid.

Correction: The necessary updates will be performed by the refactoring operation and the results can be viewed in the refactoring wizard's Details view on the Preview page. Undeploy the current instance of the resource adapter and redeploy.

Use refactoring on a JMS or generic JMS import or export

Description: Renaming an interface operation with the following steps:

1. In the interface editor, right-click the operation that you want to change.

2. From the menu, select Refactor > Rename Operation.

Problem: The operation name on the binding will not match the operation name on the interface.

Correction: The necessary updates will be performed by the refactoring operation and the results can be viewed in the refactoring wizard's Details view on the Preview page.

Description: An export with a JMS binding has been dragged and dropped to another module to create a matching import. Now refactoring has occurred by moving the JMS export to another folder within the module by following these steps:

1. In the Business Integration view, right-click the export that you want to move.

2. From the menu, select Refactor > Move.

3. In the Move Artifact wizard, choose a new location for the export. Click the plus sign to expand the menu to see levels below modules and libraries.

Problem: When an export is moved to another folder within the module, the destinations' JNDI lookup name value in the JMS import becomes invalid.

Correction: The necessary updates will be performed by the refactoring operation and the results can be viewed in the refactoring wizard's Details view on the Preview page. The refactoring operation will change the JMS import's destination JNDI lookup name value to contain the token with the new export name location.

For example, these destination elements in an import have been changed as follows:

<destination implType="com.ibm.ws.sib.api.jms.impl.JmsQueueImpl"
	target="ModuleWithExport/NewExportLocation/ExportName_RECEIVE_D"
	type="javax.jms.Queue" usage="send" />
<destination implType="com.ibm.ws.sib.api.jms.impl.JmsQueueImpl"
	target="ModuleWithExport/NewExportLocation/ExportName_SEND_D"
	type="javax.jms.Queue" usage="receive" />

Description: An export with a JMS binding has been dragged and dropped to another module to create a matching import. Now refactoring has occurred by renaming the JMS export by following these steps:

1. In the Business Integration view, right-click the export that you want to rename.

2. From the menu, select Refactor > Rename.

Problem: When an export is renamed, the destinations' JNDI lookup name value in the JMS import becomes invalid.

Correction: The necessary updates will be performed by the refactoring operation and the results can be viewed in the refactoring wizard's Details view on the Preview page. The refactoring operation will change the JMS import's destination JNDI lookup name value to contain the token with the new export name location.

For example, these destination elements in an import have been changed as follows:

<destination implType="com.ibm.ws.sib.api.jms.impl.JmsQueueImpl"
	target="ModuleWithExport/NewExportName_RECEIVE_D"
	type="javax.jms.Queue" usage="send" />
<destination implType="com.ibm.ws.sib.api.jms.impl.JmsQueueImpl"
	target="ModuleWithExport/NewExportName_SEND_D" type="javax.jms.Queue"
	usage="receive" />

Description: An export with a JMS binding has been dragged and dropped to another module to create a matching import. Now refactoring has occurred by renaming the module containing the JMS export by following these steps:

1. In the Business Integration view, right-click the module that you want to rename.

2. From the menu, select Refactor > Rename.

Problem: When the module is renamed, the destinations' JNDI lookup name value in the JMS import becomes invalid.

Correction: The necessary updates will be performed by refactoring operation and the results can be viewed in the refactoring wizard's Details view on the Preview page. The refactoring operation will change the JMS import's destination JNDI lookup name value to contain the token with the new export name location.

For example, these destination elements in an import have been changed as follows:

<destination implType="com.ibm.ws.sib.api.jms.impl.JmsQueueImpl"
	target="NewModuleWithExport/ExportName_RECEIVE_D"
	type="javax.jms.Queue" usage="send" />
<destination implType="com.ibm.ws.sib.api.jms.impl.JmsQueueImpl"
	target="NewModuleWithExport/ExportName_SEND_D" type="javax.jms.Queue"
	usage="receive" />

Description: You have an import with a JMS binding and you deployed it to the server.

You want to have an export that will communicate with the import. If that export has to have the same interface as import. You update the export's destination JNDI names with the JNDI names that the import is using. You retrieve the destination JNDI names from the import's Summary page of the properties view. Then you deploy the export and it will communicate with the import.

Problem: When the import is moved to another folder within the module, the destinations' JNDI lookup name value that might be referenced by the JMS export becomes invalid.

Correction: You undeploy both import and export and then you refactor the import. The necessary updates will be performed by refactoring operation and the results can be viewed in the refactoring wizard's Details view on the Preview page. The refactoring operation will change the JMS export's destination JNDI lookup name value to contain the token with the new import name location.

For example, these destination elements in an export have been changed as follows:

<destination implType="com.ibm.ws.sib.api.jms.impl.JmsQueueImpl"
	target="ModuleWithImport/NewImportLocation/ImportName_SEND_D"
	type="javax.jms.Queue" usage="receive" />
<destination implType="com.ibm.ws.sib.api.jms.impl.JmsQueueImpl"
	target="ModuleWithImport/NewImportLocation/ImportName_RECEIVE_D"
	type="javax.jms.Queue" usage="send" />

Then you redeploy.

If you did not deploy originally, then the correction is simple. You refactor the import and the export is updated. Now you are ready to deploy and test.

Description: You have an import with a JMS binding and you deployed it to the server. You want to have an export that will communicate with the import. If that the export has to have the same interface as the import. You update the export's destination JNDI names with the JNDI names that the import is using.

You retrieve the destination JNDI names from the import's Summary page of the properties view. Then you deploy the export and it will communicate with the import.

Problem: When the import name is changed, the destinations' JNDI lookup name value that might be referenced by the JMS export becomes invalid.

Correction:

You undeploy both import and export and then you refactor the import. The necessary updates will be performed by refactoring operation and the results can be viewed in the refactoring wizard's Details view on the Preview page. The refactoring operation will change the JMS export's destination JNDI lookup name value to contain the token with the new import name.

For example, these destination elements in an export have been changed as follows:

<destination implType="com.ibm.ws.sib.api.jms.impl.JmsQueueImpl"
	target="ModuleWithImport/NewImportName_SEND_D" type="javax.jms.Queue"
	usage="receive" />
<destination implType="com.ibm.ws.sib.api.jms.impl.JmsQueueImpl"
	target="ModuleWithImport/NewImportName_RECEIVE_D"
	type="javax.jms.Queue" usage="send" />

Then you redeploy.

If you did not deploy originally, then the correction is simple. You refactor the import and the export is updated. Now you are ready to deploy and test.

Description: You have an import with a JMS binding and you deployed it to the server. You want to have an export that will communicate with the import. If that export has to have the same interface as import. You update the export's destination JNDI names with the JNDI names that the import is using.

You retrieve the destination JNDI names from the import's Summary page of the properties view. Then you deploy the export and it will communicate with the import.

Problem: When the import's module name is changed, the destinations' JNDI lookup name value that might be referenced by the JMS export becomes invalid.

Correction:

You undeploy both import and export and then you refactor the import. The necessary updates will be performed by refactoring operation and the results can be viewed in the refactoring wizard's Details view on the Preview page. The refactoring operation will change the JMS export's destination JNDI lookup name value to contain the token with the new import's module name.

For example, these destination elements in an export have been changed as follows:

<destination implType="com.ibm.ws.sib.api.jms.impl.JmsQueueImpl"
	target="NewModuleWithImport/ImportName_SEND_D" type="javax.jms.Queue"
	usage="receive" />
<destination implType="com.ibm.ws.sib.api.jms.impl.JmsQueueImpl"
	target="NewModuleWithImport/ImportName_RECEIVE_D"
	type="javax.jms.Queue" usage="send" />

Then you redeploy.

If you did not deploy originally, then the correction is simple. You refactor the import and the export is updated. Now you are ready to deploy and test.

Use refactoring on an MQ JMS import or export

Description: Renaming an interface operation with the following steps:

1. In the interface editor, right-click the operation that you want to change.

2. From the menu, select Refactor > Rename Operation.

Problem: The operation name on the binding will not match the operation name on the interface.

Correction: The necessary updates will be performed by the refactoring operation and the results can be viewed in the refactoring wizard's Details view on the Preview page.

Description: Refactoring has occurred and moved the MQ JMS export to another folder within the module by following these steps:

1. In the Business Integration view, right-click the export that you want to move.

2. From the menu, select Refactor > Move.

3. In the Move Artifact wizard, choose a new location for the export. Click the plus sign to expand the menu to see levels below modules and libraries.

Problem: When an export is moved to another folder within the module, the destinations' JNDI lookup name value in the MQ JMS import becomes invalid.

Correction: The necessary updates will be performed by the refactoring operation and the results can be viewed in the refactoring wizard's Details view on the Preview page. The refactoring operation will change the MQ JMS import's destination JNDI lookup name value to contain the token with the new export name location.

For example, these destination elements in an import have been changed as follows:

<send
	target="ModuleWithExport/NewExportLocation/ExportName_MQ_RECEIVE_D"
	type="javax.jms.Queue" />
<receive
	target="ModuleWithExport/NewExportLocation/ExportName_MQ_SEND_D"
	type="javax.jms.Queue" />

Description: Refactoring has occurred and an MQ JMS export has been renamed by following these steps:

1. In the Business Integration view, right-click the export that you want to rename.

2. From the menu, select Refactor > Rename.

Problem: When an export is renamed, the destinations' JNDI lookup name value in the MQ JMS import becomes invalid.

Correction: The necessary updates will be performed by the refactoring operation and the results can be viewed in the refactoring wizard's Details view on the Preview page. The refactoring operation will change the MQ JMS import's destination JNDI lookup name value to contain the token with the new export name.

For example, these destination elements in an import have been changed as follows:

<send target="ModuleWithExport/NewExportName_MQ_RECEIVE_D"
	type="javax.jms.Queue" />
<receive target="ModuleWithExport/NewExportName_MQ_SEND_D"
	type="javax.jms.Queue" />

Description: Refactoring has occurred and renamed a module containing an MQ JMS export by following these steps:

1. In the Business Integration view, right-click the module that you want to rename.

2. From the menu, select Refactor > Rename.

Problem: When the module is renamed, the destinations' JNDI lookup name value in the MQ JMS import becomes invalid.

Correction: The necessary updates will be performed by refactoring operation and the results can be viewed in the refactoring wizard's Details view on the Preview page. The refactoring operation will change the MQ JMS import's destination JNDI lookup name value to contain the token with the new export name location.

For example, these destination elements in an import have been changed as follows:

<send target="NewModuleWithExport/ExportName_MQ_RECEIVE_D"
	type="javax.jms.Queue" />
<receive target="NewModuleWithExport/ExportName_MQ_SEND_D"
	type="javax.jms.Queue" />

Description: You have an import with an MQ JMS binding and you deployed it to the server. You want to have an export that will communicate with the import. If that the export has to have the same interface as import. You update the export's destination JNDI names with the JNDI names that the import is using.

You retrieve the destination JNDI names from the import's Summary page of the properties view. Then you deploy the export and it will communicate with the import.

Problem: When the import is moved to another folder within the module, the destinations' JNDI lookup name value that might be referenced by the MQ JMS export becomes invalid.

Correction: You undeploy both import and export and then you refactor the import. The necessary updates will be performed by refactoring operation and the results can be viewed in the refactoring wizard's Details view on the Preview page. The refactoring operation will change the MQ JMS export's destination JNDI lookup name value to contain the token with the new import name location.

For example, these destination elements in an export have been changed as follows:

<receive
	target="ModuleWithImport/NewImportLocation/ImportName_MQ_SEND_D"
	type="javax.jms.Queue" />
<send
	target="ModuleWithImport/NewImportLocation/ImportName_MQ_RECEIVE_D"
	type="javax.jms.Queue" />

Then you redeploy. If you did not deploy originally, then the correction is simple. You refactor the import and the export is updated. Now you are ready to deploy and test.

Description: You have an import with a MQ JMS binding and you deployed it to the server. You want to have an export that will communicate with the import. If that the export has to have the same interface as the import. You update the export's destination JNDI names with the JNDI names that the import is using.

You retrieve the destination JNDI names from the import's Summary page of the properties view. Then you deploy the export and it will communicate with the import.

Problem: When the import name is changed, the destinations' JNDI lookup name value that might be referenced by the MQ JMS export becomes invalid.

Correction:

You undeploy both import and export and then you refactor the import. The necessary updates will be performed by refactoring operation and the results can be viewed in the refactoring wizard's Details view on the Preview page. The refactoring operation will change the JMS export's destination JNDI lookup name value to contain the token with the new import name.

For example, these destination elements in an export have been changed as follows:

<receive target="ModuleWithImport/NewImportName_MQ_SEND_D"
	type="javax.jms.Queue" />
<send target="ModuleWithImport/NewImportName_MQ_RECEIVE_D"
	type="javax.jms.Queue" />

Then you redeploy. If you did not deploy originally, then the correction is simple. You refactor the import and the export is updated. Now you are ready to deploy and test.

Description: You have an import with an MQ JMS binding and you deployed it to the server. You want to have an export that will communicate with the import. If that the export has to have the same interface as import. You update the export's destination JNDI names with the JNDI names that the import is using.

You retrieve the destination JNDI names from the import's Summary page of the properties view. Then you deploy the export and it will communicate with the import.

Problem: When the import's module name is changed, the destinations' JNDI lookup name value that might be referenced by the MQ JMS export becomes invalid.

Correction:

You undeploy both import and export and then you refactor the import. The necessary updates will be performed by refactoring operation and the results can be viewed in the refactoring wizard's Details view on the Preview page. The refactoring operation will change the MQ JMS export's destination JNDI lookup name value to contain the token with the new import's module name.

For example, these destination elements in an export have been changed as follows:

<receive target="NewModuleWithImport/NewImportName_MQ_SEND_D"
	type="javax.jms.Queue" />
<send target="NewModuleWithImport/NewImportName_MQ_RECEIVE_D"
	type="javax.jms.Queue" />

Then you redeploy. If you did not deploy originally, then the correction is simple. You refactor the import and the export is updated. Now you are ready to deploy and test.

Use refactoring on an HTTP import or export

Description: The operation name on the interface will differ from the operation name on the binding when you rename an interface operation with the following steps:

1. In the interface editor, right-click the operation that you want to change.

2. From the menu, select Refactor > Rename Operation.

Problem: The operation name on the binding will not match the operation name on the interface.

Correction: The necessary updates will be performed as you continue with the refactoring operation and the results can be viewed in the refactoring wizard's Details view on the Preview page.

Use refactoring to move operations and merge interfaces

Moving operations or merging interfaces results in the following behavior.

When you move an operation, you will receive a message that states that the method binding does not have a matching operation on the interface. This method binding is from the previous operation before you moved it. This old method binding is intentionally left in case there is some configuration information you may still need. If you do not need this old method binding, you can delete it.

When you merge an interface, you will receive a message that the interface does not have a method binding. This message is intentional. You are being asked to consciously create and configure method bindings and their properties that are consistent with your existing method bindings.

Refactoring artifacts manually without using the refactoring wizard

Refactoring artifacts without using the refactoring wizard affects the following artifacts:

• Business objects and XSD files
• Interfaces and WSDL files
• Imports and exports
• Exports
• Modules
• Libraries

Business objects and XSD files

• Delete a business object: manually, that is, not using the refactoring function, deleting a business object (including an element, ComplexType or XSD file that points to another business object that is referenced by this business object) created by the external service wizard results in a WSDL message part error. Also, the data binding generator will not be able to find the business object XSD. To correct the problem, you can do one of the following actions:
  • Rerun the external data wizard, selecting the same properties as selected originally when running the external service wizard. You may also need to rebuild the module project.
  • Rerun the external service wizard if a business object with a different name is wanted. You may want to clean up the deleted business object data binding code by cleaning up the module project.
  • Remove the business object references from the interface and WSDL files.

• Delete a business object: manually, that is, not using the refactoring function, deleting a business object (including an element, ComplexType or XSD file) created by the external data wizard can result in a referencing error, if the business object was referenced from a library module. To correct the problem, rerun the external data wizard selecting the same properties as the previous execution.
• Changing a business object structure: manually, that is, not using the refactoring function, changing a business object structure created by the external service wizard or the external data discovery wizard results in a runtime exception as the business object does not match the one on the Enterprise Information System (EIS). To correct the problem, create the original business object with a valid structure.
• Rename a business object: manually, that is, not using the refactoring function, renaming a business object created by the external service wizard results in a Web Services Description Language (WSDL) type definition error and data bindings will need to be regenerated. To correct the problem, follow these steps:
  1. Rename the business object in the interface editor and WSDL editor.
  2. Renaming will force you to save the changes, which will regenerate the data bindings.
• Rename a business object namespace: manually, that is, not using the refactoring function, renaming a business object namespace of a business object created by the external service wizard results in a Web Services Description Language (WSDL) type definition error and data bindings will need to be regenerated. To correct the problem, follow these steps:
  1. Rename the business object's namespace in the interface editor and WSDL editor.
  2. Renaming will force you to save the changes, which will regenerate the data bindings.
• Moving a business object: manually, that is, not using the refactoring function, moving a business object created by the external service wizard or external data wizard to the library module results in a WSDL message part error. To correct the problem, follow these steps:
  1. Correct the WSDL import schemaLocation attribute value to point to the current location of the XSD file.

  2. Add the library as a module dependency and rebuild the module.

Interfaces and WSDL files

• Delete an operation: if you have an interface generated by the external service wizard or by using the assembly editor on an import or export and you delete an operation manually, that is, not using the refactoring function, then the method in the import or export will not have a matching operation on the interface. To correct the problem, choose one of the following actions:
  • Rerun the external service wizard selecting the same properties as the previous execution of the wizard.
  • Rerun the external service wizard or assembly editor if you want an operation with a different name.
  • Delete the method binding in the import or export.

• Delete a port type: if you have an interface generated by the external service wizard or by using the assembly editor on an import or export and you delete a port type manually, that is, not using the refactoring function, then the WSDL port type defined in the interface is invalid. To correct the problem, choose one of the following actions:
  • Rerun the external service wizard selecting the same properties as the previous execution of the wizard.
  • Rerun the external service wizard or assembly editor if you want a port type with a different name and delete the original import or export and WSDL files.
  • Delete the interface and the binding in the import or export.

• Delete a WSDL file: if you have an interface generated by the external service wizard or by using the assembly editor on an import or export and you delete a WSDL file manually, that is, not using the refactoring function, then the WSDL port type defined in the interface is invalid. To correct the problem, choose one of the following actions:
  • Rerun the external service wizard selecting the same properties as the previous execution of the wizard.
  • Rerun the external service wizard or assembly editor if you want a port type with a different name and delete the original import or export and WSDL files.
  • Delete the interface and the binding in the import or export.

• Rename a port type: if you have an interface generated by the external service wizard or by using the assembly editor on an import or export and you rename a port type manually, that is, not using the refactoring function, then the WSDL port type defined in the interface is invalid. To correct the problem, rename the port type in the import or export to match port type name on the interface.

Imports and exports

• Delete an import or export: if you have an import or export generated by the external service wizard or by using the assembly editor and you delete it manually, that is, not using the refactoring function, then there will not be a problem if it has not been wired to other components. If the import or export was wired to other components, then re-run the external service wizard or sequence in the assembly editor, selecting the same properties as the previous execution of the wizard

  In the case of a Java™ Message Service (JMS) binding where you created an import by dragging and dropping an export, there is a matching export for that import. Re-create the import and export pair if one of them is deleted.

Exports

A shortcut often used to create an import with a JMS binding is to drag an export with a JMS binding from one module into the module where you want to create the import. However, if you refactor the interface of the original export, it will not modify the interface of the import accordingly. This section describes the manual steps you would need to perform to correct the interface of the import.

Moving an export with a JMS binding to another module to create an import (drag scenario)

• Both the import and export have the same interface: if you have added a JMS binding to an export in the assembly editor and dragged that export into another module creating a matching import, then the WSDL port type defined in the import interface will be invalid if the module with import does not contain the right interface. To correct the problem, copy the interface, WSDL files and business object files from the module with the export to the module with the import.
• Both the modules containing the import and export have dependencies on a library containing their interface: if you have added a JMS binding to an export in the assembly editor and dragged that export into a module creating a matching import, then the WSDL port type defined in the import interface will be invalid. In this case, however, the interface, WSDL files and business objects were created in a library, the export was created without an interface, and the library was added as a dependency to the module with the export. Then the interface from the library was added to the export, the JMS binding generated and the export dragged into another module to create the import. To correct the problem of an invalid port type defined in the import interface in this case, add the library as a dependency to the module with the import and rebuild the project.

Modules

• Delete a module: if you added a JMS binding to an export in the assembly editor and dragged that export into a module creating a matching import and then deleted the module containing the export, then there will be an invalid target attribute value on the destination element in the import binding. To correct the problem, if you intended to delete the module then delete the import. If you did not intend to delete the module, create the module and the export. There is no refactoring function that supports dragging and dropping an export to create in import.

Libraries

• Delete a library: if you deleted a library manually and the library had been added as a module dependency, then there will be a module classpath error. The error will indicate the removal of library artifacts that the dependent module artifacts depend upon. To correct the problem, choose one of the following actions:

  • Create the library with the removed artifacts and add it to the module dependencies.
  • Remove the original library from the module dependencies and also cleanup the module's artifacts (for example, you may need to delete the interface and binding in an import or export if the library contained an interface or WSDL files and the library's port type was referenced by the import or export).

Access external services with adapters

Related concepts:
Pattern of accessing external services with adapters
Developing services with adapters
Simple adapter wizard
Migrating applications using previous adapter levels

Related tasks:
Configure and using adapters
Create a business object from a source file

Related reference:
J2C data bindings
A closer look at business objects from data structures
J2C imports and exports at run time
Trade-offs when developing adapter imports and exports
Considerations when using adapters
Contributing your own external service or data wizard plug-in
Limitations for adapter imports and exports