1/*
2 * Copyright (c) 2003, Oracle and/or its affiliates. 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. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * 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
42extern "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 */
49extern jboolean
50initializeFallbackError(JNIEnv* jnienv);
51
52/*
53 * Mapping support. Allows different clients to map checked exceptions in different ways.
54 */
55typedef jthrowable (*CheckedExceptionMapper)
56 ( JNIEnv * jnienv,
57 jthrowable throwableToMap);
58
59/* Default mapper. Map everything checked to InternalError; can return null if error */
60extern jthrowable
61mapAllCheckedToInternalErrorMapper( 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 */
72extern jthrowable
73createThrowable( JNIEnv* jnienv,
74 const char* className,
75 jstring message);
76
77/* creates a java.lang.InternalError; can return null if error */
78extern jthrowable
79createInternalError(JNIEnv * jnienv, jstring message);
80
81/* creates the appropriate java Throwable based on the error code; can return null if error */
82extern jthrowable
83createThrowableFromJVMTIErrorCode(JNIEnv * jnienv, jvmtiError errorCode);
84
85/* fetches the message string out of the supplied throwable, null if there is none, null if error */
86extern jstring
87getMessageFromThrowable( JNIEnv* jnienv,
88 jthrowable exception);
89
90/* true if the supplied throwable is unchecked. null will return true. */
91extern jboolean
92isUnchecked( JNIEnv* jnienv,
93 jthrowable exception);
94
95/* true if the env contains a thrown exception */
96extern jboolean
97checkForThrowable( JNIEnv* jnienv);
98
99/* true if the env is clean for JNI calls */
100extern jboolean
101isSafeForJNICalls( 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 */
108extern void
109logThrowable( 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 */
117extern void
118throwThrowable( JNIEnv * jnienv,
119 jthrowable exception);
120
121/* returns current throwable. always clears the JNIEnv exception */
122extern jthrowable
123preserveThrowable(JNIEnv * jnienv);
124
125/* undoes preserveThrowable (Throws the supplied throwable). always sets the JNIEnv throwable */
126extern void
127restoreThrowable( JNIEnv * jnienv,
128 jthrowable preservedException);
129
130/* always clears the JNIEnv throwable. returns true if an exception was pending on entry. */
131extern jboolean
132checkForAndClearThrowable( 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 */
138extern void
139createAndThrowThrowableFromJVMTIErrorCode(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 */
145extern void
146createAndThrowInternalError(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 */
154extern void
155mapThrownThrowableIfNecessary(JNIEnv * jnienv, CheckedExceptionMapper mapper);
156
157#ifdef __cplusplus
158} /* extern "C" */
159#endif /* __cplusplus */
160
161
162#endif
163