Spec-Zone .ru спецификации, руководства, описания, API

Содержание документации

Улучшения JNI
Представленный в версии 1.2 ^JavaTM 2 SDK

JNI был улучшен в Java 2 SDK к:

• включите новые функции в развивающуюся платформу Java,
• гарантируйте эффективный и устойчивый интерфейс для интеграции Java/собственного кода.

Новые Константы

#define JNI_VERSION_1_1 0x00010001
#define JNI_VERSION_1_2 0x00010002

/* Error codes */
#define JNI_EDETACHED    (-2)              /* thread detached from the VM */
#define JNI_EVERSION     (-3)              /* JNI version error */

Улучшения к Существующему API

• Операции класса
  • FindClass
• API вызова
  • JNI_CreateJavaVM
  • AttachCurrentThread
  • DetachCurrentThread
  • DestroyJavaVM

Новые Функции

• Библиотека и управление Версией
  • JNI_OnLoad
  • JNI_OnUnload
• Локальное Ссылочное управление
  • EnsureLocalCapacity
  • PushLocalFrame
  • PopLocalFrame
  • NewLocalRef
• Исключения
  • ExceptionCheck
• Слабые Глобальные Ссылки
  • NewWeakGlobalRef
  • DeleteWeakGlobalRef
• Операции над массивом
  • GetPrimitiveArrayCritical
  • ReleasePrimitiveArrayCritical
• Строковые Операции
  • GetStringRegion
  • GetStringUTFRegion
  • GetStringCritical
  • ReleaseStringCritical
• Отражательная Поддержка
  • FromReflectedMethod
  • FromReflectedField
  • ToReflectedMethod
  • ToReflectedField
• API вызова
  • GetEnv

Операции класса

jclass FindClass(JNIEnv *env, const char *name);

В JDK 1.1, FindClass искавшие только локальные классы в CLASSPATH. У получающихся классов не было загрузчика class.

Модель обеспечения безопасности Java была расширена, чтобы позволить несистемным классам загружать и вызывать собственные методы. В Java 2 Платформы, FindClass определяет местоположение загрузчика class, связанного с текущим собственным методом. Если собственный код будет принадлежать системе class, то никакой загрузчик class не будет включен. Иначе, надлежащий загрузчик class будет вызван, чтобы загрузить и соединить именованный class.

Когда FindClass вызывается через Интерфейс Вызова, нет никакого текущего собственного метода или его связанного загрузчика class. В этом случае, результат ClassLoader.getBaseClassLoader используется. Это - загрузчик class, который виртуальная машина создает для приложений, и в состоянии определить местоположение классов, перечисленных в java.class.path свойство.

Библиотека и управление Версией

• class может по ошибке соединиться с собственными библиотеками, загруженными class тем же самым именем в различном загрузчике class.
• Собственные методы могут легко смешать классы от различных загрузчиков class. Это повреждает разделение пространства имен, предлагаемое загрузчиками class, и приводит к проблемам безопасности типов.

В Java 2 SDK каждый загрузчик class управляет своим собственным набором собственных библиотек. Тот же самый JNI собственная библиотека не может быть загружен больше чем в один загрузчик class. Выполнение так причины UnsatisfiedLinkError быть брошенным. Например, System.loadLibrary броски UnsatisfiedLinkError когда использующийся загрузить собственную библиотеку в два загрузчика class. Преимущества нового подхода:

• Разделение пространства имен, основанное на загрузчиках class, сохраняется в собственных библиотеках. Собственная библиотека не может легко смешать классы от различных загрузчиков class.
• Кроме того, собственные библиотеки могут быть разгружены, когда их соответствующие загрузчики class собираются "мусор".

Чтобы облегчить управление управлением версиями и управление ресурсами, библиотеки JNI в Java, 2 Платформы могут дополнительно экспортировать следующие две функции:

jint JNI_OnLoad(JavaVM *vm, void *reserved);

Чтобы использовать любую из новых функций JNI, собственная библиотека должна экспортировать a JNI_OnLoad функция, которая возвращается JNI_VERSION_1_2. Если собственная библиотека не экспортирует a JNI_OnLoad функция, VM предполагает, что библиотека только требует версии JNI JNI_VERSION_1_1. Если VM не распознает номер версии, возвращенный JNI_OnLoad, собственная библиотека не может быть загружена.

void JNI_OnUnload(JavaVM *vm, void *reserved);

Отметьте это JNI_OnLoad и JNI_OnUnload две функции, дополнительно предоставленные библиотеками JNI, не экспортируемыми от VM.

Локальное Ссылочное управление

JDK 1.1 обеспечивает a DeleteLocalRef функционируйте так, чтобы программисты могли вручную удалить локальные ссылки. Например, если собственный код выполняет итерации через потенциально многочисленный массив объектов и использует один элемент в каждой итерации, это - хорошая практика, чтобы удалить локальную ссылку на больше используемый элемент массива прежде, чем новая локальная ссылка будет создана в следующей итерации.

Java 2 SDK обеспечивает дополнительный набор функций для локального ссылочного управления временем жизни.

jint EnsureLocalCapacity(JNIEnv *env, jint capacity);

Гарантирует, что, по крайней мере, данное число локальных ссылок может быть создано в текущем потоке. Возвраты 0 на успехе; иначе возвращает отрицательное число и бросает OutOfMemoryError.

Прежде, чем это введет собственный метод, VM автоматически гарантирует, что могут быть созданы по крайней мере 16 локальных ссылок.

Для обратной совместимости VM выделяет локальные ссылки вне обеспеченной емкости. (Как поддержка отладки, VM может дать пользовательские предупреждения, что создаются слишком много локальных ссылок. В Java 2 SDK программист может предоставить -verbose:jni параметр командной строки, чтобы включить эти сообщения.) Вызовы VM FatalError если больше локальных ссылок не может быть создано вне обеспеченной емкости.

jint PushLocalFrame(JNIEnv *env, jint capacity);

Создает новый локальный ссылочный фрейм, в котором может быть создано, по крайней мере, данное число локальных ссылок. Возвраты 0 на успехе, отрицательном числе и ожидании OutOfMemoryError при отказе.

Отметьте, что локальные ссылки, уже создаваемые в предыдущих локальных фреймах, все еще допустимы в текущем локальном фрейме.

jobject PopLocalFrame(JNIEnv *env, jobject result);

Появляется от текущего локального ссылочного фрейма, освобождает все локальные ссылки, и возвращает локальную ссылку в предыдущем локальном ссылочном фрейме для данного result объект.

Передача NULL как result если Вы не должны возвратить ссылку на предыдущий фрейм.

jobject NewLocalRef(JNIEnv *env, jobject ref);

Исключения

jboolean ExceptionCheck(JNIEnv *env);

Слабые Глобальные Ссылки

Слабые глобальные ссылки в JNI являются упрощенной версией Слабых ссылок Java, доступных как часть Java 2 API Платформы ( java.lang.ref пакет и его классы).

Разъяснение   (добавленный июнь 2001)

Так как сборка "мусора" может произойти, в то время как собственные методы работают, объекты, упомянутые слабыми глобальными ссылками, могут быть освобождены в любое время. В то время как слабые глобальные ссылки могут использоваться, где глобальные ссылки используются, обычно неуместно сделать так, поскольку они могут стать функционально эквивалентными NULL без уведомления.

В то время как IsSameObject может использоваться, чтобы определить, обращается ли слабая глобальная ссылка к освобожденному объекту, она не препятствует объекту быть освобожденным сразу после того. Следовательно, программисты, возможно, не полагаются на эту проверку, чтобы определить, может ли слабая глобальная ссылка используемый (как не -NULL ссылка) в любом будущем вызове функции JNI.

Чтобы преодолеть это свойственное ограничение, рекомендуется, чтобы стандарт (strong) локальная или глобальная ссылка на тот же самый объект был получен, используя функции JNI NewLocalRef или NewGlobalRef, и что эта ссылка strong использоваться, чтобы получить доступ к намеченному объекту. Эти функции возвратятся NULL если объект был освобожден, и иначе возвратит ссылку strong (который будет препятствовать объекту быть освобожденным). Новая ссылка должна быть явно удалена, когда немедленный доступ к объекту больше не требуется, позволяя объект быть освобожденным.

Слабая глобальная ссылка более слаба чем другие типы слабых ссылок (объекты Java классов SoftReference или WeakReference). Слабая глобальная ссылка на конкретную цель не будет становиться функционально эквивалентной NULL пока SoftReference или объектам WeakReference, обращающимся к той же самой конкретной цели, не очистили их ссылки.

Слабая глобальная ссылка более слаба чем внутренние ссылки Java на объекты, требующие завершения. Слабая глобальная ссылка не будет становиться функционально эквивалентной NULL до окончания завершения финализатора для объекта, на который ссылаются, если существующий.

Взаимодействия между слабыми глобальными ссылками и PhantomReferences неопределены. В частности реализации Java VM может (или не может) обрабатывать слабые глобальные ссылки после PhantomReferences, и это может (или не может), будьте возможны, чтобы использовать слабые глобальные ссылки, чтобы держаться за объекты, который также упоминаетесь объектами PhantomReference. Этого неопределенного использования слабых глобальных ссылок нужно избежать.

jweak NewWeakGlobalRef(JNIEnv *env, jobject obj);

void DeleteWeakGlobalRef(JNIEnv *env, jweak obj);

Операции над массивом

В JDK 1.1, программисты могут использовать Get/Release<PrimitiveType>ArrayElements функции, чтобы получить указатель на примитивные элементы массива. Если VM поддерживает прикрепление, указатель на исходные данные возвращается; иначе, копия делается.

Новые функции позволяют собственному коду получать прямой указатель, чтобы выстроить элементы, даже если VM не поддерживает прикрепление.

void * GetPrimitiveArrayCritical(JNIEnv *env, jarray array, jboolean *isCopy);
void ReleasePrimitiveArrayCritical(JNIEnv *env, jarray array, void *carray, jint mode);

После вызова GetPrimitiveArrayCritical, собственный код не должен работать за длительным периодом времени прежде, чем это вызовет ReleasePrimitiveArrayCritical. Мы должны обработать код в этой паре функций как работающий в "критической области." В критической области собственный код не должен вызвать другие функции JNI, или любой системный вызов, который может заставить текущий поток блокировать и ожидать другого потока Java. (Например, текущий поток не должен вызвать read на потоке, записанном другим потоком Java.)

Эти ограничения делают это более вероятно, что собственный код получит нескопированную версию массива, даже если VM не будет поддерживать прикрепление. Например, VM может временно отключить сборку "мусора", когда собственный код содержит указатель на массив, полученный через GetPrimitiveArrayCritical.

Многократные пары GetPrimtiveArrayCritical и ReleasePrimitiveArrayCritical может быть вложен. Например:

  jint len = (*env)->GetArrayLength(env, arr1); 
  jbyte *a1 = (*env)->GetPrimitiveArrayCritical(env, arr1, 0);
  jbyte *a2 = (*env)->GetPrimitiveArrayCritical(env, arr2, 0);
  /* We need to check in case the VM tried to make a copy. */
  if (a1 == NULL || a2 == NULL) {
    ... /* out of memory exception thrown */
  }
  memcpy(a1, a2, len);
  (*env)->ReleasePrimitiveArrayCritical(env, arr2, a2, 0);
  (*env)->ReleasePrimitiveArrayCritical(env, arr1, a1, 0);

Отметьте это GetPrimitiveArrayCritical мог бы все еще сделать копию массива, если VM внутренне представляет массивы в различном формате. Поэтому мы должны проверить его возвращаемое значение по NULL для возможного из ситуаций с памятью.

Строковые Операции

void GetStringRegion(JNIEnv *env, jstring str, jsize start, jsize len, jchar *buf);

Броски StringIndexOutOfBoundsException на индексируют переполнение.

< void GetStringUTFRegion(JNIEnv *env, jstring str, jsize start, jsize len, char *buf);

Броски StringIndexOutOfBoundsException на индексируют переполнение.

const jchar * GetStringCritical(JNIEnv *env, jstring string, jboolean *isCopy);
void ReleaseStringCritical(JNIEnv *env, jstring string, const jchar *carray);

Ограничения на Get/ReleaseStringCritical подобны тем на Get/ReleasePrimitiveArrayCritical.

Отражательная Поддержка

Программисты могут использовать JNI, чтобы вызвать методы Java или поля Java доступа, если они знают имя и тип методов или полей. API Reflection Ядра Java позволяет программистам анализировать классы Java во времени выполнения. JNI обеспечивает ряд функций преобразования между полем и ID метода, привыкшими в JNI к полю и объектам метода, используемым в API Reflection Ядра Java.

jmethodID FromReflectedMethod(JNIEnv *env, jobject method);

jfieldID FromReflectedField(JNIEnv *env, jobject field);

jobject ToReflectedMethod(JNIEnv *env, jclass cls,
  jmethodID methodID);

Броски OutOfMemoryError и возвраты 0, если сбои.

jobject ToReflectedField(JNIEnv *env, jclass cls,
  jfieldID fieldID);

Броски OutOfMemoryError и возвраты 0, если сбои.

API вызова

jint JNI_CreateJavaVM(JavaVM **pvm, void **penv, void *args);

В Java 2 SDK мы представляем стандартную структуру инициализации VM. Обратная совместимость сохраняется. Если параметр инициализации VM указывает на a JDK1_1InitArgs структура, JNI_CreateJavaVM все еще возвращает 1.1 версии указателя на интерфейс JNI. VM возвращает 1.2 версии указателя на интерфейс JNI, если третий параметр указывает на a JavaVMInitArgs структура. В отличие от этого JDK1_1InitArgs, который содержит фиксированный набор опций, JavaVMInitArgs опция использования представляет в виде строки, чтобы закодировать произвольные опции запуска VM.

typedef struct JavaVMInitArgs {
    jint version;

    jint nOptions;
    JavaVMOption *options;
    jboolean ignoreUnrecognized;
} JavaVMInitArgs;

typedef struct JavaVMOption {
    char *optionString;
    void *extraInfo;
} JavaVMOption;

Кроме того, каждая реализация VM может поддерживать свой собственный набор нестандартных строк опции. Нестандартные имена опции должны начаться"-X"или подчеркивание ("_"). Например, Java 2 SDK поддерживает -Xms и -Xmx опции, чтобы позволить программистам определяют начальный и максимальный размер "кучи". Опции, которые начинаются"-X"доступны от"java"командная строка.

Вот пример кода, который создает Java VM в Java 2 SDK:

JavaVMInitArgs vm_args;
JavaVMOption options[4];

options[0].optionString = "-Djava.compiler=NONE";           /* disable JIT */
options[1].optionString = "-Djava.class.path=c:\myclasses"; /* user classes */
options[2].optionString = "-Djava.library.path=c:\mylibs";  /* set native library path */
options[3].optionString = "-verbose:jni";                   /* print JNI-related messages */

vm_args.version = JNI_VERSION_1_2;
vm_args.options = options;
vm_args.nOptions = 4;
vm_args.ignoreUnrecognized = TRUE;

/* Note that in the Java 2 SDK, there is no longer any need to call 
 * JNI_GetDefaultJavaVMInitArgs. 
 */
res = JNI_CreateJavaVM(&vm, (void **)&env, &vm_args);
if (res < 0) ...

Java 2 SDK все еще поддерживает JDK1_1InitArgs точно таким же образом как JDK 1.1.

jint AttachCurrentThread(JavaVM *vm, void **penv, void *args);

В Java 2 SDK Вы передаете NULL как третий параметр за 1.1 поведения, или передача указатель на следующую структуру, чтобы определить дополнительную информацию:

typedef struct JavaVMAttachArgs {
    jint version;  /* must be JNI_VERSION_1_2 */
    char *name;    /* the name of the thread, or NULL */
    jobject group; /* global ref of a ThreadGroup object, or NULL */
} JavaVMAttachArgs;

jint DetachCurrentThread(JavaVM *vm);

В Java 2 SDK основной поток может быть отсоединен от VM.

jint DestroyJavaVM(JavaVM *vm);

jint GetEnv(JavaVM *vm, void **env, jint version);

---

Авторское право © 1993, 2012, Oracle и/или его филиалы. Все права защищены.

Свяжитесь с Нами