Spec-Zone .ru
спецификации, руководства, описания, API
Содержание документации
Содержание | Предыдущий | Следующий

Функции JNI


 Глава 4

Эта глава служит ссылочным разделом для функций JNI. Это обеспечивает полный список всех функций JNI. Это также представляет точное расположение таблицы функции JNI.

Отметьте использование термина "должный", чтобы описать ограничения на программистов JNI. Например, когда Вы видите, что определенная функция JNI должна получить НЕНУЛЕВОЙ объект, это - Ваша обязанность гарантировать, что НУЛЬ не передают к той функции JNI. В результате реализация JNI не должна выполнить регистрации Нулевого указателя той функции JNI.

Часть этой главы адаптируется из документации Netscape JRI.

Ссылочные материальные группы функционируют своим использованием. Ссылочный раздел организуется следующими функциональными областями:

Таблица Функции интерфейса

Каждая функция доступна при фиксированном смещении через параметр JNIEnv. Тип JNIEnv является указателем на структуру, хранящую все указатели функции JNI. Это определяется следующим образом:

typedef const struct JNINativeInterface *JNIEnv; 

VM инициализирует функциональную таблицу, как показано Примером кода 4-1. Отметьте, что первые три записи резервируются для будущей совместимости с COM. Кроме того, мы резервируем много дополнительные NULL записи около начала функциональной таблицы, так, чтобы, например, будущая связанная с классом работа JNI может быть добавлена после FindClass, а не в конце таблицы.

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


Пример кода 4-1
const struct JNINativeInterface ... = {

    NULL,
    NULL,
    NULL,
    NULL,
    GetVersion,

    DefineClass,
    FindClass,

    FromReflectedMethod,
    FromReflectedField,
    ToReflectedMethod,

    GetSuperclass,
    IsAssignableFrom,

    ToReflectedField,

    Throw,
    ThrowNew,
    ExceptionOccurred,
    ExceptionDescribe,
    ExceptionClear,
    FatalError,

    PushLocalFrame,
    PopLocalFrame,

    NewGlobalRef,
    DeleteGlobalRef,
    DeleteLocalRef,
    IsSameObject,
    NewLocalRef,
    EnsureLocalCapacity,

    AllocObject,
    NewObject,
    NewObjectV,
    NewObjectA,

    GetObjectClass,
    IsInstanceOf,

    GetMethodID,

    CallObjectMethod,
    CallObjectMethodV,
    CallObjectMethodA,
    CallBooleanMethod,
    CallBooleanMethodV,
    CallBooleanMethodA,
    CallByteMethod,
    CallByteMethodV,
    CallByteMethodA,
    CallCharMethod,
    CallCharMethodV,
    CallCharMethodA,
    CallShortMethod,
    CallShortMethodV,
    CallShortMethodA,
    CallIntMethod,
    CallIntMethodV,
    CallIntMethodA,
    CallLongMethod,
    CallLongMethodV,
    CallLongMethodA,
    CallFloatMethod,
    CallFloatMethodV,
    CallFloatMethodA,
    CallDoubleMethod,
    CallDoubleMethodV,
    CallDoubleMethodA,
    CallVoidMethod,
    CallVoidMethodV,
    CallVoidMethodA,

    CallNonvirtualObjectMethod,
    CallNonvirtualObjectMethodV,
    CallNonvirtualObjectMethodA,
    CallNonvirtualBooleanMethod,
    CallNonvirtualBooleanMethodV,
    CallNonvirtualBooleanMethodA,
    CallNonvirtualByteMethod,
    CallNonvirtualByteMethodV,
    CallNonvirtualByteMethodA,
    CallNonvirtualCharMethod,
    CallNonvirtualCharMethodV,
    CallNonvirtualCharMethodA,
    CallNonvirtualShortMethod,
    CallNonvirtualShortMethodV,
    CallNonvirtualShortMethodA,
    CallNonvirtualIntMethod,
    CallNonvirtualIntMethodV,
    CallNonvirtualIntMethodA,
    CallNonvirtualLongMethod,
    CallNonvirtualLongMethodV,
    CallNonvirtualLongMethodA,
    CallNonvirtualFloatMethod,
    CallNonvirtualFloatMethodV,
    CallNonvirtualFloatMethodA,
    CallNonvirtualDoubleMethod,
    CallNonvirtualDoubleMethodV,
    CallNonvirtualDoubleMethodA,
    CallNonvirtualVoidMethod,
    CallNonvirtualVoidMethodV,
    CallNonvirtualVoidMethodA,

    GetFieldID,

    GetObjectField,
    GetBooleanField,
    GetByteField,
    GetCharField,
    GetShortField,
    GetIntField,
    GetLongField,
    GetFloatField,
    GetDoubleField,
    SetObjectField,
    SetBooleanField,
    SetByteField,
    SetCharField,
    SetShortField,
    SetIntField,
    SetLongField,
    SetFloatField,
    SetDoubleField,

    GetStaticMethodID,

    CallStaticObjectMethod,
    CallStaticObjectMethodV,
    CallStaticObjectMethodA,
    CallStaticBooleanMethod,
    CallStaticBooleanMethodV,
    CallStaticBooleanMethodA,
    CallStaticByteMethod,
    CallStaticByteMethodV,
    CallStaticByteMethodA,
    CallStaticCharMethod,
    CallStaticCharMethodV,
    CallStaticCharMethodA,
    CallStaticShortMethod,
    CallStaticShortMethodV,
    CallStaticShortMethodA,
    CallStaticIntMethod,
    CallStaticIntMethodV,
    CallStaticIntMethodA,
    CallStaticLongMethod,
    CallStaticLongMethodV,
    CallStaticLongMethodA,
    CallStaticFloatMethod,
    CallStaticFloatMethodV,
    CallStaticFloatMethodA,
    CallStaticDoubleMethod,
    CallStaticDoubleMethodV,
    CallStaticDoubleMethodA,
    CallStaticVoidMethod,
    CallStaticVoidMethodV,
    CallStaticVoidMethodA,

    GetStaticFieldID,

    GetStaticObjectField,
    GetStaticBooleanField,
    GetStaticByteField,
    GetStaticCharField,
    GetStaticShortField,
    GetStaticIntField,
    GetStaticLongField,
    GetStaticFloatField,
    GetStaticDoubleField,

    SetStaticObjectField,
    SetStaticBooleanField,
    SetStaticByteField,
    SetStaticCharField,
    SetStaticShortField,
    SetStaticIntField,
    SetStaticLongField,
    SetStaticFloatField,
    SetStaticDoubleField,

    NewString,

    GetStringLength,
    GetStringChars,
    ReleaseStringChars,

    NewStringUTF,
    GetStringUTFLength,
    GetStringUTFChars,
    ReleaseStringUTFChars,

    GetArrayLength,

    NewObjectArray,
    GetObjectArrayElement,
    SetObjectArrayElement,

    NewBooleanArray,
    NewByteArray,
    NewCharArray,
    NewShortArray,
    NewIntArray,
    NewLongArray,
    NewFloatArray,
    NewDoubleArray,

    GetBooleanArrayElements,
    GetByteArrayElements,
    GetCharArrayElements,
    GetShortArrayElements,
    GetIntArrayElements,
    GetLongArrayElements,
    GetFloatArrayElements,
    GetDoubleArrayElements,

    ReleaseBooleanArrayElements,
    ReleaseByteArrayElements,
    ReleaseCharArrayElements,
    ReleaseShortArrayElements,
    ReleaseIntArrayElements,
    ReleaseLongArrayElements,
    ReleaseFloatArrayElements,
    ReleaseDoubleArrayElements,

    GetBooleanArrayRegion,
    GetByteArrayRegion,
    GetCharArrayRegion,
    GetShortArrayRegion,
    GetIntArrayRegion,
    GetLongArrayRegion,
    GetFloatArrayRegion,
    GetDoubleArrayRegion,
    SetBooleanArrayRegion,
    SetByteArrayRegion,
    SetCharArrayRegion,
    SetShortArrayRegion,
    SetIntArrayRegion,
    SetLongArrayRegion,
    SetFloatArrayRegion,
    SetDoubleArrayRegion,

    RegisterNatives,
    UnregisterNatives,

    MonitorEnter,
    MonitorExit,

    GetJavaVM,

    GetStringRegion,
    GetStringUTFRegion,

    GetPrimitiveArrayCritical,
    ReleasePrimitiveArrayCritical,

    GetStringCritical,
    ReleaseStringCritical,

    NewWeakGlobalRef,
    DeleteWeakGlobalRef,

    ExceptionCheck,

    NewDirectByteBuffer,
    GetDirectBufferAddress,
    GetDirectBufferCapacity,

    GetObjectRefType
  };

Информация о версии

GetVersion

jint GetVersion(JNIEnv *env);

Возвращает версию собственного интерфейса метода.

РЕДАКТИРОВАНИЕ:

Индекс 4 в таблице функции интерфейса JNIEnv.

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

ВОЗВРАТЫ:

Возвращает номер основной версии в более высоких 16 битах и номер вспомогательной версии в более низких 16 битах.

В JDK/JRE 1.1, GetVersion() возвраты 0x00010001.

В JDK/JRE 1.2, GetVersion() возвраты 0x00010002.

В JDK/JRE 1.4, GetVersion() возвраты 0x00010004.

В JDK/JRE 1.6, GetVersion() возвраты 0x00010006.

Константы

НАЧИНАЯ С JDK/JRE 1.2:

#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 

НАЧИНАЯ С JDK/JRE 1.4:

    #define JNI_VERSION_1_4 0x00010004

НАЧИНАЯ С JDK/JRE 1.6:

    #define JNI_VERSION_1_6 0x00010006

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

DefineClass

jclass DefineClass(JNIEnv *env, const char *name, jobject loader,
const jbyte *buf, jsize bufLen);

Загружает класс из буфера необработанных данных класса. На буфер, содержащий необработанные данные класса, не ссылается VM после возвратов вызова DefineClass, и это может быть отброшено при желании.

РЕДАКТИРОВАНИЕ:

Индекс 5 в таблице функции интерфейса JNIEnv.

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

name: имя класса или интерфейса, который будет определен. Строка кодируется в измененном UTF-8.

loader: загрузчик класса, присвоенный определенному классу.

buf: буфер, содержащий .class данные файла.

bufLen: буферная длина.

ВОЗВРАТЫ:

Возвращает объект класса Java или NULL если ошибка происходит.

БРОСКИ:

ClassFormatError: если данные класса не определяют допустимый класс.

ClassCircularityError: если бы класс или интерфейс были бы своим собственным суперклассом или суперинтерфейсом.

OutOfMemoryError: если система исчерпывает память.

SecurityException: если вызывающая сторона пытается определить класс в дереве пакета "java".

FindClass

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

В выпуске 1.1 JDK эта функция загружает локально определенный класс. Это ищет каталоги и файлы zip, определенные CLASSPATH переменная окружения для класса с указанным именем.

Начиная с Java 2 выпуска 1.2 SDK модель обеспечения безопасности Java позволяет несистемным классам загружать и вызывать собственные методы. FindClass определяет местоположение загрузчика класса, связанного с текущим собственным методом; то есть, загрузчик класса класса, который объявил собственный метод. Если собственный метод будет принадлежать системному классу, то никакой загрузчик класса не будет включен. Иначе, надлежащий загрузчик класса будет вызван, чтобы загрузить и соединить именованный класс.

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

name параметром является полностью определенное имя класса или подпись типа массива. Например, полностью определенное имя класса для java.lang.String класс:

                   "java/lang/String"

Подпись типа массива класса массива java.lang.Object[] :

                   "[Ljava/lang/Object;"


РЕДАКТИРОВАНИЕ:

Индекс 6 в таблице функции интерфейса JNIEnv.

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

name: полностью определенное имя класса (то есть, имя пакета, разграниченное“/”, сопровождаемый именем класса). Если имя начинается“[“(символ подписи массива), это возвращает класс массива. Строка кодируется в измененном UTF-8.

ВОЗВРАТЫ:

Возвращает объект класса из полностью определенного имени, или NULL если класс не может быть найден.

БРОСКИ:

ClassFormatError: если данные класса не определяют допустимый класс.

ClassCircularityError: если бы класс или интерфейс были бы своим собственным суперклассом или суперинтерфейсом.

NoClassDefFoundError: если никакое определение для требуемого класса или интерфейса не может быть найдено.

OutOfMemoryError: если система исчерпывает память.

GetSuperclass

jclass GetSuperclass(JNIEnv *env, jclass clazz);

Если clazz представляет любой класс кроме класса Object, тогда эта функция возвращает объект, который представляет суперкласс класса, определенного clazz.

Если clazz определяет класс Object, или clazz представляет интерфейс, эта функция возвраты NULL.

РЕДАКТИРОВАНИЕ:

Индекс 10 в таблице функции интерфейса JNIEnv.

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

clazz: объект класса Java.

ВОЗВРАТЫ:

Возвращает суперкласс класса, представленного clazz, или NULL.

IsAssignableFrom

jboolean IsAssignableFrom(JNIEnv *env, jclass clazz1,
jclass clazz2);

Определяет ли объект clazz1 может быть безопасно брошен к clazz2.

РЕДАКТИРОВАНИЕ:

Индекс 11 в таблице функции интерфейса JNIEnv.

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

clazz1: параметр первого класса.

clazz2: второй параметр класса.

ВОЗВРАТЫ:

Возвраты JNI_TRUE если любое из следующего является истиной:

Исключения

Бросок

jint Throw(JNIEnv *env, jthrowable obj);

Причины a java.lang.Throwable объект, который будет брошен.

РЕДАКТИРОВАНИЕ:

Индекс 13 в таблице функции интерфейса JNIEnv.

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

obj: a java.lang.Throwable объект.

ВОЗВРАТЫ:

Возвраты 0 на успехе; отрицательная величина при отказе.

БРОСКИ:

java.lang.Throwable object obj.

ThrowNew

jint ThrowNew(JNIEnv *env, jclass clazz,
const char *message);

Создает объект исключения из указанного класса с сообщением, определенным message и причины, что исключение, которое будет брошено.

РЕДАКТИРОВАНИЕ:

Индекс 14 в таблице функции интерфейса JNIEnv.

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

clazz: подкласс java.lang.Throwable.

message: сообщение, используемое, чтобы создать java.lang.Throwable объект. Строка кодируется в измененном UTF-8.

ВОЗВРАТЫ:

Возвраты 0 на успехе; отрицательная величина при отказе.

БРОСКИ:

недавно созданный java.lang.Throwable объект.

ExceptionOccurred

jthrowable ExceptionOccurred(JNIEnv *env);

Определяет, выдается ли исключение. Исключение остается брошенным до любого собственные вызовы кода ExceptionClear(), или код Java обрабатывает исключение.

РЕДАКТИРОВАНИЕ:

Индекс 15 в таблице функции интерфейса JNIEnv.

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

ВОЗВРАТЫ:

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

ExceptionDescribe

void ExceptionDescribe(JNIEnv *env);

Печатает исключение и след стека к системному каналу сообщения об ошибке, такой как stderr. Это - подпрограмма удобства, предусмотрел отладку.

РЕДАКТИРОВАНИЕ:

Индекс 16 в таблице функции интерфейса JNIEnv.

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

ExceptionClear

void ExceptionClear(JNIEnv *env);

Очищает любое исключение, которое в настоящий момент выдается. Если никакое исключение в настоящий момент не выдается, эта подпрограмма не имеет никакого эффекта.

РЕДАКТИРОВАНИЕ:

Индекс 17 в таблице функции интерфейса JNIEnv.

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

FatalError

void FatalError(JNIEnv *env, const char *msg);

Повышает фатальную ошибку и не ожидает, что VM восстановится. Эта функция не возвращается.

РЕДАКТИРОВАНИЕ:

Индекс 18 в таблице функции интерфейса JNIEnv.

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

msg: сообщение об ошибке. Строка кодируется в измененном UTF-8.

ExceptionCheck

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

jboolean ExceptionCheck(JNIEnv *env);

Возвраты JNI_TRUE когда есть исключение на ожидании; иначе, возвраты JNI_FALSE.

РЕДАКТИРОВАНИЕ:

Индекс 228 в таблице функции интерфейса JNIEnv.

С ТЕХ ПОР:

JDK/JRE 1.2

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

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

NewGlobalRef

jobject NewGlobalRef(JNIEnv *env, jobject obj);

Создает новую глобальную ссылку на объект, упомянутый obj параметр. obj параметром может быть глобальная или локальная ссылка. От глобальных ссылок нужно явно избавиться, вызывая DeleteGlobalRef().

РЕДАКТИРОВАНИЕ:

Индекс 21 в таблице функции интерфейса JNIEnv.

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

obj: глобальная или локальная ссылка.

ВОЗВРАТЫ:

Возвращает глобальную ссылку, или NULL если система исчерпывает память.

DeleteGlobalRef

void DeleteGlobalRef(JNIEnv *env, jobject globalRef);

Удаляет глобальную ссылку, которой указывают globalRef.

РЕДАКТИРОВАНИЕ:

Индекс 22 в таблице функции интерфейса JNIEnv.

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

globalRef: глобальная ссылка.

Локальные Ссылки

Локальные ссылки допустимы для продолжительности собственного вызова метода. Они освобождаются автоматически после собственных возвратов метода. Каждая локальная ссылка стоит некоторого количества ресурса виртуальной машины Java. Программисты должны удостовериться, что собственные методы не чрезмерно выделяют локальные ссылки. Хотя локальные ссылки автоматически освобождаются после того, как собственный метод возвращается к Java, чрезмерное выделение локальных ссылок может заставить VM исчерпывать память во время выполнения собственного метода.

DeleteLocalRef

void DeleteLocalRef(JNIEnv *env, jobject localRef);

Удаляет локальную ссылку, которой указывают localRef.

РЕДАКТИРОВАНИЕ:

Индекс 23 в таблице функции интерфейса JNIEnv.

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

localRef: локальная ссылка.

Отметить

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

С JDK/JRE 1.2 дополнительный набор функций обеспечиваются для локального ссылочного управления временем жизни. Они - четыре упомянутые ниже функции.

EnsureLocalCapacity

jint EnsureLocalCapacity(JNIEnv *env, jint capacity);

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

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

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

РЕДАКТИРОВАНИЕ:

Индекс 26 в таблице функции интерфейса JNIEnv.

С ТЕХ ПОР:

JDK/JRE 1.2

PushLocalFrame

jint PushLocalFrame(JNIEnv *env, jint capacity);

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

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

РЕДАКТИРОВАНИЕ:

Индекс 19 в таблице функции интерфейса JNIEnv.

С ТЕХ ПОР:

JDK/JRE 1.2

PopLocalFrame

jobject PopLocalFrame(JNIEnv *env, jobject result);

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

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

РЕДАКТИРОВАНИЕ:

Индекс 20 в таблице функции интерфейса JNIEnv.

С ТЕХ ПОР:

JDK/JRE 1.2

NewLocalRef

jobject NewLocalRef(JNIEnv *env, jobject ref);

Создает новую локальную ссылку, которая обращается к тому же самому объекту как ref. Данный ref может быть глобальная или локальная ссылка. Возвраты NULL если ref обращается к null.

РЕДАКТИРОВАНИЕ:

Индекс 25 в таблице функции интерфейса JNIEnv.

С ТЕХ ПОР:

JDK/JRE 1.2

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

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

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

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

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

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

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

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

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

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

NewWeakGlobalRef

jweak NewWeakGlobalRef(JNIEnv *env, jobject obj);

Создает новую слабую глобальную ссылку. Возвраты NULL если obj обращается к null, или если VM исчерпывает память. Если VM исчерпывает память, OutOfMemoryError будет брошен.

РЕДАКТИРОВАНИЕ:

Индекс 226 в таблице функции интерфейса JNIEnv.

С ТЕХ ПОР:

JDK/JRE 1.2

DeleteWeakGlobalRef

void DeleteWeakGlobalRef(JNIEnv *env, jweak obj);

Удалите ресурсы VM, необходимые для данной слабой глобальной ссылки.

РЕДАКТИРОВАНИЕ:

Индекс 227 в таблице функции интерфейса JNIEnv.

С ТЕХ ПОР:

JDK/JRE 1.2

Объектные Операции

AllocObject

jobject AllocObject(JNIEnv *env, jclass clazz);

Выделяет новый объект Java, не вызывая ни одного из конструкторов для объекта. Возвращает ссылку на объект.

clazz параметр не должен обратиться к классу массива.

РЕДАКТИРОВАНИЕ:

Индекс 27 в таблице функции интерфейса JNIEnv.

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

clazz: объект класса Java.

ВОЗВРАТЫ:

Возвращает объект Java, или NULL если объект не может быть создан.

БРОСКИ:

InstantiationException: если класс является интерфейсом или абстрактным классом.

OutOfMemoryError: если система исчерпывает память.

NewObject
NewObjectA
NewObjectV

jobject NewObject(JNIEnv *env, jclass clazz,
jmethodID methodID, ...);

jobject NewObjectA(JNIEnv *env, jclass clazz,
jmethodID methodID, const jvalue *args);

jobject NewObjectV(JNIEnv *env, jclass clazz,
jmethodID methodID, va_list args);

Создает новый объект Java. ID метода указывает который метод конструктора вызвать. Этот ID должен быть получен, вызывая GetMethodID() с <init> как имя метода и void (V) как тип возврата.

clazz параметр не должен обратиться к классу массива.

NewObject

Программисты помещают все параметры, которые нужно сразу передать конструктору после methodID параметр. NewObject() принимает эти параметры и передает их к методу Java, который программист хочет вызвать.

РЕДАКТИРОВАНИЕ:

Индекс 28 в таблице функции интерфейса JNIEnv.

NewObjectA

Программисты помещают все параметры, которые нужно передать конструктору в args массив jvalues это сразу следует methodID параметр. NewObjectA() принимает параметры в этом массиве, и, поочередно, передает их к методу Java, который программист хочет вызвать.

РЕДАКТИРОВАНИЕ:

Индекс 30 в таблице функции интерфейса JNIEnv.

NewObjectV

Программисты помещают все параметры, которые нужно передать конструктору в args параметр типа va_list это сразу следует methodID параметр. NewObjectV() принимает эти параметры, и, поочередно, передает их к методу Java, который программист хочет вызвать.

РЕДАКТИРОВАНИЕ:

Индекс 29 в таблице функции интерфейса JNIEnv.

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

clazz: объект класса Java.

methodID: ID метода конструктора.

Дополнительный Параметр для NewObject:

параметры конструктору.

Дополнительный Параметр для NewObjectA:

args: массив параметров конструктору.

Дополнительный Параметр для NewObjectV:

args: va_list параметров конструктору.

ВОЗВРАТЫ:

Возвращает объект Java, или NULL если объект не может быть создан.

БРОСКИ:

InstantiationException: если класс является интерфейсом или абстрактным классом.

OutOfMemoryError: если система исчерпывает память.

Любые исключения, выданные конструктором.

GetObjectClass

jclass GetObjectClass(JNIEnv *env, jobject obj);

Возвращает класс объекта.

РЕДАКТИРОВАНИЕ:

Индекс 31 в таблице функции интерфейса JNIEnv.

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

obj: объект Java (не должен быть NULL).

ВОЗВРАТЫ:

Возвращает объект класса Java.

GetObjectRefType

jobjectRefType GetObjectRefType(JNIEnv* env, jobject obj);

Возвращает тип объекта, упомянутого obj параметр. Параметр obj может или быть локальная, глобальная или слабая глобальная ссылка.

РЕДАКТИРОВАНИЕ:

Индекс 232 в таблице функции интерфейса JNIEnv.

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

obj: локальная, глобальная или слабая глобальная ссылка.

vm: экземпляр виртуальной машины, от которого будет получен интерфейс.

env: указатель на расположение, куда указатель на интерфейс JNI для текущего потока будет помещен.

version: требуемая версия JNI.

ВОЗВРАТЫ:

Функция GetObjectRefType возвраты одно из следующих перечисляемых значений, определенных как a jobjectRefType:

JNIInvalidRefType = 0,
JNILocalRefType = 1,
JNIGlobalRefType = 2,
JNIWeakGlobalRefType = 3

Если параметр obj слабый глобальный ссылочный тип, возврат будет JNIWeakGlobalRefType.

Если параметр obj глобальный ссылочный тип, возвращаемое значение будет JNIGlobalRefType.

Если параметр obj локальный ссылочный тип, возврат будет JNILocalRefType.

Если obj параметром не является допустимая ссылка, возвращаемое значение для этой функции будет JNIInvalidRefType.

Недопустимая ссылка является ссылкой, которая не является допустимым дескриптором. Таким образом, obj адрес указателя не указывает на расположение в памяти, которая была выделена от одного из Касательно функций создания или возвращена из функции JNI.

Также, NULL была бы недопустимая ссылка и GetObjectRefType(env,NULL) возвратился бы JNIInvalidRefType.

С другой стороны нулевая ссылка, которая является ссылкой, которая указывает на нуль, возвратила бы тип ссылки, что нулевая ссылка первоначально создавалась как.

GetObjectRefType не может использоваться на удаленных ссылках.

Так как ссылки обычно реализуются как указатели на структуры данных памяти, которые могут потенциально быть снова использованы любой из ссылочных служб выделения в VM, когда-то удаленном, он не определяется что значение GetObjectRefType возвратится.

С ТЕХ ПОР:

JDK/JRE 1.6

IsInstanceOf

jboolean IsInstanceOf(JNIEnv *env, jobject obj,
jclass clazz);

Тесты, является ли объект экземпляром класса.

РЕДАКТИРОВАНИЕ:

Индекс 32 в таблице функции интерфейса JNIEnv.

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

obj: объект Java.

clazz: объект класса Java.

ВОЗВРАТЫ:

Возвраты JNI_TRUE если obj может быть брошен к clazz; иначе, возвраты JNI_FALSE. A NULL объект может быть брошен к любому классу.

IsSameObject

jboolean IsSameObject(JNIEnv *env, jobject ref1,
jobject ref2);

Тесты, обращаются ли две ссылки к тому же самому объекту Java.

РЕДАКТИРОВАНИЕ:

Индекс 24 в таблице функции интерфейса JNIEnv.

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

ref1: объект Java.

ref2: объект Java.

ВОЗВРАТЫ:

Возвраты JNI_TRUE если ref1 и ref2 обратитесь к тому же самому объекту Java, или оба NULL; иначе, возвраты JNI_FALSE.

Доступ к Полям Объектов

GetFieldID

jfieldID GetFieldID(JNIEnv *env, jclass clazz,
const char *name, const char *sig);

Возвращает полевой ID для экземпляра (нестатическое) поле класса. Поле определяется его именем и подписью. Получить <тип> Поле и Набор <тип> семейства Field средства доступа функционируют полевые ID использования, чтобы получить объектные поля.

GetFieldID() заставляет неинициализированный класс быть инициализированным.

GetFieldID() не может использоваться, чтобы получить поле длины массива. Использовать GetArrayLength() вместо этого.

РЕДАКТИРОВАНИЕ:

Индекс 94 в таблице функции интерфейса JNIEnv.

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

clazz: объект класса Java.

name: имя поля в 0 завершенном изменило строку UTF-8.

sig: полевая подпись в 0 завершенном изменила строку UTF-8.

ВОЗВРАТЫ:

Возвращает полевой ID, или NULL если работа перестала работать.

БРОСКИ:

NoSuchFieldError: если указанное поле не может быть найдено.

ExceptionInInitializerError: если инициализатор класса перестал работать из-за исключения.

OutOfMemoryError: если система исчерпывает память.

Доберитесь <вводят> Полевые Подпрограммы

NativeType Добираются <вводят> Поле(JNIEnv *env, jobject obj,
jfieldID fieldID);

Это семейство подпрограмм средства доступа возвращает значение экземпляра (нестатическое) поле объекта. Поле к доступу определяется полевым ID, полученным, вызывая GetFieldID().

Следующая таблица описывает Получать вводят Полевое имя подпрограммы и тип результата. Следует заменить, вводят, Добираются <вводят> Поле с типом Java поля, или используют одно из фактических стандартных имен от таблицы, и заменяют NativeType соответствующим собственным типом для той подпрограммы.

 4-1a таблица Добирается <вводят> Полевое семейство Подпрограмм Средства доступа
Доберитесь вводят Полевое Имя Подпрограммы
Собственный Тип
GetObjectField()
jobject
GetBooleanField()
jboolean
GetByteField()
jbyte
GetCharField()
jchar
GetShortField()
jshort
GetIntField()
jint
GetLongField()
jlong
GetFloatField()
jfloat
GetDoubleField()
jdouble

РЕДАКТИРОВАНИЕ:

Индексы в таблице функции интерфейса JNIEnv:
 4-1b таблица Добирается <вводят> Полевое семейство Подпрограмм Средства доступа
Доберитесь вводят Полевое Имя Подпрограммы
Индекс
GetObjectField()
95
GetBooleanField()
96
GetByteField()
97
GetCharField()
98
GetShortField()
99
GetIntField()
100
GetLongField()
101
GetFloatField()
102
GetDoubleField()
103

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

obj: объект Java (не должен быть NULL).

fieldID: допустимый полевой ID.

ВОЗВРАТЫ:

Возвращает контент поля.

Набор <тип> Полевые Подпрограммы

void Набор <тип> Поле(JNIEnv *env, jobject obj, jfieldID fieldID,
NativeType value);

Это семейство подпрограмм средства доступа устанавливает значение экземпляра (нестатическое) поле объекта. Поле к доступу определяется полевым ID, полученным, вызывая GetFieldID().

Следующая таблица описывает Набор вводят Полевое имя подпрограммы и оценивают тип. Следует заменить, вводят Набор <тип> Поле с типом Java поля, или используют одно из фактических стандартных имен от таблицы, и заменяют NativeType соответствующим собственным типом для той подпрограммы.

Таблица 4-2a Набор <тип> Полевое семейство Подпрограмм Средства доступа
Набор <тип> Полевая Подпрограмма
Собственный Тип
SetObjectField()
jobject
SetBooleanField()
jboolean
SetByteField()
jbyte
SetCharField()
jchar
SetShortField()
jshort
SetIntField()
jint
SetLongField()
jlong
SetFloatField()
jfloat
SetDoubleField()
jdouble

РЕДАКТИРОВАНИЕ:

Индексы в таблице функции интерфейса JNIEnv.

Таблица 4-2b Набор <тип> Полевое семейство Подпрограмм Средства доступа
Набор <тип> Полевая Подпрограмма
Индекс
SetObjectField()
104
SetBooleanField()
105
SetByteField()
106
SetCharField()
107
SetShortField()
108
SetIntField()
109
SetLongField()
110
SetFloatField()
111
SetDoubleField()
112

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

obj: объект Java (не должен быть NULL).

fieldID: допустимый полевой ID.

value: новое значение поля.

Вызов Методов экземпляра

GetMethodID

jmethodID GetMethodID(JNIEnv *env, jclass clazz,
const char *name, const char *sig);

Возвращает ID метода для экземпляра (нестатический) метод класса или интерфейса. Метод может быть определен в одном из clazz’s суперклассы и наследованный clazz. Метод определяется его именем и подписью.

GetMethodID() заставляет неинициализированный класс быть инициализированным.

Получить ID метода конструктора, предоставления <init> как имя метода и void (V) как тип возврата.

РЕДАКТИРОВАНИЕ:

Индекс 33 в таблице функции интерфейса JNIEnv.

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

clazz: объект класса Java.

name: имя метода в 0 завершенном изменило строку UTF-8.

sig: сигнатура метода в 0 завершенном изменила строку UTF-8.

ВОЗВРАТЫ:

Возвращает ID метода, или NULL если указанный метод не может быть найден.

БРОСКИ:

NoSuchMethodError: если указанный метод не может быть найден.

ExceptionInInitializerError: если инициализатор класса перестал работать из-за исключения.

OutOfMemoryError: если система исчерпывает память.

Вызовите <вводят> Подпрограммы Метода
Вызовите <вводят> Подпрограммы MethodA
Вызовите <вводят> Подпрограммы MethodV

Вызов NativeType <тип> Метод(JNIEnv *env, jobject obj,
jmethodID methodID, ...);

Вызов NativeType <тип> MethodA(JNIEnv *env, jobject obj,
jmethodID methodID, const jvalue *args);

Вызов NativeType <тип> MethodV(JNIEnv *env, jobject obj,
jmethodID methodID, va_list args);

Методы от этих трех семейств операций используются, чтобы вызвать метод экземпляра Java от собственного метода. Они только отличаются по их механизму для того, чтобы передать параметры к методам, которые они вызывают.

Эти семейства операций вызывают экземпляр (нестатический) метод на объект Java согласно указанному ID метода. methodID параметр должен быть получен, вызывая GetMethodID().

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

Вызовите <вводят> Подпрограммы Метода

Программисты помещают все параметры, которые нужно сразу передать к методу после methodID параметр. Вызов <тип> подпрограмма Метода принимает эти параметры и передает их к методу Java, который программист хочет вызвать.

Вызовите <вводят> Подпрограммы MethodA

Программисты помещают все параметры методу в args массив jvalues это сразу следует methodID параметр. Вызов <тип>, подпрограмма MethodA принимает параметры в этом массиве, и, поочередно, передает их к методу Java, что программист хочет вызвать.

Вызовите <вводят> Подпрограммы MethodV

Программисты помещают все параметры методу в args параметр типа va_list это сразу следует methodID параметр. Вызов <тип>, подпрограмма MethodV принимает параметры, и, поочередно, передает их к методу Java, что программист хочет вызвать.

Следующая таблица описывает каждую из вызывающих подпрограмм метода согласно их типу результата. Следует заменить, вводят Вызов <тип> Метод с типом Java метода, который Вы вызываете (или используйте одно из фактических имен вызывающей подпрограммы метода от таблицы), и замените NativeType соответствующим собственным типом для той подпрограммы.

Таблица 4-3a Вызывающие подпрограммы Метода экземпляра
Вызов вводит Имя Подпрограммы Метода
Собственный Тип
CallVoidMethod()
CallVoidMethodA()
CallVoidMethodV()
пусто
CallObjectMethod()
CallObjectMethodA()
CallObjectMethodV()
jobject
CallBooleanMethod()
CallBooleanMethodA()
CallBooleanMethodV()
jboolean
CallByteMethod()
CallByteMethodA()
CallByteMethodV()
jbyte
CallCharMethod()
CallCharMethodA()
CallCharMethodV()
jchar
CallShortMethod()
CallShortMethodA()
CallShortMethodV()
jshort
CallIntMethod()
CallIntMethodA()
CallIntMethodV()
jint
CallLongMethod()
CallLongMethodA()
CallLongMethodV()
jlong
CallFloatMethod()
CallFloatMethodA()
CallFloatMethodV()
jfloat
CallDoubleMethod()
CallDoubleMethodA()
CallDoubleMethodV()
jdouble

РЕДАКТИРОВАНИЕ:

Индексы в таблице функции интерфейса JNIEnv:

Таблица 4-3b Вызывающие подпрограммы Метода экземпляра
Вызов вводит Имя Подпрограммы Метода
Индекс
CallVoidMethod()
CallVoidMethodA()
CallVoidMethodV()

61
63
62

CallObjectMethod()
CallObjectMethodA()
CallObjectMethodV()

34
36
35

CallBooleanMethod()
CallBooleanMethodA()
CallBooleanMethodV()

37
39
38

CallByteMethod()
CallByteMethodA()
CallByteMethodV()

40
42
41

CallCharMethod()
CallCharMethodA()
CallCharMethodV()

43
45
44

CallShortMethod()
CallShortMethodA()
CallShortMethodV()

46
48
47

CallIntMethod()
CallIntMethodA()
CallIntMethodV()

49
51
50

CallLongMethod()
CallLongMethodA()
CallLongMethodV()

52
54
53

CallFloatMethod()
CallFloatMethodA()
CallFloatMethodV()

55
57
56

CallDoubleMethod()
CallDoubleMethodA()
CallDoubleMethodV()

58
60
59

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

obj: объект Java.

methodID: ID метода.

Дополнительный Параметр для Вызова <тип> Подпрограммы Метода:

параметры методу Java.

Дополнительный Параметр для Вызова <тип> Подпрограммы MethodA:

args: массив параметров.

Дополнительный Параметр для Вызова <тип> Подпрограммы MethodV:

args: va_list параметров.

ВОЗВРАТЫ:

Возвращает результат вызова метода Java.

БРОСКИ:

Exceptions raised during the execution of the Java method.

CallNonvirtual <тип> Подпрограммы Метода
CallNonvirtual <тип> Подпрограммы MethodA
CallNonvirtual <тип> Подпрограммы MethodV

NativeType CallNonvirtual <тип> Метод(JNIEnv *env, jobject obj,
jclass clazz, jmethodID methodID, ...);

NativeType CallNonvirtual <тип> MethodA(JNIEnv *env, jobject obj,
jclass clazz, jmethodID methodID, const jvalue *args);

NativeType CallNonvirtual <тип> MethodV(JNIEnv *env, jobject obj,
jclass clazz, jmethodID methodID, va_list args);

Эти семейства операций вызывают экземпляр (нестатический) метод на объект Java согласно указанному классу и ID метода. methodID параметр должен быть получен, вызывая GetMethodID() на классе clazz.

CallNonvirtual <тип> семейства Method подпрограмм и Вызова <тип> семейства Method подпрограмм отличаются. Вызовите <вводят> подпрограммы Метода, вызывают метод, основанный на классе объекта, в то время как CallNonvirtual <тип> подпрограммы Метода вызывают метод, основанный на классе, определяемом clazz параметр, из которого получается ID метода. ID метода должен быть получен из реального класса объекта или от одного из его суперклассов.

CallNonvirtual <тип> Подпрограммы Метода

Программисты помещают все параметры, которые нужно сразу передать к методу после methodID параметр. CallNonvirtual <тип> подпрограмма Метода принимает эти параметры и передает их к методу Java, который программист хочет вызвать.

CallNonvirtual <тип> Подпрограммы MethodA

Программисты помещают все параметры методу в args массив jvalues это сразу следует methodID параметр. CallNonvirtual <тип>, подпрограмма MethodA принимает параметры в этом массиве, и, поочередно, передает их к методу Java, что программист хочет вызвать.

CallNonvirtual <тип> Подпрограммы MethodV

Программисты помещают все параметры методу в args параметр типа va_list это сразу следует methodID параметр. Подпрограмма CallNonvirtualMethodV принимает параметры, и, поочередно, передает их к методу Java, который программист хочет вызвать.

Следующая таблица описывает каждую из вызывающих подпрограмм метода согласно их типу результата. Следует заменить, вводят CallNonvirtual <тип> Метод с типом Java метода, или используют одно из фактических имен вызывающей подпрограммы метода от таблицы, и заменяют NativeType соответствующим собственным типом для той подпрограммы.

Таблица 4-4a CallNonvirtual <тип> Подпрограммы Метода
CallNonvirtual вводят Имя Подпрограммы Метода
Собственный Тип
CallNonvirtualVoidMethod()
CallNonvirtualVoidMethodA()
CallNonvirtualVoidMethodV()
пусто
CallNonvirtualObjectMethod()
CallNonvirtualObjectMethodA()
CallNonvirtualObjectMethodV()
jobject
CallNonvirtualBooleanMethod()
CallNonvirtualBooleanMethodA()
CallNonvirtualBooleanMethodV()
jboolean
CallNonvirtualByteMethod()
CallNonvirtualByteMethodA()
CallNonvirtualByteMethodV()
jbyte
CallNonvirtualCharMethod()
CallNonvirtualCharMethodA()
CallNonvirtualCharMethodV()
jchar
CallNonvirtualShortMethod()
CallNonvirtualShortMethodA()
CallNonvirtualShortMethodV()
jshort
CallNonvirtualIntMethod()
CallNonvirtualIntMethodA()
CallNonvirtualIntMethodV()
jint
CallNonvirtualLongMethod()
CallNonvirtualLongMethodA()
CallNonvirtualLongMethodV()
jlong
CallNonvirtualFloatMethod()
CallNonvirtualFloatMethodA()
CallNonvirtualFloatMethodV()
jfloat
CallNonvirtualDoubleMethod()
CallNonvirtualDoubleMethodA()
CallNonvirtualDoubleMethodV()
jdouble

РЕДАКТИРОВАНИЕ:

Индексы в таблице функции интерфейса JNIEnv.

Таблица 4-4b CallNonvirtual <тип> Подпрограммы Метода
CallNonvirtual вводят Имя Подпрограммы Метода
Индекс
CallNonvirtualVoidMethod()
CallNonvirtualVoidMethodA()
CallNonvirtualVoidMethodV()
91
93
92
CallNonvirtualObjectMethod()
CallNonvirtualObjectMethodA()
CallNonvirtualObjectMethodV()
64
66
65
CallNonvirtualBooleanMethod()
CallNonvirtualBooleanMethodA()
CallNonvirtualBooleanMethodV()
67
69
68
CallNonvirtualByteMethod()
CallNonvirtualByteMethodA()
CallNonvirtualByteMethodV()
70
72
71
CallNonvirtualCharMethod()
CallNonvirtualCharMethodA()
CallNonvirtualCharMethodV()
73
75
74
CallNonvirtualShortMethod()
CallNonvirtualShortMethodA()
CallNonvirtualShortMethodV()
76
78
77
CallNonvirtualIntMethod()
CallNonvirtualIntMethodA()
CallNonvirtualIntMethodV()
79
81
80
CallNonvirtualLongMethod()
CallNonvirtualLongMethodA()
CallNonvirtualLongMethodV()
82
84
83
CallNonvirtualFloatMethod()
CallNonvirtualFloatMethodA()
CallNonvirtualFloatMethodV()
85
87
86
CallNonvirtualDoubleMethod()
CallNonvirtualDoubleMethodA()
CallNonvirtualDoubleMethodV()
88
90
89

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

clazz: a Класс Java.

obj: объект Java.

methodID: ID метода.

Дополнительный Параметр для CallNonvirtual <тип> Подпрограммы Метода:

параметры методу Java.

Дополнительный Параметр для CallNonvirtual <тип> Подпрограммы MethodA:

args: массив параметров.

Дополнительный Параметр для CallNonvirtual <тип> Подпрограммы MethodV:

args: a va_list из параметров.

ВОЗВРАТЫ:

Возвращает результат вызова метода Java.

БРОСКИ:

Исключения повышаются во время выполнения метода Java.

Доступ к Статическим Полям

GetStaticFieldID

jfieldID GetStaticFieldID(JNIEnv *env, jclass clazz,
const char *name, const char *sig);

Возвращает полевой ID для статического поля класса. Поле определяется его именем и подписью. GetStatic <тип> Поле и SetStatic <тип> семейства Field средства доступа функционирует полевые ID использования, чтобы получить статические поля.

GetStaticFieldID() заставляет неинициализированный класс быть инициализированным.

РЕДАКТИРОВАНИЕ:

Индекс 144 в таблице функции интерфейса JNIEnv.

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

clazz: объект класса Java.

name: статическое имя поля в 0 завершенном изменило строку UTF-8.

sig: полевая подпись в 0 завершенном изменила строку UTF-8.

ВОЗВРАТЫ:

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

БРОСКИ:

NoSuchFieldError: если указанное статическое поле не может быть найдено.

ExceptionInInitializerError: если инициализатор класса перестал работать из-за исключения.

OutOfMemoryError: если система исчерпывает память.

GetStatic <тип> Полевые Подпрограммы

NativeType GetStatic <тип> Поле(JNIEnv *env, jclass clazz,
jfieldID fieldID);

Это семейство подпрограмм средства доступа возвращает значение статического поля объекта. Поле к доступу определяется полевым ID, который получается, вызывая GetStaticFieldID().

Следующая таблица описывает семейство, получают стандартные имена и типы результата. Следует заменить, вводят GetStatic <тип> Поле с типом Java поля, или одним из фактических статических полевых имен подпрограммы средства доступа от таблицы, и заменяют NativeType соответствующим собственным типом для той подпрограммы.

Таблица 4-5a GetStatic <тип> Полевое семейство Подпрограмм Средства доступа
GetStatic вводят Полевое Имя Подпрограммы
Собственный Тип
GetStaticObjectField()
jobject
GetStaticBooleanField()
jboolean
GetStaticByteField()
jbyte
GetStaticCharField()
jchar
GetStaticShortField()
jshort
GetStaticIntField()
jint
GetStaticLongField()
jlong
GetStaticFloatField()
jfloat
GetStaticDoubleField()
jdouble

РЕДАКТИРОВАНИЕ:

Индексы в таблице функции интерфейса JNIEnv.

Таблица 4-5b GetStatic <тип> Полевое семейство Подпрограмм Средства доступа
GetStatic вводят Полевое Имя Подпрограммы
Индекс
GetStaticObjectField()
145
GetStaticBooleanField()
146
GetStaticByteField()
147
GetStaticCharField()
148
GetStaticShortField()
149
GetStaticIntField()
150
GetStaticLongField()
151
GetStaticFloatField()
152
GetStaticDoubleField()
153

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

clazz: объект класса Java.

fieldID: статический полевой ID.

ВОЗВРАТЫ:

Возвращает контент статического поля.

SetStatic <тип> Полевые Подпрограммы

void SetStatic <тип> Поле(JNIEnv *env, jclass clazz,
jfieldID fieldID,
NativeType value);

Это семейство подпрограмм средства доступа устанавливает значение статического поля объекта. Поле к доступу определяется полевым ID, который получается, вызывая GetStaticFieldID().

Следующая таблица описывает имя подпрограммы набора и типы значения. Следует заменить, вводят SetStatic <тип> Поле с типом Java поля, или одним из фактического набора статические полевые имена подпрограммы от таблицы, и заменяют NativeType соответствующим собственным типом для той подпрограммы.

Таблица 4-6a SetStatic <тип> Полевое семейство Подпрограмм Средства доступа
SetStatic вводят Полевое Имя Подпрограммы
NativeType
SetStaticObjectField()
jobject
SetStaticBooleanField()
jboolean
SetStaticByteField()
jbyte
SetStaticCharField()
jchar
SetStaticShortField()
jshort
SetStaticIntField()
jint
SetStaticLongField()
jlong
SetStaticFloatField()
jfloat
SetStaticDoubleField()
jdouble

РЕДАКТИРОВАНИЕ:

Индексы в таблице функции интерфейса JNIEnv.

Таблица 4-6b SetStatic <тип> Полевое семейство Подпрограмм Средства доступа
SetStatic вводят Полевое Имя Подпрограммы
Индекс
SetStaticObjectField()
154
SetStaticBooleanField()
155
SetStaticByteField()
156
SetStaticCharField()
157
SetStaticShortField()
158
SetStaticIntField()
159
SetStaticLongField()
160
SetStaticFloatField()
161
SetStaticDoubleField()
162

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

clazz: объект класса Java.

fieldID: статический полевой ID.

value: новое значение поля.

Вызов Статических Методов

GetStaticMethodID

jmethodID GetStaticMethodID(JNIEnv *env, jclass clazz,
const char *name, const char *sig);

Возвращает ID метода для статического метода класса. Метод определяется его именем и подписью.

GetStaticMethodID() заставляет неинициализированный класс быть инициализированным.

РЕДАКТИРОВАНИЕ:

Индекс 113 в таблице функции интерфейса JNIEnv.

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

clazz: объект класса Java.

name: статическое имя метода в 0 завершенном изменило строку UTF-8.

sig: сигнатура метода в 0 завершенном изменила строку UTF-8.

ВОЗВРАТЫ:

Возвращает ID метода, или NULL если работа перестала работать.

БРОСКИ:

NoSuchMethodError: если указанный статический метод не может быть найден.

ExceptionInInitializerError: если инициализатор класса перестал работать из-за исключения.

OutOfMemoryError: если система исчерпывает память.

CallStatic <тип> Подпрограммы Метода
CallStatic <тип> Подпрограммы MethodA
CallStatic <тип> Подпрограммы MethodV

NativeType CallStatic <тип> Метод(JNIEnv *env, jclass clazz,
jmethodID methodID, ...);

NativeType CallStatic <тип> MethodA(JNIEnv *env, jclass clazz,
jmethodID methodID, jvalue *args);

NativeType CallStatic <тип> MethodV(JNIEnv *env, jclass clazz,
jmethodID methodID, va_list args);

Это семейство операций вызывает статический метод на объект Java согласно указанному ID метода. methodID параметр должен быть получен, вызывая GetStaticMethodID().

ID метода должен быть получен из clazz, не от одного из его суперклассов.

CallStatic <тип> Подпрограммы Метода

Программисты должны поместить все параметры, которые нужно сразу передать к методу после methodID параметр. CallStatic <тип> подпрограмма Метода принимает эти параметры и передает их к методу Java, который программист хочет вызвать.

CallStatic <тип> Подпрограммы MethodA

Программисты должны поместить все параметры методу в args массив jvalues это сразу следует methodID параметр. Подпрограмма CallStaticMethodA принимает параметры в этом массиве, и, поочередно, передает их к методу Java, который программист хочет вызвать.

CallStatic <тип> Подпрограммы MethodV

Программисты должны поместить все параметры методу в args параметр типа va_list это сразу следует methodID параметр. Подпрограмма CallStaticMethodV принимает параметры, и, поочередно, передает их к методу Java, который программист хочет вызвать.

Следующая таблица описывает каждую из вызывающих подпрограмм метода согласно их типам результата. Следует заменить, вводят CallStatic <тип> Метод с типом Java метода, или одним из фактических имен вызывающей подпрограммы метода от таблицы, и заменяют NativeType соответствующим собственным типом для той подпрограммы.

Таблица 4-7a CallStatic <тип> Вызывающие подпрограммы Метода
CallStatic вводят Имя Подпрограммы Метода
Собственный Тип
CallStaticVoidMethod()
CallStaticVoidMethodA()
CallStaticVoidMethodV()
пусто
CallStaticObjectMethod()
CallStaticObjectMethodA()
CallStaticObjectMethodV()
jobject
CallStaticBooleanMethod()
CallStaticBooleanMethodA()
CallStaticBooleanMethodV()
jboolean
CallStaticByteMethod()
CallStaticByteMethodA()
CallStaticByteMethodV()
jbyte
CallStaticCharMethod()
CallStaticCharMethodA()
CallStaticCharMethodV()
jchar
CallStaticShortMethod()
CallStaticShortMethodA()
CallStaticShortMethodV()
jshort
CallStaticIntMethod()
CallStaticIntMethodA()
CallStaticIntMethodV()
jint
CallStaticLongMethod()
CallStaticLongMethodA()
CallStaticLongMethodV()
jlong
CallStaticFloatMethod()
CallStaticFloatMethodA()
CallStaticFloatMethodV()
jfloat
CallStaticDoubleMethod()
CallStaticDoubleMethodA()
CallStaticDoubleMethodV()
jdouble

РЕДАКТИРОВАНИЕ:

Индексы в таблице функции интерфейса JNIEnv.

Таблица 4-7b CallStatic <тип> Вызывающие подпрограммы Метода
CallStatic вводят Имя Подпрограммы Метода
Индекс
CallStaticVoidMethod()
CallStaticVoidMethodA()
CallStaticVoidMethodV()
141
143
142
CallStaticObjectMethod()
CallStaticObjectMethodA()
CallStaticObjectMethodV()
114
116
115
CallStaticBooleanMethod()
CallStaticBooleanMethodA()
CallStaticBooleanMethodV()
117
119
118
CallStaticByteMethod()
CallStaticByteMethodA()
CallStaticByteMethodV()
120
122
121
CallStaticCharMethod()
CallStaticCharMethodA()
CallStaticCharMethodV()
123
125
124
CallStaticShortMethod()
CallStaticShortMethodA()
CallStaticShortMethodV()
126
128
127
CallStaticIntMethod()
CallStaticIntMethodA()
CallStaticIntMethodV()
129
131
130
CallStaticLongMethod()
CallStaticLongMethodA()
CallStaticLongMethodV()
132
134
133
CallStaticFloatMethod()
CallStaticFloatMethodA()
CallStaticFloatMethodV()
135
137
136
CallStaticDoubleMethod()
CallStaticDoubleMethodA()
CallStaticDoubleMethodV()
138
140
139

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

clazz: объект класса Java.

methodID: статический ID метода.

Дополнительный Параметр для CallStatic <тип> Подпрограммы Метода:

параметры статическому методу.

Дополнительный Параметр для CallStatic <тип> Подпрограммы MethodA:

args: массив параметров.

Дополнительный Параметр для CallStatic <тип> Подпрограммы MethodV:

args: a va_list из параметров.

ВОЗВРАТЫ:

Возвращает результат вызова статического метода Java.

БРОСКИ:

Exceptions raised during the execution of the Java method.

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

NewString

jstring NewString(JNIEnv *env, const jchar *unicodeChars,
jsize len);

Создает новое java.lang.String объект от массива символов Unicode.

РЕДАКТИРОВАНИЕ:

Индекс 163 в таблице функции интерфейса JNIEnv.

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

unicodeChars: указатель на строку Unicode.

len: длина строки Unicode.

ВОЗВРАТЫ:

Возвращает строковый объект Java, или NULL если строка не может быть создана.

БРОСКИ:

OutOfMemoryError: если система исчерпывает память.

GetStringLength

jsize GetStringLength(JNIEnv *env, jstring string);

Возвращает длину (количество символов Unicode) строки Java.

РЕДАКТИРОВАНИЕ:

Индекс 164 в таблице функции интерфейса JNIEnv.

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

string: строковый объект Java.

ВОЗВРАТЫ:

Возвращает длину строки Java.

GetStringChars

const jchar * GetStringChars(JNIEnv *env, jstring string,
jboolean *isCopy);

Возвращает указатель на массив символов Unicode строки. Этот указатель не допустим до ReleaseStringchars() вызывается.

Если isCopy не NULL, тогда *isCopy устанавливается в JNI_TRUE если копия делается; или это устанавливается в JNI_FALSE если никакая копия не делается.

РЕДАКТИРОВАНИЕ:

Индекс 165 в таблице функции интерфейса JNIEnv.

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

string: строковый объект Java.

isCopy: указатель на булевскую переменную.

ВОЗВРАТЫ:

Возвращает указатель на строку Unicode, или NULL если работа перестала работать.

ReleaseStringChars

void ReleaseStringChars(JNIEnv *env, jstring string,
const jchar *chars);

Сообщает VM, что собственный код больше не нуждается в доступе к chars. chars параметром является указатель, полученный из string использование GetStringChars().

РЕДАКТИРОВАНИЕ:

Индекс 166 в таблице функции интерфейса JNIEnv.

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

string: строковый объект Java.

chars: указатель на строку Unicode.

NewStringUTF

jstring NewStringUTF(JNIEnv *env, const char *bytes);

Создает новое java.lang.String объект от массива символов в измененном кодировании UTF-8.

РЕДАКТИРОВАНИЕ:

Индекс 167 в таблице функции интерфейса JNIEnv.

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

bytes: указатель на измененную строку UTF-8.

ВОЗВРАТЫ:

Возвращает строковый объект Java, или NULL если строка не может быть создана.

БРОСКИ:

OutOfMemoryError: если система исчерпывает память.

GetStringUTFLength

jsize GetStringUTFLength(JNIEnv *env, jstring string);

Возвращает длину в байтах измененного представления UTF-8 строки.

РЕДАКТИРОВАНИЕ:

Индекс 168 в таблице функции интерфейса JNIEnv.

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

string: строковый объект Java.

ВОЗВРАТЫ:

Возвращает длину UTF-8 строки.

GetStringUTFChars

const char * GetStringUTFChars(JNIEnv *env, jstring string,
jboolean *isCopy);

Возвращает указатель на массив байтов, представляющих строку в измененном кодировании UTF-8. Этот массив допустим, пока он не выпускается ReleaseStringUTFChars().

Если isCopy не NULL, тогда *isCopy устанавливается в JNI_TRUE если копия делается; или это устанавливается в JNI_FALSE если никакая копия не делается.

РЕДАКТИРОВАНИЕ:

Индекс 169 в таблице функции интерфейса JNIEnv.

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

string: строковый объект Java.

isCopy: указатель на булевскую переменную.

ВОЗВРАТЫ:

Возвращает указатель на измененную строку UTF-8, или NULL если работа перестала работать.

ReleaseStringUTFChars

void ReleaseStringUTFChars(JNIEnv *env, jstring string,
const char *utf);

Сообщает VM, что собственный код больше не нуждается в доступе к utf. utf параметром является указатель, полученный из string использование GetStringUTFChars().

РЕДАКТИРОВАНИЕ:

Индекс 170 в таблице функции интерфейса JNIEnv.

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

string: строковый объект Java.

utf: указатель на измененную строку UTF-8.

Отметить

В JDK/JRE 1.1, программисты могут получить примитивные элементы массива в предоставленном пользователем буфере. С JDK/JRE 1.2 дополнительных набора функций обеспечиваются, позволяя собственный код получить символы в Unicode (UTF-16) или изменяются UTF-8, кодирующий в предоставленном пользователем буфере. См. функции ниже.

GetStringRegion

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

Копии len число символов Unicode, начинающихся при смещении start к данному буферу buf.

Броски StringIndexOutOfBoundsException на индексном переполнении.

РЕДАКТИРОВАНИЕ:

Индекс 220 в таблице функции интерфейса JNIEnv.

С ТЕХ ПОР:

JDK/JRE 1.2

GetStringUTFRegion

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

Преобразовывает len число символов Unicode, начинающихся при смещении start в измененное кодирование UTF-8 и место результат в данном буфере buf.

Броски StringIndexOutOfBoundsException на индексном переполнении.

РЕДАКТИРОВАНИЕ:

Индекс 221 в таблице функции интерфейса JNIEnv.

С ТЕХ ПОР:

JDK/JRE 1.2

GetStringCritical
ReleaseStringCritical

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

Семантика этих двух функций подобна существующему Get/ReleaseStringChars функции. Если возможный, VM возвращает указатель, чтобы представить элементы в виде строки; иначе, копия делается. Однако, есть существенные ограничения на то, как эти функции могут использоваться. В сегменте кода, включенном Get/ReleaseStringCritical вызовы, собственный код не должен издать произвольные приказы JNI, или заставить текущий поток блокировать.

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

РЕДАКТИРОВАНИЕ (GetStringCritical):

Индекс 224 в таблице функции интерфейса JNIEnv.

РЕДАКТИРОВАНИЕ (ReleaseStingCritical):

Индекс 225 в таблице функции интерфейса JNIEnv.

С ТЕХ ПОР:

JDK/JRE 1.2

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

GetArrayLength

jsize GetArrayLength(JNIEnv *env, jarray array);

Возвращает число элементов в массиве.

РЕДАКТИРОВАНИЕ:

Индекс 171 в таблице функции интерфейса JNIEnv.

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

array: объект массива Java.

ВОЗВРАТЫ:

Возвращает длину массива.

NewObjectArray

jobjectArray NewObjectArray(JNIEnv *env, jsize length,
jclass elementClass, jobject initialElement);

Создает новый массив, содержащий объекты в классе elementClass. Все элементы первоначально устанавливаются в initialElement.

РЕДАКТИРОВАНИЕ:

Индекс 172 в таблице функции интерфейса JNIEnv.

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

length: размер массива.

elementClass: класс элемента массива.

initialElement: значение инициализации.

ВОЗВРАТЫ:

Возвращает объект массива Java, или NULL если массив не может быть создан.

БРОСКИ:

OutOfMemoryError: если система исчерпывает память.

GetObjectArrayElement

jobject GetObjectArrayElement(JNIEnv *env,
jobjectArray array, jsize index);

Возвращает элемент Object массив.

РЕДАКТИРОВАНИЕ:

Индекс 173 в таблице функции интерфейса JNIEnv.

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

array: массив Java.

index: индекс массива.

ВОЗВРАТЫ:

Возвращает объект Java.

БРОСКИ:

ArrayIndexOutOfBoundsException: если index не определяет допустимый индекс в массиве.

SetObjectArrayElement

void SetObjectArrayElement(JNIEnv *env, jobjectArray array,
jsize index, jobject value);

Устанавливает элемент Object массив.

РЕДАКТИРОВАНИЕ:

Индекс 174 в таблице функции интерфейса JNIEnv.

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

array: массив Java.

index: индекс массива.

value: новое значение.

БРОСКИ:

ArrayIndexOutOfBoundsException: если index не определяет допустимый индекс в массиве.

ArrayStoreException: если класс value не подкласс класса элемента массива.

Новый <PrimitiveType> Подпрограммы Массива

ArrayType, Новый <PrimitiveType> Массив(JNIEnv *env, jsize length);

Семейство операций, используемых, чтобы создать новый примитивный объект массива.  Таблица 4-8 описывает определенных примитивных конструкторов массива. Следует заменить Новый <PrimitiveType> Массив с одним из фактических примитивных имен подпрограммы конструктора массива от следующей таблицы, и заменить ArrayType соответствующим типом массива для той подпрограммы.

Таблица , 4-8a Новый <PrimitiveType> семейство Массива Конструкторов Массива
Новый <PrimitiveType> Подпрограммы Массива
Тип массива
NewBooleanArray()
jbooleanArray
NewByteArray()
jbyteArray
NewCharArray()
jcharArray
NewShortArray()
jshortArray
NewIntArray()
jintArray
NewLongArray()
jlongArray
NewFloatArray()
jfloatArray
NewDoubleArray()
jdoubleArray

РЕДАКТИРОВАНИЕ:

Индексы в таблице функции интерфейса JNIEnv.

Таблица , 4-8b Новый <PrimitiveType> семейство Массива Конструкторов Массива
Новый <PrimitiveType> Подпрограммы Массива
Индекс
NewBooleanArray()
175
NewByteArray()
176
NewCharArray()
177
NewShortArray()
178
NewIntArray()
179
NewLongArray()
180
NewFloatArray()
181
NewDoubleArray()
182

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

length: длина массива.

ВОЗВРАТЫ:

Возвращает массив Java, или NULL если массив не может быть создан.

Получите Подпрограммы ArrayElements <PrimitiveType>

NativeType *Получите ArrayElements <PrimitiveType>(JNIEnv *env,
ArrayType array, jboolean *isCopy);

Семейство функций, которое возвращает тело примитивного массива. Результат допустим до соответствующего Выпуска<PrimitiveType>ArrayElements () функция вызывают. Так как возвращенный массив может быть копией массива Java, изменения, произведенные в возвращенном массиве, будут не обязательно отражены в оригинале array до Release<PrimitiveType>ArrayElements() вызывается.

Если isCopy не NULL, тогда *isCopy устанавливается в JNI_TRUE если копия делается; или это устанавливается в JNI_FALSE если никакая копия не делается.

Следующая таблица описывает определенные примитивные средства доступа элемента массива. Следует сделать следующие замены:

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

 4-9a таблица Получает семейство ArrayElements <PrimitiveType> Подпрограмм Средства доступа
Получите Подпрограммы ArrayElements <PrimitiveType>
Тип массива
Собственный Тип
GetBooleanArrayElements()
jbooleanArray
jboolean
GetByteArrayElements()
jbyteArray
jbyte
GetCharArrayElements()
jcharArray
jchar
GetShortArrayElements()
jshortArray
jshort
GetIntArrayElements()
jintArray
jint
GetLongArrayElements()
jlongArray
jlong
GetFloatArrayElements()
jfloatArray
jfloat
GetDoubleArrayElements()
jdoubleArray
jdouble

РЕДАКТИРОВАНИЕ:

Индексы в таблице функции интерфейса JNIEnv.

 4-9b таблица Получает семейство ArrayElements <PrimitiveType> Подпрограмм Средства доступа
Получите Подпрограммы ArrayElements <PrimitiveType>
Индекс
GetBooleanArrayElements()
183
GetByteArrayElements()
184
GetCharArrayElements()
185
GetShortArrayElements()
186
GetIntArrayElements()
187
GetLongArrayElements()
188
GetFloatArrayElements()
189
GetDoubleArrayElements()
190

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

array: строковый объект Java.

isCopy: указатель на булевскую переменную.

ВОЗВРАТЫ:

Возвращает указатель на элементы массива, или NULL если работа перестала работать.

Выпуск <PrimitiveType> Подпрограммы ArrayElements

void Выпуск <PrimitiveType> ArrayElements(JNIEnv *env,
ArrayType array, NativeType *elems, jint mode);

Семейство функций, которое сообщает VM, что собственный код больше не нуждается в доступе к elems. elems параметром является указатель, полученный из array использование соответствия Добирается<PrimitiveType>ArrayElements () функция. В случае необходимости эта функция копирует назад все изменения, произведенные в elems исходному массиву.

mode параметр предоставляет информацию о том, как буфер массива должен быть выпущен. mode не имеет никакого эффекта если elems не копия элементов в array. Иначе, mode оказывает следующее влияние, как показано в следующей таблице:

 Таблица 4-10 Примитивные Режимы Выпуска Массива
режим
действия
0
скопируйте поддерживают контент и освобождают elems буфер
JNI_COMMIT
скопируйте поддерживают контент, но не освобождают elems буфер
JNI_ABORT
освободите буфер, не копируя назад возможные изменения

В большинстве случаев программисты передают “0” к mode параметр, чтобы гарантировать непротиворечивое поведение и для прикрепленных и для скопированных массивов. Другие опции дают программисту больше контроля управлением памятью и должны использоваться с большой осторожностью.

Следующая таблица описывает определенные подпрограммы, которые включают семейство примитивных устройств обработки отходов массива. Следует сделать следующие замены:

Таблица 4-11a Выпуск <PrimitiveType> семейство ArrayElements Подпрограмм Массива
Выпуск <PrimitiveType> Подпрограммы ArrayElements
Тип массива
Собственный Тип
ReleaseBooleanArrayElements()
jbooleanArray
jboolean
ReleaseByteArrayElements()
jbyteArray
jbyte
ReleaseCharArrayElements()
jcharArray
jchar
ReleaseShortArrayElements()
jshortArray
jshort
ReleaseIntArrayElements()
jintArray
jint
ReleaseLongArrayElements()
jlongArray
jlong
ReleaseFloatArrayElements()
jfloatArray
jfloat
ReleaseDoubleArrayElements()
jdoubleArray
jdouble

РЕДАКТИРОВАНИЕ:

Индексы в таблице функции интерфейса JNIEnv.

Таблица 4-11b Выпуск <PrimitiveType> семейство ArrayElements Подпрограмм Массива
Выпуск <PrimitiveType> Подпрограммы ArrayElements
Индекс
ReleaseBooleanArrayElements()
191
ReleaseByteArrayElements()
192
ReleaseCharArrayElements()
193
ReleaseShortArrayElements()
194
ReleaseIntArrayElements()
195
ReleaseLongArrayElements()
196
ReleaseFloatArrayElements()
197
ReleaseDoubleArrayElements()
198

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

array: объект массива Java.

elems: указатель, чтобы выстроить элементы.

mode: режим выпуска.

Получите Подпрограммы ArrayRegion <PrimitiveType>

пусто Получите ArrayRegion <PrimitiveType>(JNIEnv *env, ArrayType array,
jsize start, jsize len,
NativeType *buf);

Семейство функций, которое копирует область примитивного массива в буфер.

Следующая таблица описывает определенные примитивные средства доступа элемента массива. Следует сделать следующие замены:

 4-12a таблица Получает семейство ArrayRegion <PrimitiveType> Подпрограмм Средства доступа Массива
Получите Подпрограмму ArrayRegion <PrimitiveType>
Тип массива
Собственный Тип
GetBooleanArrayRegion()
jbooleanArray
jboolean
GetByteArrayRegion()
jbyteArray
jbyte
GetCharArrayRegion()
jcharArray
jchar
GetShortArrayRegion()
jshortArray
jhort
GetIntArrayRegion()
jintArray
jint
GetLongArrayRegion()
jlongArray
jlong
GetFloatArrayRegion()
jfloatArray
jloat
GetDoubleArrayRegion()
jdoubleArray
jdouble

РЕДАКТИРОВАНИЕ:

Индексы в таблице функции интерфейса JNIEnv.

 4-12b таблица Получает семейство ArrayRegion <PrimitiveType> Подпрограмм Средства доступа Массива
Получите Подпрограмму ArrayRegion <PrimitiveType>
Индекс
GetBooleanArrayRegion()
199
GetByteArrayRegion()
200
GetCharArrayRegion()
201
GetShortArrayRegion()
202
GetIntArrayRegion()
203
GetLongArrayRegion()
204
GetFloatArrayRegion()
205
GetDoubleArrayRegion()
206

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

array: массив Java.

start: начальное значение индекса.

len: число элементов, которое будет скопировано.

buf: целевой буфер.

БРОСКИ:

ArrayIndexOutOfBoundsException: если один из индексов в области не допустим.

Набор <PrimitiveType> Подпрограммы ArrayRegion

void Набор <PrimitiveType> ArrayRegion(JNIEnv *env, ArrayType array,
jsize start, jsize len,
константа NativeType *buf);

Семейство функций, которое копирует назад область примитивного массива от буфера.

Следующая таблица описывает определенные примитивные средства доступа элемента массива. Следует сделать следующие замены:

РЕДАКТИРОВАНИЕ:

Индексы в таблице функции интерфейса JNIEnv.

Таблица 4-13b Набор <PrimitiveType> семейство ArrayRegion Подпрограмм Средства доступа Массива
Набор <PrimitiveType> Подпрограмма ArrayRegion
Индекс
SetBooleanArrayRegion()
207
SetByteArrayRegion()
208
SetCharArrayRegion()
209
SetShortArrayRegion()
210
SetIntArrayRegion()
211
SetLongArrayRegion()
212
SetFloatArrayRegion()
213
SetDoubleArrayRegion()
214

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

array: массив Java.

start: начальное значение индекса.

len: число элементов, которое будет скопировано.

buf: исходный буфер.

БРОСКИ:

ArrayIndexOutOfBoundsException: если один из индексов в области не допустим.

Отметить

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

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

GetPrimitiveArrayCritical
ReleasePrimitiveArrayCritical

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

Семантика этих двух функций очень подобна существующему Get/Release<primitivetype>ArrayElements functions. If possible, the VM returns a pointer to the primitive array; otherwise, a copy is made. However, there are significant restrictions on how these functions can be used.

После вызова 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 для возможного из ситуаций с памятью.

РЕДАКТИРОВАНИЕ (GetPrimitiveArrayCritical):

Индекс 222 редактирования в таблице функции интерфейса JNIEnv.

РЕДАКТИРОВАНИЕ (ReleasePrimitiveArrayCritical):

Индекс 223 редактирования в таблице функции интерфейса JNIEnv.

С ТЕХ ПОР:

JDK/JRE 1.2

Регистрация Собственных Методов

RegisterNatives

jint RegisterNatives(JNIEnv *env, jclass clazz,
const JNINativeMethod *methods, jint nMethods);

Регистрирует собственные методы в классе, определенном clazz параметр. methods параметр определяет массив JNINativeMethod структуры, которые содержат имена, подписи, и указатели функции собственных методов. name и signature поля структуры JNINativeMethod являются указателями на измененные строки UTF-8. nMethods параметр определяет число собственных методов в массиве. JNINativeMethod структура определяется следующим образом:

typedef struct { 

    char *name; 

    char *signature; 

    void *fnPtr; 

} JNINativeMethod; 

У указателей функции номинально должна быть следующая подпись:

ReturnType (*fnPtr)(JNIEnv *env, jobject objectOrClass, ...); 

РЕДАКТИРОВАНИЕ:

Индекс 215 в таблице функции интерфейса JNIEnv.

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

clazz: объект класса Java.

methods: собственные методы в классе.

nMethods: число собственных методов в классе.

ВОЗВРАТЫ:

Возвраты “0” на успехе; возвращает отрицательную величину при отказе.

БРОСКИ:

NoSuchMethodError: если указанный метод не может быть найден или если метод не является собственным.

UnregisterNatives

jint UnregisterNatives(JNIEnv *env, jclass clazz);

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

Эта функция не должна использоваться в нормальном собственном коде. Вместо этого это обеспечивает специальные программы способ перезагрузить и повторно соединить собственные библиотеки.

РЕДАКТИРОВАНИЕ:

Индекс 216 в таблице функции интерфейса JNIEnv.

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

clazz: объект класса Java.

ВОЗВРАТЫ:

Возвраты “0” на успехе; возвращает отрицательную величину при отказе.

Операции монитора

MonitorEnter

jint MonitorEnter(JNIEnv *env, jobject obj);

Вводит монитор, связанный с базовым объектом Java, упомянутым obj.

Вводит монитор, связанный с объектом, упомянутым obj. obj ссылка не должна быть NULL.

Каждому объекту Java связали монитор с этим. Если текущему потоку уже принадлежит монитор, связанный с obj, это постепенно увеличивает счетчик в мониторе, указывающем на число раз, этот поток ввел монитор. Если монитор, связанный с obj не принадлежит никакому потоку, текущий поток становится владельцем монитора, устанавливая количество записи этого монитора к 1. Если другому потоку уже принадлежит монитор, связанный с obj, текущий поток ожидает, пока монитор не выпускается, затем попробовал еще раз получать владение.

Монитор вошел через a MonitorEnter Из вызова функции JNI нельзя выйти, используя monitorexit Инструкция виртуальной машины Java или синхронизируемый возврат метода. A MonitorEnter Вызов функции JNI и a monitorenter Инструкция виртуальной машины Java может мчаться, чтобы ввести монитор, связанный с тем же самым объектом.

Избегать мертвых блокировок, монитор, вводимый через a MonitorEnter Из вызова функции JNI нужно выйти, используя MonitorExit Вызов JNI, если DetachCurrentThread вызов используется, чтобы неявно выпустить мониторы JNI.

РЕДАКТИРОВАНИЕ:

Индекс 217 в таблице функции интерфейса JNIEnv.

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

obj: нормальный объект Java или объект класса.

ВОЗВРАТЫ:

Возвраты “0” на успехе; возвращает отрицательную величину при отказе.

MonitorExit

jint MonitorExit(JNIEnv *env, jobject obj);

Текущий поток должен быть владельцем монитора, связанного с базовым объектом Java, упомянутым obj. Поток постепенно уменьшает счетчик, указывающий на число раз, это ввело этот монитор. Если значение счетчика становится нулем, текущий поток выпускает монитор.

Собственный код не должен использовать MonitorExit выходить из монитора, вводимого через синхронизируемый метод или a monitorenter Инструкция виртуальной машины Java.

РЕДАКТИРОВАНИЕ:

Индекс 218 в таблице функции интерфейса JNIEnv.

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

obj: нормальный объект Java или объект класса.

ВОЗВРАТЫ:

Возвраты “0” на успехе; возвращает отрицательную величину при отказе.

ИСКЛЮЧЕНИЯ:

IllegalMonitorStateException: если текущему потоку не принадлежит монитор.

Поддержка NIO

NIO-связанные точки входа позволяют собственный код доступу java.nio прямые буферы. Содержание прямого буфера может, потенциально, находиться в собственной памяти за пределами собранной "мусор" "кучи" дежурного блюда. Для получения информации о прямых буферах, пожалуйста, см. Новые API ввода-вывода и спецификацию класса java.nio.ByteBuffer.

Три новых функции, представленные в JDK/JRE 1.4, позволяют коду JNI создавать, исследовать, и управлять прямыми буферами:

Каждая реализация виртуальной машины Java должна поддерживать эти функции, но не каждая реализация обязан поддерживать доступ JNI к прямым буферам. Если JVM не поддерживает такой доступ тогда, NewDirectByteBuffer и функции GetDirectBufferAddress должны всегда возвращать NULL, и функция GetDirectBufferCapacity должна всегда возвращать -1. Если JVM действительно поддерживает такой доступ тогда, эти три функции должны быть реализованы, чтобы возвратить соответствующие значения.

NewDirectByteBuffer

jobject NewDirectByteBuffer(JNIEnv* env, void* address, jlong capacity);

Выделяет и возвращается, прямой java.nio.ByteBuffer, обращающийся к блоку памяти, запускающейся в памяти, адресуют address и расширяющий байты capacity.

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

РЕДАКТИРОВАНИЕ:

Индекс 229 в таблице функции интерфейса JNIEnv.

ПАРАМЕТРЫ:

env: указатель на интерфейс JNIEnv

address: начальный адрес области памяти (не должен быть NULL),

capacity: размер в байтах области памяти (должно быть положительным),

ВОЗВРАТЫ:

Возвращает локальную ссылку на недавно инстанцированный объект java.nio.ByteBuffer. NULL возвратов, если исключение происходит, или если доступ JNI к прямым буферам не поддерживается этой виртуальной машиной.

ИСКЛЮЧЕНИЯ:

OutOfMemoryError: если выделение ByteBuffer возражает сбоям

С ТЕХ ПОР:

JDK/JRE 1.4

GetDirectBufferAddress

void* GetDirectBufferAddress(JNIEnv* env, jobject buf);

На выборки и возвраты начальный адрес области памяти ссылается данный прямой java.nio.Buffer.

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

РЕДАКТИРОВАНИЕ:

Индекс 230 в таблице функции интерфейса JNIEnv.

ПАРАМЕТРЫ:

env: указатель на интерфейс JNIEnv

buf: прямой объект java.nio.Buffer (не должен быть NULL),

ВОЗВРАТЫ:

Возвращает начальный адрес области памяти, на которую ссылается буфер. NULL возвратов, если область памяти неопределена, если данным объектом не является прямой java.nio.Buffer, или если доступ JNI к прямым буферам не поддерживается этой виртуальной машиной.

С ТЕХ ПОР:

JDK/JRE 1.4

GetDirectBufferCapacity

jlong GetDirectBufferCapacity(JNIEnv* env, jobject buf);

На выборки и возвраты емкость области памяти ссылается данный прямой java.nio.Buffer. Емкость является числом элементов, которое содержит область памяти.

РЕДАКТИРОВАНИЕ:

Индекс 231 в таблице функции интерфейса JNIEnv.

ПАРАМЕТРЫ:

env: указатель на интерфейс JNIEnv

buf: прямой объект java.nio.Buffer (не должен быть NULL),

ВОЗВРАТЫ:

Возвращает емкость области памяти, связанной с буфером. -1 возвратов, если данным объектом не является прямой java.nio.Buffer, если объект является невыровненным буфером представления и архитектурой процессора, не поддерживает невыровненный доступ, или если доступ JNI к прямым буферам не поддерживается этой виртуальной машиной.

С ТЕХ ПОР:

JDK/JRE 1.4

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

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

FromReflectedMethod

jmethodID FromReflectedMethod(JNIEnv *env, jobject method);

Преобразовывает a java.lang.reflect.Method или java.lang.reflect.Constructor возразите против ID метода.

РЕДАКТИРОВАНИЕ:

Индекс 7 в таблице функции интерфейса JNIEnv.

С ТЕХ ПОР:

JDK/JRE 1.2

FromReflectedField

jfieldID FromReflectedField(JNIEnv *env, jobject field);

Преобразовывает a java.lang.reflect.Field к полевому ID.

РЕДАКТИРОВАНИЕ:

Индекс 8 в таблице функции интерфейса JNIEnv.

С ТЕХ ПОР:

JDK/JRE 1.2

ToReflectedMethod

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

Преобразовывает ID метода, полученный из cls к a java.lang.reflect.Method или java.lang.reflect.Constructor объект. isStatic должен быть установлен в JNI_TRUE если ID метода обращается к статическому полю, и JNI_FALSE иначе.

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

РЕДАКТИРОВАНИЕ:

Индекс 9 в таблице функции интерфейса JNIEnv.

С ТЕХ ПОР:

JDK/JRE 1.2

ToReflectedField

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

Преобразовывает полевой ID, полученный из cls к a java.lang.reflect.Field объект. isStatic должен быть установлен в JNI_TRUE если fieldID обращается к статическому полю, и JNI_FALSE иначе.

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

РЕДАКТИРОВАНИЕ:

Индекс 12 в таблице функции интерфейса JNIEnv.

С ТЕХ ПОР:

JDK/JRE 1.2

Java Интерфейс VM

GetJavaVM

jint GetJavaVM(JNIEnv *env, JavaVM **vm);

Возвращает Java интерфейс VM (используемый в API Вызова) связанный с текущим потоком. Результат помещается в расположение, на которое указывает второй параметр, vm.

РЕДАКТИРОВАНИЕ:

Индекс 219 в таблице функции интерфейса JNIEnv.

ПАРАМЕТРЫ:

env: указатель на интерфейс JNI.

vm: указатель туда, где результат должен быть помещен.

ВОЗВРАТЫ:

Возвраты “0” на успехе; возвращает отрицательную величину при отказе.

 


Содержание | Предыдущий | Следующий

Oracle и/или его филиалы Авторское право © 1993, 2011, Oracle и/или его филиалы. Все права защищены.
Свяжитесь с Нами