|
1 /* |
|
2 * Copyright (c) 1997, 2013, 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 #ifndef JNI_UTIL_H |
|
27 #define JNI_UTIL_H |
|
28 |
|
29 #include "jni.h" |
|
30 #include "jlong.h" |
|
31 |
|
32 #ifdef __cplusplus |
|
33 extern "C" { |
|
34 #endif |
|
35 |
|
36 /* |
|
37 * This file contains utility functions that can be implemented in pure JNI. |
|
38 * |
|
39 * Caution: Callers of functions declared in this file should be |
|
40 * particularly aware of the fact that these functions are convenience |
|
41 * functions, and as such are often compound operations, each one of |
|
42 * which may throw an exception. Therefore, the functions this file |
|
43 * will often return silently if an exception has occurred, and callers |
|
44 * must check for exception themselves. |
|
45 */ |
|
46 |
|
47 /* Throw a Java exception by name. Similar to SignalError. */ |
|
48 JNIEXPORT void JNICALL |
|
49 JNU_ThrowByName(JNIEnv *env, const char *name, const char *msg); |
|
50 |
|
51 /* Throw common exceptions */ |
|
52 JNIEXPORT void JNICALL |
|
53 JNU_ThrowNullPointerException(JNIEnv *env, const char *msg); |
|
54 |
|
55 JNIEXPORT void JNICALL |
|
56 JNU_ThrowArrayIndexOutOfBoundsException(JNIEnv *env, const char *msg); |
|
57 |
|
58 JNIEXPORT void JNICALL |
|
59 JNU_ThrowOutOfMemoryError(JNIEnv *env, const char *msg); |
|
60 |
|
61 JNIEXPORT void JNICALL |
|
62 JNU_ThrowIllegalArgumentException(JNIEnv *env, const char *msg); |
|
63 |
|
64 JNIEXPORT void JNICALL |
|
65 JNU_ThrowIllegalAccessError(JNIEnv *env, const char *msg); |
|
66 |
|
67 JNIEXPORT void JNICALL |
|
68 JNU_ThrowIllegalAccessException(JNIEnv *env, const char *msg); |
|
69 |
|
70 JNIEXPORT void JNICALL |
|
71 JNU_ThrowInternalError(JNIEnv *env, const char *msg); |
|
72 |
|
73 JNIEXPORT void JNICALL |
|
74 JNU_ThrowIOException(JNIEnv *env, const char *msg); |
|
75 |
|
76 JNIEXPORT void JNICALL |
|
77 JNU_ThrowNoSuchFieldException(JNIEnv *env, const char *msg); |
|
78 |
|
79 JNIEXPORT void JNICALL |
|
80 JNU_ThrowNoSuchMethodException(JNIEnv *env, const char *msg); |
|
81 |
|
82 JNIEXPORT void JNICALL |
|
83 JNU_ThrowClassNotFoundException(JNIEnv *env, const char *msg); |
|
84 |
|
85 JNIEXPORT void JNICALL |
|
86 JNU_ThrowNumberFormatException(JNIEnv *env, const char *msg); |
|
87 |
|
88 JNIEXPORT void JNICALL |
|
89 JNU_ThrowNoSuchFieldError(JNIEnv *env, const char *msg); |
|
90 |
|
91 JNIEXPORT void JNICALL |
|
92 JNU_ThrowNoSuchMethodError(JNIEnv *env, const char *msg); |
|
93 |
|
94 JNIEXPORT void JNICALL |
|
95 JNU_ThrowStringIndexOutOfBoundsException(JNIEnv *env, const char *msg); |
|
96 |
|
97 JNIEXPORT void JNICALL |
|
98 JNU_ThrowInstantiationException(JNIEnv *env, const char *msg); |
|
99 |
|
100 /* Throw an exception by name, using the string returned by |
|
101 * JVM_LastErrorString for the detail string. If the last-error |
|
102 * string is NULL, use the given default detail string. |
|
103 */ |
|
104 JNIEXPORT void JNICALL |
|
105 JNU_ThrowByNameWithLastError(JNIEnv *env, const char *name, |
|
106 const char *defaultMessage); |
|
107 |
|
108 /* Throw an IOException, using the last-error string for the detail |
|
109 * string. If the last-error string is NULL, use the given default |
|
110 * detail string. |
|
111 */ |
|
112 JNIEXPORT void JNICALL |
|
113 JNU_ThrowIOExceptionWithLastError(JNIEnv *env, const char *defaultDetail); |
|
114 |
|
115 /* Convert between Java strings and i18n C strings */ |
|
116 JNIEXPORT jstring |
|
117 NewStringPlatform(JNIEnv *env, const char *str); |
|
118 |
|
119 JNIEXPORT const char * |
|
120 GetStringPlatformChars(JNIEnv *env, jstring jstr, jboolean *isCopy); |
|
121 |
|
122 JNIEXPORT jstring JNICALL |
|
123 JNU_NewStringPlatform(JNIEnv *env, const char *str); |
|
124 |
|
125 JNIEXPORT const char * JNICALL |
|
126 JNU_GetStringPlatformChars(JNIEnv *env, jstring jstr, jboolean *isCopy); |
|
127 |
|
128 JNIEXPORT void JNICALL |
|
129 JNU_ReleaseStringPlatformChars(JNIEnv *env, jstring jstr, const char *str); |
|
130 |
|
131 /* Class constants */ |
|
132 JNIEXPORT jclass JNICALL |
|
133 JNU_ClassString(JNIEnv *env); |
|
134 |
|
135 JNIEXPORT jclass JNICALL |
|
136 JNU_ClassClass(JNIEnv *env); |
|
137 |
|
138 JNIEXPORT jclass JNICALL |
|
139 JNU_ClassObject(JNIEnv *env); |
|
140 |
|
141 JNIEXPORT jclass JNICALL |
|
142 JNU_ClassThrowable(JNIEnv *env); |
|
143 |
|
144 /* Copy count number of arguments from src to dst. Array bounds |
|
145 * and ArrayStoreException are checked. |
|
146 */ |
|
147 JNIEXPORT jint JNICALL |
|
148 JNU_CopyObjectArray(JNIEnv *env, jobjectArray dst, jobjectArray src, |
|
149 jint count); |
|
150 |
|
151 /* Invoke a object-returning static method, based on class name, |
|
152 * method name, and signature string. |
|
153 * |
|
154 * The caller should check for exceptions by setting hasException |
|
155 * argument. If the caller is not interested in whether an exception |
|
156 * has occurred, pass in NULL. |
|
157 */ |
|
158 JNIEXPORT jvalue JNICALL |
|
159 JNU_CallStaticMethodByName(JNIEnv *env, |
|
160 jboolean *hasException, |
|
161 const char *class_name, |
|
162 const char *name, |
|
163 const char *signature, |
|
164 ...); |
|
165 |
|
166 /* Invoke an instance method by name. |
|
167 */ |
|
168 JNIEXPORT jvalue JNICALL |
|
169 JNU_CallMethodByName(JNIEnv *env, |
|
170 jboolean *hasException, |
|
171 jobject obj, |
|
172 const char *name, |
|
173 const char *signature, |
|
174 ...); |
|
175 |
|
176 JNIEXPORT jvalue JNICALL |
|
177 JNU_CallMethodByNameV(JNIEnv *env, |
|
178 jboolean *hasException, |
|
179 jobject obj, |
|
180 const char *name, |
|
181 const char *signature, |
|
182 va_list args); |
|
183 |
|
184 /* Construct a new object of class, specifying the class by name, |
|
185 * and specififying which constructor to run and what arguments to |
|
186 * pass to it. |
|
187 * |
|
188 * The method will return an initialized instance if successful. |
|
189 * It will return NULL if an error has occurred (for example if |
|
190 * it ran out of memory) and the appropriate Java exception will |
|
191 * have been thrown. |
|
192 */ |
|
193 JNIEXPORT jobject JNICALL |
|
194 JNU_NewObjectByName(JNIEnv *env, const char *class_name, |
|
195 const char *constructor_sig, ...); |
|
196 |
|
197 /* returns: |
|
198 * 0: object is not an instance of the class named by classname. |
|
199 * 1: object is an instance of the class named by classname. |
|
200 * -1: the class named by classname cannot be found. An exception |
|
201 * has been thrown. |
|
202 */ |
|
203 JNIEXPORT jint JNICALL |
|
204 JNU_IsInstanceOfByName(JNIEnv *env, jobject object, char *classname); |
|
205 |
|
206 |
|
207 /* Get or set class and instance fields. |
|
208 * Note that set functions take a variable number of arguments, |
|
209 * but only one argument of the appropriate type can be passed. |
|
210 * For example, to set an integer field i to 100: |
|
211 * |
|
212 * JNU_SetFieldByName(env, &exc, obj, "i", "I", 100); |
|
213 * |
|
214 * To set a float field f to 12.3: |
|
215 * |
|
216 * JNU_SetFieldByName(env, &exc, obj, "f", "F", 12.3); |
|
217 * |
|
218 * The caller should check for exceptions by setting hasException |
|
219 * argument. If the caller is not interested in whether an exception |
|
220 * has occurred, pass in NULL. |
|
221 */ |
|
222 JNIEXPORT jvalue JNICALL |
|
223 JNU_GetFieldByName(JNIEnv *env, |
|
224 jboolean *hasException, |
|
225 jobject obj, |
|
226 const char *name, |
|
227 const char *sig); |
|
228 JNIEXPORT void JNICALL |
|
229 JNU_SetFieldByName(JNIEnv *env, |
|
230 jboolean *hasException, |
|
231 jobject obj, |
|
232 const char *name, |
|
233 const char *sig, |
|
234 ...); |
|
235 |
|
236 JNIEXPORT jvalue JNICALL |
|
237 JNU_GetStaticFieldByName(JNIEnv *env, |
|
238 jboolean *hasException, |
|
239 const char *classname, |
|
240 const char *name, |
|
241 const char *sig); |
|
242 JNIEXPORT void JNICALL |
|
243 JNU_SetStaticFieldByName(JNIEnv *env, |
|
244 jboolean *hasException, |
|
245 const char *classname, |
|
246 const char *name, |
|
247 const char *sig, |
|
248 ...); |
|
249 |
|
250 |
|
251 /* |
|
252 * Calls the .equals method. |
|
253 */ |
|
254 JNIEXPORT jboolean JNICALL |
|
255 JNU_Equals(JNIEnv *env, jobject object1, jobject object2); |
|
256 |
|
257 |
|
258 /************************************************************************ |
|
259 * Thread calls |
|
260 * |
|
261 * Convenience thread-related calls on the java.lang.Object class. |
|
262 */ |
|
263 |
|
264 JNIEXPORT void JNICALL |
|
265 JNU_MonitorWait(JNIEnv *env, jobject object, jlong timeout); |
|
266 |
|
267 JNIEXPORT void JNICALL |
|
268 JNU_Notify(JNIEnv *env, jobject object); |
|
269 |
|
270 JNIEXPORT void JNICALL |
|
271 JNU_NotifyAll(JNIEnv *env, jobject object); |
|
272 |
|
273 |
|
274 /************************************************************************ |
|
275 * Miscellaneous utilities used by the class libraries |
|
276 */ |
|
277 |
|
278 #define IS_NULL(obj) ((obj) == NULL) |
|
279 #define JNU_IsNull(env,obj) ((obj) == NULL) |
|
280 |
|
281 /************************************************************************ |
|
282 * Miscellaneous utilities used by the class libraries to return from |
|
283 * a function if a value is NULL or an exception is pending. |
|
284 */ |
|
285 |
|
286 #define CHECK_NULL(x) \ |
|
287 do { \ |
|
288 if ((x) == NULL) { \ |
|
289 return; \ |
|
290 } \ |
|
291 } while (0) \ |
|
292 |
|
293 #define CHECK_NULL_RETURN(x, y) \ |
|
294 do { \ |
|
295 if ((x) == NULL) { \ |
|
296 return (y); \ |
|
297 } \ |
|
298 } while (0) \ |
|
299 |
|
300 #ifdef __cplusplus |
|
301 #define JNU_CHECK_EXCEPTION(env) \ |
|
302 do { \ |
|
303 if ((env)->ExceptionCheck()) { \ |
|
304 return; \ |
|
305 } \ |
|
306 } while (0) \ |
|
307 |
|
308 #define JNU_CHECK_EXCEPTION_RETURN(env, y) \ |
|
309 do { \ |
|
310 if ((env)->ExceptionCheck()) { \ |
|
311 return (y); \ |
|
312 } \ |
|
313 } while (0) |
|
314 #else |
|
315 #define JNU_CHECK_EXCEPTION(env) \ |
|
316 do { \ |
|
317 if ((*env)->ExceptionCheck(env)) { \ |
|
318 return; \ |
|
319 } \ |
|
320 } while (0) \ |
|
321 |
|
322 #define JNU_CHECK_EXCEPTION_RETURN(env, y) \ |
|
323 do { \ |
|
324 if ((*env)->ExceptionCheck(env)) { \ |
|
325 return (y); \ |
|
326 } \ |
|
327 } while (0) |
|
328 #endif /* __cplusplus */ |
|
329 /************************************************************************ |
|
330 * Debugging utilities |
|
331 */ |
|
332 |
|
333 JNIEXPORT void JNICALL |
|
334 JNU_PrintString(JNIEnv *env, char *hdr, jstring string); |
|
335 |
|
336 JNIEXPORT void JNICALL |
|
337 JNU_PrintClass(JNIEnv *env, char *hdr, jobject object); |
|
338 |
|
339 JNIEXPORT jstring JNICALL |
|
340 JNU_ToString(JNIEnv *env, jobject object); |
|
341 |
|
342 /* |
|
343 * Package shorthand for use by native libraries |
|
344 */ |
|
345 #define JNU_JAVAPKG "java/lang/" |
|
346 #define JNU_JAVAIOPKG "java/io/" |
|
347 #define JNU_JAVANETPKG "java/net/" |
|
348 |
|
349 /* |
|
350 * Check if the current thread is attached to the VM, and returns |
|
351 * the JNIEnv of the specified version if the thread is attached. |
|
352 * |
|
353 * If the current thread is not attached, this function returns 0. |
|
354 * |
|
355 * If the current thread is attached, this function returns the |
|
356 * JNI environment, or returns (void *)JNI_ERR if the specified |
|
357 * version is not supported. |
|
358 */ |
|
359 JNIEXPORT void * JNICALL |
|
360 JNU_GetEnv(JavaVM *vm, jint version); |
|
361 |
|
362 /* |
|
363 * Warning free access to pointers stored in Java long fields. |
|
364 */ |
|
365 #define JNU_GetLongFieldAsPtr(env,obj,id) \ |
|
366 (jlong_to_ptr((*(env))->GetLongField((env),(obj),(id)))) |
|
367 #define JNU_SetLongFieldFromPtr(env,obj,id,val) \ |
|
368 (*(env))->SetLongField((env),(obj),(id),ptr_to_jlong(val)) |
|
369 |
|
370 /* |
|
371 * Internal use only. |
|
372 */ |
|
373 enum { |
|
374 NO_ENCODING_YET = 0, /* "sun.jnu.encoding" not yet set */ |
|
375 NO_FAST_ENCODING, /* Platform encoding is not fast */ |
|
376 FAST_8859_1, /* ISO-8859-1 */ |
|
377 FAST_CP1252, /* MS-DOS Cp1252 */ |
|
378 FAST_646_US /* US-ASCII : ISO646-US */ |
|
379 }; |
|
380 |
|
381 int getFastEncoding(); |
|
382 |
|
383 void initializeEncoding(); |
|
384 |
|
385 void* getProcessHandle(); |
|
386 |
|
387 void buildJniFunctionName(const char *sym, const char *cname, |
|
388 char *jniEntryName); |
|
389 |
|
390 #ifdef __cplusplus |
|
391 } /* extern "C" */ |
|
392 #endif /* __cplusplus */ |
|
393 |
|
394 #endif /* JNI_UTIL_H */ |