/usr/share/doc/octave-htmldoc/interpreter/Java-Interface-Functions.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ -->
<head>
<title>GNU Octave: Java Interface Functions</title>

<meta name="description" content="GNU Octave: Java Interface Functions">
<meta name="keywords" content="GNU Octave: Java Interface Functions">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Java-Interface.html#Java-Interface" rel="up" title="Java Interface">
<link href="Dialog-Box-Functions.html#Dialog-Box-Functions" rel="next" title="Dialog Box Functions">
<link href="Java-Interface.html#Java-Interface" rel="prev" title="Java Interface">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
div.smalllisp {margin-left: 3.2em}
kbd {font-style:oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space:nowrap}
span.nolinebreak {white-space:nowrap}
span.roman {font-family:serif; font-weight:normal}
span.sansserif {font-family:sans-serif; font-weight:normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="Java-Interface-Functions"></a>
<div class="header">
<p>
Next: <a href="Dialog-Box-Functions.html#Dialog-Box-Functions" accesskey="n" rel="next">Dialog Box Functions</a>, Up: <a href="Java-Interface.html#Java-Interface" accesskey="u" rel="up">Java Interface</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Java-Interface-Functions-1"></a>
<h3 class="section">37.1 Java Interface Functions</h3>

<p>The following functions are the core of the Java Interface.  They provide
a way to create a Java object, get and set its data fields, and call Java
methods which return results to Octave.
</p>
<a name="index-object_002c-creating-a-Java-object"></a>
<a name="XREFjavaObject"></a><dl>
<dt><a name="index-javaObject"></a>Built-in Function: <em><var>jobj</var> =</em> <strong>javaObject</strong> <em>(<var>classname</var>)</em></dt>
<dt><a name="index-javaObject-1"></a>Built-in Function: <em><var>jobj</var> =</em> <strong>javaObject</strong> <em>(<var>classname</var>, <var>arg1</var>, &hellip;)</em></dt>
<dd><p>Create a Java object of class <var>classsname</var>, by calling the class
constructor with the arguments <var>arg1</var>, &hellip;
</p>
<p>The first example below creates an uninitialized object,
while the second example supplies an initial argument to the constructor.
</p>
<div class="example">
<pre class="example">x = javaObject (&quot;java.lang.StringBuffer&quot;)
x = javaObject (&quot;java.lang.StringBuffer&quot;, &quot;Initial string&quot;)
</pre></div>


<p><strong>See also:</strong> <a href="#XREFjavaMethod">javaMethod</a>, <a href="#XREFjavaArray">javaArray</a>.
</p></dd></dl>


<a name="index-array_002c-creating-a-Java-array"></a>
<a name="XREFjavaArray"></a><dl>
<dt><a name="index-javaArray"></a>Function File: <em><var>jary</var> =</em> <strong>javaArray</strong> <em>(<var>classname</var>, <var>sz</var>)</em></dt>
<dt><a name="index-javaArray-1"></a>Function File: <em><var>jary</var> =</em> <strong>javaArray</strong> <em>(<var>classname</var>, <var>m</var>, <var>n</var>, &hellip;)</em></dt>
<dd>
<p>Create a Java array of size <var>sz</var> with elements of class
<var>classname</var>.  <var>classname</var> may be a Java object representing a class
or a string containing the fully qualified class name.  The size of
the object may also be specified with individual integer arguments
<var>m</var>, <var>n</var>, etc.
</p>
<p>The generated array is uninitialized.  All elements are set to null
if <var>classname</var> is a reference type, or to a default value (usually 0)
if <var>classname</var> is a primitive type.
</p>
<p>Sample code:
</p>
<div class="example">
<pre class="example">jary = javaArray (&quot;java.lang.String&quot;, 2, 2);
jary(1,1) = &quot;Hello&quot;;
</pre></div>

<p><strong>See also:</strong> <a href="#XREFjavaObject">javaObject</a>.
</p></dd></dl>


<p>There are many different variable types in Octave but only ones created through
<code>javaObject</code> can use Java functions.  Before using Java with an unknown
object the type can be checked with <code>isjava</code>.
</p>
<a name="XREFisjava"></a><dl>
<dt><a name="index-isjava"></a>Built-in Function: <em></em> <strong>isjava</strong> <em>(<var>x</var>)</em></dt>
<dd><p>Return true if <var>x</var> is a Java object.
</p>
<p><strong>See also:</strong> <a href="Built_002din-Data-Types.html#XREFclass">class</a>, <a href="Data-Types.html#XREFtypeinfo">typeinfo</a>, <a href="Built_002din-Data-Types.html#XREFisa">isa</a>, <a href="#XREFjavaObject">javaObject</a>.
</p></dd></dl>


<p>Once an object has been created it is natural to find out what fields the
object has and to read (get) and write (set) them.
</p>
<a name="index-fields_002c-displaying-available-fields-of-a-Java-object"></a>
<p>In Octave the <code>fieldnames</code> function for structures has been overloaded
to return the fields of a Java object.  For example:
</p>
<div class="example">
<pre class="example">dobj = javaObject (&quot;java.lang.Double&quot;, pi);
fieldnames (dobj)
&rArr;
{
  [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
}
</pre></div>

<a name="index-field_002c-returning-value-of-Java-object-field"></a>
<p>The analogy of objects with structures is carried over into reading and
writing object fields.  To read a field the object is indexed with the
&lsquo;<samp>.</samp>&rsquo; operator from structures.  This is the preferred method for reading
fields, but Octave also provides a function interface to read fields with
<code>java_get</code>.  An example of both styles is shown below.
</p>
<div class="example">
<pre class="example">dobj = javaObject (&quot;java.lang.Double&quot;, pi);
dobj.MAX_VALUE
&rArr;  1.7977e+308
java_get (&quot;java.lang.Float&quot;, &quot;MAX_VALUE&quot;)
&rArr;  3.4028e+38
</pre></div>

<a name="XREFjava_005fget"></a><dl>
<dt><a name="index-java_005fget"></a>Function File: <em><var>val</var> =</em> <strong>java_get</strong> <em>(<var>obj</var>, <var>name</var>)</em></dt>
<dd><p>Get the value of the field <var>name</var> of the Java object <var>obj</var>.  For
static fields, <var>obj</var> can be a string representing the fully qualified
name of the corresponding class.
</p>
<p>When <var>obj</var> is a regular Java object, structure-like indexing can be
used as a shortcut syntax.  For instance, the two following statements are
equivalent
</p>
<div class="example">
<pre class="example">  java_get (x, &quot;field1&quot;)
  x.field1
</pre></div>


<p><strong>See also:</strong> <a href="#XREFjava_005fset">java_set</a>, <a href="#XREFjavaMethod">javaMethod</a>, <a href="#XREFjavaObject">javaObject</a>.
</p></dd></dl>


<a name="index-field_002c-setting-value-of-Java-object-field"></a>
<a name="XREFjava_005fset"></a><dl>
<dt><a name="index-java_005fset"></a>Function File: <em><var>obj</var> =</em> <strong>java_set</strong> <em>(<var>obj</var>, <var>name</var>, <var>val</var>)</em></dt>
<dd><p>Set the value of the field <var>name</var> of the Java object <var>obj</var> to
<var>val</var>.  For static fields, <var>obj</var> can be a string representing the
fully qualified named of the corresponding Java class.
</p>
<p>When <var>obj</var> is a regular Java object, structure-like indexing can be
used as a shortcut syntax.  For instance, the two following statements are
equivalent
</p>
<div class="example">
<pre class="example">  java_set (x, &quot;field1&quot;, val)
  x.field1 = val
</pre></div>


<p><strong>See also:</strong> <a href="#XREFjava_005fget">java_get</a>, <a href="#XREFjavaMethod">javaMethod</a>, <a href="#XREFjavaObject">javaObject</a>.
</p></dd></dl>


<a name="index-methods_002c-displaying-available-methods-of-a-Java-object"></a>
<p>To see what functions can be called with an object use <code>methods</code>.
For example, using the previously created <var>dobj</var>:
</p>
<div class="example">
<pre class="example">methods (dobj)
&rArr;
Methods for class java.lang.Double:
boolean equals(java.lang.Object)
java.lang.String toString(double)
java.lang.String toString()
&hellip;
</pre></div>

<p>To call a method of an object the same structure indexing operator &lsquo;<samp>.</samp>&rsquo;
is used.  Octave also provides a functional interface to calling the methods
of an object through <code>javaMethod</code>.  An example showing both styles is
shown below.
</p>
<div class="example">
<pre class="example">dobj = javaObject (&quot;java.lang.Double&quot;, pi);
dobj.equals (3)
&rArr;  0
javaMethod (&quot;equals&quot;, dobj, pi)
&rArr;  1
</pre></div>

<a name="index-method_002c-invoking-a-method-of-a-Java-object"></a>
<a name="XREFjavaMethod"></a><dl>
<dt><a name="index-javaMethod"></a>Built-in Function: <em><var>ret</var> =</em> <strong>javaMethod</strong> <em>(<var>methodname</var>, <var>obj</var>)</em></dt>
<dt><a name="index-javaMethod-1"></a>Built-in Function: <em><var>ret</var> =</em> <strong>javaMethod</strong> <em>(<var>methodname</var>, <var>obj</var>, <var>arg1</var>, &hellip;)</em></dt>
<dd><p>Invoke the method <var>methodname</var> on the Java object <var>obj</var> with the
arguments <var>arg1</var>, &hellip;  For static methods, <var>obj</var> can be a string
representing the fully qualified name of the corresponding class.  The
function returns the result of the method invocation.
</p>
<p>When <var>obj</var> is a regular Java object, structure-like indexing can be
used as a shortcut syntax.  For instance, the two following statements are
equivalent
</p>
<div class="example">
<pre class="example">  ret = javaMethod (&quot;method1&quot;, x, 1.0, &quot;a string&quot;)
  ret = x.method1 (1.0, &quot;a string&quot;)
</pre></div>


<p><strong>See also:</strong> <a href="Creating-a-Class.html#XREFmethods">methods</a>, <a href="#XREFjavaObject">javaObject</a>.
</p></dd></dl>


<p>The following three functions are used to display and modify the
class path used by the Java Virtual Machine.  This is entirely separate
from Octave&rsquo;s PATH variable and is used by the JVM to find the correct
code to execute.
</p>
<a name="index-classpath_002c-displaying"></a>
<a name="index-classpath_002c-dynamic"></a>
<a name="index-dynamic-classpath"></a>
<a name="index-classpath_002c-static"></a>
<a name="index-static-classpath"></a>
<a name="XREFjavaclasspath"></a><dl>
<dt><a name="index-javaclasspath"></a>Function File: <em></em> <strong>javaclasspath</strong> <em>()</em></dt>
<dt><a name="index-javaclasspath-1"></a>Function File: <em><var>dpath</var> =</em> <strong>javaclasspath</strong> <em>()</em></dt>
<dt><a name="index-javaclasspath-2"></a>Function File: <em>[<var>dpath</var>, <var>spath</var>] =</em> <strong>javaclasspath</strong> <em>()</em></dt>
<dt><a name="index-javaclasspath-3"></a>Function File: <em><var>clspath</var> =</em> <strong>javaclasspath</strong> <em>(<var>what</var>)</em></dt>
<dd><p>Return the class path of the Java virtual machine in the form of a cell
array of strings. 
</p>
<p>If called with no inputs:
</p>
<ul>
<li> If no output is requested, the dynamic and static classpaths are printed 
to the standard output.

</li><li> If one output value <var>dpath</var> is requested, the result is
the dynamic classpath.

</li><li> If two output values<var>dpath</var> and <var>spath</var> are 
requested, the first variable will contain the dynamic classpath and
the second will be contain the static classpath.
</li></ul>

<p>If called with a single input parameter <var>what</var>:
</p>
<dl compact="compact">
<dt><code>&quot;-dynamic&quot;</code></dt>
<dd><p>Return the dynamic classpath.
</p>
</dd>
<dt><code>&quot;-static&quot;</code></dt>
<dd><p>Return the static classpath.
</p>
</dd>
<dt><code>&quot;-all&quot;</code></dt>
<dd><p>Return both the static and dynamic classpath in a single cellstr.
</p></dd>
</dl>

<p><strong>See also:</strong> <a href="#XREFjavaaddpath">javaaddpath</a>, <a href="#XREFjavarmpath">javarmpath</a>.
</p></dd></dl>


<a name="index-javaaddpath"></a>
<a name="index-classpath_002c-adding-new-path"></a>
<a name="index-path_002c-adding-to-classpath"></a>
<a name="index-classpath_002c-dynamic-1"></a>
<a name="index-dynamic-classpath_002c-adding-new-path"></a>
<a name="XREFjavaaddpath"></a><dl>
<dt><a name="index-javaaddpath-1"></a>Function File: <em></em> <strong>javaaddpath</strong> <em>(<var>clspath</var>)</em></dt>
<dt><a name="index-javaaddpath-2"></a>Function File: <em></em> <strong>javaaddpath</strong> <em>(<var>clspath1</var>, &hellip;)</em></dt>
<dd><p>Add <var>clspath</var> to the dynamic class path of the Java virtual
machine.  <var>clspath</var> may either be a directory where <samp>.class</samp>
files are found, or a <samp>.jar</samp> file containing Java classes.
Multiple paths may be added at once by specifying additional arguments.
</p>
<p><strong>See also:</strong> <a href="#XREFjavarmpath">javarmpath</a>, <a href="#XREFjavaclasspath">javaclasspath</a>.
</p></dd></dl>


<a name="index-classpath_002c-removing-path"></a>
<a name="index-path_002c-removing-from-classpath"></a>
<a name="XREFjavarmpath"></a><dl>
<dt><a name="index-javarmpath"></a>Function File: <em></em> <strong>javarmpath</strong> <em>(<var>clspath</var>)</em></dt>
<dt><a name="index-javarmpath-1"></a>Function File: <em></em> <strong>javarmpath</strong> <em>(<var>clspath1</var>, &hellip;)</em></dt>
<dd><p>Remove <var>clspath</var> from the dynamic class path of the Java virtual
machine.  <var>clspath</var> may either be a directory where <samp>.class</samp>
files are found, or a <samp>.jar</samp> file containing Java classes.
Multiple paths may be removed at once by specifying additional arguments.
</p>
<p><strong>See also:</strong> <a href="#XREFjavaaddpath">javaaddpath</a>, <a href="#XREFjavaclasspath">javaclasspath</a>.
</p></dd></dl>


<p>The following four functions provide information and control over the interface
between Octave and the Java Virtual Machine.
</p>
<a name="XREFusejava"></a><dl>
<dt><a name="index-usejava"></a>Function File: <em></em> <strong>usejava</strong> <em>(<var>feature</var>)</em></dt>
<dd><p>Return true if the Java element <var>feature</var> is available.
</p>
<p>Possible features are:
</p>
<dl compact="compact">
<dt><code>&quot;awt&quot;</code></dt>
<dd><p>Abstract Window Toolkit for GUIs.
</p>
</dd>
<dt><code>&quot;desktop&quot;</code></dt>
<dd><p>Interactive desktop is running.
</p>
</dd>
<dt><code>&quot;jvm&quot;</code></dt>
<dd><p>Java Virtual Machine.
</p>
</dd>
<dt><code>&quot;swing&quot;</code></dt>
<dd><p>Swing components for lightweight GUIs.
</p></dd>
</dl>

<p><code>usejava</code> determines if specific Java features are available in an
Octave session.  This function is provided for scripts which may alter
their behavior based on the availability of Java.  The feature
<code>&quot;desktop&quot;</code> always returns <code>false</code> as Octave has no Java-based
desktop.  Other features may be available if Octave was compiled with the
Java Interface and Java is installed.
</p></dd></dl>


<a name="index-memory_002c-displaying-Java-memory-status"></a>
<a name="XREFjavamem"></a><dl>
<dt><a name="index-javamem"></a>Function File: <em></em> <strong>javamem</strong> <em>()</em></dt>
<dt><a name="index-javamem-1"></a>Function File: <em><var>jmem</var> =</em> <strong>javamem</strong> <em>()</em></dt>
<dd><p>Show the current memory usage of the Java virtual machine (JVM)
and run the garbage collector.
</p>
<p>When no return argument is given the info is printed to the screen.
Otherwise, the output cell array <var>jmem</var> contains Maximum, Total,
and Free memory (in bytes).
</p>
<p>All Java-based routines are run in the JVM&rsquo;s shared memory pool,
a dedicated and separate part of memory claimed by the JVM from
your computer&rsquo;s total memory (which comprises physical RAM and
virtual memory / swap space on hard disk).
</p>
<p>The maximum allowable memory usage can be configured using the file
<samp>java.opts</samp>.  The directory where this file resides is
determined by the environment variable <code><span class="nolinebreak">OCTAVE_JAVA_DIR</span></code><!-- /@w -->.
If unset, the directory where <samp>javaaddpath.m</samp> resides is used instead
(typically
<samp><code><span class="nolinebreak">OCTAVE_HOME</span></code><!-- /@w -->/share/octave/<code><span class="nolinebreak">OCTAVE_VERSION</span></code><!-- /@w -->/m/java/</samp>
</p>
<p><samp>java.opts</samp> is a plain text file with one option per line.  The
default initial memory size and default maximum memory size (which
are both system dependent) can be overridden like so:
</p>
<p>-Xms64m
</p>
<p>-Xmx512m
</p>
<p>(in megabytes in this example).
You can adapt these values to your own requirements if your system
has limited available physical memory or if you get Java memory
errors.
</p>
<p>&quot;Total memory&quot; is what the operating system has currently assigned
to the JVM and depends on actual and active memory usage.
&quot;Free memory&quot; is self-explanatory.  During operation of Java-based
Octave functions the amount of Total and Free memory will vary,
due to Java&rsquo;s own cleaning up and your operating system&rsquo;s memory
management.
</p></dd></dl>


<a name="XREFjava_005fmatrix_005fautoconversion"></a><dl>
<dt><a name="index-java_005fmatrix_005fautoconversion"></a>Built-in Function: <em><var>val</var> =</em> <strong>java_matrix_autoconversion</strong> <em>()</em></dt>
<dt><a name="index-java_005fmatrix_005fautoconversion-1"></a>Built-in Function: <em><var>old_val</var> =</em> <strong>java_matrix_autoconversion</strong> <em>(<var>new_val</var>)</em></dt>
<dt><a name="index-java_005fmatrix_005fautoconversion-2"></a>Built-in Function: <em></em> <strong>java_matrix_autoconversion</strong> <em>(<var>new_val</var>, &quot;local&quot;)</em></dt>
<dd><p>Query or set the internal variable that controls whether Java arrays are
automatically converted to Octave matrices.  The default value is false.
</p>
<p>When called from inside a function with the <code>&quot;local&quot;</code> option, the
variable is changed locally for the function and any subroutines it calls.  
The original variable value is restored when exiting the function.
</p>
<p><strong>See also:</strong> <a href="#XREFjava_005funsigned_005fautoconversion">java_unsigned_autoconversion</a>, <a href="#XREFdebug_005fjava">debug_java</a>.
</p></dd></dl>


<a name="XREFjava_005funsigned_005fautoconversion"></a><dl>
<dt><a name="index-java_005funsigned_005fautoconversion"></a>Built-in Function: <em><var>val</var> =</em> <strong>java_unsigned_autoconversion</strong> <em>()</em></dt>
<dt><a name="index-java_005funsigned_005fautoconversion-1"></a>Built-in Function: <em><var>old_val</var> =</em> <strong>java_unsigned_autoconversion</strong> <em>(<var>new_val</var>)</em></dt>
<dt><a name="index-java_005funsigned_005fautoconversion-2"></a>Built-in Function: <em></em> <strong>java_unsigned_autoconversion</strong> <em>(<var>new_val</var>, &quot;local&quot;)</em></dt>
<dd><p>Query or set the internal variable that controls how integer classes are
converted when <code>java_matrix_autoconversion</code> is enabled.  When enabled,
Java arrays of class Byte or Integer are converted to matrices of class
uint8 or uint32 respectively.  The default value is true.
</p>
<p>When called from inside a function with the <code>&quot;local&quot;</code> option, the
variable is changed locally for the function and any subroutines it calls.  
The original variable value is restored when exiting the function.
</p>
<p><strong>See also:</strong> <a href="#XREFjava_005fmatrix_005fautoconversion">java_matrix_autoconversion</a>, <a href="#XREFdebug_005fjava">debug_java</a>.
</p></dd></dl>


<a name="XREFdebug_005fjava"></a><dl>
<dt><a name="index-debug_005fjava"></a>Built-in Function: <em><var>val</var> =</em> <strong>debug_java</strong> <em>()</em></dt>
<dt><a name="index-debug_005fjava-1"></a>Built-in Function: <em><var>old_val</var> =</em> <strong>debug_java</strong> <em>(<var>new_val</var>)</em></dt>
<dt><a name="index-debug_005fjava-2"></a>Built-in Function: <em></em> <strong>debug_java</strong> <em>(<var>new_val</var>, &quot;local&quot;)</em></dt>
<dd><p>Query or set the internal variable that determines whether extra debugging
information regarding the initialization of the JVM and any Java exceptions
is printed.
</p>
<p>When called from inside a function with the <code>&quot;local&quot;</code> option, the
variable is changed locally for the function and any subroutines it calls.  
The original variable value is restored when exiting the function.
</p>
<p><strong>See also:</strong> <a href="#XREFjava_005fmatrix_005fautoconversion">java_matrix_autoconversion</a>, <a href="#XREFjava_005funsigned_005fautoconversion">java_unsigned_autoconversion</a>.
</p></dd></dl>


<hr>
<div class="header">
<p>
Next: <a href="Dialog-Box-Functions.html#Dialog-Box-Functions" accesskey="n" rel="next">Dialog Box Functions</a>, Up: <a href="Java-Interface.html#Java-Interface" accesskey="u" rel="up">Java Interface</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>
octave-htmldoc 3.8.2-4 / usr / share / doc / octave-htmldoc / interpreter / Java-Interface-Functions.html
