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 jstring nativeNewStringPlatform(JNIEnv *env, const char *str);
 382 
 383 char* nativeGetStringPlatformChars(JNIEnv *env, jstring jstr, jboolean *isCopy);
 384 
 385 int getFastEncoding();
 386 
 387 void initializeEncoding();
 388 
 389 void* getProcessHandle();
 390 
 391 void buildJniFunctionName(const char *sym, const char *cname,
 392                           char *jniEntryName);
 393 
 394 #ifdef __cplusplus
 395 } /* extern "C" */
 396 #endif /* __cplusplus */
 397 
 398 #endif /* JNI_UTIL_H */