Интерфейс JNI: руководство по программированию

Интерфейс JNI

Руководство по программированию

Шенг Лиэнг

ADDISON-WESLEY
An imprint of Addison Wesley Longman, Inc.
Reading, Massachusetts • Harlow, England • Menlo Park, California
Berkeley, California • Don Mills, Ontario • Sydney
Bonn • Amsterdam • Tokyo • Mexico City

The JavaTM Native 
Interface

Programmer's Guide and Specification

Sheng Liang

Интерфейс JNI

Руководство по программированию

Москва, 2014

Шенг Лиэнг

УДК 004.6
ББК 32.973.26
 
Л55

 
 
Лиэнг Ш.

Л55 Интерфейс JNI: руководство по программированию / пер. с анг. 

Таловой И. – М.: ДМК Пресс, 2014. – 280 с.: ил. 

ISBN 978-5-94074-982-0

В книге описывается интерфейс Java Native Interface (JNI) – ин
терфейс взаимодействия языка Java с нативным кодом, написанным 
на других языках. Она будет полезна программистам на Java, интересующимися вопросами интеграции кода, написанного на C и С++, 
в Java-приложение; внедрением виртуальной машины Java в С- и С++приложения; реализация виртуальной машины Java; техническими 
вопросами организации взаимодействия между различными языками, 
в том числе имеющими отношение к работе со сборщиком мусора  

Издание предназначено разработчикам на языке Java различной 

квалификации, желающими использовать в своих программах всю 
мощь нативного кода, написанного на других языках.

 
УДК  004.6

 
ББК 32.973.26

Все права защищены. Любая часть этой книги не может быть воспроиз
ведена в какой бы то ни было форме и какими бы то ни было средствами без 
письменного разрешения владельцев авторских прав.

Материал, изложенный в данной книге, многократно проверен. Но по
скольку вероятность технических ошибок все равно существует, издательство 
не может гарантировать абсолютную точность и правильность приводимых 
сведений. В связи с этим издательство не несет ответственности за возможные 
ошибки, связанные с использованием книги.

ISBN 0-201-32577-2 (анг.) 
 ©  Sun Microsystems, Inc.

ISBN 978-5-94074-982-0 (рус.) 
©  Оформление, перевод, 

 
 
ДМК Пресс, 2014

и многопоточности.

Содержание

Предисловие..................................................................................................10

Часть I. Введение и учебный материал ..................................13

Глава 1. Введение ......................................................................................14
1.1. Платформа Java и вычислительная среда ...........................................15
1.2. Роль интерфейса JNI ..................................................................................16
1.3. Последствия использования интерфейса JNI ...................................17
1.4. Случаи использования интерфейса JNI ..............................................18
1.5. Развитие интерфейса JNI .........................................................................19
1.6. Примеры программ .....................................................................................21

Глава 2. Приступая к работе .............................................................22
2.1. Общее представление ................................................................................22
2.2. Объявление native-метода........................................................................24
2.3. Компиляция класса HelloWorld .............................................................25
2.4. Создание файла заголовков .....................................................................25
2.5. Написание кода native-метода ................................................................26
2.6. Компиляция исходного кода на языке С и создание 
native-библиотеки  ......................................................................................26
2.7. Запуск программы ......................................................................................27

Часть II. Справочное пособие 
по программированию ..........................................................................29

Глава 3. Основные типы, строки и массивы .......................30
3.1. Простой native-метод .................................................................................30
3.1.1. Прототип С-функции, реализующей native-метод ...............31
3.1.2. Аргументы native-метода ...............................................................31
3.1.3. Соответствие типов..........................................................................32
3.2. Обращение к строкам .................................................................................33
3.2.1. Преобразование к native-строкам ...............................................33
3.2.2. Освобождение ресурсов native-строк ........................................35
3.2.3. Создание новых строк .....................................................................35
3.2.4. Другие функции JNI для работы со строками ........................35
3.2.5. Новые JNI-функции для работы со строками 
в Java 2 SDK 1.2 ............................................................................................37

 Содержание

3.2.6. Перечень JNI-функций для работы со строками ...................39
3.2.7. Выбор между функциями строк ..................................................40
3.3. Обращение к массивам ..............................................................................43
3.3.1. Обращение к массивам в языке С ...............................................43
3.3.2. Обращение к массивам простых типов .....................................44
3.3.3. Перечень JNI-функций для работы с примитивными 
массивами .......................................................................................................45
3.3.4. Выбор между функциями примитивного массива ...............46
3.3.5. Обращение к массивам объектов ................................................48

Глава 4. Поля и методы .........................................................................51
4.1. Обращение к полям ....................................................................................51
4.1.1. Алгоритм обращения к полю объекта .......................................53
4.1.2. Дескрипторы поля ............................................................................53
4.1.3. Обращение к статическим полям   .............................................54
4.2. Вызов методов ..............................................................................................56
4.2.1. Вызов методов объекта ...................................................................57
4.2.2. Формирование дескриптора метода  .........................................58
4.2.3. Обращение к статическим методам ...........................................59
4.2.4. Вызов методов суперкласса ..........................................................60

4.3. Вызов конструкторов .................................................................................61
4.4. Кэширование полей и идентификаторов методов ...........................63
4.4.1. Кэширование во время использования .....................................63
4.4.2. Кэширование в блоке статической инициализации 
класса ...............................................................................................................66
4.4.3. Сравнение двух способов кэширования 
идентификаторов .........................................................................................67
4.5. Эффективность использования JNI при обращении к полям 
и методам ........................................................................................................68

Глава 5. Локальные и глобальные ссылки  ...........................71
5.1. Локальные и глобальные ссылки...........................................................72
5.1.1. Локальные ссылки ...........................................................................72
5.1.2. Глобальные ссылки ..........................................................................74
5.1.3. Слабые глобальные ссылки ..........................................................75
5.1.4. Сравнительный анализ  ..................................................................76
5.2. Освобождение ссылок ...............................................................................77
5.2.1. Освобождение локальных ссылок ..............................................77
5.2.2. Управление локальными ссылками в Java 2 SDK 1.2 ..........79

Содержание  7

5.2.3. Освобождение глобальных ссылок ............................................80
5.3. Правила управления ссылками ..............................................................81

Глава 6. Исключения ...............................................................................85
6.1. Общее представление ................................................................................85

6.1.1. Кэширование и вызов исключений в native-коде .................85
6.1.2. Вспомогательные функции ...........................................................87
6.2. Правильная обработка исключений .....................................................88
6.2.1. Проверка исключений ....................................................................88
6.2.2. Обработка исключений ..................................................................90
6.2.3. Исключения во вспомогательных функциях .........................91

Глава 7. Интерфейс вызова  .............................................................95
7.1. Создание виртуальной машины Java ...................................................95
7.2. Компоновка native-приложений с виртуальной машиной 
Java  ...................................................................................................................98
7.2.1. Компоновка с определенной виртуальной машиной 
Java ....................................................................................................................98
7.2.2. Компоновка с неизвестными виртуальными 
машинами .......................................................................................................99
7.3. Подключение native-потоков  .............................................................. 101

Глава 8. Дополнительные функции 
интерфейса JNI ......................................................................................... 105
8.1. Интерфейс JNI и потоки ........................................................................ 105
8.1.1. Ограничения ................................................................................... 105
8.1.2. Вход и выход из монитора .......................................................... 106
8.1.3. Реализация методов wait и notify в интерфейсе JNI ......... 108
8.1.4. Получение указателя JNIEnv в произвольных 
контекстах ................................................................................................... 109
8.1.5. Соответствие с моделями потоков .......................................... 110
8.2. Написание кода с многоязычной поддержкой ............................... 112
8.2.1. Создание jstrings из native-строк ............................................. 112
8.2.2. Преобразование jstrings в native-строки ............................... 113
8.3. Регистрация native-методов ................................................................. 114
8.4. Обработчики загрузки и выгрузки библиотеки ............................ 115
8.4.1. Обработчик JNI_OnLoad ............................................................ 115
8.4.2. Обработчик JNI_OnUnload ....................................................... 117
8.5. Поддержка отражения ............................................................................ 118
8.6. JNI-программирование в языке C++ ................................................. 119

 Содержание

Глава 9. Использование существующих 
native-библиотек ..................................................................................... 121
9.1. Преобразование «один к одному»  ..................................................... 122
9.2. Общие заглушки ....................................................................................... 125
9.3. Сравнение методов создания оболочек для native-функций  ....... 129
9.4. Реализация общих заглушек    ............................................................. 130
9.4.1. Класс CPointer ................................................................................ 130
9.4.2. Класс CMalloc ................................................................................. 130
9.4.3. Класс CFunction ............................................................................. 131
9.5. Peer-классы ................................................................................................. 136
9.5.1. Применение peer-классов в Java-платформе ....................... 137
9.5.2. Освобождение памяти native-структур ................................. 138
9.5.3. Обратные указатели на peer-объекты ..................................... 140

Глава 10. Проблемные и слабые места ............................... 145
10.1. Проверка ошибок ................................................................................... 145
10.2. Передача недействительных аргументов JNI-функциям ........ 145
10.3. Отличие jclass от jobject ....................................................................... 146
10.4. Приведение аргументов к типу jboolean ........................................ 146
10.5. Границы между Java-приложением и native-кодом ................... 147
10.6. Отличие идентификаторов от ссылок ............................................ 149
10.7. Кэширование идентификаторов полей и методов ..................... 150
10.8. Окончания строк Unicode   ................................................................. 152
10.9. Нарушение правил управления доступом .................................... 152
10.10. Игнорирование многоязычной поддержки ................................ 153
10.11. Сохранение ресурсов виртуальной машины .............................. 154
10.12. Чрезмерное создание локальных ссылок .................................... 155
10.13. Использование недействительных локальных ссылок .......... 156
10.14. Использование указателя JNIEnv в потоках  ............................ 156
10.15. Несоответствие модели потоков .................................................... 156

Часть III. Спецификация .................................................................... 158

Глава 11. Обзор проекта JNI .......................................................... 159
11.1. Цели проекта JNI .................................................................................... 159
11.2. Загрузка native-библиотек .................................................................. 160

11.2.1. Загрузчик классов ....................................................................... 160
11.2.2. Загрузчики классов и native-библиотеки ........................... 162
11.2.3. Поиск native-библиотек ............................................................ 163
11.2.4. Ограничение безопасности типов ......................................... 165

Содержание  9

11.2.5. Выгрузка native-библиотек ...................................................... 166
11.3. Связывание native-методов ................................................................ 166
11.4. Соглашения о вызовах ......................................................................... 168
11.5. Указатель интерфейса JNIEnv ........................................................... 168
11.5.1. Структура интерфейсного указателя JNIEnv ................... 169
11.5.2. Преимущества интерфейсного указателя........................... 170
11.6. Передача данных .................................................................................... 171
11.6.1. Глобальные и локальные ссылки ........................................... 172
11.6.2. Реализация локальных ссылок ............................................... 172
11.6.3. Слабые глобальные ссылки  .................................................... 173
11.7. Обращение к объектам ......................................................................... 173
11.7.1. Обращение к примитивным массивам ................................ 174
11.7.2. Поля и методы  ............................................................................. 176
11.8. Ошибки и исключения ......................................................................... 177
11.8.1. Отсутствие проверок программных ошибок  .................... 178
11.8.2. Исключения виртуальной машины Java ............................. 178
11.8.3. Асинхронные исключения ....................................................... 179

Глава 12. Типы интерфейса JNI  ................................................. 181
12.1. Примитивные и ссылочные типы .................................................... 181
12.1.1. Примитивные типы  ................................................................... 181
12.1.2. Ссылочные типы.......................................................................... 181
12.1.3. Тип jvalue ........................................................................................ 183
12.2. Идентификаторы полей и методов .................................................. 183
12.3. Форматы строк........................................................................................ 183
12.3.1. Строки UTF-8  .............................................................................. 183
12.3.2. Дескрипторы классов ................................................................. 184
12.3.3. Дескрипторы полей .................................................................... 185
12.3.4. Дескрипторы методов ................................................................ 186
12.4. Константы ................................................................................................. 186

Глава 13. Функции интерфейса JNI  ........................................ 188
13.1. Краткий обзор JNI-функций  ............................................................. 188
13.1.1. Непосредственно экспортируемые функции 
интерфейса вызовов ................................................................................ 189
13.1.2. Интерфейс JavaVM .................................................................... 189
13.1.3. Функции в native-библиотеках .............................................. 190
13.1.4. Интерфейс JNIEnv ...................................................................... 190
13.2. Спецификация JNI-функций ............................................................. 196

Алфавитный указатель ...................................................................... 271

Предисловие

В этой книге описывается интерфейс JNI. Она будет полезна тем, кто 
интересуется следующими вопросами:
 
 интеграция кода, написанного на таких языках программирования, как C и С++, в Java-приложение;
 
 внедрение виртуальной машины Java в существующее приложение, написанное на языках программирования С и С++;
 
 реализация виртуальной машины Java;
 
 технические вопросы организации взаимодействия между различными языками, в том числе имеющие отношение к работе 
со сборщиком мусора и многопоточности.
Во-первых, эта книга предназначена для разработчиков. Они 
с легкостью могут найти в ней необходимую информацию о том, как 
начать работу с интерфейсом JNI, подробное описание различных 
JNI-функций, а также получить полезные советы по эффективному 
использованию JNI. Впервые интерфейс JNI появился в 1997 году. 
В этой книге собран двухлетний опыт коллективной работы специалистов компании Sun Microsystems, а также опыт огромного количества разработчиков технологического сообщества Java. 
Во-вторых, в книге приведено обоснование дизайна различных 
JNI-функций. Полное понимание структуры интерфейса не только 
представляет собой интерес для научного сообщества, но также является необходимым условием его эффективного использования.
В-третьих, один из разделов книги посвящен полному описанию 
JNI-спецификации платформы Java 2. Программисты JNI могут использовать информацию из этого раздела в качестве справочного 
пособия. Разработчики виртуальных машин Java обязаны придерживаться данной спецификации.
Комментарии по спецификации или вопросы об интерфейсе JNI 
можно присылать по адресу электронной почты: jni@java.sun.com. 
Чтобы получить последние обновления платформы Java 2 или последней версии Java 2 SDK, посетите наш сайт http://java.sun.com. 
Чтобы получить обновленную информацию о Java™ Series, включая 
список ошибок данного пособия, а также просмотреть перечень книг, 
готовящихся к публикации, посетите сайт http://java.sun.com/Series. 
Результатом переговоров между компанией Sun Microsystems и обладателями лицензий на технологии Java стала разработка интерфейса JNI. Отчасти интерфейс JNI был разработан на основе интерфейса 
Java Runtime Interface (JRI) компании Netscape, созданного Уорреном