My Dear debuggers,
Some days ago I had an interesting discussion with team mates about adapters. During that discussion I was able to get a lot of information about using WebSphere Adapters in BPM environment. Let me share these information with you.
IBM WebSphere Adapters (JCA Adapters) provide a mechanism that allows for the integration of an existing EIS infrastructure with the IBM Process Server (WPS), IBM WebSphere Enterprise Service Bus (WESB) and IBM Business Process Manager Advanced (BPM). Athough there are some JCA Adapters available in the WebSphere Message Broker and IBM Integration Bus space, this article focuses on the JCA Adapters found within the WPS, WESB and BPM space - full list can be found in the official documentation
AFC (Adapter Foundation Classes) is a library (jar) that implements the Java Connector Architecture (JCA) specification. It is not a standalone entity but is embedded within all JCA Adapters (from here on Adapters).
Adapters are bundled with development tools as Resource archive .rar files (WebSphere Integration Developer, IBM Integration Designer) and are not part of the runtime. That means they need to be deployed. There are two possibilities (not exclusive):
1) Deployed with the application - known as EMBEDDED.
2) Deployed directly through WAS console - known as STANDALONE.
Similarly, the Adapter configuration (effectively ActivationSpec or ConnectionFatory configuration) can be part of (and deployed with) the application or defined through WAS
console and available through JNDI, which is then referenced by the Adapter Import/Export.
Below are some important details to consider when working with Adapters and AFC. Focus is on the runtime, not development.
- Each Adapter is composed of 2 parts, AFC library and Adapter specific code.
- AFC is developed separately so versioning may differ from versioning of the specific Adapter. For example, both SAP Adapter 22.214.171.124_IF23 and FTP Adapter 126.96.36.199_IF09 consume AFC 188.8.131.52_IF07.
- Every time an Adapter interim fix, test fix or debug fix is created, it will be bundled with the latest AFC version available at that time. Each Adapter has a specific version of AFC it works with and was tested with.
- The Adapter lab is releasing Adapter builds with the latest AFC version on demand if not already available in Fix Central.
- In BPM and WPS environments where multiple Adapters are used, it is crucial to ensure that each Adapter sees the AFC version it is bundled with. Otherwise an AFC version conflict may prevent an Adapter from starting. Or the Adapters start without errors but AFC version mismatch can cause unpredictable behaviour .
Upgrading only one Adapter may result in the need to upgrade also other used Adapters. This depends on the AFC library version consumed by each used Adapter and how the Adapters
are deployed and used in the runtime. In general there are 3 different use-cases:
1) Adapters are embedded with the application (ear) and *no* Adapters are installed in the target runtime as standalone
Here the Adapter and its configuration will get deployed with the application. When the application starts, because the application classloader is isolated, it will load the AFC library
from the embedded Adapter. If multiple Adapters are used within the same application, the classloader will load the first AFC library it finds. Which AFC is picked is unpredictable.
➔ Ensure that all used Adapters within a single application workspace are using the same AFC version to avoid the AFC version conflict.
➔ If one Adapter is upgraded and AFC version changes, other Adapters within the same application the workspace need to be upgraded as well to the same AFC level. The application needs to be rebuilt and redeployed.
This use-case allows having different versions of Adapters across different applications, because the application classloader is isolated.
It is not possible to export the ActivationSpec or ConnectionFactory configuration to WAS and make it available through JNDI as this requires the Adapter to be installed as standalone.
Each Adapter upgrade requires repackaging and redeployment of the application.
2) Adapters are installed only as standalone. Applications do not have Adapters embedded, they reference the standalone Adapters.
Here the Adapter binaries, including AFC library, will get loaded at server start. The classloader will load the first AFC library it finds and that AFC version is then used by all other
Adapters (in case multiple standalone Adapters are installed). Which AFC library from which standalone Adapter will get picked is unpredictable.
➔ Ensure that all installed standalone Adapters are using the same AFC version to avoid AFC version conflict.
➔ If only one standalone Adapter is upgraded and AFC version changes, all other standalone than Adapters have to be upgraded as well. All Adapter upgrades need to be
done at the same time and runtime needs to be restarted.
This use-case allows having activation specification / connection factory configuration created as part of the standalone Adapter and available through JNDI. Maintenance is easier because
Adapter upgrades are done only once without a need to redeploy Adapter applications.
If there are multiple different teams developing different applications, then this option would require ALL teams/applications to upgrade and test when 1 team makes a change
3) Some applications have Adapters embedded and some Adapters are installed as standalone.
This is the most complex use-case, it is harder to maintain and troubleshoot in case of issues. Extra care is required. So we strongly recommend considering use-case 1) or 2) instead of this one.
Standalone Adapter will take precedence in terms of AFC version loaded in runtime compared to embedded Adapter. And from point 2) we know that, in case multiple standalone Adapters
are used in the target runtime, we can't control which AFC library from which standalone Adapter will get loaded. That is why in this use-case, all used Adapters in the target runtime,
either standalone or embedded, need to be on the same AFC level.
Note, this also includes scenarios where, for example, an application embeds the FlatFile Adapter but the target runtime already has standalone FlatFile Adapter installed. Even if the
application references the embedded Adapter that has a different AFC library compared to the standalone Adapter, because of above reasons, AFC from standalone Adapter will be loaded
➔ Ensure that all embedded and standalone Adapters used in the target runtime are using the same AFC versions to avoid AFC version conflict.
➔ If only one standalone Adapter is upgraded, all other standalone or embedded Adapters have to be upgraded as well with the builds with same AFC version to avoid AFC version
conflict. All Adapter upgrades need to be done at the same time. Impacted applications need to be repackaged and redeployed and the runtime restarted.
This use-case allows multiple different projects from different teams and different Adapter packaging approaches to be deployed in the same runtime.
This use-case is subject to disadvantages presented for use-cases 1) and 2) If you are not aware already, the Adapter AFC version information can be found by inspecting
the CWYBS_AdapterFoundation.jar within the Adapter .rar file following these instructions:
- standalone Adapter in runtime is extracted here:
<WAS root dir>\profiles\<profile>\installedConnectors\<AdapterRAR>\
- embedded Adapter in runtime is extracted here:
I hope this posting will help you to get a generally overview of WebSphere adapter and its behavior at runtime.
And if neither of this works, take two of these and call me in the morning.
Your Doc D.