Main Page | Namespace List | Alphabetical List | Data Structures | Directories | File List | Data Fields | Globals | Related Pages

jlObject.h

Go to the documentation of this file.
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 

Generated on Fri Sep 30 18:48:57 2005 by  doxygen 1.4.4