00001 #ifndef _jlObject_h_included_ 00002 #define _jlObject_h_included_ 00003 00004 /*! 00005 * @file jlObject.h 00006 * 00007 * @brief Public interface to native implementation of 00008 * @c @b java.lang.Object 00009 * 00010 * Two parallel sets of definitions are used here, one for internal 00011 * implementation purposes, the other for the JNI interface. The first 00012 * uses internal data types (via @link #JLOBJECT_LOCAL_DEFINED 00013 \#ifdef JLOBJECT_LOCAL_DEFINED@endlink) where the second does not. 00014 * Instead, it uses @c @b <jni.h> data types. Those types @e must 00015 * match up for JNI to work, yet by keeping them 00016 * absolutely separate, application JNI code does @e not have 00017 * @b any dependencies on the core code of this JVM implementation. 00018 * 00019 * Even though there is only apparently @e one set of definitions, 00020 * the @c @b \#ifdef statement controls which set is used. 00021 * 00022 * This file must be included by JNI code along with the 00023 * @c @b java.lang.Class JNI header file. The following example 00024 * shows how to call one of the @e local native methods of this class 00025 * from the JNI environment. Notice that although this is not necessary 00026 * due to the local implementation shortcut defined in 00027 * @link jvm/src/native.c native.c@endlink, it is not only possible, 00028 * but sometimes quite desirable to do so. 00029 * 00030 * @verbatim 00031 #include <jni.h> 00032 #include <solaris/jni_md.h> ... or appropriate platform-specifics 00033 #include "java_lang_Object.h" ... JNI definitions 00034 #include "jlObject.h" ... this file 00035 00036 JNIEXPORT jint JNICALL 00037 Java_java_lang_Object_hashCode(JNIEnv *env, jobject thisobj) 00038 { 00039 jint i; 00040 00041 i = jlClass_hashCode(thisobj); ... call native implementation 00042 00043 return(i); 00044 } 00045 @endverbatim 00046 * 00047 * @attention This local native method implementation is defined 00048 * in @link jvm/src/native.c native.c@endlink and 00049 * does @e not make use of the @b JNIENV pointer in 00050 * @e any manner. 00051 * 00052 * @attention Although @link #jvalue jvalue@endlink is indeed a part 00053 * of both this implementation and the standard JNI interface 00054 * through @c @b <jni.h> , it is @e not recommended to use 00055 * it if at all possible. Due to the fact that both 00056 * definitions involve unions, along with the slightly 00057 * differing contents between the two versions, it is almost 00058 * certain that there will be compilation compatibility 00059 * problems in the memory layouts from one platform to 00060 * another, and possibly between the layouts between them on 00061 * any given platform. Since @link #jvalue jvalue@endlink 00062 * is not specificaly a @e Java type, but instead a JNI 00063 * construction, this may not be a problem, but this 00064 * advisory is raised anyway in order to encourage reliable 00065 * implementation of JNI. 00066 * 00067 * @section Control 00068 * 00069 * \$URL: https://svn.apache.org/path/name/jlObject.h $ \$Id: jlObject.h 0 09/28/2005 dlydick $ 00070 * 00071 * Copyright 2005 The Apache Software Foundation 00072 * or its licensors, as applicable. 00073 * 00074 * Licensed under the Apache License, Version 2.0 ("the License"); 00075 * you may not use this file except in compliance with the License. 00076 * You may obtain a copy of the License at 00077 * 00078 * http://www.apache.org/licenses/LICENSE-2.0 00079 * 00080 * Unless required by applicable law or agreed to in writing, 00081 * software distributed under the License is distributed on an 00082 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, 00083 * either express or implied. 00084 * 00085 * See the License for the specific language governing permissions 00086 * and limitations under the License. 00087 * 00088 * @version \$LastChangedRevision: 0 $ 00089 * 00090 * @date \$LastChangedDate: 09/28/2005 $ 00091 * 00092 * @author \$LastChangedBy: dlydick $ 00093 * Original code contributed by Daniel Lydick on 09/28/2005. 00094 * 00095 * @section Reference 00096 * 00097 */ 00098 00099 00100 /**********************************************************************/ 00101 #ifdef JLOBJECT_LOCAL_DEFINED 00102 00103 ARCH_COPYRIGHT_APACHE(jlObject, h, "$URL: https://svn.apache.org/path/name/jlObject.h $ $Id: jlObject.h 0 09/28/2005 dlydick $"); 00104 00105 /**********************************************************************/ 00106 #else /* JLOBJECT_LOCAL_DEFINED */ 00107 00108 /*! 00109 * @name Reserved native local method ordinal numbers 00110 * 00111 * @brief These ordinal values are reserved for use by the 00112 * local native method interface as implemented in 00113 * @link jvm/src/native.c native.c@endlink 00114 * 00115 */ 00116 /*@{*/ 00117 /*! 00118 * @brief Empty table index for code internals. 00119 * 00120 * See also parallel definition in 00121 * @link #JVMCFG_JLOBJECT_NMO_NULL jvmcfg.h@endlink 00122 */ 00123 #define JLOBJECT_NMO_NULL 0 00124 00125 00126 /*! 00127 * @brief Reserved table index for JNI method registration. 00128 * 00129 * See also parallel definition in 00130 * @link #JVMCFG_JLOBJECT_NMO_REGISTER jvmcfg.h@endlink 00131 */ 00132 #define JLOBJECT_NMO_REGISTER 1 00133 00134 00135 /*! 00136 * @brief Reserved table index for JNI method <em>de</em>-registration. 00137 * 00138 * See also parallel definition in 00139 * @link #JVMCFG_JLOBJECT_NMO_UNREGISTER jvmcfg.h@endlink 00140 */ 00141 #define JLOBJECT_NMO_UNREGISTER 2 00142 00143 /*}@*/ 00144 00145 /*! 00146 * @name JNI parallel type definitions. 00147 * 00148 * @brief Implementation type definitions, but redefined from 00149 * @c @b <jni.h> so no implementation header files are needed by 00150 * JNI source code. 00151 * 00152 * See also respective parallel definition for each one as found 00153 * particularly in @link jvm/src/jvmcfg.h jvmcfg.h@endlink 00154 * 00155 */ 00156 00157 /*@{*/ 00158 00159 /*! 00160 * @brief Implementation type definition for @c @b jobject 00161 * 00162 * This symbol is defined for use in the core JVM code in 00163 * @link jvm/src/jvmcfg.h jvmcfg.h@endlink. 00164 * 00165 * @attention See comments about @c @b jobject and @c @b jclass in 00166 * the local definition of @b jvm_class_index. 00167 * 00168 * @todo In the JVM spec, an object reference seems to look like an 00169 * arbitrary integer token. However, looking at the JNI header 00170 * file for the Solaris JDK 1.4.2_06 implementation, it appears 00171 * to be a pointer to an empty structure. The apparent purpose 00172 * of this definition is to have a @e completely generic 00173 * definition of use by any implementation. @b HOWEVER, there 00174 * is a problem with this: What happens when the implementation 00175 * is ported to a 64-bit hardware runtime environment? All 00176 * pointers change from 32 bits (namely, from 00177 * @c @b sizeof(jint)) to 64 bits (namely, 00178 * @c @b sizeof(jlong)), taking a second 32-bit word. 00179 * This can have @e significant implications for code, and not 00180 * only for the JNI interface. This needs some detailed scrutiny 00181 * so that the JNI interface and the implementation as a whole 00182 * properly compensates for this situtation or declares it a 00183 * non-issue. 00184 * 00185 * @note As an aside, and in addition to the above @todo item, the 00186 * consider that many GC implementations use a variation 00187 * of "copying garbage collection" (sometimes with adjectives 00188 * in front, such as "generational copying garbage collection," 00189 * etc.). These tend to be more efficient than the old 00190 * mark-and-sweep, even though they usually add an extra 00191 * layer of indirection. For example, every pointer might 00192 * actually be an index into a table of pointers or perhaps 00193 * a pointer to a pointer. The idea is that the GC algorithm 00194 * can relocate/copy the object, knowing it needs to update 00195 * only one pointer and all current accesses to the object 00196 * at its old location will now be able to access it at its new 00197 * location without missing a beat. In this case, the 32-bit 00198 * unsigned int might be an index into a table of pointers and 00199 * the pointers might be 64-bits or 32-bits or anything else. 00200 * 00201 */ 00202 typedef jobject jvm_object_hash; 00203 00204 /*! 00205 * @brief Implementation type definition for @c @b jclass 00206 * 00207 * This symbol is defined for use in the core JVM code in 00208 * @link jvm/src/jvmcfg.h jvmcfg.h@endlink. 00209 * 00210 * @attention As long as this type definition is the same width or 00211 * narrower than the local definition of @b jvm_object_hash, all 00212 * code will connect the JNI and JVM environments properly. Some 00213 * Java implementations may consider @c @b jobject to be an ordinal, 00214 * some may consider it to be an array index, some may consider it 00215 * to be a pointer. If @c @b jclass is compatible with such definition, 00216 * then everything should work fine. The compiler will provide the 00217 * necessary width adjustments without loss of any significant digits. 00218 * @e Therefore, notice that this data type @e cannot be defined as 00219 * being any @e wider than @c @b jobject and @b jvm_object_hash. 00220 */ 00221 typedef jclass jvm_class_index; 00222 00223 /*! 00224 * @brief Definition of Java @c @b void as used in 00225 * this implementation. 00226 * 00227 * This type definition is @e not typically part 00228 * of @c @b <jni.h> but used extensively here. 00229 * 00230 * This symbol is defined for use in the core JVM code in 00231 * @link jvm/src/jrtypes.h jrtypes.h@endlink. 00232 */ 00233 typedef void jvoid; 00234 00235 /*@}*/ 00236 00237 #endif /* JLOBJECT_LOCAL_DEFINED */ 00238 /**********************************************************************/ 00239 00240 /*! 00241 * @name Unified set of prototypes for functions 00242 * in @link jvm/src/jlObject.c jlObject.c@endlink 00243 * 00244 * @brief JNI table index and external reference to 00245 * each function that locally implements a JNI native method. 00246 * 00247 * The JVM native interface ordinal definition base for this class 00248 * is 10. An enumeration is used so the compiler can help the use 00249 * to not choose duplicate values. 00250 * 00251 */ 00252 00253 /*@{ */ /* Begin grouped definitions */ 00254 00255 typedef enum 00256 { 00257 00258 JLOBJECT_NMO_GETCLASS = 10, /**< Ordinal for 00259 @link #jlObject_getClass() getClass()@endlink */ 00260 00261 JLOBJECT_NMO_HASHCODE = 11, /**< Ordinal for 00262 @link #jlObject_hashCode() hashCode()@endlink */ 00263 00264 JLOBJECT_NMO_WAIT4EVER = 12, /**< Ordinal for 00265 @link #jlObject_wait4ever() wait4ever()@endlink */ 00266 00267 JLOBJECT_NMO_WAITTIMED = 13 /**< Ordinal for 00268 @link #jlObject_waittimed() waittimed()@endlink */ 00269 00270 } jlObject_nmo_enum; 00271 00272 /* 00273 * Add one function prototype below 00274 * for each local native method enumeration above: 00275 */ 00276 00277 /*! 00278 * @brief JNI hook to @link #jlObject_getClass() getClass()@endlink 00279 */ 00280 jvm_object_hash jlObject_getClass(jvm_object_hash objhash); 00281 00282 /*! 00283 * @brief JNI hook to @link #jlObject_hashCode() hashCode()@endlink 00284 */ 00285 jint jlObject_hashCode(jvm_object_hash objhash); 00286 00287 /*! 00288 * @brief JNI hook to @link #jlObject_wait4ever() wait4ever()@endlink 00289 */ 00290 extern jvoid jlObject_wait4ever(jvm_object_hash objhashcurr); 00291 00292 /*! 00293 * @brief JNI hook to @link #jlObject_waittimed() waittimed()@endlink 00294 */ 00295 extern jvoid jlObject_waittimed(jvm_object_hash objhashcurr, 00296 jlong sleeptime); 00297 00298 /*@} */ /* End grouped definitions */ 00299 00300 00301 /*! 00302 * @name Connection to local native method tables. 00303 * 00304 * @brief These manifest constant code fragments are designed to be 00305 * inserted directly into locations in 00306 * @link jvm/src/native.c native.c@endlink without any other 00307 * modification to that file except a @e single entry to actually 00308 * invoke the method. 00309 * 00310 */ 00311 /*@{ */ /* Begin grouped definitions */ 00312 00313 00314 /*! 00315 * @brief Complete list of local native method ordinals 00316 * for @c @b java.lang.Object 00317 */ 00318 #define NATIVE_TABLE_JLOBJECT \ 00319 case JLOBJECT_NMO_GETCLASS: \ 00320 case JLOBJECT_NMO_HASHCODE: \ 00321 case JLOBJECT_NMO_WAIT4EVER: \ 00322 case JLOBJECT_NMO_WAITTIMED: 00323 00324 /*! 00325 * @brief Table of local native methods and their descriptors 00326 * for @c @b java.lang.Object 00327 */ 00328 #define NATIVE_TABLE_JLOBJECT_ORDINALS \ 00329 { \ 00330 { JLOBJECT_NMO_GETCLASS, "getClass", "()Ljava/lang/Class" }, \ 00331 { JLOBJECT_NMO_HASHCODE, "hashCode", "()I" }, \ 00332 { JLOBJECT_NMO_WAIT4EVER, "wait", "()V" }, \ 00333 { JLOBJECT_NMO_WAIT4EVER, "wait", "(J)V" }, \ 00334 \ 00335 /* Add other method entries here */ \ 00336 \ 00337 \ 00338 /* End of table marker */ \ 00339 { JVMCFG_JLOBJECT_NMO_NULL, \ 00340 CHEAT_AND_USE_NULL_TO_INITIALIZE, \ 00341 CHEAT_AND_USE_NULL_TO_INITIALIZE } \ 00342 } 00343 00344 /*! 00345 * @brief @c @b (jvoid) local native method ordinal table 00346 * for @c @b java.lang.Object 00347 */ 00348 #define NATIVE_TABLE_JLOBJECT_JVOID \ 00349 case JLOBJECT_NMO_WAIT4EVER: \ 00350 case JLOBJECT_NMO_WAITTIMED: 00351 00352 /*! 00353 * @brief @c @b (jobject) local native method ordinal table 00354 * for @c @b java.lang.Object 00355 */ 00356 #define NATIVE_TABLE_JLOBJECT_JOBJECT \ 00357 case JLOBJECT_NMO_GETCLASS: 00358 00359 /*! 00360 * @brief @c @b (jint) local native method ordinal table 00361 * for @c @b java.lang.Object 00362 */ 00363 #define NATIVE_TABLE_JLOBJECT_JINT \ 00364 case JLOBJECT_NMO_HASHCODE: 00365 00366 #define NATIVE_TABLE_JLOBJECT_JFLOAT /**< No @c @b (jfloat) methods */ 00367 #define NATIVE_TABLE_JLOBJECT_JLONG /**< No @c @b (jlong) methods */ 00368 #define NATIVE_TABLE_JLOBJECT_JDOUBLE /**< No @c @b (jdouble) methods*/ 00369 00370 /*@} */ /* End grouped definitions */ 00371 00372 00373 #endif /* _jlObject_h_included_ */ 00374 00375 00376 /* EOF */ 00377