dtj_util.h revision fb3fb4f3d76d55b64440afd0af72775dfad3bd1d
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * CDDL HEADER START
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * The contents of this file are subject to the terms of the
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Common Development and Distribution License (the "License").
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * You may not use this file except in compliance with the License.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * See the License for the specific language governing permissions
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * and limitations under the License.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * When distributing Covered Code, include this CDDL HEADER in each
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * If applicable, add the following below this CDDL HEADER, with the
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * fields enclosed by brackets "[]" replaced with your own identifying
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * information: Portions Copyright [yyyy] [name of copyright owner]
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * CDDL HEADER END
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Use is subject to license terms.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee#pragma ident "%Z%%M% %I% %E% SMI"
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern "C" {
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * dtj_util.h separates functionality that is generally useful from
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * that which is specific to the Java DTrace API. If moved to a separate
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * library, this functionality could be shared by other JNI wrappers.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee#define WRAP_EXCEPTION(JENV) dtj_wrap_exception((JENV), __FILE__, __LINE__)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeetypedef enum dtj_status {
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeetypedef enum dtj_type {
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Convenient description format for java classes, methods, and fields. The
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * java_class_t, java_method_t, and java_field_t structures derived from these
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * descriptions are used to create a table of usable JNI jclass, jmethodID, and
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * jfieldID instances.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeetypedef struct dtj_table_entry {
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee void *djte_addr; /* jclass, jmethodID, or jfieldID address */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeetypedef struct dtj_java_class {
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee jclass *djc_ptr; /* address in user-defined structure */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee char *djc_name; /* fully qualified '/' delimited class name */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee uu_list_t *djc_methods; /* element type (java_method_t *) */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee uu_list_t *djc_fields; /* element type (java_field_t *) */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeetypedef struct dtj_java_method {
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee jmethodID *djm_ptr; /* address in user-defined structure */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee char *djm_signature; /* javap -s method signature string */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee boolean_t djm_static; /* flag indicating static qualifier */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeetypedef struct dtj_java_field {
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee jfieldID *djf_ptr; /* address in user-defined structure */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee boolean_t djf_static; /* flag indicating static qualifier */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Table of cached jclass, jmethodID, and jfieldID values usable across multiple
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * native method calls and multiple threads.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Suffix conventions:
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * jc java class
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * jm java method
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * jsm java static method
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * jf java field
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * jsf java static field
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* NativeException */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* java.io.Serializable */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* java.lang.Number */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* java.lang.Byte */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* java.lang.Character */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* java.lang.Short */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* java.lang.Integer */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* java.lang.Long */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* java.lang.String */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* java.lang.StringBuffer */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* java.lang.Object */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* java.lang.Enum */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Populates the common java class references and associated method and field
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * IDs declared in this file (above) using the dtj_cache_jni_classes() method.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Populates the user-declared java class references and associated method and
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * field IDs described in the given table. Because the class references are
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * created as global JNI references, the method and field IDs remain valid
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * across multiple native method calls and across multiple threads.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * This function assumes that the given table of java class, method, and field
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * descriptions is terminated by an entry with DTJ_TYPE_END, and that the
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * method and field descriptions immediately follow the description of their
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * containing class.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Throws NoClassDefFoundError, NoSuchMethodError, or NoSuchFieldError if any
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * dtj_table_entry_t in common_jni_table.c is incorrect.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern dtj_status_t dtj_cache_jni_classes(JNIEnv *, const dtj_table_entry_t *);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* Common utilities */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * The following functions each create a pending Java Error or Exception:
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * OutOfMemoryError
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * NullPointerException
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * IllegalArgumentException
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * IllegalStateException
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * NoSuchElementException
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * ClassCastException
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * AssertionError
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * org.opensolaris.os.support.ResourceLimitException
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Control should be returned to Java immediately afterwards.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern void dtj_throw_out_of_memory(JNIEnv *, const char *, ...);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern void dtj_throw_null_pointer(JNIEnv *, const char *, ...);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern void dtj_throw_illegal_argument(JNIEnv *, const char *, ...);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern void dtj_throw_illegal_state(JNIEnv *, const char *, ...);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern void dtj_throw_no_such_element(JNIEnv *, const char *, ...);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern void dtj_throw_class_cast(JNIEnv *, const char *, ...);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern void dtj_throw_assertion(JNIEnv *, const char *, ...);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern void dtj_throw_resource_limit(JNIEnv *, const char *, ...);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Attaches native filename and line number to the currently pending java
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * exception, since that information is not present in the exception stack
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern void dtj_wrap_exception(JNIEnv *, const char *, int);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Calls the toString() method of the given object and prints the value to
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * stdout (useful for debugging). If an exception is thrown in this function,
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * it is described on stdout and cleared. It's guaranteed that no exception is
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * pending when this function returns.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern void dtj_print_object(JNIEnv *jenv, jobject obj);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Gets a formatted String (local reference) from a format and a variable
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * argument list of placeholder values. Returns NULL if OutOfMemoryError is
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern jstring dtj_format_string(JNIEnv *jenv, const char *fmt, ...);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Internationalization support. These functions taken (not verbatim) from
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Section 8.2 of The Java Native Interface by Sheng Liang, The Java Series.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Use these functions for locale-specific strings such as file names.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern jstring dtj_NewStringNative(JNIEnv *jenv, const char *str);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern char *dtj_GetStringNativeChars(JNIEnv *jenv, jstring jstr);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern void dtj_ReleaseStringNativeChars(JNIEnv *jenv, jstring jstr,
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee const char *str);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Converts the args array of main(String[] args) in Java into a native
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * dynamically allocated array of strings. The returned array must be
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * deallocated by calling free_argv(). A java exception is pending if this
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * function returns NULL (in that case, any allocations made up to the point of
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * failure in get_argv() are automatically freed).
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Returns a NULL-terminated array that works with functions that expect a
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * terminating NULL rather than relying on an element count. The argc parameter
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * is also overwritten with the number of returned array elements (not including
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * the terminating NULL).
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern char **dtj_get_argv(JNIEnv *jenv, jobjectArray args, int *argc);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Tokenizes a command string to create a native dynamically allocated array of
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * strings. The first element of the returned array is assumed to be the name
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * of the command, and subsequent elements are arguments to that command.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Otherwise behaves exactly like get_argv() above, including requiring a
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * subsequent call to free_argv() on the returned array.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Throws NullPointerException if cmd is NULL.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Throws IllegalArgumentException if cmd is empty.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern char **dtj_make_argv(JNIEnv *jenv, jstring cmd, int *argc);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* Wrappers for uu_list_t */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * List element destructor.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * params: node pointer, user arg (may be NULL)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeetypedef void dtj_value_destroy_f(void *, void *);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * uu_list_t generic entry type for pointers compared by pointer value, similar
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * to Java's default Object.equals() implementation (referenced objects are
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * equal only if they have the same address in memory). Used with
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * pointer_list_entry_cmp.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeetypedef struct dtj_pointer_list_entry {
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeetypedef struct dtj_string_list_entry {
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* Comparison functions, uu_compare_fn_t signature */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern int dtj_pointer_list_entry_cmp(const void *, const void *, void *);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern int dtj_string_list_entry_cmp(const void *, const void *, void *);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* Constructors */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern dtj_pointer_list_entry_t *dtj_pointer_list_entry_create(void *);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern dtj_string_list_entry_t *dtj_string_list_entry_create(const char *);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* Destructors */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern void dtj_pointer_list_entry_destroy(void *, dtj_value_destroy_f *,
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern void dtj_string_list_entry_destroy(void *, void *);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Convenience function destroys a uu_list_t and its values.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * param list: list to be destroyed, call is a no-op if list is NULL
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * param value_destroy: optional destructor; if non-NULL, it is called on each
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * list value
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * param arg: user argument to the optional destructor
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern void dtj_list_destroy(uu_list_t *, dtj_value_destroy_f *, void *);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern void dtj_pointer_list_destroy(uu_list_t *, dtj_value_destroy_f *,
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Convenience functions clear a uu_list_t without destroying it. Destroys all
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * list elements and leaves the list empty. The *_list_destroy() functions
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * implicitly clear the list before destroying it.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern void dtj_list_clear(uu_list_t *, dtj_value_destroy_f *, void *);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern void dtj_pointer_list_clear(uu_list_t *, dtj_value_destroy_f *,
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* Return B_TRUE if successful, B_FALSE otherwise */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern boolean_t dtj_pointer_list_add(uu_list_t *, void *);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern boolean_t dtj_string_list_add(uu_list_t *, const char *);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* Return INVALID_PTR if list is empty (NULL is a valid list element) */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* Return INVALID_STR if list is empty (NULL is a valid list element) */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* Return INVALID_PTR at end of list (NULL is a valid list element) */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern void *dtj_pointer_list_walk_next(uu_list_walk_t *);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* Return INVALID_STR at end of list (NULL is a valid list element) */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern const char *dtj_string_list_walk_next(uu_list_walk_t *);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee#endif /* _DTJ_UTIL_H */