IBM VisualAge® for Java™,Version3.5 C++ Access Builder Note! Before using this information and the product it supports, be sure to read the general information under Notices. Edition notice This edition applies to Version 3.5 of IBM VisualAge for Java and to all subsequent releases and modifications until otherwise indicated in new editions. © Copyright International Business Machines Corporation 1997, 2000. All rights reserved. US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. Contents Chapter 1. C++ Access Builder .....1 Chapter 7. Testing the client from C++ Access Builder: overview ........1 program main............41 Language Elements Used in Mapping Java to C++. 3 Inheritance ..............3 Chapter 8. Deploying the client as a Constructors and destructors ........5 stand-alone application .......43 Methods ...............6 Membervariables............7 Operators..............8 Chapter 9. Tutorial ..........45 Global definitions ...........11 Sample: accessing a C++ library .......45 Pointers ..............13 Objectives ..............45 References ..............14 Time required ............45 Unionsandenums...........16 Beforeyoubegin...........45 Conversion functions ..........17 Description .............45 Type conversion ............18 Running the sample program ........46 Design Considerations with the C++ Access Builder 20 Add the project to the workbench ......46 Businesslogic............20 RunthesampleintheIDE........46 Wrapper classes ............22 Developthesampleprogram........47 Memoryallocation...........24 Add the project to the workbench ......47 Classes generated by the C++ Access Builder . 26 Generate the C++ access beans and wrapper files 47 C++ Access Builder limitations ........29 Createthesharedlibrary.........47 Create the client class ..........48 Chapter 2. Using the C++ Access Add the StStack bean to the Visual Composition Builder...............31 Editor...............48 Create the client program GUI .......48 Accessing C++ services: overview .......31 Connect the client program GUI ......48 Run your sample program in the IDE ....49 Chapter 3. Preparing to Generate C++ Run the sample program from the command line. 50 Access Beans ...........33 Startthesample............50 Creating a package for C++ access beans ....33 Run the sample as an application from the Creating C++ header files for interfaces .....33 commandline............50 Chapter 4. Generating C++ access Appendix. Reference Information . 51 beans and wrapper files .......35 Makefile targets .............51 Chapter 5. Creating Shared Libraries 37 Notices ..............53 Creatingasharedlibrary..........37 Creating a shared library without a makefile . 38 Programming interface information . 57 Chapter 6. Creating a client using C++ Trademarks and service marks ....59 access beans ............39 © Copyright IBM Corp. 1997, 2000 iii iv C++ Access Builder Chapter 1. C++ Access Builder C++ Access Builder: overview Java™ software developers face a number of problems when enabling Java programs to access C++ services. Fortunately, these problems are largely resolved by the C++ Access Builder. This VisualAge® for Java tool makes it easy for a Java client program, run as a stand-alone application, to access C++ services locally. The C++ Access Builder generates code in the form of access beans and associated C++ files that enable your Java program to access existing C++ classes. It is designed to integrate C++ objects as seamlessly as possible, so programmers get the impression that the objects are actually implemented in Java. The C++ Access Builder also generates a makefile. The makefile automatically builds a library that enables C++ classes to be accessed as native methods. The source code generated by the C++ Access Builder works in conjunction with the Java Native Interface (JNI) Specification, Release 1.1. This specification is implemented in the 1.1 version of the JavaSoft Java Developers Kit (JDK). JNI is a native programming interface that allows Java code to interoperate with libraries written in other programming languages, such as C and C++. The C++ Access Builder generates a makefile for the compiler you define; if your compiler is not supported, you may have to modify the generated makefile to work with your compiler. The C++ Access Builder consists of two components: a generation-time tool and a run-time class library. Generation-time tool The generation-time tool uses a SmartGuide to start and control the code-generation activities of the C++ Access Builder. Typically, the C++ Access Builder generates access beans and C++ wrapper files. Information about using the C++ Access Builder is found in the topic “Generating C++ access beans and wrapper files”. Run-time class library The run-time class library provides execution-time support to the access beans and associated files generated by the C++ Access Builder. The class library hides the complexity of the generated code and provides the generated code with some required generic services. The C++ Access Builder generation tool generates to the run-time class library com.ibm.ivj.eab.j2cppaccess. For additional information about the individual C++ Access Builder run-time classes and their methods, see the information on IBM® APIs in the Reference online help. How does the C++ Access Builder work? When accessing another object-oriented language from Java using the procedural native code interface defined by JNI, there are several problems that must be addressed: v No JNI support for the instantiation of C++ classes. © Copyright IBM Corp. 1997, 2000 1 v No Java support for accessing methods and members of C++ objects. v No Java support for operator overloading. v No Java support for passing objects by value and reference. v No Java support for several C++ primitive types, including unsigned int and signed char. To help address these problems, the C++ Access Builder generates a Java class to represent each C++ class. It also generates a C++ wrapper that can be safely invoked using the C native method calling convention for the Java virtual machine. This C++ wrapper interfaces with the original C++ class. When a Java representative class is instantiated, a corresponding C++ class is instantiated and a reference to the new C++ object is stored by the new Java object. The Java object uses this reference to invoke methods and access members of the corresponding C++ object. This bridging technique reproduces inheritance relationships between imported C++ classes on the Java side and also supports polymorphic C++ methods. Those C++ class methods which expect objects to be passed as parameters, or to return C++ objects, are accessible from Java using the Java representative objects as parameters instead. In the case of static members, access is possible without first instantiating the object pair. The implementation of the C++ classes to be interfaced can be provided by C++ files, shared libraries, or as a combination of both. This allows the user to extend an existing C++ library by user-defined subclasses before using the C++ Access Builder to generate the Java interface. The C++ Access Builder also maps C++ code that does not belong to a particular C++ class definition, such as overloaded non-member operators, global functions, and global variables. This code is represented by a special Java Statics class that contains Java access methods for each C++ declaration that was not part of any C++ class. 2 C++ Access Builder C++ Access Builder class selection Because the C++ Access Builder resolves typedef clauses and #define compiler directives, it can parse the whole hierarchy of include files for a given class definition file. Without an appropriate selection scheme indicating which classes are to be wrapped, all found C++ classes are mapped, including those found in the standard include files. To ensure that only the desired C++ classes are wrapped, the C++ Access Builder uses a mechanism comparable to the Java CLASSPATH. The C++ Access Builder maintains a list of directories, referred to here as J2CPP_CLASSPATH, to determine whether a found C++ class is to be mapped to Java or not. For C++ classes which are to be mapped to Java, the following predicate must hold: C++ class contained in class definition file contained in directory element of J2CPP_CLASSPATH In other words, a C++ class is mapped if it is contained in a class definition file that is located in one of the member directories of J2CPP_CLASSPATH. The C++ class may be a declaration of a class, a pointer to a class, or a reference to a class. The default class path used by the C++ Access Builder is the set of all directory prefixes of the class definition files specified in the SmartGuide. This means that J2CPP_CLASSPATH only needs to be set explicitly if classes are to be mapped which are defined in files other than those specified in the SmartGuide, such as those included using #include. J2CPP_CLASSPATH can be modified one of the following ways: v By specifing the directories in the Add directories that contain additional header files to wrap field on the first page of the SmartGuide. v By setting the J2CPP_CLASSPATH environment variable. A file named keyword.ignore is found in the help directory. It specifies any keywords that you want to ignore. If the C++ Access Builder parser cannot parse a particular word, then you can direct the parser to ignore the word by adding it to the keyword.ignore file. Classes generated by the C++ Access Builder C++