Интерфейс 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, созданного Уорреном 

Предисловие  11

Харрисом (Warren Harris). Активное участие в обсуждениях проекта 
принимали представители компаний, занимающихся лицензиями 
Java-технологий, такие как: Расс Арун (Russ Arun), Ян Эллисон (Ian 
Ellison) и Майк Тоутонги-Тейлор (Mike Toutonghi-Taylor) – представители компании Microsoft, Патрик Берд (Patrick Beard) – представитель компании Apple, Симон Нэш (Simon Nash) – представитель 
компании IBM, Кен Рут (Ken Root) – представитель компании Intel.
Внутренние исследования компании Sun, проводимые Дэйвом 
Бауэном (Dave Bowen), Джеймсом Гослингом (James Gosling), Питером Кесслером (Peter Kessler), Тимом Линдгольмом (Tim Lindholm), 
Марком Рейнхольдом (Mark Reinhold), Дереком Уайтом (Derek 
White) и Фрэнком Йеллином (Frank Yellin), также принесли большую пользу проекту JNI. Дэйв Браун (Dave Brown), Дэйв Коннелли (Dave Connelly), Джеймс Макилри (James McIlree), Бенжамин 
Ренод (Benjamin Renaud) и Том Родригез (Tom Rodriguez) внесли 
существенный вклад в усовершенствование интерфейса JNI в Java 2 
SDK 1.2. Команда тестировщиков под руководством Карлы Шроер 
(Carla Schroer) в Новосибирске создала тесты на совместимость для 
JNI. В ходе работы группа выявила слабые места, в которых исходная 
спецификация была неточной и неполной. 
Технология JNI не смогла бы развиться и реализоваться без поддержки руководства компании в лице Дэйва Бауэна (Dave Bowen), 
Ларри Абраамса (Larry Abrahams), Дика Нейсса (Dick Neiss), Йона 
Каннегаарда (Jon Kannegaard) и Алана Бараца (Alan Baratz). Я получил полную поддержку и содействие в работе над этой книгой от 
моего руководителя Дэйва Бауэна (Dave Bowen).
В то время когда начиналась разработка интерфейса JNI, Тим 
Линдгольм (Tim Lindholm), автор книги «Спецификация виртуальной машины Java» («The Java™ Virtual Machine Specification»), возглавил работу по развитию виртуальной машины Java. Он занимался 
разработкой виртуальной машины и native-интерфейсов, выступал за 
использование интерфейса JNI и привнес точность и ясность в книгу. Он также представил первоначальный эскиз обложки данного пособия.
Многие коллеги оказали помощь при создании книги. Ананд Паланисуами (Anand Palaniswamy) работал над темой общих системных сбоев и ошибок в одном из разделов 10-й главы. Джанет Коениг (Janet Koenig) внимательно изучала предварительный проект 
и делилась множеством полезных идей. Бэт Стирнс (Beth Stearns) 
написала проект ко 2-й главе, основываясь на учебном онлайн-посо

бии по интерфейсу JNI. Я получил ценные советы по созданию этой 
книги от Крега Дж. Борделона (Craig J. Bordelon), Мишеля Брандеджа (Michael Brundage), Мэри Дэйджфорд (Mary Dageforde), Джошуа 
Энгела (Joshua Engel) и Эллиота Хьюза (Elliott Hughes).
Благодаря Лайзе Френдли (Lisa Friendly), редактору книги «Последовательность в Java» («The Java™ Series»), эта книга была написана и опубликована. Кен Арнольд (Ken Arnold) , автор книги «Язык 
программирования Java» («The Java™ Programming Language»), был 
первым, кто предложил написать книгу по интерфейсу JNI. Я очень 
признателен сотрудникам издательства Addison-Wesley в лице Майка Хендриксона (Mike Hendrikson) и Марины Ланг (Marina Lang) за 
их помощь и терпение, проявленные в процессе работы над книгой. 
Дайан Фрид (Diane Freed) курировала весь ход работы, начиная с момента написания до момента публикации книги. 
За последние несколько лет я имел удовольствие работать с группой талантливых и преданных своему делу людей, которые занимаются разработкой программного обеспечения Java в компании Sun 
Microsystems, в частности с членами команд разработчиков виртуальных машин HotSpot и Sun Labs. Эта книга посвящена всем им. 

Шенг Лиэнг
май 1999 года

12  Предисловие

Часть I

Введение 
и учебный материал

Глава 1

Введение

Интерфейс JNI (Java Native Interface) является мощным инструментом платформы Java. Приложения, использующие интерфейс JNI, 
могут включать в себя как native-код , написанный на языках программирования C и C++, так и код, написанный на языке программирования Java. Интерфейс JNI позволяет программистам использовать 
всю мощь Java-платформы без отказа от своих предыдущих наработок. Поскольку интерфейс JNI является частью платформы Java, 
программисту достаточно будет один раз решить проблему взаимодействия имеющегося кода и Java, и он может рассчитывать на то, что 
это решение будет работать со всеми реализациями Java-платформ. 
Эта книга является одновременно как руководством по программированию, так и справочником по JNI. Книга состоит из трех основных частей, которые включают в себя следующие главы:
 
 глава 1 представляет собой введение, которое дает читателям 
общее представление об интерфейсе JNI. В главе 2 рассматривается интерфейс JNI на простом примере. Эта глава представляет собой учебное пособие для начинающих, которые еще не 
знакомы с интерфейсом JNI; 
 
 главы 3–10 являются справочным пособием по программированию, которое дает широкое представление о ряде функций 
интерфейса JNI. Небольшие наглядные примеры позволят выделить различные характерные особенности интерфейса JNI 
и продемонстрировать методы, полезные при программировании с использованием JNI;
 
 в главах 11–13 содержится подробное описание всех типов интерфейса JNI и его функций. Главы построены таким образом, 
что могут служить справочным пособием.
Книга рассчитана на широкий круг читателей, интересующихся 
интерфейсом JNI. Целевой аудиторией учебного раздела книги и раздела по программированию являются начинающие программисты, 
что же касается опытных разработчиков и специалистов по интерфейсу JNI, то их могут больше заинтересовать справочные разделы 

 15

книги. Основными читателями книги, вероятнее всего, станут разработчики, использующие JNI для написания приложений. Данная 
книга адресована в большей степени программистам, использующим 
JNI. В меньшей же степени книга будет интересна разработчикам самого интерфейса JNI или конечным пользователям приложений, которые написаны с использованием интерфейса JNI.
Предполагается, что читатель имеет базовые знания языков программирования Java, C и C++. Если же знания в данных областях отсутствуют или недостаточны, то будет полезно ознакомиться с такими 
книгами, как: «Язык программирования Java ™», второе издание (The 
Java™ Programming Language, Second Edition), написанной Кэном 
Арнольдом (Ken Arnold) и Джеймсом Гослингом (James Gosling) (издательство «Addison-Wesley», 1998), «Язык программирования С», 
второе издание (The C Programming Language, Second Edition), написанной Брайаном Керниганом (Brian Kernighan) и Деннисом Ритчи 
(Dennis Ritchie) (издательство «Prentice Hall», 1988), а также «Язык 
программирования С++», третье издание (The C++ Programming 
Language, Third Edition), написанной Бьёрном Страуструпом (Bjarne 
Stroustrup) (издательство «Addison-Wesley», 1997).
Заключительный раздел данной главы посвящен происхождению, 
роли и этапам развития интерфейса JNI.

1.1. Платформа Java  и вычислительная 
среда

Поскольку данная книга охватывает приложения, написанные на 
языке программирования Java, а также на языках программирования 
native-уровня (C, C++ и т. д.), то для начала необходимо определить 
состав программного окружения этих языков.
Java-платформа является программной средой, состоящей из виртуальной машины Java (ВМ) и интерфейса программирования приложений Java (Java API ). Java-приложения пишутся на языке программирования Java и компилируются в машинно-независимый код 
(двоичный формат класса). Класс может быть выполнен на любой 
виртуальной машине Java. Java API состоит из набора определенных 
классов. Любая реализация Java-платформы гарантированно поддерживает язык программирования Java, виртуальную машину и API. 
Понятие «вычислительная среда» (host environment) включает 
в себя операционную систему, под которой работает виртуальная 

Платформа Java и вычислительная среда