Introduction
One of the final frontiers of Java development in PI is the development of a custom adapter. Unlike other Java developments in PI (mappings, adapter modules) which have extensive coverage in terms of documentation and guides, custom adapter development materials are few and far between. Although the following SAP Library link provides the steps for Developing a Java Adapter for SAP PI, these steps have not been updated since XI 3.0 days and in practice, the steps are somewhat vague with certain information missing that is required for proper development and deployment of the adapter.
With all these "hurdles" and no proper guide, it is no wonder that the following blog mentions that there is a high learning curve involved and the cost may come up to $500K.
Do you need a custom adapter in PI?
Due to these prohibitive factors, many alternative workarounds have been used to meet the various integration needs. Some of these involves developing IO connection in Java mappings or adapter modules even though these violates EJB's specification.
Over the next few weeks, I'll be sharing a series of posts covering the various aspects of custom adapter development. The aim is to shorten the learning curve by illustrating both the basics as well as the key points of such developments.
Without further ado, we will begin with the necessary setup and configuration to reproduce a clone copy of the sample JCA adapter provided by SAP.
Step 1 - Getting All the Necessary Files
As the first step, we need to get all the necessary files required to set up the project correctly. These are:-
i) The source code for the sample JCA adapter
ii) The configuration and deployment descriptor files
iii) The reference JAR library files for adapter development
i) Sample adapter source code
The source code is no longer provided in the installation SCA files. However these are available as an attachment in an older version of the following SAP Note:-
1004000 - SAP NetWeaver PI Adapter/Module Development: API Changes
Switch to version 20 of the note and download the attached ZIP file.
Extract the ZIP file into a suitable temporary location in the local computer.
ii) Configuration and deployment files
These files are not included in the above ZIP file (and even the external link provided in the SAP Note is not working). However, these are included in the Adapter Framework SCA file that can be downloaded from SMP.
Go to the Download Software section of SMP, and select Support Packages & Patches.
Navigate to the section for XI Adapter Framework as shown below and download the XIAF SCA file. Note that although the screenshot shows the SCA file that is relevant to my PI system, it is actually not really important which version of PI or SP level that is downloaded, as we just need a copy of the files.
Open the SCA file in a ZIP utility like 7-Zip, and navigate to the following RAR entry within the SCA file to access the sample adapter's file.
Open the RAR file and extract the following two folders to a temporary location in the local computer.
iii) PI adapter development reference libraries
Although NWDS 7.31 (and above) contains built-in libraries that are sufficient for mapping or adapter module development, there are a few more library files required for adapter development.
Retrieve the following four files from the PI system (either by accessing them directly at OS level or using an approach like Browsing File System of a Java-only System)
/usr/sap/<SID>/J<nr>/j2ee/cluster/bin/ext/security.class/lib/sap.com~tc~sec~ssf.jar
/usr/sap/<SID>/J<nr>/j2ee/cluster/bin/ext/tc~bl~txmanager~plb/lib/private/sap.com~tc~bl~txmanagerimpl~plb~impl.jar
/usr/sap/<SID>/J<nr>/j2ee/cluster/bin/core_lib/sap.com~tc~bl~guidgenerator~impl.jar
/usr/sap/<SID>/J<nr>/j2ee/cluster/bin/interfaces/appcontext_api/lib/private/sap.com~tc~je~appcontext_api~API.jar
Step 2 - Setting Up the Project in NWDS
With all the necessary files in place, we can proceed to set up the following projects in NWDS:-
i) Java Project for the adapter source codes
ii) Connector Project for the RAR file generation
i) Adapter Java Project
Create a new Java project in NWDS. The project name is arbitrary but some of the subsequent files will refer to it, so it is recommended to follow some form of naming convention.
Next, create a package within the project. The package name needs to be exactlycom.sap.aii.af.sample.adapter.ra (don't worry, this will be refactored later) in order to match the package declaration in the sample source codes.
With the package in place, copy the sample source codes that were extracted above (in Step 1 - i) and paste it into the package.
Initially, there will be various errors for the source codes. These need to be rectified by configuring the build path. Add the following two built-in libraries to the project.
Next, add the four PI adapter libraries as External JARs as shown below. Once this is done, the project will compile and build successfully.
ii) Connector Project
Select File > New > Connector Project to create the RAR project and accept the default values.
The project will be created with default files in the META-INF folder.
These need to be replaced by the following seven files that was extracted from the XIAF SCA file above (in Step 1 - ii).
Copy and paste the files into the META-INF folder (overwriting any existing files). The final view of the RAR project is as follows.
Step 3 - Modifying the of Source Code and Configuration Files
As the existing sample JCA adapter is normally already deployed in the PI system, we need to make some modifications to the codes and configuration files in order to be able to deploy a clone copy of the adapter.
i) Rename the package in the Java project
Right click on the package com.sap.aii.af.sample.adapter.ra and select Refactor > Rename, providing an appropriate name according to a suitable naming convention. This automatically updates all the underlying source codes with the new package name.
ii) Update adapter type and namespace in SPIManagedConnectionFactory.java
Open the above class, and navigate to the run() method. Modify the values for adapterType and adapterNamespace.
Note that this is a very crucial step, as it affects the actual registration of the adapter to the framework during deployment. The combination of these two values must be a unique pair.
iii) Update the deployment descriptor ra.xml
Open the ra.xml file in the META-INF folder of the RAR project. Update the following three values with the same package name that was used in item i) above.
In the same file, update the following values for the adapter type and namespace with the same value used in item ii) above.
iv) Update log-configuration.xml
Update the following values in the log configuration files. These values affect the logging that is displayed in NWA's Log Viewer.
v) Update the deployment file SAP_MANIFEST.MF
This file affects the deployment of the adapter. The combination of keyvendor and keyname values must be a unique pair so that it does not clash with other applications that are already deployed in the system.
Step 4 - Creating the Adapter Metadata in ESR
Next we will import the Adapter Metadata into the ESR.
i) Update JNDIName in the metadata file
SampleRA.xml is the Adapter Metadata file which was extracted from the XIAF SCA file (in Step 1 - ii).
Update the JNDIName value following the name of the Java Project (in Step 2 - i).
ii) Create Adapter Metadata object in ESR
Create a new namespace in ESR and then create a new Adapter Metadata object. The combination of adapter name and namespace must match exactly the values used in Step 3 - ii above.
Upon creation of the object, it will provide a default metadata. Overwrite this metadata by importing the modified SampleRA.xml above.
Activate the new metadata object.
Step 5 - Building and Deploying the Adapter
We are now ready to build and deploy the adapter! 
i) Export JAR file for Java project
Firstly, we export the JAR file of the Java project. The destination of the export will be the connectorModule folder of the RAR project.
Once the export is completed, refresh the RAR project and verify that the JAR file is in the connectorModule folder.
ii) Export RAR file for RAR project
Right click on the RAR project and export it as a RAR file.
The destination will be the root folder of the RAR project itself.
Once the export is completed, refresh the RAR project and verify that the RAR file is available.
iii) Deploy the RAR file to the SAP AS Java server
Prior to deployment, make sure that the AS Java server is configured under Windows > Preferences > SAP As Java.
Switch to the Deployment perspective. Click Import and select the RAR file from the workspace.
Click Start to begin deployment of the RAR file.
Upon completion, the following pop up dialog will display the result of the successful deployment.
iv) Verify deployment was successful
We can verify that the deployment was really successful with the following tools.
Go to NWA > Troubleshooting > Logs and Traces > Log Viewer. Check that the following errors are generated - they are just sample messages and can be ignored.
Go to NWA > Configuration > Infrastructure > Application Modules. Enter the filters for Type and Application to verify that the resource adapter is available.
Go to NWA > Troubleshooting > Java > JNDI Browser. Navigate to the deployedAdapters folder and verify that the JNDI object name is correctly registered. The JNDI name specified in the Adapter Metadata must match this value.
Go to NWA > Operations > System > Start & Stop. Select Java Applications tab and filter by the adapter name. Check that the application status is started.
Step 6 - Using the Adapter in a Communication Channel
After successful deployment, we can create communication channels using this new adapter.
Select the Adapter from the list of adapter and populate all the mandatory fields.
Activate the channel and check that it's successful in the Communication Channel Monitor.
Ta-daaaa!
This channel can then be used in an integration scenario as per normal configuration. However, usage of this channel which is based on the sample adapter's behavior will not be covered here.
Conclusion
As shown above, with clear and concise steps, we are able to setup the projects in NWDS correctly to build and deploy a clone copy of the sample JCA adapter. Communication channels can then be created to use this adapter in integration scenarios. The sample JCA adapter provides some simple logic to connect to the file system of the PI system.
This clone adapter forms the basis for the subsequent posts in this series. We will look at the different aspects of the development, and aim to change the logic and behavior of the adapter according for an example requirement.
In the next post we will be examining the source codes of the custom adapter, looking at some of the key classes and methods in order to understand the behavior of the adapter. Watch this space!