docs/technotes/guides/jni/spec/functions.html

Print this page




1082 <p><code>void DeleteWeakGlobalRef(JNIEnv *env, jweak
1083 obj);</code></p>
1084 <p>Delete the VM resources needed for the given weak global
1085 reference.</p>
1086 <h4>LINKAGE:</h4>
1087 Index 227 in the JNIEnv interface function table.
1088 <h4>SINCE:</h4>
1089 <p>JDK/JRE 1.2<a name="arrayops"></a></p>
1090 <!-- ******************************************************** -->
1091 <h2><a name="object_operations">Object Operations</a></h2>
1092 
1093 <h3><a name="AllocObject">AllocObject</a></h3>
1094 
1095 <p><code>jobject AllocObject(JNIEnv
1096 *env, jclass clazz);</code></p>
1097 
1098 <p>Allocates a new Java object without invoking any
1099 of the constructors for the object. Returns a reference to the
1100 object.</p>
1101 


1102 <p>The clazz argument must not refer to an array
1103 class.</p>
1104 
1105 <h4>LINKAGE:</h4>
1106 <p>Index 27 in the JNIEnv interface function table.</p>
1107 <h4>PARAMETERS:</h4>
1108 
1109 <p><code>env</code>: the JNI interface
1110 pointer.</p>
1111 
1112 <p><code>clazz</code>: a Java class
1113 object.</p>
1114 
1115 <h4>RETURNS:</h4>
1116 
1117 <p>Returns a Java object, or <code class=
1118 "cCode">NULL</code> if the object cannot be constructed.</p>
1119 
1120 <h4>THROWS:</h4>
1121 


2396 jclass clazz, jmethodID methodID, va_list args);</code></p>
2397 
2398 <p>These families of operations invoke an instance
2399 (nonstatic) method on a Java object, according to the specified
2400 class and method ID. The <code>methodID</code>
2401 argument must be obtained by calling <code class=
2402 "cCode">GetMethodID</code><code>()</code> on the
2403 class <code>clazz</code>.</p>
2404 
2405 <p>The <em class=
2406 "cEmphasis">CallNonvirtual&lt;type&gt;Method</em> families of
2407 routines and the <em>Call&lt;type&gt;Method</em>
2408 families of routines are different. <em class=
2409 "cEmphasis">Call&lt;type&gt;Method</em> routines invoke the method
2410 based on the class of the object, while <em class=
2411 "cEmphasis">CallNonvirtual&lt;type&gt;Method</em> routines invoke
2412 the method based on the class, designated by the <code class=
2413 "cCode">clazz</code> parameter, from which the method ID is
2414 obtained. The method ID must be obtained from the real class of the
2415 object or from one of its superclasses.</p>


2416 
2417 <h4>CallNonvirtual&lt;type&gt;Method
2418 Routines</h4>
2419 
2420 <p>Programmers place all arguments that are to be
2421 passed to the method immediately following the <code class=
2422 "cCode">methodID</code> argument. The <em class=
2423 "cEmphasis">CallNonvirtual&lt;type&gt;Method</em> routine accepts
2424 these arguments and passes them to the Java method that the
2425 programmer wishes to invoke.</p>
2426 
2427 <h4>CallNonvirtual&lt;type&gt;MethodA
2428 Routines</h4>
2429 
2430 <p>Programmers place all arguments to the method in
2431 an <code>args</code> array of <code class=
2432 "cCode">jvalues</code> that immediately follows the <code class=
2433 "cCode">methodID</code> argument. The <em class=
2434 "cEmphasis">CallNonvirtual&lt;type&gt;MethodA</em> routine accepts
2435 the arguments in this array, and, in turn, passes them to the Java




1082 <p><code>void DeleteWeakGlobalRef(JNIEnv *env, jweak
1083 obj);</code></p>
1084 <p>Delete the VM resources needed for the given weak global
1085 reference.</p>
1086 <h4>LINKAGE:</h4>
1087 Index 227 in the JNIEnv interface function table.
1088 <h4>SINCE:</h4>
1089 <p>JDK/JRE 1.2<a name="arrayops"></a></p>
1090 <!-- ******************************************************** -->
1091 <h2><a name="object_operations">Object Operations</a></h2>
1092 
1093 <h3><a name="AllocObject">AllocObject</a></h3>
1094 
1095 <p><code>jobject AllocObject(JNIEnv
1096 *env, jclass clazz);</code></p>
1097 
1098 <p>Allocates a new Java object without invoking any
1099 of the constructors for the object. Returns a reference to the
1100 object.</p>
1101 
1102 <p><b>Note:</b> The Java Language Specification, "Implementing Finalization" (<a href="http://docs.oracle.com/javase/specs/jls/se8/html/jls-12.html#jls-12.6.1">JLS &sect;12.6.1</a>) states: "An object o is not finalizable until its constructor has invoked the constructor for Object on o and that invocation has completed successfully". Since AllocObject() does not invoke a constructor, objects created with this function are not eligible for finalization.</p>
1103 
1104 <p>The clazz argument must not refer to an array
1105 class.</p>
1106 
1107 <h4>LINKAGE:</h4>
1108 <p>Index 27 in the JNIEnv interface function table.</p>
1109 <h4>PARAMETERS:</h4>
1110 
1111 <p><code>env</code>: the JNI interface
1112 pointer.</p>
1113 
1114 <p><code>clazz</code>: a Java class
1115 object.</p>
1116 
1117 <h4>RETURNS:</h4>
1118 
1119 <p>Returns a Java object, or <code class=
1120 "cCode">NULL</code> if the object cannot be constructed.</p>
1121 
1122 <h4>THROWS:</h4>
1123 


2398 jclass clazz, jmethodID methodID, va_list args);</code></p>
2399 
2400 <p>These families of operations invoke an instance
2401 (nonstatic) method on a Java object, according to the specified
2402 class and method ID. The <code>methodID</code>
2403 argument must be obtained by calling <code class=
2404 "cCode">GetMethodID</code><code>()</code> on the
2405 class <code>clazz</code>.</p>
2406 
2407 <p>The <em class=
2408 "cEmphasis">CallNonvirtual&lt;type&gt;Method</em> families of
2409 routines and the <em>Call&lt;type&gt;Method</em>
2410 families of routines are different. <em class=
2411 "cEmphasis">Call&lt;type&gt;Method</em> routines invoke the method
2412 based on the class of the object, while <em class=
2413 "cEmphasis">CallNonvirtual&lt;type&gt;Method</em> routines invoke
2414 the method based on the class, designated by the <code class=
2415 "cCode">clazz</code> parameter, from which the method ID is
2416 obtained. The method ID must be obtained from the real class of the
2417 object or from one of its superclasses.</p>
2418 
2419 <p><em class="cEmphasis">CallNonvirtual&lt;type&gt;Method</em> routines are the mechanism for invoking <em>"default interface methods"</em> introduced in Java 8.</p>
2420 
2421 <h4>CallNonvirtual&lt;type&gt;Method
2422 Routines</h4>
2423 
2424 <p>Programmers place all arguments that are to be
2425 passed to the method immediately following the <code class=
2426 "cCode">methodID</code> argument. The <em class=
2427 "cEmphasis">CallNonvirtual&lt;type&gt;Method</em> routine accepts
2428 these arguments and passes them to the Java method that the
2429 programmer wishes to invoke.</p>
2430 
2431 <h4>CallNonvirtual&lt;type&gt;MethodA
2432 Routines</h4>
2433 
2434 <p>Programmers place all arguments to the method in
2435 an <code>args</code> array of <code class=
2436 "cCode">jvalues</code> that immediately follows the <code class=
2437 "cCode">methodID</code> argument. The <em class=
2438 "cEmphasis">CallNonvirtual&lt;type&gt;MethodA</em> routine accepts
2439 the arguments in this array, and, in turn, passes them to the Java