Demystifying Custom Adapter Development: Part 3 – Examining the Deployment and Metadata Files
In the previous parts of this custom adapter development series, we have explored the steps to clone the sample JCA adapter as well as having a closer look at the source code of the adapter. Now we turn our attention to the various other files that are part of the custom adapter project. These includes the deployment descriptor, manifest and the adapter metadata files.
This part is not meant to exhaustively cover every detail of the files, but aims to highlight some of the key aspects of these files.
Deployment Descriptor File
The deployment descriptor for the resource adapter is the ra.xml file located in the META-INF folder of the RAR project.
The first section of the file provides the option to configure the details of the resource adapter. These are arbitrary values and do not affect the runtime functionality of the adapter.
If the values are changed in this file, after successful deployment, these can be viewed in NWA > Configuration > Infrastructure > Application Modules.
As covered in part 1, the ra.xml contains the following section to configure the properties of the resource adapter.
Upon successful deployment, these properties are displayed in the corresponding JCA Connection Factory, accessible via NWA > Configuration > Infrastructure > Application Resources under the Configuration Properties tab.
Note: If there are additional configuration properties defined in the ra.xml file, it is important that the SMCF (SPIManagedConnectionFactory) source code contains corresponding getters and setters for these properties. This is to ensure that the SMCF is a Java Bean that complies to the JCA standard. Any missing getters/setters will cause errors or warnings during deployment.
There are two manifest files in the META-INF folder of the RAR project.
The MANIFEST.MF file do not affect deployment so it can be left as is.
For deployment to the AS Java server, the SAP_MANIFEST.MF affects the deployment process. A key attribute of this file is the keycounter value which determines the version of deployment.
During the deployment process, this value is checked against the version in the server (if it was already deployed previously). If the value is not newer than the version deployed in the server, the deployment process fails as shown in the example below. As a recommendation, I would suggest to use the Semantic Versioning approach to maintain the keycounter/version value and incrementing the value for each subsequent deployment.
Adapter Metadata File
As briefly covered in part 1, the SampleRA.xml file contains the Adapter Metadata that is imported into ESR. This file will be modified accordingly to allow configuration of the behavior of the adapter during creation of an associated communication channel. Following are several key aspects of the adapter metadata file.
i) Transport Protocol
An adapter can support multiple transport protocol. For example, the mail receiver adapter supports SMTP and IMAP4. Transport protocols are defined in the section /AdapterTypeMetaData/<Direction>/TransportProtocol of the file. Valid Message Protocols for each supported Transport Protocol are also listed in this section.
From source code, method getTransProt() of interface com.sap.aii.af.service.cpa.Channel is used to retrieve this value from a communication channel.
ii) Message Protocol
An adapter can additionally support different message protocols for each of the supported transport protocols. For example, transport protocol HTTP of the SOAP adapter supports SOAP 1.1 and XI 3.0 message protocols. Message protocols are defined in the section /AdapterTypeMetaData/<Direction>/MessageProtocol of the file.
From source code, method getMsgProt() of interface com.sap.aii.af.service.cpa.Channel is used to retrieve this value from a communication channel.
iii) Channel Attributes
An adapter supports configurable attributes that affect the functionality and behavior of the associated channel. The valid attributes are defined in section /AdapterTypeMetaData/<Direction>/TransportProtocol/ChannelAttributes/AttributeGroup/AttributeReference/ReferenceName of the file.
The details of each attribute are further defined in section /AdapterTypeMetaData/Attribute of the file. This includes the type, length, mandatory value and even if the attribute can be transportable.
From source code, interface com.sap.aii.af.service.cpa.Channel provides numerous getValueXXX() methods to retrieve the value(s) from the channel attributes depending on the type of the attribute.
In this part, we have gained an understanding of the various files that affects the design and deployment of the custom adapter. Together with the knowledge from the previous parts, we now have the fundamental knowledge required to customise the adapter to suit specific integration requirements.
Stay tuned for the eagerly awaited next part of this series, where we will be walking through hands-on steps to modify, deploy and test the custom adapter.
Other Parts of this Series