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

jlObject.h File Reference


Detailed Description

Public interface to native implementation of java.lang.Object.

Two parallel sets of definitions are used here, one for internal implementation purposes, the other for the JNI interface. The first uses internal data types (via #ifdef JLOBJECT_LOCAL_DEFINED) where the second does not. Instead, it uses <jni.h> data types. Those types must match up for JNI to work, yet by keeping them absolutely separate, application JNI code does not have any dependencies on the core code of this JVM implementation.

Even though there is only apparently one set of definitions, the #ifdef statement controls which set is used.

This file must be included by JNI code along with the java.lang.Class JNI header file. The following example shows how to call one of the local native methods of this class from the JNI environment. Notice that although this is not necessary due to the local implementation shortcut defined in native.c, it is not only possible, but sometimes quite desirable to do so.

   #include <jni.h>
   #include <solaris/jni_md.h>   ... or appropriate platform-specifics
   #include "java_lang_Object.h" ... JNI definitions
   #include "jlObject.h"         ... this file
  
   JNIEXPORT jint JNICALL
       Java_java_lang_Object_hashCode(JNIEnv  *env, jobject thisobj)
   {
       jint i;

       i = jlClass_hashCode(thisobj); ... call native implementation

       return(i);
   }
   

Attention:
This local native method implementation is defined in native.c and does not make use of the JNIENV pointer in any manner.

Although jvalue is indeed a part of both this implementation and the standard JNI interface through <jni.h> , it is not recommended to use it if at all possible. Due to the fact that both definitions involve unions, along with the slightly differing contents between the two versions, it is almost certain that there will be compilation compatibility problems in the memory layouts from one platform to another, and possibly between the layouts between them on any given platform. Since jvalue is not specificaly a Java type, but instead a JNI construction, this may not be a problem, but this advisory is raised anyway in order to encourage reliable implementation of JNI.

Control

$URL: https://svn.apache.org/path/name/jlObject.h $ $Id: jlObject.h 0 09/28/2005 dlydick $

Copyright 2005 The Apache Software Foundation or its licensors, as applicable.

Licensed under the Apache License, Version 2.0 ("the License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

See the License for the specific language governing permissions and limitations under the License.

Version:
$LastChangedRevision: 0 $
Date:
$LastChangedDate: 09/28/2005 $
Author:
$LastChangedBy: dlydick $ Original code contributed by Daniel Lydick on 09/28/2005.

Reference

Definition in file jlObject.h.

Go to the source code of this file.

Reserved native local method ordinal numbers

These ordinal values are reserved for use by the local native method interface as implemented in native.c

#define JLOBJECT_NMO_NULL   0
 Empty table index for code internals.
#define JLOBJECT_NMO_REGISTER   1
 Reserved table index for JNI method registration.
#define JLOBJECT_NMO_UNREGISTER   2
 Reserved table index for JNI method de-registration.

Connection to local native method tables.

These manifest constant code fragments are designed to be inserted directly into locations in native.c without any other modification to that file except a single entry to actually invoke the method.

#define NATIVE_TABLE_JLOBJECT
 Complete list of local native method ordinals for java.lang.Object.
#define NATIVE_TABLE_JLOBJECT_JDOUBLE
 No (jdouble) methods.
#define NATIVE_TABLE_JLOBJECT_JFLOAT
 No (jfloat) methods.
#define NATIVE_TABLE_JLOBJECT_JINT   case JLOBJECT_NMO_HASHCODE:
 (jint) local native method ordinal table for java.lang.Object
#define NATIVE_TABLE_JLOBJECT_JLONG
 No (jlong) methods.
#define NATIVE_TABLE_JLOBJECT_JOBJECT   case JLOBJECT_NMO_GETCLASS:
 (jobject) local native method ordinal table for java.lang.Object
#define NATIVE_TABLE_JLOBJECT_JVOID
 (jvoid) local native method ordinal table for java.lang.Object
#define NATIVE_TABLE_JLOBJECT_ORDINALS
 Table of local native methods and their descriptors for java.lang.Object.

JNI parallel type definitions.

Implementation type definitions, but redefined from <jni.h> so no implementation header files are needed by JNI source code.

See also respective parallel definition for each one as found particularly in jvmcfg.h

typedef jclass jvm_class_index
 Implementation type definition for jclass.
typedef jobject jvm_object_hash
 Implementation type definition for jobject.
typedef void jvoid
 Definition of Java void as used in this implementation.

Unified set of prototypes for functions

JNI table index and external reference to each function that locally implements a JNI native method.

in jlObject.c

The JVM native interface ordinal definition base for this class is 10. An enumeration is used so the compiler can help the use to not choose duplicate values.

enum  jlObject_nmo_enum { JLOBJECT_NMO_GETCLASS = 10, JLOBJECT_NMO_HASHCODE = 11, JLOBJECT_NMO_WAIT4EVER = 12, JLOBJECT_NMO_WAITTIMED = 13 }
jvm_object_hash jlObject_getClass (jvm_object_hash objhash)
 JNI hook to getClass().
jint jlObject_hashCode (jvm_object_hash objhash)
 JNI hook to hashCode().
jvoid jlObject_wait4ever (jvm_object_hash objhashcurr)
 JNI hook to wait4ever().
jvoid jlObject_waittimed (jvm_object_hash objhashcurr, jlong sleeptime)
 JNI hook to waittimed().


Define Documentation

#define JLOBJECT_NMO_NULL   0
 

Empty table index for code internals.

See also parallel definition in jvmcfg.h

Definition at line 123 of file jlObject.h.

#define JLOBJECT_NMO_REGISTER   1
 

Reserved table index for JNI method registration.

See also parallel definition in jvmcfg.h

Definition at line 132 of file jlObject.h.

#define JLOBJECT_NMO_UNREGISTER   2
 

Reserved table index for JNI method de-registration.

See also parallel definition in jvmcfg.h

Definition at line 141 of file jlObject.h.

#define NATIVE_TABLE_JLOBJECT
 

Value:

Complete list of local native method ordinals for java.lang.Object.

Definition at line 318 of file jlObject.h.

Referenced by native_verify_ordinal_definition().

#define NATIVE_TABLE_JLOBJECT_ORDINALS
 

Value:

{                                                                 \
        { JLOBJECT_NMO_GETCLASS, "getClass", "()Ljava/lang/Class"  }, \
        { JLOBJECT_NMO_HASHCODE, "hashCode", "()I"  },                \
        { JLOBJECT_NMO_WAIT4EVER, "wait",    "()V"  },                \
        { JLOBJECT_NMO_WAIT4EVER, "wait",    "(J)V" },                \
                                                                      \
        /* Add other method entries here */                           \
                                                                      \
                                                                      \
        /* End of table marker */                                     \
        { JVMCFG_JLOBJECT_NMO_NULL,                                   \
          CHEAT_AND_USE_NULL_TO_INITIALIZE,                           \
          CHEAT_AND_USE_NULL_TO_INITIALIZE }                          \
    }
Table of local native methods and their descriptors for java.lang.Object.

Definition at line 328 of file jlObject.h.

#define NATIVE_TABLE_JLOBJECT_JVOID
 

Value:

(jvoid) local native method ordinal table for java.lang.Object

Definition at line 348 of file jlObject.h.

#define NATIVE_TABLE_JLOBJECT_JOBJECT   case JLOBJECT_NMO_GETCLASS:
 

(jobject) local native method ordinal table for java.lang.Object

Definition at line 356 of file jlObject.h.

#define NATIVE_TABLE_JLOBJECT_JINT   case JLOBJECT_NMO_HASHCODE:
 

(jint) local native method ordinal table for java.lang.Object

Definition at line 363 of file jlObject.h.

#define NATIVE_TABLE_JLOBJECT_JFLOAT
 

No (jfloat) methods.

Definition at line 366 of file jlObject.h.

#define NATIVE_TABLE_JLOBJECT_JLONG
 

No (jlong) methods.

Definition at line 367 of file jlObject.h.

#define NATIVE_TABLE_JLOBJECT_JDOUBLE
 

No (jdouble) methods.

Definition at line 368 of file jlObject.h.


Typedef Documentation

typedef jobject jvm_object_hash
 

Implementation type definition for jobject.

This symbol is defined for use in the core JVM code in jvmcfg.h.

Attention:
See comments about jobject and jclass in the local definition of jvm_class_index.
Todo:
In the JVM spec, an object reference seems to look like an arbitrary integer token. However, looking at the JNI header file for the Solaris JDK 1.4.2_06 implementation, it appears to be a pointer to an empty structure. The apparent purpose of this definition is to have a completely generic definition of use by any implementation. HOWEVER, there is a problem with this: What happens when the implementation is ported to a 64-bit hardware runtime environment? All pointers change from 32 bits (namely, from sizeof(jint)) to 64 bits (namely, sizeof(jlong)), taking a second 32-bit word. This can have significant implications for code, and not only for the JNI interface. This needs some detailed scrutiny so that the JNI interface and the implementation as a whole properly compensates for this situtation or declares it a non-issue.
Note:
As an aside, and in addition to the above
Todo:
item, the consider that many GC implementations use a variation of "copying garbage collection" (sometimes with adjectives in front, such as "generational copying garbage collection," etc.). These tend to be more efficient than the old mark-and-sweep, even though they usually add an extra layer of indirection. For example, every pointer might actually be an index into a table of pointers or perhaps a pointer to a pointer. The idea is that the GC algorithm can relocate/copy the object, knowing it needs to update only one pointer and all current accesses to the object at its old location will now be able to access it at its new location without missing a beat. In this case, the 32-bit unsigned int might be an index into a table of pointers and the pointers might be 64-bits or 32-bits or anything else.

Definition at line 202 of file jlObject.h.

typedef jclass jvm_class_index
 

Implementation type definition for jclass.

This symbol is defined for use in the core JVM code in jvmcfg.h.

Attention:
As long as this type definition is the same width or narrower than the local definition of jvm_object_hash, all code will connect the JNI and JVM environments properly. Some Java implementations may consider jobject to be an ordinal, some may consider it to be an array index, some may consider it to be a pointer. If jclass is compatible with such definition, then everything should work fine. The compiler will provide the necessary width adjustments without loss of any significant digits. Therefore, notice that this data type cannot be defined as being any wider than jobject and jvm_object_hash.

Definition at line 221 of file jlObject.h.

typedef void jvoid
 

Definition of Java void as used in this implementation.

This type definition is not typically part of <jni.h> but used extensively here.

This symbol is defined for use in the core JVM code in jrtypes.h.

Definition at line 233 of file jlObject.h.


Enumeration Type Documentation

enum jlObject_nmo_enum
 

Enumerator:
JLOBJECT_NMO_GETCLASS  Ordinal for getClass().
JLOBJECT_NMO_HASHCODE  Ordinal for hashCode().
JLOBJECT_NMO_WAIT4EVER  Ordinal for wait4ever().
JLOBJECT_NMO_WAITTIMED  Ordinal for waittimed().

Definition at line 255 of file jlObject.h.


Function Documentation

jvm_object_hash jlObject_getClass jvm_object_hash  objhashthis  ) 
 

JNI hook to getClass().

Parameters:
objhashthis Object table hash of this object.
Returns:
java.lang.Object of OBJECT(objhashthis)

Definition at line 102 of file jlObject.c.

References CLASS, and OBJECT_CLASS_LINKAGE.

Referenced by Java_java_lang_Object_getClass(), and native_run_local_return_jobject().

jint jlObject_hashCode jvm_object_hash  objhashthis  ) 
 

JNI hook to hashCode().

Parameters:
objhashthis Object table hash of this object.
Returns:
input objhashthis by definition

Definition at line 121 of file jlObject.c.

Referenced by Java_java_lang_Object_hashCode(), and native_run_local_return_jint().

jvoid jlObject_wait4ever jvm_object_hash  objhashthis  ) 
 

JNI hook to wait4ever().

< This slot contains an object

< Object is a java/Lang/Thread < This slot contains an object

< Object is a java/Lang/Thread < This slot contains an object

< Object is a java/Lang/Thread < This slot contains a thread

< This slot contains an object

< Object is a java/Lang/Thread < Null thread (only 1 exists in normal use, any else besides the JVMCFG_NULL_THREAD is a thread slot that is being initialized.)

< This slot contains an object

< Object is a java/Lang/Thread < This slot contains an object

< Object is a java/Lang/Thread < This slot contains an object

< This slot contains an object

< Object is a java/Lang/Thread < NULL object (only 1 exists in normal use, any else besides the JVMCFG_NULL_OBJECT is an object slot now being initialized.)

< This slot contains an object

< Object is a java/Lang/Thread < Object is a java/Lang/Thread < Object monitor locked by mlock_thridx

< Access structures of the thread now running in the JVM.

< thread is unconditionally waiting

< Access structures of the thread now running in the JVM.

< thread threw a java.lang.Exception (but NOT a java.lang.Error). The object type is found in pThrowableEvent and is not rnull.

Definition at line 174 of file jlObject.c.

References CURRENT_THREAD, JVMCLASS_JAVA_LANG_ILLEGALMONITORSTATEEXCEPTION, OBJECT, OBJECT_CLASS_LINKAGE, OBJECT_STATUS_MLOCK, OBJECT_THREAD_LINKAGE, objectutil_release(), rtrue, THREAD, THREAD_STATUS_THREW_EXCEPTION, THREAD_STATUS_WAIT4EVER, thread_throw_exception(), VERIFY_OBJECT_THREAD_LINKAGE, and VERIFY_THREAD_LINKAGE.

Referenced by Java_java_lang_Object_wait(), and native_run_local_return_jvoid().

jvoid jlObject_waittimed jvm_object_hash  objhashthis,
jlong  sleeptime
 

JNI hook to waittimed().

< This slot contains an object

< Object is a java/Lang/Thread < This slot contains an object

< Object is a java/Lang/Thread < This slot contains an object

< Object is a java/Lang/Thread < This slot contains a thread

< This slot contains an object

< Object is a java/Lang/Thread < Null thread (only 1 exists in normal use, any else besides the JVMCFG_NULL_THREAD is a thread slot that is being initialized.)

< This slot contains an object

< Object is a java/Lang/Thread < This slot contains an object

< Object is a java/Lang/Thread < This slot contains an object

< This slot contains an object

< Object is a java/Lang/Thread < NULL object (only 1 exists in normal use, any else besides the JVMCFG_NULL_OBJECT is an object slot now being initialized.)

< This slot contains an object

< Object is a java/Lang/Thread < Object is a java/Lang/Thread < Object monitor locked by mlock_thridx

< Access structures of the thread now running in the JVM.

< thread has joined another, but is waiting for a finite time

< Access structures of the thread now running in the JVM.

< thread threw a java.lang.Exception (but NOT a java.lang.Error). The object type is found in pThrowableEvent and is not rnull.

Definition at line 239 of file jlObject.c.

References jvm_object_hash_null, OBJECT_THREAD_LINKAGE, rtrue, VERIFY_OBJECT_THREAD_LINKAGE, and VERIFY_THREAD_LINKAGE.

Referenced by Java_java_lang_Object_wait__J(), and native_run_local_return_jvoid().


Generated on Fri Sep 30 18:59:46 2005 by  doxygen 1.4.4