Essential JNI: Java Native Interface

Description

67989-4

Leverage platform-specific features without compromising binary compatibility!

With the Java Native Interface API, you get the best of both worlds: access to the native platform features you need to get the job done plus full binary compatibility across multiple Java Virtual Machines. And there is no better way to master the JNI than this fast-paced, example-rich guide, which focuses on proven techniques.

Walk step-by-step through writing Java and native code components, building libraries, loading and invoking native methods, and more. Discover powerful techniques for creating Java Virtual Machines from within any native application. Learn proven approaches to integrating Java and C++ code, converting C structures, and providing serial I/O from Java on both POSIX and Win32 platforms. Get comprehensive debugging help. There's even a complete, easy-to-use API reference!

With JNI, you can leverage Java's extraordinary capabilities without sacrificing proven legacy code.

Essential JNI: Java Native Interface gives you the insight, proven techniques, and real-world sample code you'll need to get results with JNI, plus:

• A complete, task-oriented reference to the entire Java Native Interface API
• Tools and strategies for integrating legacy code with new Java applications
• Extensive code examples and detailed debugging tips
• Clear explanations of JNI native types, signatures, references, and object and class functions
• Specific techniques for managing C++ code and converting C structures

Sample Content

Downloadable Sample Chapter

Click here for a sample chapter for this book: 0136798950.pdf

Table of Contents

(NOTE: Each chapter beings with an Introduction and concludes with a Summary.)

Preface.

What This Book is About. Who Should Read This Book? Structure of This Book. Whose Java? Downloading Example Source. Building the Examples. Setting Up the Environment. How To Build. A Word About the Examples. Some Conventions. Help From Fellow Travelers. A Word About Borrowed Words. Acknowledgments.

Virtual Machine, Real Machine. JNI and Binary Compatibility. Memory Loss. The JNI Solution. Features of the JNI.

The Big Picture. The Steps. Identify Native Functionality. Describing the Interface to the Native Code. Writing the Java Code. Using javac to Generate Class Files. Using javah to Generate Include Files. Writing Native Code. Building a Library. Loading and Invoking the native Method. Building and Running Your Java Application. The Steps in Pictures.

What Is All This Talk About C and C++? Some of the Basics. Setting Java Object Data Fields. Native Access to an Objects Own Data Fields. Making It Happen. Native Access to Another Object's Data Fields. Making It Happen. Getting a Java Object's Data Fields. Invoking a Java Method. Native Access to an Objects Own Methods. Native Access to Private Methods of Another Object. Making It Happen. A Disclaimer of Sorts. Returning a Value From Java Methods. Non-Virtual Method Invocation. Use of JNI Non-Virtual Functions. Yet More Ways to Call a Java Method.

Java Types. Java Native Types. Primitive Native Types. Reference Native Types. Programming Considerations. The jvalue Type. Field and Method Identifier Types. Method Signatures. Signature and Constructors. Type Signatures and Data Fields. The JNIEnv Pointer. A Word About Passing Arguments.

JNI References. Code Natively, Reference Locally. Coding Globally. Releasing a Local Reference. A Few More Facts About Native References. JNI Object Functions. Determining an Object's Class. Creating a New Object Instance. Using NewObject. Using NewObjectA. Using NewObjectV. Example Object Creation. Allocating Memory for an Object. Comparing Two References. A Native instanceof. Testing Class Inheritance Relationship. JNI Class Functions. From Class Name to Class. From Class to Superclass. From Bytes to Class. A Simple Class Loader. A Loader Using DefineClass.

JNI Array Functions. Object Arrays. Array of Arrays. Some Output. Primitive Type Arrays. Creating a Primitive Array. Getting Primitive Array Elements. Accessing the Entire Array Contents of a Primitive Array. An Example: Accessing an Entire Array. Accessing a Region of a Primitive Array. JNI String Functions. UTF-8 String Handling. Creating a New String Object. Unicode String Functions.

Throwing Exceptions. Throwing an Exception. Building and Throwing an Exception. When Does an Exception Get Raised? Catching Exceptions. A Native Try-Catch. Passing Exceptions to Java. A JNI Stack Trace. General Exception Handling Guidelines.

JNI Synchronization Support. The Producer-Consumer Problem. A Java Implementation. A JNI Producer-Consumer Implementation. The C++ Product Info Class. The init Method. C++/Java Object Correspondence. Native Implementation of Produce Method. Native Implementation of Consume Method. A Native Wait and Notify. Native Producer-Consumer Output. A Reminder. A Global Reference as Lock.

C++ Legacy Code. The General Strategy. Mirroring Example. The C++ Side. The Java Side. Type Mappings. Object Construction. Finalization. Cloning. Serialization. The Native Methods. The Registry Interface. Object Construction and the Registry. Instance Data Access and the Registry. Object Finalization and the Registry. Object Cloning and the Registry. Serialization and the Registry. The Registry Implementation. MFC Implementation of ObjMap. Tools.h++ Implementation of ObjMap. Static Variables and Methods. C++ Class Methods. Public Data Field Access. Java Mirroring at Work 176 An Alternative to the Registry. Some Other Issues. Multiple Inheritance. C++ Templates.

The Java Source. The C Adapter Code. POSIX User Database Access. Using structConverter. Running the C Preprocessor. The structConverter Configuration File. Running structConverter. The Java Source File. StructConverter Data Type Conversion. InitFIDs and the static Block. The Adapter Source File. Field ID Initialization. Adapter Code. Tying It All Together. Another Database Example. Updating a Booking Record. Generating Just Java. Some Design Considerations. A Bit More About structConverter.

The portio Package. Using portio. Portio Template Class Files. Augmenting portio. Portio and POSIX tty. The PosixPortDriver Class. The PosixPortReader Class. The PosixPortPrivate Class. The POSIX Native Code. Opening and Closing a Port Using POSIX System Calls. Reading and Writing a Port Using POSIX System Calls. Using POSIX System Calls flush, sendBreak and purge. Setting POSIX Device Parameters. Portio and Win32 COM.

JVM Initialization. Stack and Heap Values. Garbage Collection Settings. Load Verification Mode. The classpath Field. The properties Field (JDK 1.1.2 and Greater). Application Hooks for the JVM. Invocation API Overview. invokeMain: Creating a JVM. A Java-enabled Application in Action. Building a Java-Enabled Application. The Invocation API and Reflection. JNI and Reflection. Running miniInvoker. A Small Disclaimer. Registering Native Methods. The JNINativeMethod Structure. Using RegisterNatives. Building for Native Method Registration. Avoiding Static Libraries.

The Service Control Manager. Registering a Service With the SCM. The Service Process. The Executing Service. Reporting Service Status. The service_controller Routine. The Java Agent Server. Starting the Java Agent Server. Stopping the Java Agent Server. Support for Java Agent Creation. The JVM as Service: Some Considerations. The JVM's Current Working Directory. Displaying a Frame. Some Common Errors. A Java Agent Service. Overview of a Java Logging Agent. Source for a Java Logging Agent. Making It Happen.

What Is It You Are Debugging? JNI Debugging Tips. Microsoft Visual Studio. The JVM: Starting a Debug Session. Debugging on Solaris. Using dbx. Debugging With Sun Workshop. When All Else Fails.

Summary of Enhancements. Summary of Additional Functionality. JDK 1.2 JNI Enhancements. JVM Initialization. Improvements to Invocation API Functions. FindClass Enhancements. New JDK 1.2 JNI Functions. Weak References. “Critical Region” String and Array Manipulation. Local Reference Management. Core Reflection Support. String Character Extraction. New Invocation API Functionality. Loading and Unloading Notification. Native Library Management Via Class Loaders.

Notation. The Invocation API.

javah Usage. Using javah to Generate 1.0-Style Native Code. Using javah to Generate JNI Function Prototypes. Include File Requirements. The Pieces, Side-by-Side. Building Native Libraries. A printString Example. The Execution Environment. Function Specification and Naming. Data Types. Argument Handling. Signatures. Accessing Java Data Fields. Accessing Instance Data. Accessing Class Data. Invoking Methods. Invoking a Java Instance Method. Invoking a Java Class Method. Creating an Object. Exceptions. String Manipulation. Arrays. Garbage Collection Issues.

Command Syntax. Options.

Command Syntax. Options. Description. Environment Variables.

General JDK Security. Netscape Communicator Security. Netscape Capabilities API and Object Signing. Avoiding Signatures. Using Native Code With Applets. How Did the Native Library Get There?

Preface

Before we plow an unfamiliar patch It is well to be informed about the winds, About the variations in the sky, The native traits and habits of the place, What each locale permits, and what denies Virgil The Georgics

Preface

What This Book is About
The subject of this book is the Java Native Interface (JNI) Application Programming Interface (API). The JNI was introduced in release 1.1 of the Java Development Kit (JDK) as distributed by JavaSoft. This book covers the entire API for the JNI including the enhancements introduced in release 1.2 of the JDK. Where there are minor differences between various 1.1 point releases, these are discussed.

Who Should Read This Book?
This book is written for the software engineer who needs to make Java and C or C++ talk to one another. Experience with C/C++ and Java is assumed. This book also assumes some familiarity with both UNIX and Win32 platforms.

If you are a Java programmer who needs to step outside the Java Virtual Machine to take advantage of some platform-specific functionality, this book will show you how. If you are a C programmer responsible for putting a Java font-end on a legacy application, this book will show you how. If you are a C++ programmer wanting to take advantage of an existing C++ class library, this book will show you how.

Further, this book covers these topics for both UNIX and Win32 platforms.
Okay, now turn around and walk to the sales counter.

Structure of This Book

This book can be thought of as having three distinct parts. The first part, roughly the first eight chapters, covers the JNI API in great detail. The second part, the remaining chapters, covers some general issues involved with native method programming. The third part, a series of appendices, contains reference material, both for the JNI and for tools introduced in this book. There is also an appendix that compares the JNI with the old-style native method programming model introduced in JDK 1.0. The last appendix offers a brief discussion of native methods, applets and security issues.

The early chapters contain plenty of simple examples intended to highlight the essential features of the API. No attempt is made to place JNI function calls into large, complex examples that obscure their salient features.

The first part of the book takes a walk-before-you-run approach. After an overview of the JNI in Chapter 1.
Chapter 2 presents a JNI version of the classic "Hello World" example.
Chapter 3 then follows with examples of some of the more common JNI operations before plunging into the syntactical details of the JNI in Chapter 4.
With all that work behind you, Chapter 5 through Chapter 8 provides detailed coverage of the remaining JNI functions.

The second half of the book deals with a series of general topics on using the JNI to integrate Java code with non-Java code. Chapter 9 presents an approach for mirroring existing C++ classes in Java. Chapter 10 introduces a tool for the automatic conversion of C structures into Java classes and an accompanying set of adapter functions for copying data between an instance of a C structure and a Java object. Chapter 11 starts with a collection of Java classes that provide a high-level interface to serial and parallel ports. Throughout this chapter the native code for targetting these classes for both POSIX and Win32 platforms is presented and discussed. The Java package used in this chapter is the portio package which is freely-available from Central Data (www.cd.com) as well as being included with the examples at the Prentice-Hall ftp site.

Chapter 12 and Chapter 13 deal with the Invocation API. Chapter 12 is a broad discussion of the mechanics involved with starting a Java Virtual Machine from a C/C++ application. Chapter 13 provides a very specific example of this facility, namely, starting the Java Virtual Machine (JVM) as an NT service. This chapter is for NT developers who wish to use Sun's JVM as an engine for their Java applications. Chapter 14 presents some approaches to debugging a Java application that includes native code. Finally, Chapter 15 is dedicated to changes and enhancements to the JNI in the JDK 1.2.

Whose Java?
This book covers the Java Native Interface API. To use the Java Native Interface API, you will need to run your Java code on a Java Virtual Machine that supports the JNI. The list of JVM vendors supporting the JNI is growing, but a sure bet is the JVM distributed by Sun. The Sun JVM, the Java Core classes and the JNI are available as part of the Java Development Kit (JDK). The JNI is supported starting in release 1.1 of the JDK.

To download the JDK, surf to the JavaSoft download site: http://java.sun.com/products/jdk/1.1/index.html and follow the instructions.
The JDK 1.2 release is available from: http://java.sun.com/products/jdk/1.2/index.html
Downloading Example Source
The source code to the examples in this book is available at the Prentice Hall ftp site, ftp.prenhall.com.
This site is available via anonymous ftp. The following sequence of steps illustrates how to download the Essential JNI examples. You type the bold.
% ftp ftp.prenhall.com
Connected to iq-ss3.prenhall.com.
220 iq-ss3 FTP server(UNIX(r) System V Release 4.0) ready.
User (iq-ss3.prenhall.com:(none)): anonymous
331 Guest login ok, send ident as password.
Password:
230 Guest login ok, access restrictions apply.
ftp> cd /pub/ptr/professional_computer_science.w-022/gordon/essential_jni
250 CWD command successful.
ftp> get ejni_ex.tar
200 PORT command successful.
150 ASCII data connection for ejni_examples.tar (38.11.232.6,1099) (19818 bytes).
226 ASCII Transfer complete.
20184 bytes received in 5.93 seconds (3.40 Kbytes/sec)
ftp> bye

Goodbye.
The ftp directory named in line 1 contains two examples files described in the following table.
File Name
Format
Size
ejni_ex.zip
zip
452KB
ejni_ex.tar
tar
1.55MB
These two files include makefiles for both Win32 and Solaris.
After downloading the examples, unzip or untar the file in a directory of your choice. Users of a UNIX zip utility should be careful to use the -a flag with unzip so that CR/NL sequences are properly converted. Extracting the files will create a directory named ejni. Within the ejni directory will be another directory, examples.

The directory ejni/examples is known as the examples directory throughout this book.
Building the Examples
Before the examples can be built and run, some environment must be set up.

Setting Up the Environment
Two files are included with the example files that describe the appropriate environment settings. The file csh.env is provided for UNIX csh users. It is easily modified for other shells. The file win32.bat is provided for Win32 users. Both files must be modified to specify the location of your JDK and the location of your examples directory. Specifically, two environment variables are provided, JDK_HOME and EJNI_HOME, which point to these locations.

Additionally, these files define an appropriate setting for the CLASSPATH environment variable, adding the directories required to run the examples.

Finally, there are some platform-specific environment variables that need to be set.

Solaris Environment
The environment variable LD_LIBRARY_PATH is set within the csh.env file. The directory in which the example native libraries are installed is added to your existing value.
The Solaris build assumes you are using Sun's compilers. Be certain to modify the CC settings in EJNI_HOME/Makefile.master to point to the proper installation directory, or comment it out and use your environment settings.
The examples in Chapter 9 require Rogue Wave's Tools.h++ class library. If you have this software, you will need to set the relevant macros in EJNI_HOME/Makefile.master to the appropriate values. If you are a UNIX user and don't have the Tools.h++ software, remove the target chap9 from the SUBDIRS macro in EJNI_HOME/Makefile. Your enjoyment of this example will be necessarily limited to viewing the source.
Win32 Environment
Win32 users can use the batch file win32.bat located in EJNI_HOME to set up their environment for building the examples. The file win32.bat batch assumes you are building using MicrosoftÕs compiler, specifically Visual C++ and cl.exe. The appropriate environment for running cl from the command line is set using the vcvars32.bat batch file shipped with Visual C++. This file is located in your Visual C++ bin directory, typically \Program Files\DevStudio\VC\bin. vcvars32.bat should be run before running win32.bat.
If you get the message "Out of environment space," you will need to use the command command from the DOS prompt as shown below.
Increasing DOS Environment Space
C:\> command /e:8192
This setting will only be in effect for the current DOS shell. To set this value permanently, add the following line to your CONFIG.SYS file.
shell=command.com /e:8192 /p

How To Build
Once the environment is set up you are ready to build. On Solaris, the following make commands, executed from the EJNI_HOME directory, build the Java class files and native libraries.

Building on Solaris
% make all; make install
On Win32 systems, the nmake command is used to build the example Java class files and native DLLs.
This command must be executed from the EJNI_HOME directory.

Building on Win32
% nmake TARGET=all /f nmake.mak all
When the build is complete, all the class files live in $EJNI_HOME/classes and all the native libraries live in $EJNI_HOME/platform/lib where platform is either sparc or win32. Tilt the slashes appropriately for Win32 platforms.
A Word About the Examples
All of native coding examples are written in either C or C++. As you will learn, the syntax for calling a JNI function differs across the two languages.
In the first part of the book, through Chapter 8, all of the examples are written in C++. Therefore, whenever a reference is made to the first argument to a JNI function, it is understood not to count the JNIEnv pointer argument that is present in a C call of a JNI function.
The examples directory contains a directory for each chapter. Within the chapter directory is a directory for each example. Example 1 in Chapter 5 resides in ejni/examples/chap5/example1.
A README file in each example directory describes how to run the example since the book does not actually show all the examples running.

Some Conventions
All code listings, output, all variable, method and function names that appear in the text, command names, directory names, and all URLs appear in courier.
User input appears in bold courier.
Special terms, upon their introduction, and parameters to be substituted for appear in italics.
Pseudo-code and labels within figures appear in helvetica.
Help From Fellow Travellers
There are at least two list-servers available for JNI programmers. The first deals directly with native method programming. On the jnative-l list you will find discussions of JNI as well as old-style JDK native method programming, Microsoft's Runtime Native Interface (RNI), Netscape's Java Runtime Environment (JRE) and, to a lesser extent, problems with incorporating native code with various browsers. To subscribe to this list, send an e-mail message to majordomo@lists.teleport.com with the text subscribe jnative-l in the body of the message.

It is not unusual for questions related to native method programming to appear on the Advanced Java list. To subscribe to this list, send mail to majordomo@xcf.berkeley.edu with an empty subject and the following body:
subscribe advanced-java your_email_address
end
Do not use this latter list injudiciously. It is heavily patrolled by self-appointed experts who spend as much time telling people their question is not sufficiently "advanced" as they do providing answers to those question that they deem worthy of their consideration.

To stay in step with updates and enhancements to the JDK and the JNI, you may want to register with the Java Developer's Connection (JDC). To do so, follow the link off the JavaSoft home page (java.sun.com). As a member of the JDC, you are eligible for Early Access APIs. This is also the place to submit and track bugs. The JDC is a free service from JavaSoft but you do have to register.
A Word About Borrowed Words
Reading the quotes at the beginning of each chapter is a requirement for successful completion of this book. Too many late nights were spent finding them and too many phone calls were made acquiring permission to use them for you to ignore them.

Why include them at all? A guy who takes writing seriously has to do something to catch the eye of the reviewers at The New York Times Review of Books. Besides, it was fun trying to decorate the often bland minutia of a programming API with the distinguished dress of great ideas. I don't know if it worked, but I highly recommend all the quoted authors. Well, I can take or leave Nietszche. As for Hobbes, I think he had it backwards. We are heading toward where he thinks we began.

Updates

Submit Errata