Working with C/C++ API

This module describes the following topic:

• Bringing the Legacy C, C++ API to Java

Bringing the Legacy C, C++ API to Java

---

This topic covers the details of how to build the Resource Adapter using Connector Builder for your legacy C/C++ API.

Connector Builder requires the API to be in Java, however, most of the legacy EISs or Applications only provide a C/C++ API. This section describes how you can build the Resource Adapter using Connector Builder for those legacy APIs.

You need to first create a Java (JNI) wrapper to the C/C++ API. Connector Builder recommends using the Native Connector Toolkit (NCT) tool available from the IDE. NCT is an easy to use tool that quickly generates Java wrappers for C/C++ applications using JNI. The output Java wrapper files generated by the NCT Tool become the input while defining the EIS API in the Connector Builder.

To Use NCT for Building the Java Wrapper

This section describes the process of using NCT to create the Java wrapper for the C/C++ API. Currently NCT works only on Solaris platforms. For detailed instructions on using the tool and supported platforms, refer to NCT documentation available under the IDE Help menu.

1. The legacy library should have been built using the -xnativeconnect compiler option. If compilation and linking are done in two different steps, use the -xnativeconnect option in both steps. This option is available with the latest Sun ONE Developer 7 Compiler Collection from Sun Microsystems. Refer to the Sun ONE 7 Compiler Collection documentation for more details on the compiler options. If the library is not built using this option, NCT cannot be used to create the Java wrappers and in that case, you need to write your own Java wrappers around the legacy API.
2. In cases where the sources for the API library are not available, you can create a simple wrapper program in C/C++ to wrap all the desired classes, methods and functions from the original library. Then compile and link this wrapper file with the original API shared object while using the -xnativeconnect option. Now you can use the newly created wrapper shared library with NCT module to create the Java wrapper.
3. Mount the directory containing the shared object in the IDE. Right click on the shared object and choose "Create a Native Connector". Provide the necessary details such as the name for the Native connector. When you are done, it creates the native connector definition file (.cdf). In the IDE, open the definition file and add all the methods and functions that you want to wrap in Java.
4. After selecting all the desired methods, click Generate. NCT creates the native connector under the directory _generated_<name>_nc. The IDE automatically mounts this directory. The directory structure underneath it is as follows:

1. The com directory contains the runtime components for NCT.
2. The cplus/jni directory contains the C++ code for JNI.
3. The nc/<name> directory contains the java code for JNI. It contains two .java files for each underlying API class (classname.java and classnameAccessor.java). All the global functions of the API are wrapped in Global.java and GlobalAccesor.java.
4. The sparc-SunOS directory contains the JNI wrapper shared object and a runtime shared object (libnamedConnector.so and libnc_rt.so)
5. The Javadoc directory contains the Java Doc for the generated connector Java code.
5. The nc directory under the _generated_<name>_nc directory contains the connector class files that are required while defining the EIS API to Connector Builder. You should jar the entire nc directory using

Jar -cvf <yourconnector>.jar nc.

To Use the NCT Generated Java Wrapper to Define the Adapter in Connector Builder

When you use NCT to create the Java wrapper (called the native connector), NCT generates a set of class files and two shared libraries. The nativeconnector .jar file is required when you define the resource adapter to Connector Builder. See Step 5 of the previous section.

1. Mount the nativeconnector .jar file in the IDE to be able to select the classes and methods to define in Connector Builder.
2. Start defining the Resource Adapter (See "Creating the Resource Adapter"" for more details). In Step 4 - Mapping the EIS API select the above .jar file and navigate to the nc.<connectorname>. The class 'Global' in this package contains all the global functions. Choose this class to define the API's global functions to Connector Builder. The other member functions of API classes are in their corresponding java classes. Choose all the desired classes to define their methods to Connector Builder.
3. Continue the process of defining your adapter as you would with a normal Java API.
4. Create a .jar file for the directory structure com under the NCT generated _generated_name_nc directory. (Refer to Step 4 a of the previous section). Go to the directory _generated_name_nc and run the command jar cvf <filename>.jar com

This is required as the package com.sun.forte.nc contains the runtime helper classes for the generated JNI wrapper. This package should be in the CLASSPATH to successfully compile and run the generated Resource Adapter. Since Connector Builder uses only .jar files and not class files placed in the packaged structure, this package needs to be in a jar file.

5. Place both the jar files (step 1 and step 4 of this section) in the Resource Adapter's lib directory. Using the Import Files context menu option of the generated resource adapter to do so.

Runtime Requirements

The two NCT generated shared objects - a native connector shared object(.so) file and a run time libnc_rt.so shared object file should be in the system's LD_LIBRARY_PATH at run time.

These two libraries should be packaged along with the resource adapter. Use the Import Files context menu option to copy these files into the adapter's lib directory from which the files are automatically packaged with the adapter.