A.4.4 Функции интерфейса Java

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

jobj = javaObject (имя_класса)

jobj = javaObject (имя_класса, arg1, …)

Создаёт объект Java класса имя_класса, вызывая конструктор класса с аргументами arg1, …

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

x = javaObject ("java.lang.StringBuffer")
x = javaObject ("java.lang.StringBuffer", "Initial string")

См. также: javaMethod, javaArray.

jary = javaArray (имя_класса, размер)

jary = javaArray (имя_класса, m, n, …)

Создаёт массив Java размером размер с элементами класса имя_класса.

имя_класса может быть объектом Java, представляющим класс, или строкой, содержащей полное имя класса. Размер объекта также может быть указан отдельными целочисленными аргументами m, n и т. д.

Созданный массив не инициализирован. Все элементы установлены в null, если имя_класса — тип ссылки, или в значение по умолчанию (обычно 0), если имя_класса — примитивный тип.

Пример кода:

jary = javaArray ("java.lang.String", 2, 2);
jary(1,1) = "Hello";

См. также: javaObject.

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

isjava (x)

Возвращает true, если x является объектом Java.

См. также: class, typeinfo, isa, javaObject.

После создания объекта естественно узнать, какие поля у объекта есть, и читать (получать) и записывать (устанавливать) их.

В Octave функция fieldnames для структур перегружена, чтобы возвращать поля объекта Java. Например:

dobj = javaObject ("java.lang.Double", pi);
fieldnames (dobj)
⇒
{
  [1,1] = public static final double java.lang.Double.POSITIVE_INFINITY
  [1,2] = public static final double java.lang.Double.NEGATIVE_INFINITY
  [1,3] = public static final double java.lang.Double.NaN
  [1,4] = public static final double java.lang.Double.MAX_VALUE
  [1,5] = public static final double java.lang.Double.MIN_NORMAL
  [1,6] = public static final double java.lang.Double.MIN_VALUE
  [1,7] = public static final int java.lang.Double.MAX_EXPONENT
  [1,8] = public static final int java.lang.Double.MIN_EXPONENT
  [1,9] = public static final int java.lang.Double.SIZE
  [1,10] = public static final java.lang.Class java.lang.Double.TYPE
}

Аналогия объектов со структурами сохраняется при чтении и записи полей объекта. Для чтения поля к объекту применяется оператор ‘.’ из структур. Это предпочтительный метод для чтения полей, но Octave также предоставляет функциональный интерфейс для чтения полей с помощью java_get. Ниже показан пример обоих стилей.

dobj = javaObject ("java.lang.Double", pi);
dobj.MAX_VALUE
⇒  1.7977e+308
java_get ("java.lang.Float", "MAX_VALUE")
⇒  3.4028e+38

val = java_get (obj, имя)

Получить значение поля имя объекта Java obj.

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

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

java_get (x, "field1")
  x.field1

См. также: java_set, javaMethod, javaObject.

obj = java_set (obj, имя, значение)

Установить значение поля имя объекта Java obj на значение.

Для статических полей obj может быть строкой, представляющей полное квалифицированное имя соответствующего класса Java.

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

java_set (x, "field1", val)
  x.field1 = val

См. также: java_get, javaMethod, javaObject.

Чтобы узнать, какие функции можно вызывать с объектом, используйте methods. Например, используя ранее созданный dobj:

methods (dobj)
⇒
Methods for class java.lang.Double:
boolean equals(java.lang.Object)
java.lang.String toString(double)
java.lang.String toString()
…

Для вызова метода объекта используется тот же оператор индексации в стиле структур ‘.’. Octave также предоставляет функциональный интерфейс для вызова методов объекта с помощью javaMethod. Пример, показывающий оба стиля, приведён ниже.

dobj = javaObject ("java.lang.Double", pi);
dobj.equals (3)
⇒  0
javaMethod ("equals", dobj, pi)
⇒  1

ret = javaMethod (имя_метода, obj)

ret = javaMethod (имя_метода, obj, arg1, …)

Вызывает метод имя_метода на объекте Java obj с аргументами arg1, ….

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

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

ret = javaMethod ("method1", x, 1.0, "a string")
  ret = x.method1 (1.0, "a string")

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

См. также: methods, javaObject.

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

javaclasspath ()

dpath = javaclasspath ()

[dpath, spath] = javaclasspath ()

clspath = javaclasspath (что)

Возвращает путь класса виртуальной машины Java в виде массива строк.

Если вызывается без входных параметров:

• Если выходные значения не запрашиваются, динамический и статический пути класса выводятся в стандартный вывод.
• Если запрашивается одно выходное значение dpath, результатом является динамический путь класса.
• Если запрашиваются два выходных значения dpath и spath, первая переменная будет содержать динамический путь класса, а вторая — статический путь класса.

Если вызывается с единственным входным параметром что:

"-dynamic"

Возвращает динамический путь класса.

"-static"

Возвращает статический путь класса.

"-all"

Возвращает и статический, и динамический пути класса в одном cellstr.

См. также: javaaddpath, javarmpath.

javaaddpath (clspath)

javaaddpath (clspath1, …)

Добавляет clspath к динамическому пути класса виртуальной машины Java.

clspath может быть либо каталогом, где находятся файлы .class, либо файлом .jar, содержащим классы Java. Несколько путей можно добавить сразу, указав дополнительные аргументы.

См. также: javarmpath, javaclasspath.

javarmpath (clspath)

javarmpath (clspath1, …)

Удаляет clspath из динамического пути класса виртуальной машины Java.

clspath может быть либо каталогом, где находятся файлы .class, либо файлом .jar, содержащим классы Java. Несколько путей можно удалить сразу, указав дополнительные аргументы.

См. также: javaaddpath, javaclasspath.

Следующие функции предоставляют информацию и управление интерфейсом между Octave и виртуальной машиной Java.

javachk (функция)

javachk (функция, вызывающий)

msg = javachk (…)

Проверяет наличие Java функции в текущем сеансе. Возвращает структуру ошибки, если функция недоступна, отключена или не распознана.

Возможные распознанные функции:

"awt"

Набор инструментов абстрактного окна для графических интерфейсов пользователя.

"desktop"

Интерактивная рабочая среда запущена.

"jvm"

Виртуальная машина Java.

"swing"

Компоненты Swing для лёгких графических интерфейсов пользователя.

Если функция не поддерживается, возвращается скалярная структура с полями "message" и "identifier". Поле "message" содержит сообщение об ошибке, упоминающее функцию, а также необязательный указанный пользователем вызывающий. Эта структура подходит для передачи в функцию error.

Если функция поддерживается и доступна, возвращается пустой массив структур с полями "message" и "identifier".

javachk определяет, доступны ли определённые функции Java в сеансе Octave. Эта функция предоставляется для скриптов, которые могут изменять своё поведение в зависимости от доступности Java или определённых функций среды выполнения Java.

Примечание по совместимости: функция "desktop" никогда не доступна, так как у Octave нет графического интерфейса пользователя на основе Java.

См. также: usejava, error.

usejava (функция)

Возвращает true, если элемент Java функция доступен.

Возможные функции:

"awt"

Набор инструментов абстрактного окна для графических интерфейсов пользователя.

"desktop"

Интерактивная рабочая среда запущена.

"jvm"

Виртуальная машина Java.

"swing"

Компоненты Swing для лёгких графических интерфейсов пользователя.

usejava определяет, доступны ли определённые функции Java в сеансе Octave. Эта функция предоставляется для скриптов, которые могут изменять своё поведение в зависимости от доступности Java. Функция "desktop" всегда возвращает false, так как у Octave нет графического интерфейса пользователя на основе Java. Другие функции могут быть доступны, если Octave был скомпилирован с интерфейсом Java, и Java установлен.

См. также: javachk.

javamem ()

jmem = javamem ()

Показывает текущее использование памяти виртуальной машины Java (JVM) и запускает сборщик мусора.

Если не задан возвращаемый аргумент, информация выводится на экран. В противном случае, ячейка вывода jmem содержит максимальный, общий и свободный объём памяти (в байтах).

Все Java-базированные функции выполняются в общем пуле памяти JVM, выделенной и отдельной части памяти, запрошенной JVM у вашей системы (которая включает физическую оперативную память и виртуальную память/свайп-пространство на жестком диске).

Максимально допустимое использование памяти можно настроить, используя файл java.opts. Директория, где находится этот файл, определяется переменной среды OCTAVE_JAVA_DIR. Если она не задана, используется директория, в которой находится javaaddpath.m (обычно OCTAVE_HOME/share/octave/OCTAVE_VERSION/m/java/).

java.opts — это текстовый файл с одним параметром на строке. Можно переопределить начальный размер памяти по умолчанию и максимальный размер памяти по умолчанию (которые зависят от системы) следующим образом:

-Xms64m

-Xmx512m

(в мегабайтах в этом примере). Вы можете адаптировать эти значения к своим потребностям, если ваша система имеет ограниченный объём физической памяти или если у вас возникают ошибки памяти Java.

"Total memory" — это то, что в данный момент операционная система назначила JVM, и зависит от фактического и активного использования памяти. "Free memory" — это самоочевидный параметр. Во время работы Java-базированных функций Octave количество общей и свободной памяти будет меняться, из-за собственных операций очистки Java и управления памятью вашей операционной системы.

val = java_matrix_autoconversion ()

old_val = java_matrix_autoconversion (new_val)

java_matrix_autoconversion (new_val, "local")

Запрос или установка внутренней переменной, которая управляет автоматическим преобразованием массивов Java в матрицы Octave.

Значение по умолчанию — false.

Когда вызывается изнутри функции с опцией "local", переменная изменяется локально для функции и всех вызываемых ею подпрограмм. Исходное значение переменной восстанавливается при выходе из функции.

См. также: java_unsigned_autoconversion, debug_java.

val = java_unsigned_autoconversion ()

old_val = java_unsigned_autoconversion (new_val)

java_unsigned_autoconversion (new_val, "local")

Запрос или установка внутренней переменной, которая управляет преобразованием целочисленных классов при включённом java_matrix_autoconversion.

При включении массивы Java класса Byte или Integer преобразуются в матрицы класса uint8 или uint32 соответственно. Значение по умолчанию — true.

Когда вызывается изнутри функции с опцией "local", переменная изменяется локально для функции и всех вызываемых ею подпрограмм. Исходное значение переменной восстанавливается при выходе из функции.

См. также: java_matrix_autoconversion, debug_java.

val = debug_java ()

old_val = debug_java (new_val)

debug_java (new_val, "local")

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

Когда вызывается изнутри функции с опцией "local", переменная изменяется локально для функции и всех вызываемых ею подпрограмм. Исходное значение переменной восстанавливается при выходе из функции.

См. также: java_matrix_autoconversion, java_unsigned_autoconversion.