631 <p>There are two cases where the programmer needs to
 632 check for exceptions without being able to first check an error
 633 code:</p>
 634 
 635 
 636 <ul>
 637 <li>The JNI functions that invoke a Java method return the result
 638 of the Java method. The programmer must call <code>ExceptionOccurred()</code> to check for possible exceptions
 639 that occurred during the execution of the Java method.</li>
 640 <li>Some of the JNI array access functions do not return an error
 641 code, but may throw an <code>ArrayIndexOutOfBoundsException</code> or <code>ArrayStoreException</code>.</li>
 642 </ul>
 643 
 644 
 645 
 646 <p>In all other cases, a non-error return value
 647 guarantees that no exceptions have been thrown.</p>
 648 
 649 <h3><a name="asynchronous_exceptions">Asynchronous Exceptions</a></h3>
 650 
 651 <p>In cases of multiple threads, threads other than
 652 the current thread may post an asynchronous exception. An
 653 asynchronous exception does not immediately affect the execution of
 654 the native code in the current thread, until:</p>







 655 


 656 
 657 <ul>
 658 <li>the native code calls one of the JNI functions that could raise
 659 synchronous exceptions, or</li>
 660 <li>the native code uses <code>ExceptionOccurred()</code> to explicitly check for
 661 synchronous and asynchronous exceptions.</li>

 662 </ul>
 663 


 664 







 665 
 666 <p>Note that only those JNI function that could
 667 potentially raise synchronous exceptions check for asynchronous
 668 exceptions.</p>
 669 
 670 <p>Native methods should insert <code>ExceptionOccurred()</code>checks in necessary places (such
 671 as in a tight loop without other exception checks) to ensure that
 672 the current thread responds to asynchronous exceptions in a
 673 reasonable amount of time.</p>
 674 
 675 <h3><a name="exception_handling">Exception Handling</a></h3>
 676 
 677 <p>There are two ways to handle an exception in
 678 native code:</p>
 679 
 680 
 681 <ul>
 682 <li>The native method can choose to return immediately, causing the
 683 exception to be thrown in the Java code that initiated the native
 684 method call.</li>
 685 <li>The native code can clear the exception by calling <code>ExceptionClear()</code>, and then execute its own
 686 exception-handling code.</li>
 687 </ul>
 688 
 689 
 690 
 691 <p>After an exception has been raised, the native
 692 code must first clear the exception before making other JNI calls.
 693 When there is a pending exception, the JNI functions that are safe

 631 <p>There are two cases where the programmer needs to
 632 check for exceptions without being able to first check an error
 633 code:</p>
 634 
 635 
 636 <ul>
 637 <li>The JNI functions that invoke a Java method return the result
 638 of the Java method. The programmer must call <code>ExceptionOccurred()</code> to check for possible exceptions
 639 that occurred during the execution of the Java method.</li>
 640 <li>Some of the JNI array access functions do not return an error
 641 code, but may throw an <code>ArrayIndexOutOfBoundsException</code> or <code>ArrayStoreException</code>.</li>
 642 </ul>
 643 
 644 
 645 
 646 <p>In all other cases, a non-error return value
 647 guarantees that no exceptions have been thrown.</p>
 648 
 649 <h3><a name="asynchronous_exceptions">Asynchronous Exceptions</a></h3>
 650 
 651 <p>One thread may raise an asynchronous exception in another thread by calling
 652 the <code>Thread.stop()</code> method, which has been deprecated since Java 2
 653 SDK release 1.2. Programmers are strongly discouraged from using
 654 <code>Thread.stop()</code> as it generally leads to an indeterminate application
 655 state.</p>
 656 
 657 <p>Furthermore, the JVM may produce exceptions in the current thread without
 658 being the direct result of a JNI API call, but because of various JVM internal
 659 errors, for example: <code>VirtualMachineError</code> like
 660 <code>StackOverflowError</code> or <code>OutOfMemoryError</code>. These are also
 661 referred to as asynchronous exceptions.</p>
 662 
 663 <p>Asynchronous exceptions do not immediately affect the execution of the native
 664 code in the current thread, until:</p>
 665 
 666 <ul>
 667   <li>the native code calls one of the JNI functions that could raise synchronous
 668     exceptions, or</li>
 669 
 670   <li>the native code uses <code>ExceptionOccurred()</code> to explicitly check
 671     for synchronous and asynchronous exceptions.</li>
 672 </ul>
 673 
 674 <p>Note that only those JNI functions that could potentially raise synchronous
 675 exceptions check for asynchronous exceptions.</p>
 676 
 677 <p>Native methods should insert <code>ExceptionOccurred()</code> checks in
 678 necessary places, such as in any long running code without other exception
 679 checks (this may include tight loops). This ensures that the current thread
 680 responds to asynchronous exceptions in a reasonable amount of time. However,
 681 because of their asynchronous nature, making an exception check before a call is
 682 no guarantee that an asynchronous exception won't be raised between the check
 683 and the call.</p>
 684 








 685 
 686 <h3><a name="exception_handling">Exception Handling</a></h3>
 687 
 688 <p>There are two ways to handle an exception in
 689 native code:</p>
 690 
 691 
 692 <ul>
 693 <li>The native method can choose to return immediately, causing the
 694 exception to be thrown in the Java code that initiated the native
 695 method call.</li>
 696 <li>The native code can clear the exception by calling <code>ExceptionClear()</code>, and then execute its own
 697 exception-handling code.</li>
 698 </ul>
 699 
 700 
 701 
 702 <p>After an exception has been raised, the native
 703 code must first clear the exception before making other JNI calls.
 704 When there is a pending exception, the JNI functions that are safe