Integration of C++ Shared Libraries

This appendix explains how to use the functionality of C and C++ native libraries in a web service. The explanation assumes that you have general familiarity with the Sun ONE Studio 4, Enterprise Edition for Java IDE and that you have read the earlier parts of this book, especially and Chapter 3, which explain how to create web services and web service clients.

There are two aspects to the integration process, roughly corresponding to the roles of the C++ developer and the Java web service developer. This book is addressed to the Java web service developer. In that role, you might find it helpful to have a general understanding of what the C++ developer does to prepare a C++ component so that its methods can be exposed in a Sun ONE Studio Java web service. The following section provides a summary of the C++ side of the process. For more information on that subject, see the Native Connector Tool online help in the IDE.

---

Tasks of the C++ Developer

The role of the C++ developer is to provide a native connector file and native connector components.

The native connector file is used by the Java developer in the IDE to select methods and add them to a web service, either as direct method invocations or as part of more complex XML operations. Native connector file names end with the .cdf extension. They are displayed in the Explorer with an icon containing an orange sphere (). The content of a native connector file is an XML document.

The native connector components are used by the web service at runtime. Java wrapper classes are generated, along with required descriptors and interfaces. C++ methods in a native shared library are accessed as Java methods in the generated wrappers.

The Native Connector Tool (NCT) is used by the C++ developer in the IDE to create and edit the native connector file, and to generate the native connector components.

The NCT provides a wizard to create native connectors, an editor to select native functions and data objects to be visible to Java components, and a code generator to create the interfaces between the native code and Java components, using the Java Native Interface (JNI). The resulting Java wrapper classes can be used anywhere that the Java language can be used.

The basic steps in the process are these:

1. Create an enhanced native library by compiling the library source code using the -xnativeconnect compiler option.

You must use compilers in the Sun Open Net Environment (Sun ONE) Studio 7, Compiler Collection for this step.

2. Create a native connector file for the enhanced native library.

3. Edit the native connector file (with the NCT editor) to select the objects, methods, and properties to expose in the Java API.

---

Note - If you add methods individually, you must also add the class's no-arg constructor. This is a Sun ONE Studio 4, Enterprise Edition for Java web services requirement. If you add methods by clicking Add All, the constructor is added automatically.

---

4. Generate the native connector file to create the native connector (wrapper) components.

The process is displayed in FIGURE A-1.

 FIGURE A-1 Native Connector Tool Work Flow

---

Tasks of the Java Web Service Developer

The Java web service developer can expose methods of C and C++ shared libraries in direct method calls or as part of XML operations. The same web service can also expose the methods of EJB components and (if the web-centric architecture is used) web tier components. See for a complete explanation of how to build, test, assemble, and deploy a web service.

The following procedure assumes that a C++ developer has provided you with the required C++ shared libraries and the native connector file. To add a C or C++ method to your web service:

1. Mount the directory containing the native connector file.

The file name should have a .cdf extension. FIGURE A-2 shows a native connector node named myConnector expanded in the Explorer. The available methods are displayed in the Methods and Field Accessors node.

 FIGURE A-2 Native Connector Node

2. Right-click your web service in the Explorer, and choose Add Reference.

A file browser is displayed.

3. Select the native connector node, expand it in the file browser tree view, and select the desired methods.

You can select more than one method by holding down the Control key while clicking.

4. Click OK in the file browser.

The selected methods are added to your web service.

You can also add methods from the New Web Service wizard, which displays the file browser as part of the process of creating a new web service.

---

Note - Apart from Step 1 and Step 3, this is the same procedure, described in , that you use to expose Java component methods in a web service.

---

---

Software Requirements

For information about the required platforms and operating systems, see the release notes on the following web site:

http://forte.sun.com/ffj/documentation/index.html

When you install the Sun ONE Studio 4, Enterprise Edition for Java IDE, use the installation wizard and install everything, including Core Platform and Modules, and Solaris Developer.

---

Customizing Your J2EE RI Installation

When you install the IDE, the installer puts the J2EE Reference Implementation in a directory directly under your top-level directory for Sun ONE Studio 4, Enterprise Edition for JavaSun ONE Studio 4, Enterprise Edition for Java: $s1studio_HOME/j2sdkee1.3.1. You can also use an external RI. If you are using an external RI, modify the following procedure to refer to the corresponding files in your RI location.

1. Edit the file $J2EE_HOME/lib/security/server.policy.

Near the bottom of this file is a section labeled "default permissions granted to all domains." The first permission grants the queuePrintJob runtime permission to all domains. Add the following line after the first permission:

Permission java.lang.RuntimePermission "loadLibrary.*";

2. Edit the file $J2EE_HOME/bin/setenv.sh.

Find the line that defines the SYSTEM_LIB_DIR variable. Insert the following two lines after it:

LD_LIBRARY_PATH=$J2EE_HOME/nativelib

export LD_LIBRARY_PATH

---

Installing the Shared Libraries in Your Application Server

Three shared libraries are used at runtime, as illustrated in FIGURE A-1. The libraries must be installed on the system that hosts the application server, so that they can be found by the application server.

The J2EE RI has a directory named nativelib that is intended for native libraries. Copy your three shared libraries to this directory. The J2EE RI uses the value of LD_LIBRARY_PATH to find the libraries.

From a terminal window, install the shared libraries by executing commands such as the following:

cd /mydisk1/NativeConnectorDemo/_generated_NCDemo_nc/sparc-SunOS

cp *.so $s1studio_HOME/j2sdkee1.3.1/nativelib