1 /*

     2  * Copyright 2003 Sun Microsystems, Inc.  All Rights Reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Sun designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Sun in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

    22  * CA 95054 USA or visit www.sun.com if you need additional information or

    23  * have any questions.

    24  */

    25 

    26 /*

    27  * Copyright 2003 Wily Technology, Inc.

    28  */

    29 

    30 #ifndef _JAVAEXCEPTIONS_H_

    31 #define _JAVAEXCEPTIONS_H_

    32 

    33 #include    <jni.h>

    34 #include    <jvmti.h>

    35 

    36 /**

    37  * This module contains utility routines for manipulating Java throwables

    38  * and JNIEnv throwable state from native code.

    39  */

    40 

    41 #ifdef __cplusplus

    42 extern "C" {

    43 #endif

    44 

    45 /*

    46  * Set up static state. Needs java, must be called at or after VMInit.

    47  * Returns true if it succeeds, false if it fails.

    48  */

    49 extern jboolean

    50 initializeFallbackError(JNIEnv* jnienv);

    51 

    52 /*

    53  *  Mapping support. Allows different clients to map checked exceptions in different ways.

    54  */

    55 typedef jthrowable (*CheckedExceptionMapper)

    56     (   JNIEnv *    jnienv,

    57         jthrowable  throwableToMap);

    58 

    59 /* Default mapper. Map everything checked to InternalError; can return null if error */

    60 extern jthrowable

    61 mapAllCheckedToInternalErrorMapper( JNIEnv *    jnienv,

    62                                     jthrowable  throwableToMap);

    63 

    64 

    65 

    66 /*

    67  *  Exception-helper routines that do not modify the JNIEnv.

    68  *  They require a clean JNIEnv on entry, and they guarantee a clean JNIEnv on exit.

    69  */

    70 

    71 /* creates a throwable from the supplied parameters; can return null if error */

    72 extern jthrowable

    73 createThrowable(    JNIEnv*     jnienv,

    74                     const char* className,

    75                     jstring     message);

    76 

    77 /* creates a java.lang.InternalError; can return null if error */

    78 extern jthrowable

    79 createInternalError(JNIEnv * jnienv, jstring message);

    80 

    81 /* creates the appropriate java Throwable based on the error code; can return null if error */

    82 extern jthrowable

    83 createThrowableFromJVMTIErrorCode(JNIEnv * jnienv, jvmtiError errorCode);

    84 

    85 /* fetches the message string out of the supplied throwable, null if there is none, null if error   */

    86 extern jstring

    87 getMessageFromThrowable(    JNIEnv*     jnienv,

    88                             jthrowable  exception);

    89 

    90 /* true if the supplied throwable is unchecked. null will return true.  */

    91 extern jboolean

    92 isUnchecked(    JNIEnv*     jnienv,

    93                 jthrowable  exception);

    94 

    95 /* true if the env contains a thrown exception */

    96 extern jboolean

    97 checkForThrowable(  JNIEnv*     jnienv);

    98 

    99 /* true if the env is clean for JNI calls */

   100 extern jboolean

   101 isSafeForJNICalls(  JNIEnv * jnienv);

   102 

   103 /*

   104  * Logs the outstanding throwable, if one exists.

   105  * This call assumes an outstanding exception, but does not

   106  * modify the JNIEnv outstanding Throwable state.

   107  */

   108 extern void

   109 logThrowable(   JNIEnv * jnienv);

   110 

   111 

   112 /*

   113  *  These routines do modify the JNIEnv outstanding Throwable state.

   114  */

   115 

   116 /* Throws the supplied throwable. always sets the JNIEnv throwable */

   117 extern void

   118 throwThrowable(     JNIEnv *    jnienv,

   119                     jthrowable  exception);

   120 

   121 /* returns current throwable. always clears the JNIEnv exception */

   122 extern jthrowable

   123 preserveThrowable(JNIEnv * jnienv);

   124 

   125 /* undoes preserveThrowable (Throws the supplied throwable). always sets the JNIEnv throwable */

   126 extern void

   127 restoreThrowable(   JNIEnv *    jnienv,

   128                     jthrowable  preservedException);

   129 

   130 /* always clears the JNIEnv throwable. returns true if an exception was pending on entry. */

   131 extern jboolean

   132 checkForAndClearThrowable(  JNIEnv *    jnienv);

   133 

   134 /* creates the appropriate java Throwable based on the error code

   135  * does the very best it can to make sure an exception ends up installed; uses fallback if necessary

   136  * always sets the JNIEnv exception

   137  */

   138 extern void

   139 createAndThrowThrowableFromJVMTIErrorCode(JNIEnv * jnienv, jvmtiError errorCode);

   140 

   141 /* creates a java.lang.InternalError and installs it into the JNIEnv.

   142  * does the very best it can to make sure an exception ends up installed; uses fallback if necessary

   143  * always sets the JNIEnv exception

   144  */

   145 extern void

   146 createAndThrowInternalError(JNIEnv * jnienv);

   147 

   148 /* If no throwable is outstanding, do nothing.

   149  * If a throwable is outstanding, make sure it is of a legal type according to the supplied

   150  * mapping function.

   151  * Leaves the "thrown" state the same (none on exit if none on entry, thrown on exit if

   152  * thrown on entry); may change the type of the thrown exception.

   153  */

   154 extern void

   155 mapThrownThrowableIfNecessary(JNIEnv * jnienv, CheckedExceptionMapper mapper);

   156 

   157 #ifdef __cplusplus

   158 } /* extern "C" */

   159 #endif /* __cplusplus */

   160 

   161 

   162 #endif