book

Java™ Native Interface: Programmer’s Guide and Specification, The

Name: Java™ Native Interface: Programmer’s Guide and Specification, The
Author: Sheng Liang
ISBN: 0201325772

by Sheng Liang

June 1999

Intermediate to advanced

320 pages

5h 20m

English

Addison-Wesley Professional

Read now

Unlock full access

Copyright
Dedication
Preface
I. Introduction and Tutorial
1. Introduction
1.1. The Java Platform and Host Environment1.2. Role of the JNI1.3. Implications of Using the JNI1.4. When to Use the JNI1.5. Evolution of the JNI1.6. Example Programs
2. Getting Started
2.1. Overview2.2. Declare the Native Method2.3. Compile the HelloWorld Class2.4. Create the Native Method Header File2.5. Write the Native Method Implementation2.6. Compile the C Source and Create a Native Library2.7. Run the Program
II. Programmer’s Guide
3. Basic Types, Strings, and Arrays
3.1. A Simple Native Method3.1.1. C Prototype for Implementing the Native Method3.1.2. Native Method Arguments3.1.3. Mapping of Types3.2. Accessing Strings3.2.1. Converting to Native Strings3.2.2. Freeing Native String Resources3.2.3. Constructing New Strings3.2.4. Other JNI String Functions3.2.5. New JNI String Functions in Java 2 SDK Release 1.23.2.6. Summary of JNI String Functions3.2.7. Choosing among the String Functions3.3. Accessing Arrays3.3.1. Accessing Arrays in C3.3.2. Accessing Arrays of Primitive Types3.3.3. Summary of JNI Primitive Array Functions3.3.4. Choosing among the Primitive Array Functions3.3.5. Accessing Arrays of Objects
4. Fields and Methods
4.1. Accessing Fields4.1.1. Procedure for Accessing an Instance Field4.1.2. Field Descriptors4.1.3. Accessing Static Fields4.2. Calling Methods4.2.1. Calling Instance Methods4.2.2. Forming the Method Descriptor4.2.3. Calling Static Methods4.2.4. Calling Instance Methods of a Superclass4.3. Invoking Constructors4.4. Caching Field and Method IDs4.4.1. Caching at the Point of Use4.4.2. Caching in the Defining Class’s Initializer4.4.3. Comparison between the Two Approaches to Caching IDs4.5. Performance of JNI Field and Method Operations
5. Local and Global References
5.1. Local and Global References5.1.1. Local References5.1.2. Global References5.1.3. Weak Global References5.1.4. Comparing References5.2. Freeing References5.2.1. Freeing Local References5.2.2. Managing Local References in Java 2 SDK Release 1.25.2.3. Freeing Global References5.3. Rules for Managing References
6. Exceptions
6.1. Overview6.1.1. Caching and Throwing Exceptions in Native Code6.1.2. A Utility Function6.2. Proper Exception Handling6.2.1. Checking for Exceptions6.2.2. Handling Exceptions6.2.3. Exceptions in Utility Functions

7. The Invocation Interface
7.1. Creating the Java Virtual Machine7.2. Linking Native Applications with the Java Virtual Machine7.2.1. Linking with a Known Java Virtual Machine7.2.2. Linking with Unknown Java Virtual Machines7.3. Attaching Native Threads
8. Additional JNI Features
8.1. JNI and Threads8.1.1. Constraints8.1.2. Monitor Entry and Exit8.1.3. Monitor Wait and Notify8.1.4. Obtaining a JNIEnv Pointer in Arbitrary Contexts8.1.5. Matching the Thread Models8.2. Writing Internationalized Code8.2.1. Creating jstrings from Native Strings8.2.2. Translating jstrings to Native Strings8.3. Registering Native Methods8.4. Load and Unload Handlers8.4.1. The JNI_OnLoad Handler8.4.2. The JNI_OnUnload Handler8.5. Reflection Support8.6. JNI Programming in C++
9. Leveraging Existing Native Libraries
9.1. One-to-One Mapping9.2. Shared Stubs9.3. One-to-One Mapping versus Shared Stubs9.4. Implementation of Shared Stubs9.4.1. The CPointer Class9.4.2. The CMalloc Class9.4.3. The CFunction Class9.5. Peer Classes9.5.1. Peer Classes in the Java Platform9.5.2. Freeing Native Data Structures9.5.3. Backpointers to Peer Instances
10. Traps and Pitfalls
10.1. Error Checking10.2. Passing Invalid Arguments to JNI Functions10.3. Confusing jclass with jobject10.4. Truncating jboolean Arguments10.5. Boundaries between Java Application and Native Code10.6. Confusing IDs with References10.7. Caching Field and Method IDs10.8. Terminating Unicode Strings10.9. Violating Access Control Rules10.10. Disregarding Internationalization10.11. Retaining Virtual Machine Resources10.12. Excessive Local Reference Creation10.13. Using Invalid Local References10.14. Using the JNIEnv across Threads10.15. Mismatched Thread Models
III. Specification
11. Overview of the JNI Design
11.1. Design Goals11.2. Loading Native Libraries11.2.1. Class Loaders11.2.2. Class Loaders and Native Libraries11.2.3. Locating Native Libraries11.2.4. A Type Safety Restriction11.2.5. Unloading Native Libraries11.3. Linking Native Methods11.4. Calling Conventions11.5. The JNIEnv Interface Pointer11.5.1. Organization of the JNIEnv Interface Pointer11.5.2. Benefits of an Interface Pointer11.6. Passing Data11.6.1. Global and Local References11.6.2. Implementing Local References11.6.3. Weak Global References11.7. Accessing Objects11.7.1. Accessing Primitive Arrays11.7.2. Fields and Methods11.8. Errors and Exceptions11.8.1. No Checking for Programming Errors11.8.2. Java Virtual Machine Exceptions11.8.3. Asynchronous Exceptions
12. JNI Types
12.1. Primitive and Reference Types12.1.1. Primitive Types12.1.2. Reference Types12.1.3. The jvalue Type12.2. Field and Method IDs12.3. String Formats12.3.1. UTF-8 Strings12.3.2. Class Descriptors12.3.3. Field Descriptors12.3.4. Method Descriptors12.4. Constants
13. JNI Functions
13.1. Summary of the JNI Functions13.1.1. Directly-Exported Invocation Interface Functions13.1.2. The JavaVM Interface13.1.3. Functions Defined in Native Libraries13.1.4. The JNIEnv InterfaceVersion InformationClass and Interface OperationsExceptionsGlobal and Local ReferencesObject OperationsInstance Field AccessStatic Field AccessInstance Method CallsStatic Method CallsString OperationsArray OperationsNative Method RegistrationMonitor OperationsJavaVM InterfaceReflection Support13.2. Specification of JNI FunctionsAllocObjectPrototypeDescriptionLinkageParametersReturn ValuesExceptionsAttachCurrentThreadPrototypeDescriptionLinkageParametersReturn ValuesExceptionsCall<Type>MethodPrototypeFormsDescriptionLinkageParametersReturn ValuesExceptionsCall<Type>MethodAPrototypeFormsDescriptionLinkageParametersReturn ValuesExceptionsCall<Type>MethodVPrototypeFormsDescriptionLinkageParametersReturn ValuesExceptionsCallNonvirtual<Type>MethodPrototypeFormsDescriptionsLinkageParametersReturn ValuesExceptionsCallNonvirtual<Type>MethodAPrototypeFormsDescriptionLinkageParametersReturn ValuesExceptionsCallNonvirtual<Type>MethodVPrototypeFormsDescriptionLinkageParametersReturn ValuesExceptionsCallStatic<Type>MethodPrototypeFormsDescriptionLinkageParametersReturn ValuesExceptionsCallStatic<Type>MethodAPrototypeFormsDescriptionLinkageParametersReturn ValuesExceptionsCallStatic<Type>MethodVPrototypeFormsDescriptionLinkageParametersReturn ValuesExceptionsDefineClassPrototypeDescriptionLinkageParametersReturn ValuesExceptionsDeleteGlobalRefPrototypeDescriptionLinkageParametersExceptionsDeleteLocalRefPrototypeDescriptionLinkageParametersExceptionsDeleteWeakGlobalRefPrototypeDescriptionLinkageParametersExceptionsDestroyJavaVMPrototypeDescriptionLinkageParametersReturn ValuesExceptionsDetachCurrentThreadPrototypeDescriptionLinkageParametersReturn ValuesExceptionsEnsureLocalCapacityPrototypeDescriptionLinkageParametersReturn ValuesExceptionsExceptionCheckPrototypeDescriptionLinkageParametersReturn ValuesExceptionsExceptionClearPrototypeDescriptionLinkageParametersExceptionsExceptionDescribePrototypeDescriptionLinkageParametersExceptionsExceptionOccurredPrototypeDescriptionLinkageParametersReturn ValuesExceptionsFatalErrorPrototypeDescriptionLinkageParametersExceptionsFindClassPrototypeDescriptionLinkageParametersReturn ValuesExceptionsFromReflectedFieldPrototypeDescriptionLinkageParametersReturn ValuesExceptionsFromReflectedMethodPrototypeDescriptionLinkageParametersReturn ValuesExceptionsGetArrayLengthPrototypeDescriptionLinkageParametersReturn ValuesExceptionsGet<Type>ArrayElementsPrototypeFormsDescriptionLinkageParametersReturn ValuesExceptionsGet<Type>ArrayRegionPrototypeFormsDescriptionLinkageParametersExceptionsGet<Type>FieldPrototypeFormsDescriptionLinkageParametersReturn ValuesExceptionsGetEnvPrototypeDescriptionLinkageParametersReturn ValuesExceptionsGetFieldIDPrototypeDescriptionLinkageParametersReturn ValuesExceptionsGetJavaVMPrototypeDescriptionLinkageParametersReturn ValuesExceptionsGetMethodIDPrototypeDescriptionLinkageParametersReturn ValuesExceptionsGetObjectArrayElementPrototypeDescriptionLinkageParametersReturn ValuesExceptionsGetObjectClassPrototypeDescriptionLinkageParametersReturn ValuesExceptionsGetPrimitiveArrayCriticalPrototypeDescriptionLinkageParametersReturn ValuesExceptionsGetStaticFieldIDPrototypeDescriptionLinkageParametersReturn ValuesExceptionsGetStatic<Type>FieldPrototypeFormsDescriptionLinkageParametersReturn ValuesExceptionsGetStaticMethodIDPrototypeDescriptionLinkageParametersReturn ValuesExceptionsGetStringCharsPrototypeDescriptionLinkageParametersReturn ValuesExceptionsGetStringCriticalPrototypeDescriptionLinkageParametersReturn ValuesExceptionsGetStringLengthPrototypeDescriptionLinkageParametersReturn ValuesExceptionsGetStringRegionPrototypeDescriptionLinkageParametersExceptionsGetStringUTFCharsPrototypeDescriptionLinkageParametersReturn ValuesExceptionsGetStringUTFLengthPrototypeDescriptionLinkageParametersReturn ValuesExceptionsGetStringUTFRegionPrototypeDescriptionLinkageParametersExceptionsGetSuperclassPrototypeDescriptionLinkageParametersReturn ValuesExceptionsGetVersionPrototypeDescriptionLinkageParametersReturn ValuesExceptionsIsAssignableFromPrototypeDescriptionLinkageParametersReturn ValuesExceptionsIsInstanceOfPrototypeDescriptionLinkageParametersReturn ValuesExceptionsIsSameObjectPrototypeDescriptionLinkageParametersReturn ValuesExceptionsJNI_CreateJavaVMPrototypeDescriptionLinkageParametersReturn ValuesExceptionsJNI_GetCreatedJavaVMsPrototypeDescriptionLinkageParametersReturn ValuesExceptionsJNI_GetDefaultJavaVMInitArgsPrototypeDescriptionLinkageParametersReturn ValuesExceptionsJNI_OnLoadPrototypeDescriptionLinkageParametersReturn ValuesExceptionsJNI_OnUnloadPrototypeDescriptionLinkageParametersExceptionsMonitorEnterPrototypeDescriptionLinkageParametersReturn ValuesExceptionsMonitorExitPrototypeDescriptionLinkageParametersReturn ValuesExceptionsNewGlobalRefPrototypeDescriptionLinkageParametersReturn ValuesExceptionsNewLocalRefPrototypeDescriptionLinkageParametersReturn ValuesExceptionsNewObjectPrototypeDescriptionLinkageParametersReturn ValuesExceptionsNewObjectAPrototypeDescriptionLinkageParametersReturn ValuesExceptionsNewObjectVPrototypeDescriptionLinkageParametersReturn ValuesExceptionsNewObjectArrayPrototypeDescriptionLinkageParametersReturn ValuesExceptionsNew<Type>ArrayPrototypeFormsDescriptionLinkageParametersReturn ValuesExceptionsNewStringPrototypeDescriptionLinkageParametersReturn ValuesExceptionsNewStringUTFPrototypeDescriptionLinkageParametersReturn ValuesExceptionsNewWeakGlobalRefPrototypeDescriptionLinkageParametersReturn ValuesExceptionsPopLocalFramePrototypeDescriptionLinkageParametersReturn ValuesExceptionsPushLocalFramePrototypeDescriptionLinkageParametersReturn ValuesExceptionsRegisterNativesPrototypeDescriptionLinkageParametersReturn ValuesExceptionsRelease<Type>ArrayElementsPrototypeFormsDescriptionLinkageParametersExceptionsReleasePrimitiveArrayCriticalPrototypeDescriptionLinkageParametersExceptionsReleaseStringCharsPrototypeDescriptionLinkageParametersExceptionsReleaseStringCriticalPrototypeDescriptionLinkageParametersExceptionsReleaseStringUTFCharsPrototypeDescriptionLinkageParametersExceptionsSet<Type>ArrayRegionPrototypeFormsDescriptionLinkageParametersExceptionsSet<Type>FieldPrototypeFormsDescriptionLinkageParametersExceptionsSetObjectArrayElementPrototypeDescriptionLinkageParametersExceptionsSetStatic<Type>FieldPrototypeFormsDescriptionLinkageParametersExceptionsThrowPrototypeDescriptionLinkageParametersReturn ValuesExceptionsThrowNewPrototypeDescriptionLinkageParametersReturn ValuesExceptionsToReflectedFieldPrototypeDescriptionLinkageParametersReturn ValuesExceptionsToReflectedMethodPrototypeDescriptionLinkageParametersReturn ValuesExceptionsUnregisterNativesPrototypeDescriptionLinkageParametersReturn ValuesExceptions

Content preview from Java™ Native Interface: Programmer’s Guide and Specification, The

Chapter 6. Exceptions

We have encountered numerous situations in which native code checks for possible errors after making JNI function calls. This chapter examines how native code can detect and recover from these error conditions.

We will focus on errors that occur as the result of issuing JNI function calls, not arbitrary errors that happen in native code. If a native method makes an operating systems call, it simply follows the documented way of checking for possible failures in the system call. If, on the other hand, the native method issues a callback to a Java API method, then it must follow the steps described in this chapter to properly check for and recover from possible exceptions that have occurred in the method execution.

Overview

Become an O’Reilly member and get unlimited access to this title plus top books and audiobooks from O’Reilly and nearly 200 top publishers, thousands of courses curated by job role, 150+ live events each month,
and much more.

Read now

Unlock full access

More than 5,000 organizations count on O’Reilly

O’Reilly covers everything we've got, with content to help us build a world-class technology community, upgrade the capabilities and competencies of our teams, and improve overall team performance as well as their engagement.

Julian F.

Head of Cybersecurity

I wanted to learn C and C++, but it didn't click for me until I picked up an O'Reilly book. When I went on the O’Reilly platform, I was astonished to find all the books there, plus live events and sandboxes so you could play around with the technology.

Addison B.

Field Engineer

I’ve been on the O’Reilly platform for more than eight years. I use a couple of learning platforms, but I'm on O'Reilly more than anybody else. When you're there, you start learning. I'm never disappointed.

Amir M.

Data Platform Tech Lead

I'm always learning. So when I got on to O'Reilly, I was like a kid in a candy store. There are playlists. There are answers. There's on-demand training. It's worth its weight in gold, in terms of what it allows me to do.

Mark W.

Embedded Software Engineer

Android NDK Beginner`s Guide - Second Edition

Publisher Resources

ISBN: 0201325772Purchase book

Cloud Computing

Data Engineering

Data Science

AI & ML

Programming Languages

Software Architecture

IT/Ops

Security

Design

Business

Soft Skills

Java™ Native Interface: Programmer’s Guide and Specification, The

by Sheng Liang

Chapter 6. Exceptions

Overview

Become an O’Reilly member and get unlimited access to this title plus top books and audiobooks from O’Reilly and nearly 200 top publishers, thousands of courses curated by job role, 150+ live events each month,
and much more.