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

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

by Sheng Liang
Released June 1999
Publisher(s): Addison-Wesley Professional
ISBN: 0201325772

Read it now on the O’Reilly learning platform with a 10-day free trial.

O’Reilly members get unlimited access to books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.

Start your free trial

Book description

The Java Native Interface (JNI) enables the integration of code written in the Java programming language with code written in other languages such as C and C++. It allows programmers to take full advantage of the Java platform without having to abandon their investment in legacy code.

This book is the definitive resource and a comprehensive guide to working with the JNI. Entirely up-to-date, the book offers a tutorial, a detailed description of JNI features and programming techniques, JNI design justifications, and the official specification for all JNI types and functions.

You will find coverage of important topics such as:

  • Writing native methods

  • Passing data types between the Java language and native programming languages

  • Embedding a Java virtual machine implementation in native applications

  • Leveraging legacy native libraries

  • Improving the efficiency and reliability of your code

    • An entire chapter is devoted to avoiding common traps and pitfalls. The book uses numerous examples to illustrate programming techniques that have proven to be effective.



    0201325772B04062001

    Table of contents

    1. Copyright
      1. Dedication
    2. Preface
    3. I. Introduction and Tutorial
      1. 1. Introduction
        1. 1.1. The Java Platform and Host Environment
        2. 1.2. Role of the JNI
        3. 1.3. Implications of Using the JNI
        4. 1.4. When to Use the JNI
        5. 1.5. Evolution of the JNI
        6. 1.6. Example Programs
      2. 2. Getting Started
        1. 2.1. Overview
        2. 2.2. Declare the Native Method
        3. 2.3. Compile the HelloWorld Class
        4. 2.4. Create the Native Method Header File
        5. 2.5. Write the Native Method Implementation
        6. 2.6. Compile the C Source and Create a Native Library
        7. 2.7. Run the Program
    4. II. Programmer’s Guide
      1. 3. Basic Types, Strings, and Arrays
        1. 3.1. A Simple Native Method
          1. 3.1.1. C Prototype for Implementing the Native Method
          2. 3.1.2. Native Method Arguments
          3. 3.1.3. Mapping of Types
        2. 3.2. Accessing Strings
          1. 3.2.1. Converting to Native Strings
          2. 3.2.2. Freeing Native String Resources
          3. 3.2.3. Constructing New Strings
          4. 3.2.4. Other JNI String Functions
          5. 3.2.5. New JNI String Functions in Java 2 SDK Release 1.2
          6. 3.2.6. Summary of JNI String Functions
          7. 3.2.7. Choosing among the String Functions
        3. 3.3. Accessing Arrays
          1. 3.3.1. Accessing Arrays in C
          2. 3.3.2. Accessing Arrays of Primitive Types
          3. 3.3.3. Summary of JNI Primitive Array Functions
          4. 3.3.4. Choosing among the Primitive Array Functions
          5. 3.3.5. Accessing Arrays of Objects
      2. 4. Fields and Methods
        1. 4.1. Accessing Fields
          1. 4.1.1. Procedure for Accessing an Instance Field
          2. 4.1.2. Field Descriptors
          3. 4.1.3. Accessing Static Fields
        2. 4.2. Calling Methods
          1. 4.2.1. Calling Instance Methods
          2. 4.2.2. Forming the Method Descriptor
          3. 4.2.3. Calling Static Methods
          4. 4.2.4. Calling Instance Methods of a Superclass
        3. 4.3. Invoking Constructors
        4. 4.4. Caching Field and Method IDs
          1. 4.4.1. Caching at the Point of Use
          2. 4.4.2. Caching in the Defining Class’s Initializer
          3. 4.4.3. Comparison between the Two Approaches to Caching IDs
        5. 4.5. Performance of JNI Field and Method Operations
      3. 5. Local and Global References
        1. 5.1. Local and Global References
          1. 5.1.1. Local References
          2. 5.1.2. Global References
          3. 5.1.3. Weak Global References
          4. 5.1.4. Comparing References
        2. 5.2. Freeing References
          1. 5.2.1. Freeing Local References
          2. 5.2.2. Managing Local References in Java 2 SDK Release 1.2
          3. 5.2.3. Freeing Global References
        3. 5.3. Rules for Managing References
      4. 6. Exceptions
        1. 6.1. Overview
          1. 6.1.1. Caching and Throwing Exceptions in Native Code
          2. 6.1.2. A Utility Function
        2. 6.2. Proper Exception Handling
          1. 6.2.1. Checking for Exceptions
          2. 6.2.2. Handling Exceptions
          3. 6.2.3. Exceptions in Utility Functions
      5. 7. The Invocation Interface
        1. 7.1. Creating the Java Virtual Machine
        2. 7.2. Linking Native Applications with the Java Virtual Machine
          1. 7.2.1. Linking with a Known Java Virtual Machine
          2. 7.2.2. Linking with Unknown Java Virtual Machines
        3. 7.3. Attaching Native Threads
      6. 8. Additional JNI Features
        1. 8.1. JNI and Threads
          1. 8.1.1. Constraints
          2. 8.1.2. Monitor Entry and Exit
          3. 8.1.3. Monitor Wait and Notify
          4. 8.1.4. Obtaining a JNIEnv Pointer in Arbitrary Contexts
          5. 8.1.5. Matching the Thread Models
        2. 8.2. Writing Internationalized Code
          1. 8.2.1. Creating jstrings from Native Strings
          2. 8.2.2. Translating jstrings to Native Strings
        3. 8.3. Registering Native Methods
        4. 8.4. Load and Unload Handlers
          1. 8.4.1. The JNI_OnLoad Handler
          2. 8.4.2. The JNI_OnUnload Handler
        5. 8.5. Reflection Support
        6. 8.6. JNI Programming in C++
      7. 9. Leveraging Existing Native Libraries
        1. 9.1. One-to-One Mapping
        2. 9.2. Shared Stubs
        3. 9.3. One-to-One Mapping versus Shared Stubs
        4. 9.4. Implementation of Shared Stubs
          1. 9.4.1. The CPointer Class
          2. 9.4.2. The CMalloc Class
          3. 9.4.3. The CFunction Class
        5. 9.5. Peer Classes
          1. 9.5.1. Peer Classes in the Java Platform
          2. 9.5.2. Freeing Native Data Structures
          3. 9.5.3. Backpointers to Peer Instances
      8. 10. Traps and Pitfalls
        1. 10.1. Error Checking
        2. 10.2. Passing Invalid Arguments to JNI Functions
        3. 10.3. Confusing jclass with jobject
        4. 10.4. Truncating jboolean Arguments
        5. 10.5. Boundaries between Java Application and Native Code
        6. 10.6. Confusing IDs with References
        7. 10.7. Caching Field and Method IDs
        8. 10.8. Terminating Unicode Strings
        9. 10.9. Violating Access Control Rules
        10. 10.10. Disregarding Internationalization
        11. 10.11. Retaining Virtual Machine Resources
        12. 10.12. Excessive Local Reference Creation
        13. 10.13. Using Invalid Local References
        14. 10.14. Using the JNIEnv across Threads
        15. 10.15. Mismatched Thread Models
    5. III. Specification
      1. 11. Overview of the JNI Design
        1. 11.1. Design Goals
        2. 11.2. Loading Native Libraries
          1. 11.2.1. Class Loaders
          2. 11.2.2. Class Loaders and Native Libraries
          3. 11.2.3. Locating Native Libraries
          4. 11.2.4. A Type Safety Restriction
          5. 11.2.5. Unloading Native Libraries
        3. 11.3. Linking Native Methods
        4. 11.4. Calling Conventions
        5. 11.5. The JNIEnv Interface Pointer
          1. 11.5.1. Organization of the JNIEnv Interface Pointer
          2. 11.5.2. Benefits of an Interface Pointer
        6. 11.6. Passing Data
          1. 11.6.1. Global and Local References
          2. 11.6.2. Implementing Local References
          3. 11.6.3. Weak Global References
        7. 11.7. Accessing Objects
          1. 11.7.1. Accessing Primitive Arrays
          2. 11.7.2. Fields and Methods
        8. 11.8. Errors and Exceptions
          1. 11.8.1. No Checking for Programming Errors
          2. 11.8.2. Java Virtual Machine Exceptions
          3. 11.8.3. Asynchronous Exceptions
      2. 12. JNI Types
        1. 12.1. Primitive and Reference Types
          1. 12.1.1. Primitive Types
          2. 12.1.2. Reference Types
          3. 12.1.3. The jvalue Type
        2. 12.2. Field and Method IDs
        3. 12.3. String Formats
          1. 12.3.1. UTF-8 Strings
          2. 12.3.2. Class Descriptors
          3. 12.3.3. Field Descriptors
          4. 12.3.4. Method Descriptors
        4. 12.4. Constants
      3. 13. JNI Functions
        1. 13.1. Summary of the JNI Functions
          1. 13.1.1. Directly-Exported Invocation Interface Functions
          2. 13.1.2. The JavaVM Interface
          3. 13.1.3. Functions Defined in Native Libraries
          4. 13.1.4. The JNIEnv Interface
          5. Version Information
          6. Class and Interface Operations
          7. Exceptions
          8. Global and Local References
          9. Object Operations
          10. Instance Field Access
          11. Static Field Access
          12. Instance Method Calls
          13. Static Method Calls
          14. String Operations
          15. Array Operations
          16. Native Method Registration
          17. Monitor Operations
          18. JavaVM Interface
          19. Reflection Support
        2. 13.2. Specification of JNI Functions
          1. AllocObject
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          2. AttachCurrentThread
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          3. Call<Type>Method
            1. Prototype
            2. Forms
            3. Description
            4. Linkage
            5. Parameters
            6. Return Values
            7. Exceptions
          4. Call<Type>MethodA
            1. Prototype
            2. Forms
            3. Description
            4. Linkage
            5. Parameters
            6. Return Values
            7. Exceptions
          5. Call<Type>MethodV
            1. Prototype
            2. Forms
            3. Description
            4. Linkage
            5. Parameters
            6. Return Values
            7. Exceptions
          6. CallNonvirtual<Type>Method
            1. Prototype
            2. Forms
            3. Descriptions
            4. Linkage
            5. Parameters
            6. Return Values
            7. Exceptions
          7. CallNonvirtual<Type>MethodA
            1. Prototype
            2. Forms
            3. Description
            4. Linkage
            5. Parameters
            6. Return Values
            7. Exceptions
          8. CallNonvirtual<Type>MethodV
            1. Prototype
            2. Forms
            3. Description
            4. Linkage
            5. Parameters
            6. Return Values
            7. Exceptions
          9. CallStatic<Type>Method
            1. Prototype
            2. Forms
            3. Description
            4. Linkage
            5. Parameters
            6. Return Values
            7. Exceptions
          10. CallStatic<Type>MethodA
            1. Prototype
            2. Forms
            3. Description
            4. Linkage
            5. Parameters
            6. Return Values
            7. Exceptions
          11. CallStatic<Type>MethodV
            1. Prototype
            2. Forms
            3. Description
            4. Linkage
            5. Parameters
            6. Return Values
            7. Exceptions
          12. DefineClass
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          13. DeleteGlobalRef
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Exceptions
          14. DeleteLocalRef
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Exceptions
          15. DeleteWeakGlobalRef
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Exceptions
          16. DestroyJavaVM
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          17. DetachCurrentThread
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          18. EnsureLocalCapacity
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          19. ExceptionCheck
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          20. ExceptionClear
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Exceptions
          21. ExceptionDescribe
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Exceptions
          22. ExceptionOccurred
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          23. FatalError
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Exceptions
          24. FindClass
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          25. FromReflectedField
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          26. FromReflectedMethod
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          27. GetArrayLength
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          28. Get<Type>ArrayElements
            1. Prototype
            2. Forms
            3. Description
            4. Linkage
            5. Parameters
            6. Return Values
            7. Exceptions
          29. Get<Type>ArrayRegion
            1. Prototype
            2. Forms
            3. Description
            4. Linkage
            5. Parameters
            6. Exceptions
          30. Get<Type>Field
            1. Prototype
            2. Forms
            3. Description
            4. Linkage
            5. Parameters
            6. Return Values
            7. Exceptions
          31. GetEnv
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          32. GetFieldID
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          33. GetJavaVM
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          34. GetMethodID
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          35. GetObjectArrayElement
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          36. GetObjectClass
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          37. GetPrimitiveArrayCritical
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          38. GetStaticFieldID
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          39. GetStatic<Type>Field
            1. Prototype
            2. Forms
            3. Description
            4. Linkage
            5. Parameters
            6. Return Values
            7. Exceptions
          40. GetStaticMethodID
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          41. GetStringChars
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          42. GetStringCritical
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          43. GetStringLength
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          44. GetStringRegion
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Exceptions
          45. GetStringUTFChars
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          46. GetStringUTFLength
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          47. GetStringUTFRegion
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Exceptions
          48. GetSuperclass
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          49. GetVersion
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          50. IsAssignableFrom
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          51. IsInstanceOf
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          52. IsSameObject
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          53. JNI_CreateJavaVM
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          54. JNI_GetCreatedJavaVMs
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          55. JNI_GetDefaultJavaVMInitArgs
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          56. JNI_OnLoad
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          57. JNI_OnUnload
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Exceptions
          58. MonitorEnter
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          59. MonitorExit
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          60. NewGlobalRef
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          61. NewLocalRef
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          62. NewObject
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          63. NewObjectA
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          64. NewObjectV
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          65. NewObjectArray
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          66. New<Type>Array
            1. Prototype
            2. Forms
            3. Description
            4. Linkage
            5. Parameters
            6. Return Values
            7. Exceptions
          67. NewString
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          68. NewStringUTF
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          69. NewWeakGlobalRef
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          70. PopLocalFrame
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          71. PushLocalFrame
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          72. RegisterNatives
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          73. Release<Type>ArrayElements
            1. Prototype
            2. Forms
            3. Description
            4. Linkage
            5. Parameters
            6. Exceptions
          74. ReleasePrimitiveArrayCritical
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Exceptions
          75. ReleaseStringChars
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Exceptions
          76. ReleaseStringCritical
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Exceptions
          77. ReleaseStringUTFChars
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Exceptions
          78. Set<Type>ArrayRegion
            1. Prototype
            2. Forms
            3. Description
            4. Linkage
            5. Parameters
            6. Exceptions
          79. Set<Type>Field
            1. Prototype
            2. Forms
            3. Description
            4. Linkage
            5. Parameters
            6. Exceptions
          80. SetObjectArrayElement
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Exceptions
          81. SetStatic<Type>Field
            1. Prototype
            2. Forms
            3. Description
            4. Linkage
            5. Parameters
            6. Exceptions
          82. Throw
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          83. ThrowNew
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          84. ToReflectedField
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          85. ToReflectedMethod
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions
          86. UnregisterNatives
            1. Prototype
            2. Description
            3. Linkage
            4. Parameters
            5. Return Values
            6. Exceptions

    Product information

    • Title: Java™ Native Interface: Programmer’s Guide and Specification, The
    • Author(s): Sheng Liang
    • Release date: June 1999
    • Publisher(s): Addison-Wesley Professional
    • ISBN: 0201325772