GNU Octave  6.2.0
A high-level interpreted language, primarily intended for numerical computations, mostly compatible with Matlab
ov-java.cc File Reference

Provides Octave's Java interface. More...

#include <algorithm>
#include <fstream>
#include <map>
#include <string>
#include <vector>
#include <clocale>
#include "Cell.h"
#include "builtin-defun-decls.h"
#include "cmd-edit.h"
#include "defaults.h"
#include "defun.h"
#include "error.h"
#include "errwarn.h"
#include "file-ops.h"
#include "file-stat.h"
#include "fpucw-wrappers.h"
#include "interpreter.h"
#include "interpreter-private.h"
#include "load-path.h"
#include "lo-sysdep.h"
#include "oct-env.h"
#include "oct-process.h"
#include "oct-shlib.h"
#include "ov-java.h"
#include "parse.h"
#include "variables.h"
#include <jni.h>
Include dependency graph for ov-java.cc:

Go to the source code of this file.

Classes

class  java_local_ref< T >
 
class  octave::JVMArgs
 

Namespaces

 octave
 

Macros

#define BOX_PRIMITIVE_ARRAY(JAVA_TYPE, JAVA_ID, JAVA_TYPE_CAP, OCTAVE_ID)
 
#define LIBJVM_FILE_NAME   "libjvm.so"
 
#define TO_JAVA(obj)   dynamic_cast<octave_java *> ((obj).internal_rep ())
 
#define TO_JCLASS(obj)   reinterpret_cast<jclass> (obj)
 
#define TO_JNIENV(env)   reinterpret_cast<JNIEnv *> (env)
 
#define TO_JOBJECT(obj)   reinterpret_cast<jobject> (obj)
 
#define UNBOX_PRIMITIVE_ARRAY(METHOD_T, OCTAVE_T, JAVA_T, JAVA_T_CAP)
 
#define UNBOX_PRIMITIVE_SCALAR(OCTAVE_T, METHOD_T, JAVA_T, JAVA_CON)
 

Typedefs

typedef java_local_ref< jbyteArray > jbyteArray_ref
 
typedef java_local_ref< jclass > jclass_ref
 
typedef java_local_ref< jdoubleArray > jdoubleArray_ref
 
typedef java_local_ref< jintArray > jintArray_ref
 
typedef jint(JNICALL * JNI_CreateJavaVM_t) (JavaVM **pvm, JNIEnv **penv, void *args)
 
typedef jint(JNICALL * JNI_GetCreatedJavaVMs_t) (JavaVM **pvm, jsize bufLen, jsize *nVMs)
 
typedef java_local_ref< jobject > jobject_ref
 
typedef java_local_ref< jobjectArray > jobjectArray_ref
 
typedef java_local_ref< jstring > jstring_ref
 
typedef java_local_ref< jthrowable > jthrowable_ref
 

Functions

static octave_value box (JNIEnv *jni_env, void *jobj, void *jcls_arg=nullptr)
 
static octave_value box_more (JNIEnv *jni_env, void *jobj_arg, void *jcls_arg=nullptr)
 
static octave_value check_exception (JNIEnv *jni_env)
 
static dim_vector compute_array_dimensions (JNIEnv *jni_env, jobject obj)
 
static jclass find_octave_class (JNIEnv *jni_env, const char *name)
 
static octave_value get_array_elements (JNIEnv *jni_env, jobject jobj, const octave_value_list &idx)
 
static std::string get_jvm_lib_path_in_subdir (std::string java_home_path)
 
static std::string initial_class_path (void)
 Return the initial classpath. More...
 
static std::string initial_java_dir (void)
 The java initialization directory is given by the environment variable OCTAVE_JAVA_DIR if defined; otherwise it is the directory of Octave's m-files defining Java functions. More...
 
static void initialize_jvm (void)
 Initialize the java virtual machine (jvm) and field jvm if necessary. More...
 
JNIEXPORT jboolean JNICALL Java_org_octave_Octave_call (JNIEnv *, jclass, jstring, jobjectArray, jobjectArray)
 
JNIEXPORT void JNICALL Java_org_octave_Octave_doEvalString (JNIEnv *, jclass, jstring)
 
JNIEXPORT void JNICALL Java_org_octave_Octave_doInvoke (JNIEnv *, jclass, jint, jobjectArray)
 
JNIEXPORT jboolean JNICALL Java_org_octave_Octave_needThreadedInvokation (JNIEnv *, jclass)
 
JNIEXPORT void JNICALL Java_org_octave_OctaveReference_doFinalize (JNIEnv *, jclass, jint)
 
static std::string jstring_to_string (JNIEnv *jni_env, jobject obj)
 
static std::string jstring_to_string (JNIEnv *jni_env, jstring s)
 Converts a Java string object to std::string. More...
 
static jobject make_java_index (JNIEnv *jni_env, const octave_value_list &idx)
 
static std::string read_classpath_txt (const std::string &filepath)
 Return the classpath in the given file filepath as a string. More...
 
static void terminate_jvm (void)
 Terminate the current jvm, if there is any. More...
 
static JNIEnv * thread_jni_env (void)
 } More...
 
static bool unbox (JNIEnv *jni_env, const octave_value &val, jobject_ref &jobj, jclass_ref &jcls)
 
static bool unbox (JNIEnv *jni_env, const octave_value_list &args, jobjectArray_ref &jobjs, jobjectArray_ref &jclss)
 

Variables

static JavaVM * jvm = nullptr
 The pointer to a java virtual machine either created in the current thread or attached this thread to it. More...
 
static bool jvm_attached = false
 Whether the current thread is attached to the jvm given by jvm. More...
 
static octave::dynamic_library jvm_lib
 Need to keep hold of the shared library handle until exit. More...
 
static std::map< int, octave_valuelistener_map
 
static int octave_java_refcount = 0
 
static std::map< int, octave_valueoctave_ref_map
 
static long octave_thread_ID = -1
 The thread id of the currently executing thread or -1 if this is unknown. More...
 
bool Vdebug_java = false
 
bool Vjava_matrix_autoconversion = false
 
bool Vjava_unsigned_autoconversion = true
 

Detailed Description

Provides Octave's Java interface.

Definition in file ov-java.cc.

Macro Definition Documentation

◆ BOX_PRIMITIVE_ARRAY

#define BOX_PRIMITIVE_ARRAY (   JAVA_TYPE,
  JAVA_ID,
  JAVA_TYPE_CAP,
  OCTAVE_ID 
)
Value:
cls = jni_env->FindClass (JAVA_ID); \
if (jni_env->IsInstanceOf (jobj, cls)) \
{ \
const JAVA_TYPE ## Array jarr = reinterpret_cast<JAVA_TYPE ## Array> (jobj); \
const jsize len = jni_env->GetArrayLength (jarr); \
OCTAVE_ID ## NDArray d (dim_vector (len, 1)); \
JAVA_TYPE *buffer = reinterpret_cast<JAVA_TYPE *> (d.fortran_vec ()); \
jni_env->Get ## JAVA_TYPE_CAP ## ArrayRegion (jarr, 0, len, buffer); \
retval = d; \
break; \
}
N Dimensional Array with copy-on-write semantics.
Definition: Array.h:128
Vector representing the dimensions (size) of an Array.
Definition: dim-vector.h:95
F77_RET_T const F77_DBLE const F77_DBLE F77_DBLE * d
F77_RET_T len
Definition: xerbla.cc:61

◆ LIBJVM_FILE_NAME

#define LIBJVM_FILE_NAME   "libjvm.so"

Definition at line 82 of file ov-java.cc.

◆ TO_JAVA

#define TO_JAVA (   obj)    dynamic_cast<octave_java *> ((obj).internal_rep ())

◆ TO_JCLASS

#define TO_JCLASS (   obj)    reinterpret_cast<jclass> (obj)

Definition at line 86 of file ov-java.cc.

◆ TO_JNIENV

#define TO_JNIENV (   env)    reinterpret_cast<JNIEnv *> (env)

Definition at line 88 of file ov-java.cc.

◆ TO_JOBJECT

#define TO_JOBJECT (   obj)    reinterpret_cast<jobject> (obj)

Definition at line 85 of file ov-java.cc.

◆ UNBOX_PRIMITIVE_ARRAY

#define UNBOX_PRIMITIVE_ARRAY (   METHOD_T,
  OCTAVE_T,
  JAVA_T,
  JAVA_T_CAP 
)
Value:
do \
{ \
const OCTAVE_T ## NDArray v = val.METHOD_T ## array_value (); \
JAVA_T ## Array jarr = jni_env->New ## JAVA_T_CAP ## Array (v.numel ()); \
const JAVA_T *jv = reinterpret_cast<const JAVA_T *> (v.data ()); \
jni_env->Set ## JAVA_T_CAP ## ArrayRegion (jarr, 0, v.numel (), jv); \
jobj = reinterpret_cast<jobject> (jarr); \
jcls = jni_env->GetObjectClass (jobj); \
} \
while (0)

◆ UNBOX_PRIMITIVE_SCALAR

#define UNBOX_PRIMITIVE_SCALAR (   OCTAVE_T,
  METHOD_T,
  JAVA_T,
  JAVA_CON 
)
Value:
do \
{ \
const OCTAVE_T ov = val.METHOD_T ## _value (); \
jclass_ref dcls (jni_env, jni_env->FindClass (JAVA_T)); \
const jfieldID fid = jni_env->GetStaticFieldID (dcls, "TYPE", "Ljava/lang/Class;"); \
const jmethodID mid = jni_env->GetMethodID (dcls, "<init>", JAVA_CON); \
jcls = reinterpret_cast<jclass> (jni_env->GetStaticObjectField (dcls, fid)); \
jobj = jni_env->NewObject (dcls, mid, ov); \
} \
while (0)

Typedef Documentation

◆ jbyteArray_ref

typedef java_local_ref<jbyteArray> jbyteArray_ref

Definition at line 150 of file ov-java.cc.

◆ jclass_ref

typedef java_local_ref<jclass> jclass_ref

Definition at line 146 of file ov-java.cc.

◆ jdoubleArray_ref

typedef java_local_ref<jdoubleArray> jdoubleArray_ref

Definition at line 151 of file ov-java.cc.

◆ jintArray_ref

typedef java_local_ref<jintArray> jintArray_ref

Definition at line 149 of file ov-java.cc.

◆ JNI_CreateJavaVM_t

typedef jint(JNICALL * JNI_CreateJavaVM_t) (JavaVM **pvm, JNIEnv **penv, void *args)

Definition at line 90 of file ov-java.cc.

◆ JNI_GetCreatedJavaVMs_t

typedef jint(JNICALL * JNI_GetCreatedJavaVMs_t) (JavaVM **pvm, jsize bufLen, jsize *nVMs)

Definition at line 93 of file ov-java.cc.

◆ jobject_ref

typedef java_local_ref<jobject> jobject_ref

Definition at line 145 of file ov-java.cc.

◆ jobjectArray_ref

typedef java_local_ref<jobjectArray> jobjectArray_ref

Definition at line 148 of file ov-java.cc.

◆ jstring_ref

typedef java_local_ref<jstring> jstring_ref

Definition at line 147 of file ov-java.cc.

◆ jthrowable_ref

typedef java_local_ref<jthrowable> jthrowable_ref

Definition at line 152 of file ov-java.cc.

Function Documentation

◆ box()

◆ box_more()

static octave_value box_more ( JNIEnv *  jni_env,
void *  jobj_arg,
void *  jcls_arg = nullptr 
)
static

◆ check_exception()

static octave_value check_exception ( JNIEnv *  jni_env)
static

Definition at line 969 of file ov-java.cc.

References error(), jstring_to_string(), retval, and Vdebug_java.

Referenced by get_array_elements(), and make_java_index().

◆ compute_array_dimensions()

static dim_vector compute_array_dimensions ( JNIEnv *  jni_env,
jobject  obj 
)
static

◆ find_octave_class()

static jclass find_octave_class ( JNIEnv *  jni_env,
const char *  name 
)
static

Definition at line 999 of file ov-java.cc.

References jstring_to_string(), and name.

Referenced by get_array_elements().

◆ get_array_elements()

static octave_value get_array_elements ( JNIEnv *  jni_env,
jobject  jobj,
const octave_value_list idx 
)
static

◆ get_jvm_lib_path_in_subdir()

static std::string get_jvm_lib_path_in_subdir ( std::string  java_home_path)
static

Definition at line 511 of file ov-java.cc.

References LIBJVM_FILE_NAME.

Referenced by initialize_jvm().

◆ initial_class_path()

static std::string initial_class_path ( void  )
static

Return the initial classpath.

The initial classpath starts with a pointer to octave.jar which is located in the initial java directory given by #java_init_dir().

Attention
This is nowhere documented and also the script javaclasspath.m drops this. On the other hand, this is vital because octave.jar contains the java core classes of octave's java interface.

The rest of the classpath is read sequentially from files javaclasspath.txt located in either:

  • the current directory,
  • the user's home directory,
  • the initial java directory returned by initial_java_dir()
Returns
The initial classpath.

Definition at line 422 of file ov-java.cc.

References octave::sys::file_ops::dir_sep_str(), error(), octave::sys::env::get_current_directory(), octave::sys::env::get_home_directory(), initial_java_dir(), read_classpath_txt(), retval, and octave::sys::file_ops::tilde_expand().

Referenced by initialize_jvm().

◆ initial_java_dir()

static std::string initial_java_dir ( void  )
static

The java initialization directory is given by the environment variable OCTAVE_JAVA_DIR if defined; otherwise it is the directory of Octave's m-files defining Java functions.

The Java initialization directory is the directory where resides:

  • octave.jar, defining the java classes implementing octave's java interface,
  • javaclasspath.txt, defining the installation defined portion of the (static) classpath,
  • java.opts, defining the configurable options of the java virtual machine.

Note that the (static) java classpath of the java virtual machine starts with octave.jar, and that the static java classpath ends with what is read from javaclasspath.txt located in the initial java directory. Moreover, the java virtual machine is created essentially with the options given by java.opts.

Definition at line 342 of file ov-java.cc.

References octave::sys::file_ops::dir_sep_str(), octave::config::fcn_file_dir(), and octave::sys::env::getenv().

Referenced by initial_class_path(), and initialize_jvm().

◆ initialize_jvm()

static void initialize_jvm ( void  )
static

Initialize the java virtual machine (jvm) and field jvm if necessary.

If the jvm exists and is initialized, jvm points to it, i.e. is not 0 and there is nothing to do.

If jvm is 0 and if at least one jvm exists, attach the current thread to it by setting jvm_attached. Otherwise, create a jvm with some hard- coded options:

Further options are read from the file java.opts in the directory given by #java_init_dir().

Note that initial_class_path() determines the initial classpath. This is the static classpath which cannot be changed. Elements of the dynamic classpath can be added and removed using the m-file scripts javaaddpath.m and javarmpath.m.

See also
terminate_jvm()

The number of created jvm's.

Definition at line 670 of file ov-java.cc.

References octave::JVMArgs::add(), octave::sys::file_ops::dir_sep_str(), error(), octave::process_execution_result::exit_status(), get_jvm_lib_path_in_subdir(), octave::sys::env::getenv(), initial_class_path(), initial_java_dir(), jvm, jvm_attached, jvm_lib, LIBJVM_FILE_NAME, octave::JVMArgs::read_java_opts(), octave::run_command_and_return_output(), octave::dynamic_library::search(), octave::process_execution_result::stdout_output(), and octave::JVMArgs::to_args().

◆ Java_org_octave_Octave_call()

JNIEXPORT jboolean JNICALL Java_org_octave_Octave_call ( JNIEnv *  ,
jclass  ,
jstring  ,
jobjectArray  ,
jobjectArray   
)

◆ Java_org_octave_Octave_doEvalString()

JNIEXPORT void JNICALL Java_org_octave_Octave_doEvalString ( JNIEnv *  ,
jclass  ,
jstring   
)

◆ Java_org_octave_Octave_doInvoke()

JNIEXPORT void JNICALL Java_org_octave_Octave_doInvoke ( JNIEnv *  ,
jclass  ,
jint  ,
jobjectArray   
)

◆ Java_org_octave_Octave_needThreadedInvokation()

JNIEXPORT jboolean JNICALL Java_org_octave_Octave_needThreadedInvokation ( JNIEnv *  ,
jclass   
)

◆ Java_org_octave_OctaveReference_doFinalize()

JNIEXPORT void JNICALL Java_org_octave_OctaveReference_doFinalize ( JNIEnv *  ,
jclass  ,
jint   
)

◆ jstring_to_string() [1/2]

static std::string jstring_to_string ( JNIEnv *  jni_env,
jobject  obj 
)
static

Definition at line 872 of file ov-java.cc.

References jstring_to_string(), and retval.

◆ jstring_to_string() [2/2]

static std::string jstring_to_string ( JNIEnv *  jni_env,
jstring  s 
)
static

Converts a Java string object to std::string.

{

Definition at line 857 of file ov-java.cc.

References retval.

Referenced by check_exception(), find_octave_class(), and jstring_to_string().

◆ make_java_index()

static jobject make_java_index ( JNIEnv *  jni_env,
const octave_value_list idx 
)
static

◆ read_classpath_txt()

static std::string read_classpath_txt ( const std::string &  filepath)
static

Return the classpath in the given file filepath as a string.

In the classpath file, each line which is neither empty nor a comment, is interpreted as a segment of a path. Comment lines are those starting with a # or with a % in the very first column.

Parameters
filepathThe path to the file (usually classpath.txt) containing a portion of the classpath.
Returns
A string consisting of the lines of filepath which are neither comments nor empty without trailing whitespace separated by 'octave::directory_path::path_sep_str()'. The returned string also starts with that path separator.

Definition at line 373 of file ov-java.cc.

References octave::sys::ifstream(), octave::directory_path::path_sep_str(), and octave::sys::file_ops::tilde_expand().

Referenced by initial_class_path().

◆ terminate_jvm()

static void terminate_jvm ( void  )
static

Terminate the current jvm, if there is any.

Otherwise, detach the jvm if this thread is attached to it and unload it if this thread created it itself.

See also
initialize_jvm()

Definition at line 833 of file ov-java.cc.

References octave::dynamic_library::close(), jvm, jvm_attached, jvm_lib, and octave_set_default_fpucw().

◆ thread_jni_env()

static JNIEnv* thread_jni_env ( void  )
inlinestatic

}

Returns a reference to the jni (java native interface) environment of the Java virtual machine jvm.

Returns
A reference to jni, if jvm is present, otherwise nullptr.

Definition at line 897 of file ov-java.cc.

References jvm.

Referenced by octave_java::is_instance_of(), and octave_java::is_java_string().

◆ unbox() [1/2]

static bool unbox ( JNIEnv *  jni_env,
const octave_value val,
jobject_ref jobj,
jclass_ref jcls 
)
static

◆ unbox() [2/2]

static bool unbox ( JNIEnv *  jni_env,
const octave_value_list args,
jobjectArray_ref jobjs,
jobjectArray_ref jclss 
)
static

Variable Documentation

◆ jvm

JavaVM* jvm = nullptr
static

The pointer to a java virtual machine either created in the current thread or attached this thread to it.

Definition at line 196 of file ov-java.cc.

Referenced by initialize_jvm(), terminate_jvm(), and thread_jni_env().

◆ jvm_attached

bool jvm_attached = false
static

Whether the current thread is attached to the jvm given by jvm.

This is false also if no jvm exists, i.e. if jvm is nullptr.

See also
initialize_jvm()
terminate_jvm()

Definition at line 203 of file ov-java.cc.

Referenced by initialize_jvm(), and terminate_jvm().

◆ jvm_lib

octave::dynamic_library jvm_lib
static

Need to keep hold of the shared library handle until exit.

See also
initialize_jvm()
terminate_jvm()

Definition at line 209 of file ov-java.cc.

Referenced by initialize_jvm(), and terminate_jvm().

◆ listener_map

std::map<int,octave_value> listener_map
static

Definition at line 211 of file ov-java.cc.

◆ octave_java_refcount

int octave_java_refcount = 0
static

Definition at line 213 of file ov-java.cc.

◆ octave_ref_map

std::map<int,octave_value> octave_ref_map
static

Definition at line 212 of file ov-java.cc.

◆ octave_thread_ID

long octave_thread_ID = -1
static

The thread id of the currently executing thread or -1 if this is unknown.

See also
#initialize_java()

Definition at line 219 of file ov-java.cc.

◆ Vdebug_java

bool Vdebug_java = false

◆ Vjava_matrix_autoconversion

bool Vjava_matrix_autoconversion = false

Definition at line 221 of file ov-java.cc.

◆ Vjava_unsigned_autoconversion

bool Vjava_unsigned_autoconversion = true

Definition at line 222 of file ov-java.cc.