1 \input texinfo @c -*-texinfo-*-
4 @setfilename vmintegration.info
5 @settitle GNU Classpath VM Integration Guide
11 This file contains important information you will need to know if you
12 are going to write an interface between GNU Classpath and a Virtual
15 Copyright (C) 1998-2002, 2004, 2005 Free Software Foundation, Inc.
18 @dircategory GNU Libraries
20 * VM Integration: (vmintegration). GNU Classpath VM Integration Guide
26 @title GNU Classpath VM Integration Guide
28 @author C. Brian Jones
32 @vskip 0pt plus 1filll
33 Copyright @copyright{} 1998-2002 Free Software Foundation, Inc.
35 Permission is granted to make and distribute verbatim copies of
36 this document provided the copyright notice and this permission notice
37 are preserved on all copies.
39 Permission is granted to copy and distribute modified versions of this
40 document under the conditions for verbatim copying, provided that the
41 entire resulting derived work is distributed under the terms of a
42 permission notice identical to this one.
44 Permission is granted to copy and distribute translations of this manual
45 into another language, under the above conditions for modified versions,
46 except that this permission notice may be stated in a translation
47 approved by the Free Software Foundation.
52 @node Top, Introduction, (dir), (dir)
53 @top GNU Classpath Hacker's Guide
55 This file contains important information you will need to know if you
56 are going to write an interface between GNU Classpath and a Virtual
59 This document is incomplete, as we are still in alpha with the interface.
64 * Introduction:: An introduction to the Classpath project
65 * Initialization:: Initializing the classes
66 * Classpath Hooks:: Hooks from Classpath to the VM
67 * VM Hooks:: Hooks from the underlying VM to Classpath
68 * JNI Implementation:: Hooking the VM to jni.h
69 * Miscellaneous VM Requirements::
72 @node Introduction, Initialization, Top, Top
73 @comment node-name, next, previous, up
76 The Classpath Project's ambition to be a 100% clean room implementation
77 of the standard Java class libraries cannot be fulfilled without some
78 level of integration with the Virtual Machine, the underlying machinery
79 that actually runs Java.
81 There are several VMs out there, here is a small list.
84 @item @uref{http://www.hungry.com/old-hungry/products/japhar/,Japhar}
85 Japhar was the first VM to use GNU Classpath. Today you can see that
86 sort of relationship in the source tree which denotes several Japhar
87 specific files as a reference implementation of those pieces. This VM
88 has been primarily tested against Linux and lacks garbage collections, a
89 JIT, and suffers recently from slow development.
91 @item @uref{http://www.intel.com/research/mrl/orp/,Intel's Open Runtime Platform}
92 Intel surprised us not long ago with the release of this rather advanced
93 VM that uses GNU Classpath for a set of class libraries and works on
94 Linux and Windows 2000. As of June, 2004, it does not appear that ORP
95 is under active development.
97 @item @uref{http://www.sablevm.org/,SableVM}
98 SableVM is a robust, extremely portable, efficient, and
99 specifications-compliant Java Virtual Machine that aims to be easy to
100 maintain and to extend. It features a state-of-the-art, efficient
101 interpreter engine. Its source code is very accessible and easy to
102 understand, and has many robustness features that have been the object
105 @item @uref{http://www.kaffe.org,Kaffe}
106 Kaffe is an advanced VM and together with its own class libraries
107 provides a Java 1.1 compatible environment.
109 @item @uref{http://www.mozilla.org/projects/ef,Electrical Fire}
110 The Electrical File VM continues to be listed as a Mozilla project
111 though development has been somewhat quiet. A number of concepts from
112 EF were expected at one point to be rolled into Japhar, but that
113 development has not occurred as of yet.
115 @item @uref{http://latte.snu.ac.kr/,LaTTe}
116 This VM project so far supports only Sun UltraSparc processors using the
117 proprietary Solaris 2.5.1 or higher operating system. LaTTe was derived
118 from Kaffe but claims a number of improvements.
120 @item @uref{http://gcc.gnu.org/java/,GNU Compiler for Java (GCJ)}
121 This is a portable, optimizing, ahead-of-time compiler for the Java
122 Programming Language. It can compile Java source code directly to native
123 machine code, Java source code to Java bytecode (class files), and Java
124 bytecode to native machine code. Compiled applications are linked with the
125 GCJ runtime, libgcj which is based on the GNU Classpath code, which provides
126 the core class libraries, a garbage collector, and a bytecode interpreter.
127 libgcj can dynamically load and interpret class files, resulting in mixed
128 compiled/interpreted applications.
129 GCJ is part of the GNU Compiler Collection (@uref{http://gcc.gnu.org/,GCC}).
130 On March 6 2000 the libgcj and GNU Classpath projects were officially merged
131 and there is active work on merging all the classes between the projects.
132 Licensed under GPL+exception, just as GNU Classpath is.
134 @item @uref{http://kissme.sourceforge.net/,Kissme}
135 This is a free Java Virtual Machine that is being developed on GNU/Linux
136 and can run console Java applications. Kissme also provides support for
137 orthogonally persistent Java.
138 @c I don't know what ``orthogonally persistent Java'' is, and I bet
139 @c there are other people don't know either. -- Steve Augart, 4 June 2004
141 @item @uref{http://jamvm.sourceforge.net/,JamVM}
142 A simple, small bytecode interpreter that works out-of-the-box with
143 pure GNU Classpath; it is emerging as the preferred platform for
144 quickly testing a new build of GNU Classpath. Licensed under the GPL.
146 @item @uref{http://oss.software.ibm.com/jikesrvm,Jikes RVM}
147 A free runtime environment for Java, written in Java. Works
148 out-of-the-box with pure GNU Classpath. Features an optimizing JIT.
149 Runs on the x86 and PowerPC architectures, on the AIX, Linux, and Mac
150 OS/X operating systems. Licensed under the CPL (Common Public
151 License). Extensively documented. Actively developed as of June,
156 In the past integration efforts were focused mainly on Japhar with an eye
157 towards getting Electrical Fire to work. Most information contained in
158 this document is gleaned from these efforts. Recently more work has been
159 done on getting gcj, orp and kissme to work out of the box with GNU Classpath
160 but there is much to do before that becomes a reality.
163 @node Initialization, Classpath Hooks, Introduction, Top
164 @comment node-name, next, previous, up
165 @chapter Initialization
167 The order of initialization, as far as I can tell, doesn't matter just
168 yet. However, when we move to 1.2 support, it probably will matter, so
169 we'll have a note in here at that time.
171 The initialization order is currently documented in the
172 @file{Runtime.java} source file.
174 @node Classpath Hooks, VM Hooks, Initialization, Top
175 @comment node-name, next, previous, up
176 @chapter Classpath Hooks
178 The primary method of interaction between Classpath and the VM is via
179 the helper classes, which are named after the relevant core library
180 class, but include an additional `VM' prefix. The library classes from
181 Classpath call out to these to get certain VM-specific dirty work done.
182 A reference copy of each VM class exists. The majority consist of a
183 series of static methods, some of which are simply declared
184 @code{native}, and some which provide a default implementation. VMs may
185 either use these as is, or create their own local variations. When
186 using the default implementations, the VM is responsible for
187 implementing any of the code marked as @code{native} which corresponds
188 to functionality they wish their VM to provide. When using their own
189 versions of the classes, VM implementors may choose to change the mix of
190 native and non-native methods from that below, so as to best suit their
201 * java.nio.channels::
203 * Classpath Callbacks::
206 @node java.lang, gnu.classpath, Classpath Hooks, Classpath Hooks
207 @comment node-name, next, previous, up
209 @section @code{java.lang}
211 @code{java.lang} is the core Java package, being imported automatically by all
212 classes. It includes basic classes as @code{Object} and @code{String}.
213 A VM must implement at least some parts of this package in order to
217 * java.lang.VMClass::
218 * java.lang.VMObject::
219 * java.lang.VMClassLoader::
220 * java.lang.VMSystem::
221 * java.lang.VMThrowable::
222 * java.lang.VMCompiler::
223 * java.lang.VMDouble::
224 * java.lang.VMFloat::
225 * java.lang.VMProcess::
226 * java.lang.VMRuntime::
227 * java.lang.VMString::
228 * java.lang.VMThread::
229 * java.lang.VMInstrumentationImpl::
232 @node java.lang.VMClass, java.lang.VMObject ,java.lang,java.lang
233 @subsection @code{java.lang.VMClass}
235 The core class, @code{java.lang.Class}, and the corresponding VM class,
236 @code{java.lang.VMClass}, provide two main functions within GNU Classpath.
239 @item For basic VM operation, @code{java.lang.Class} provides the link between
240 the Java-based representation of a class it embodies and the VM's own
241 internal structure for a class. @xref{VM Hooks}.
243 @item As far as the user is concerned, the main function of
244 @code{java.lang.Class} is as an entry point to the reflection
245 facilities, and so it also provides this functionality, backed by the
249 This VM class lists the following methods, organized by the version of the
250 Java specification in which they occur. All are @code{native}, unless
251 otherwise specified, and pertain to reflection. As a result, the VM only
252 needs to implement these methods in order to provide reflection support,
253 and then only to the degree required.
258 @item @code{isInterface(Class)} -- This is simply a property test, and matches
259 the presence of an appropriate flag within the class file.
260 @item @code{getName(Class)} -- Returns the fully-qualified name of the class.
261 @item @code{getSuperclass(Class)} -- Returns a @code{Class} instance which
262 represents the superclass. Again, the class file contains an element directly
263 relating to this. @code{null} is returned for primitives, interfaces and
265 @item @code{getInterfaces(Class)} -- Same as the above, but the implemented
266 or extended interfaces rather than the superclass. An empty array should
267 be returned, rather than @code{null}.
268 @item @code{getDeclaredClasses(Class,boolean)} -- Returns the internal classes
269 this instance declares directly. The flag determines whether or not the
270 VM should filter out non-public classes.
271 @item @code{getDeclaredFields(Class,boolean)} -- The same for fields.
272 @item @code{getDeclaredMethods(Class,boolean)} -- And for methods.
273 @item @code{getDeclaredConstructors(Class,boolean)} -- And constructors.
274 @item @code{getClassLoader(Class)} -- Returns the @code{ClassLoader} instance
275 which is responsible for the specified class.
276 @item @code{forName(String)} -- The VM should create a @code{Class} instance
277 corresponding to the named class. As noted in @ref{VM Hooks}, the internal
278 content of the instance is the responsibility of the VM.
279 @item @code{isArray(Class)} -- Another property test, corresponding to a
281 @item @code{initialize(Class)} -- The VM should initialize the class fully,
282 if it has not already done so.
283 @item @code{loadArrayClass(String,ClassLoader)} -- This is called if
284 @code{forName} returns @code{null} and the string specifies an array class.
285 The specified array class should be loaded with the supplied class loader.
286 @item @code{throwException(Throwable)} -- The VM should throw the supplied
287 checked exception, without declaring it.
291 @item @code{isInstance(Class,Object)} -- This is a reflection-based equivalent
292 of the @code{instanceof} operator.
293 @item @code{isAssignableFrom(Class,Class)} -- Mainly a shorthand for the above,
294 removing the need to create an instance to test assignability.
295 @item @code{isPrimitive(Class)} -- Returns true if this class is simply
296 a representation of one of the primitive types: @code{boolean}, @code{byte},
297 @code{char}, @code{short}, @code{int}, @code{long}, @code{float},
298 @code{double} and @code{void}.
299 @item @code{getComponentType(Class)} -- Produces a @code{Class} instance which
300 represents the type of the members of the array the class instance represents.
301 Classes which don't represent an array type return @code{null}.
302 @item @code{getModifiers(Class,boolean)} -- Returns an integer which encodes
303 the class' modifiers, such as @code{public}. Again, this relates to
304 information stored in the class file.
305 @item @code{getDeclaringClass(Class)} -- Returns the class that declared
306 an inner or member class, or @code{null} if the instance refers to a top-level
311 @node java.lang.VMObject, java.lang.VMClassLoader, java.lang.VMClass, java.lang
312 @subsection @code{java.lang.VMObject}
314 @code{VMObject} is the bridge between the low level @code{Object} facilities
315 such as making a clone, getting the class of the object and the wait/notify
316 semantics. This is accomplished using the following @code{native}
320 @item @code{getClass(Object)} -- Returns the @code{Class} instance for the
321 object. @code{Class} objects are produced by the VM, as described in
323 @item @code{clone(Cloneable)} -- The VM should produce a low-level clone of the
324 specified object, creating a field-by-field shallow copy of the original.
325 The only difference between the two is that the new object should still be
326 @code{finalizable}, even if the original is not.
327 @item @code{notify(Object)} -- The VM should choose one of the threads waiting
328 for a lock on the specified object arbitrarily, and wake it. If the current
329 thread does not currently hold the lock on the object, then an
330 @code{IllegalMonitorStateException} should be thrown.
331 @item @code{notifyAll(Object)} -- Same as the above, but all threads are
333 @item @code{wait(Object,long,int)} -- The VM should set the current thread
334 into a waiting state, which persists until it receives a notify signal or the
335 specified time (in milliseconds and nanoseconds) is exceeded. The nanoseconds
336 restriction may be ignored if such granularity is not available, and a
337 @code{IllegalMonitorStateException} should be thrown if the current thread
338 doesn't own the object.
341 @node java.lang.VMClassLoader, java.lang.VMSystem, java.lang.VMObject, java.lang
342 @subsection @code{java.lang.VMClassLoader}
343 @code{VMClassLoader} provides methods for defining and resolving core and
344 primitive classes, as well as handling resources, packages and assertions.
345 The class is a mixture of @code{native} methods and Java-based
346 implementations, with some of the latter being @emph{stubs}.
351 @item @code{defineClass(ClassLoader,String,byte[],int,int,ProtectionDomain)}
352 -- The VM should create a @code{Class} instance from the supplied byte array.
353 @item @code{resolveClass(Class)} -- Resolve references to other classes in the
355 @item @code{loadClass(name,boolean)} -- Load a class using the bootstrap
357 @item @code{getPrimitiveClass(char)} -- The VM should provide a @code{Class}
358 implementation for one of the primitive classes. The supplied character
359 matches the JNI code for the primitive class e.g. `B' for byte and
364 @item @code{getResource(String)} -- The default implementation calls
365 @code{getResources} and returns the first element in the returned enumeration,
366 or @code{null} if there are no elements.
367 @item @code{getResources(String)} -- By default, this compiles a list of
368 URLs via the boot class path. Any matching files within a zip file are added,
369 and directories on the boot class path are automatically converted to file
370 URLs that refer to join the directory with the resource name (whether or not
372 @item @code{getPackage(String)} -- Always returns null, which may be suitable
373 if the VM does not wish to return a @code{Package} implementation. Otherwise,
374 it may be necessary to make this a @code{native} method.
375 @item @code{getPackages()} -- As with the last, a default stub implementation
376 exists (returning an empty array) which may be replaced if support is
378 @item @code{defaultAssertionStatus()} -- A stub which can be implemented
379 by VMs providing assertion support. At present, it always returns @code{true}.
380 @item @code{packageAssertionStatus()} -- Much the same status as the above.
381 The method should return a map converting package names to boolean status
382 values. The stub implementation provides an empty map.
383 @item @code{classAssertionStatus()} -- Same as the last, but for classes.
384 @item @code{getSystemClassLoader()} -- The default calls @code{ClassLoader}
385 to create a new auxillary class loader with a system and extension class
386 loader. The VM may wish to replace it if it wishes to supply its own custom
390 @node java.lang.VMSystem, java.lang.VMThrowable, java.lang.VMClassLoader, java.lang
391 @subsection @code{java.lang.VMSystem}
392 @code{VMSystem} handles the default I/O streams, provides access to the
393 system clock and environment variables and provides methods for
394 @code{System.arraycopy} and the @code{identityHashCode} of an
395 @code{Object}. It consists of @code{native} methods, but the default
396 implementation also provides some helper methods to simplify stream
402 @item @code{arraycopy(Object,int,Object,int,int)} -- The VM should copy
403 a specified number of array objects from one array to another, with
404 appropriate checks for compatible typing, available elements and space.
405 The VM should be able to perform this more efficiently using native code
406 and direct memory manipulation than would have been achieved by using Java.
407 @item @code{identityHashCode(Object)} -- This is the hashcode for
408 @code{Object}, which relates to the actual location of the object in memory.
409 @item @code{setIn(InputStream)} -- Set the system input stream.
410 @item @code{setOut(PrintStream)} -- Set the system output stream.
411 @item @code{setErr(PrintStream)} -- Set the system error stream.
412 @item @code{currentTimeMillis()} -- Gets the system time in milliseconds.
413 @item @code{getenv(String)} -- Returns the value of the specified environment
418 @item @code{makeStandardInputStream()} -- Helps provide the functionality of
419 @code{System.in} by wrapping the appropriate file descriptor in a buffered
420 file input stream. VMs may choose to create the stream from the descriptor
421 differently rather than using this method.
422 @item @code{makeStandardOutputStream()} -- Helps provide the functionality of
423 @code{System.out} by wrapping the appropriate file descriptor in a buffered
424 file output stream. VMs may choose to create the stream from the descriptor
425 differently rather than using this method.
426 @item @code{makeStandardErrorStream()} -- Helps provide the functionality of
427 @code{System.err} by wrapping the appropriate file descriptor in a buffered
428 file output stream. VMs may choose to create the stream from the descriptor
429 differently rather than using this method.
433 Classpath also provides native implementations of
436 @item @code{setIn(InputStream)}
437 @item @code{setOut(PrintStream)}
438 @item @code{setErr(PrintStream)}
439 @item @code{currentTimeMillis()}
440 @item @code{getenv(String)}
443 making a VM implementation optional.
445 @node java.lang.VMThrowable, java.lang.VMCompiler, java.lang.VMSystem, java.lang
446 @subsection @code{java.lang.VMThrowable}
447 @code{VMThrowable} is used to hold the VM state of a throwable, created either
448 when a @code{Throwable} is created or the @code{fillInStackTrace()} method is
449 called (i.e. when the actual stack trace is needed, as a lot of exceptions are
450 never actually used). The actual class has two @code{native} methods,
451 one (@code{fillInStackTrace()}) being a method of the class used to obtain
452 instances, and the other an instance method, @code{getStackTrace()}.
454 @item @code{fillInStackTrace(Throwable)} -- The VM should return the current
455 execution state of the @code{Throwable} in the form of a @code{VMThrowable}
456 instance. The VM may also return @code{null} if it does not support this
458 @item @code{getStackTrace()} -- This is used to create a real
459 @code{StackTraceElement} array for the exception, using the state data
460 stored during creation of the instance.
463 @node java.lang.VMCompiler, java.lang.VMDouble, java.lang.VMThrowable, java.lang
464 @subsection @code{java.lang.VMCompiler}
466 @code{VMCompiler} provides an interface for VMs which wish to provide
467 JIT compilation support. The default implementation is simply a series
468 of stubs. The property, @code{java.compiler}, should point to a library
469 containing the function @code{java_lang_Compiler_start()} if such support
473 @item @code{compileClass(Class)} -- Invoke the compiler to compile the specific
474 class, returning @code{true} if successful.
475 @item @code{compileClasses(String)} -- The compiler should compile the classes
476 matching the specified string, again returning @code{true} on success.
477 @item @code{command(Object)} -- The object represents a command given to the
478 compiler, and is specific to the compiler implementation.
479 @item @code{enable} -- Enable the operation of the compiler.
480 @item @code{disable} -- Disable compiler operation.
483 @node java.lang.VMDouble, java.lang.VMFloat, java.lang.VMCompiler, java.lang
484 @subsection @code{java.lang.VMDouble}
486 @code{VMDouble} provides native support for the conversion and parsing
490 @item @code{doubleToLongBits(double)} -- Converts the double to the IEEE 754
491 bit layout, collapsing NaNs to @code{0x7ff8000000000000L}.
492 @item @code{doubleToRawLongBits(double)} -- Same as the above, but preserves
494 @item @code{longBitsToDouble(long)} -- This is the inverse of the last method,
495 preserving NaNs so that the output of one can be fed into the other without
497 @item @code{toString(double,boolean)} -- Converts the double to a string,
498 giving a shorter value if the flag @code{isFloat} is @code{true}, indicating
499 that the conversion was requested by @code{java.lang.Float} rather than
500 @code{java.lang.Double}.
501 @item @code{initIDs} -- Used by JNI-based solutions to initialize the cache
502 of the static field IDs. The default @code{VMDouble} implementation has a
503 static initializer which loads the JNI library and calls this method.
504 @item @code{parseDouble} -- Turn the string into a usable double value.
507 Classpath provides native implementations of all these, making VM
508 implementation optional.
510 @node java.lang.VMFloat, java.lang.VMProcess, java.lang.VMDouble, java.lang
511 @subsection @code{java.lang.VMFloat}
513 @code{VMFloat} provides native support for the conversion of floats.
516 @item @code{floatToIntBits(float)} -- Converts the float to the IEEE 754
517 bit layout, collapsing NaNs to @code{0x7fc00000}.
518 @item @code{floatToRawIntBits(float)} -- Same as the above, but preserves
520 @item @code{intBitsToFloat(int)} -- This is the inverse of the last method,
521 preserving NaNs so that the output of one can be fed into the other without
525 Classpath provides native implementations of all these, making VM
526 implementation optional.
528 @node java.lang.VMProcess, java.lang.VMRuntime, java.lang.VMFloat, java.lang
529 @subsection @code{java.lang.VMProcess}
531 @code{VMProcess} handles the execution of external processes. In the
532 default implementation, threads are spawned and reaped by @code{ProcessThread}.
533 A constructor creates a new @code{VMProcess}, which extends rather than
534 complements @code{Process}, using an array of arguments, an array of
535 environment variables and a working directory. The instance maintains
536 system input, output and error streams linked to the external process.
537 Three @code{native} methods are used, and implementations are provided
538 for all three by Classpath, making VM implementation optional. These use
539 the POSIX functions, @code{fork()}, @code{waitpid()} and @code{kill()}.
542 @item @code{nativeSpawn(String[],String[],File)} -- The VM should create a
543 new process which uses the specified command-line arguments, environment
544 variables and working directory. Unlike the other two methods, this
545 method is linked to an instance, and must call @code{setProcessInfo()} with
546 the results before returning.
547 @item @code{nativeReap()} -- This is called to perform a reap of any
548 zombie processes, and should not block, instead returning a boolean as to
549 whether reaping actually took place.
550 @item @code{nativeKill(long)} -- The VM should terminate the specified PID.
553 @node java.lang.VMRuntime, java.lang.VMString, java.lang.VMProcess, java.lang
554 @subsection @code{java.lang.VMRuntime}
556 The @code{VMRuntime} class provides a series of native methods
557 which divulge information about the runtime or invoke certain
558 operations. This includes retrieving the amount of available memory,
559 and scheduling the garbage collector. There are two exceptions: the
560 @code{enableShutdownHooks} method, which allows the VM to put in its own
561 shutdown hooks when @code{Runtime.addShutdownHook()} is first invoked,
562 and @code{exec(String[],String[],File)} which spawns an external process.
563 These are Java-based static methods instead. The first is simply a stub by
564 default, while the second simply links to the functionality of
565 @code{VMProcess} (and should be changed if a different @code{Process}
566 implementation is used).
569 @item @code{availableProcessors()} -- Returns the number of processors
571 @item @code{freeMemory()} -- Returns the amount of memory the VM has available
572 on the heap for allocating.
573 @item @code{totalMemory()} -- Returns the size of the heap.
574 @item @code{maxMemory()} -- Returns the maximum memory block the VM will
575 attempt to allocate. May be simply @code{Long.MAX_VALUE} (8 exabytes!)
576 @item @code{gc()} -- Allows users to explicitly invoke the garbage collector.
577 This is a suggestion to the VM, rather than a command, and the garbage
578 collector should run anyway @emph{without} it being invoked.
579 @item @code{runFinalization()} -- Like the above, but related to the
580 finalilzation of objects rather than the garbage collector.
581 @item @code{runFinalizationForExit()} -- Called immediately prior to VM
582 shutdown in order to finalize all objects (including `live' ones)
583 @item @code{traceInstructions(boolean)} -- This turns on and off the optional
584 VM functionality of printing a trace of executed bytecode instructions.
585 @item @code{traceMethodCalls(boolean)} -- This turns on and off the optional
586 VM functionality of printing a trace of methods called.
587 @item @code{runFinalizersOnExit(boolean)} -- A toggleable setting for
588 running the finalization process at exit.
589 @item @code{exit(int)} -- The VM should shutdown with the specified exit code.
590 @item @code{nativeLoad(String,ClassLoader)} -- Attempts to load a file,
591 returning an integer which is non-zero for success. Nothing happens if the
592 file has already been loaded.
593 @item @code{mapLibraryName(String)} -- The VM should map the system-independent
594 library name supplied to the platform-dependent equivalent (e.g. a @code{.so}
598 @node java.lang.VMString, java.lang.VMThread, java.lang.VMRuntime, java.lang
599 @subsection @code{java.lang.VMString}
600 @code{VMString} is responsible for handling interned strings. If two strings
601 are equal (using the @code{equals()} method), then the results of calling
602 the @code{intern()} method on each of them makes them equal
603 (using @code{==}). Thus, the same string object is always returned by
604 @code{intern} if the two strings are equal. The default implementation
605 is Java-based and implements @code{intern(String)} by maintaining a
606 @code{WeakHashMap} which links the strings to their @code{WeakReference}.
607 A new mapping is created for each new string being @code{intern}ed.
608 A VM may implement this differently by implementing this method,
609 which is @code{static} and the only one in @code{VMString}.
611 @node java.lang.VMThread,java.lang.VMInstrumentationImpl, java.lang.VMString, java.lang
612 @subsection @code{java.lang.VMThread}
614 @code{VMThread} provides the link between Java's threads and the platform
615 threading support. A @code{VMThread} is created via a private constructor
616 and linked to a @code{Thread} instance. This occurs when the @code{Thread}
617 instance is started by the static @code{create(Thread,long)} method (the second
618 argument requests a certain stack size, usually zero). The thread itself is
619 executed via the @code{run()} method, which handles any problems with the
620 running of the thread and its eventual death.
622 @code{VMThread} provides the following accessors and mutators for accessing
623 the thread state via @code{VMThread},
626 @item @code{getName()}
627 @item @code{setName(String)}
628 @item @code{getPriority()}
629 @item @code{setPriotity(int)}
630 @item @code{isDaemon()}
633 all of which refer to the @code{Thread} instance. @code{setPriority(int)} also
634 calls the appropriate native method. @code{stop(Throwable)} similarly wraps
635 a native method, merely adding in a check for the state of the thread.
637 The default implementation also provides Java-based implementations of
638 @code{join(long,int)}, @code{sleep(long,int)} and
639 @code{holdsLock(Object)}. @code{join} and @code{sleep} simply wait for
640 the appropriate amount of time, with @code{join} additionally waiting
641 for the thread instance to become @code{null}. @code{holdsLock} simply
642 checks if an object is locked by the current thread by trying to invoke
643 the @code{notify} method, and catching the failing exception if this is
646 The remainder of the class is a series of @code{native} methods, some of
647 which are mandatory for VM implementation and others which provide optional
648 or deprecated functionality.
651 @item Mandatory Instance Methods
653 @item @code{start(long)} -- The VM should create the native thread and start
654 it running using the @code{run} method of the @code{VMThread} instance on
655 which this method is called.
656 @item @code{interrupt()} -- The VM should interrupt the running thread and
657 throw an appropriate exception.
658 @item @code{isInterrupted()} -- Checks the interrupted state of the thread.
659 @item @code{suspend()} -- The thread should be suspended until resumed.
660 @item @code{resume()} -- The thread should be resumed from its suspended state.
661 This pair of methods are deprecated, due to the possibility of a deadlock
662 occuring when a thread with locks is suspended.
663 @item @code{nativeSetPriority(int)} -- Called by @code{setPriority}
664 to allow the setting to flow down to the native thread.
665 @item @code{nativeStop(Throwable)} -- The VM should stop the thread abnormally
666 and throw the specified exception. This is clearly deprecated, due to the
667 ambiguous state an abruptly-stopped thread may leave.
669 @item Mandatory Class Methods
671 @item @code{currentThread()} -- Return a reference to the thread currently
673 @item @code{yield()} -- The VM should allow some other thread to run.
674 The current thread maintains its locks even though it stops executing for
676 @item @code{interrupted()} -- A shortcut to obtaining the interrupted state
677 of the current thread.
681 @item @code{countStackFrames()} -- Returns a count of the number of stack
682 frames in the thread. This depends on the deprecated method @code{suspend()}
683 having returned true, and is thus deprecated as a result.
687 @node java.lang.VMInstrumentationImpl,, java.lang.VMThread, java.lang
688 @subsection @code{java.lang.VMInstrumentationImpl}
690 The @code{java.lang.VMInstrumentationImpl} and
691 @code{java.lang.InstrumentationImpl} provides an implementation of the
692 @code{java.lang.instrument.Instrument} interface. This interface is for java
693 1.5 and is only in the generics branch.
694 A @code{InstrumentationImpl} object should be given to any agent
695 given in the command line (see the @code{java.lang.instrument} package
696 documentation). A VM has to implement the static native methods of the
697 @code{VMInstrumentationImpl} class.
700 @item @code{isRedefineClassesSupported()} -- Returns true if the JVM supports
702 @item @code{redefineClasses()} -- Gives a set of classes with new bytecodes.
703 The VM must redefine the classes by reading the new bytecodes.
704 @item @code{getAllLoadedClass()} -- Returns an array of all loaded classes.
705 @item @code{getInitiatedClass()} -- Returns an array of all classes loaded
706 by a specific class loader.
707 @item @code{getObjectSize()} -- Gives the size of an object.
710 When agents are defined, the VM has to call transformers of the
711 @code{InstrumentImpl} object each time a class is loaded, eg a call to
712 @code{VMClassLoader.defineClass}. The @code{InstrumentationImpl} class defines
713 a method that has to be called before reading a class file in the VM.
716 @item @code{callTransformers} -- Calls each transformer registered to
717 the @code{InstrumentationImpl} object and returns a new bytecode file.
720 No default implementation is provided in gnu classpath for the
721 @code{VMInstrumentationImpl} methods. A default implementation will perhaps
722 be written, but it might break the @code{ClassLoader/VMClassLoader} interface
723 for calling the @code{InstrumentationImpl.callTransformers} when a class byte
724 code is defined with @code{ClassLoader.defineClass}.
726 @node gnu.classpath, java.util, java.lang, Classpath Hooks
727 @section @code{gnu.classpath}
729 The @code{gnu.classpath} package provides Classpath-specific functionality,
730 primarily relating to the features in @code{java.lang}. At present, this
731 includes the context of a class (the stack) and the system properties.
734 * gnu.classpath.VMStackWalker::
735 * gnu.classpath.VMSystemProperties::
738 @node gnu.classpath.VMStackWalker,gnu.classpath.VMSystemProperties,gnu.classpath,gnu.classpath
739 @subsection @code{gnu.classpath.VMStackWalker}
741 @code{VMStackWalker} provides access to the class context or stack. The
742 default implementation consists of a @code{native} @code{static} method,
743 @code{getClassContext()}, which obtains the class context, and two helper
744 methods which obtain the calling class (the 3rd element in the context array)
745 and its class loader, respectively.
748 @item @code{getClassContext()} -- The VM should return an array of
749 @code{Class} objects, each of which relates to the method currently being
750 executed at that point on the stack. Thus, the first item (index 0) is the
751 class that contains this method.
752 @item @code{getCallingClass()} -- A Java-based helper method which returns
753 the @code{Class} object which contains the method that called the method
754 accessing @code{getCallingClass()}.
755 @item @code{getCallingClassLoader()} -- Like the last, but returning the class
759 @node gnu.classpath.VMSystemProperties,,gnu.classpath.VMStackWalker,gnu.classpath
760 @subsection @code{gnu.classpath.VMSystemProperties}
762 @code{VMSystemProperties} allows the VM to hook into the property creation
763 process, both before and after the system properties are added by GNU
764 Classpath. The default implementation assumes that the VM will add its
765 properties first, by making the pre-initialisation method @code{native},
766 and that the Classpath properties may then be altered by a Java-based
767 post-initialisation method.
769 As these methods are called as part of the bootstrap process, caution should
770 be used as to what classes are used, and properties should only be set
771 using @code{Properties.setProperty()}. Specifically, I/O classes should be
772 avoided at this early stage.
775 @item @code{preInit(Properties)} -- Allows the VM to add properties
776 @emph{before} the Classpath properties are added. The default implementation
777 includes a full list of properties that @emph{must} be added by the VM, but
778 additional VM-specific ones may also be added.
779 @item @code{postInit(Properties)} -- Same as the last, but called after the
780 Classpath properties have been added. The main purpose of this is to allow
781 the VM to alter the properties added by GNU Classpath to suit it.
784 @node java.util, java.io, gnu.classpath, Classpath Hooks
787 The @code{java.util} VM hooks provide links between the mix of functionality
788 present in that package, which includes collections, date and time handling
789 and parsing. At present, there is only one hook, which connects GNU Classpath
790 to the timezone information provided by the underlying platform.
793 * java.util.VMTimeZone::
796 @node java.util.VMTimeZone,,java.util,java.util
797 @subsection @code{java.util.VMTimeZone}
799 @code{VMTimeZone} joins @code{TimeZone} to the platform timezone information
800 via the static method, @code{getDefaultTimeZoneId()}. The VM hook is
801 expected to return a @code{TimeZone} instance that represents the current
802 timezone in use by the platform. The default implementation provides
803 this functionality for POSIX or GNU-like systems, and VMs that want this
804 functionality can keep this implementation and implement the native
805 method, @code{getSystemTimeZoneId()}. This method is only called when
806 obtaining the timezone name from the @code{TZ} environment variable,
807 @code{/etc/timezone} and @code{/etc/localtime} all fail. This fallback
808 mechanism also means that a system which doesn't provide the above three
809 methods, but does provide a timezone in string form, can still use this
812 @node java.io, java.security, java.util, Classpath Hooks
815 The @code{java.io} package is heavily reliant on access to the I/O facilities
816 of the underlying platform. As far as its VM hooks go, they provide two
817 areas of functionality to GNU Classpath, these being
820 @item File and directory queries and manipulation
821 @item Serialization of objects
824 The first corresponds directly to most of the @code{File} class, while
825 the latter underlies the functionality provided by the
826 @code{ObjectInputStream} and @code{ObjectOutputStream}. More low-level I/O
827 is provided by @ref{java.nio}.
831 * java.io.VMObjectInputStream::
832 * java.io.VMObjectStreamClass::
835 @node java.io.VMFile,java.io.VMObjectInputStream,java.io,java.io
836 @subsection @code{java.io.VMFile}
838 @code{VMFile} allows GNU Classpath's @code{File} representations to
839 probe and modify the file system using the native functions of the
840 platform. The default implementation (which consists of both a
841 @code{VMFile} class and the native methods) is primarily UNIX-centric,
842 working with POSIX functions and assuming case-sensitive filenames,
843 without the restriction of the 8.3 format. It consists mainly of
844 @code{static} @code{native} methods, with a few Java helper methods.
845 The native methods represent the file as a string containing its path,
846 rather than using the object itself.
851 @item @code{lastModified(String)} -- The native method should return a
852 @code{long} value that represents the last modified date of the file.
853 @item @code{setReadOnly(String)} -- Sets the file's permissions to read only,
854 in whichever way this is realised by the platform.
855 @item @code{create(String)} -- Create the named file.
856 @item @code{list(String)} -- The native method opens the named directory,
857 reads the contents and returns them as a Java @code{String} array.
858 @item @code{renameTo(String,String)} -- Renames the first file to the second.
859 @item @code{length(String)} -- Returns a @code{long} value representing
861 @item @code{exists(String)} -- Tests for the existence of the named file
863 @item @code{delete(String)} -- Deletes the file or directory.
864 @item @code{setLastModified(String,long)} -- Change the last modified time.
865 @item @code{mkdir(String)} -- Creates the named directory.
866 @item @code{isFile(String)} -- Tests that the named path references a file.
867 @item @code{canWrite(String)} -- Tests that the file can be written to.
868 This method is @code{synchronized}, so the object is locked during the check.
869 @item @code{canRead(String)} -- Complement of the last method.
870 @item @code{isDirectory(String)} -- Tests that the named path references
873 @item Java Helper Methods
875 @item @code{canWriteDirectory(File)} -- Checks that the directory can be
876 written to, by trying to create a temporary file in it.
877 @item @code{listRoots()} -- Returns the root of a GNU filesystem i.e. `/'
879 @item @code{isHidden(String)} -- Checks whether the file starts with `.',
880 which is how files are hidden on UNIX-style systems.
881 @item @code{getName(String)} -- Pulls the actual filename from the end of
882 the path, by breaking off the characters after the last occurrence of the
883 platform's file separator.
884 @item @code{getCanonicalForm(String)} -- This converts a UNIX path to
885 its canonical form by removing the `.' and `..' sections that occur within.
889 @node java.io.VMObjectInputStream,java.io.VMObjectStreamClass,java.io.VMFile,java.io
890 @subsection @code{java.io.VMObjectInputStream}
892 This class consists of two methods which provide functionality used in
893 deserializing an object. @code{currentClassLoader()} provides the first
894 user-defined class loader from the class context
895 (@xref{gnu.classpath.VMStackWalker},) via a @code{PrivilegedAction}.
896 @code{allocateObject(Class,Class,Constructor)} is a @code{native} method
897 (a reference implementation is provided) which creates an object but
898 calls the constructor of another class, which is a superclass of the
901 @node java.io.VMObjectStreamClass,,java.io.VMObjectInputStream,java.io
902 @subsection @code{java.io.VMObjectStreamClass}
904 @code{VMObjectStreamClass} is a series of @code{static} @code{native}
905 methods that provide some of the groundwork for @code{ObjectStreamClass}
906 and @code{ObjectStreamField}. @code{hasClassInitializer(Class)} works
907 with the former, and checks for the presence of a static initializer.
908 The remaining methods are of the form @code{setXXXNative(Field,Object,XXX)}
909 and support @code{ObjectStreamField}. One exists for each of the main types
910 (boolean, float, double, long, int, short, char, byte and object) and is used
911 to set the specified field in the supplied instance to the given value.
913 A default implementation is provided for all of them, so a VM implementation
916 @node java.security, java.net, java.io, Classpath Hooks
917 @section java.security
919 The @code{java.security} package provides support for Java's security
920 architecture. At present, @code{VMAccessController} represents the sole
924 * java.security.VMAccessController::
927 @node java.security.VMAccessController,,java.security,java.security
928 @subsection @code{java.security.VMAccessController}
930 The @code{AccessController} is used to perform privileged actions. Its
931 hook class, @code{VMAccessController}, maintains the
932 @code{AccessControlContext} and the default implementation is purely
933 Java-based. The VM may choose to replace this with their own.
934 The methods in the reference version are as follows:
937 @item @code{pushContext(AccessControlContext)} -- Adds a new context to the
938 stack for the current thread. This is called before a privileged action
940 @item @code{popContext()} -- Removes the top context from the stack. This
941 is performed after the privileged action takes place.
942 @item @code{getContext()} -- Either derives a context based on the
943 @code{ProtectionDomain}s of the call stack (see the next method) or returns
944 the top of the context stack.
945 @item @code{getStack()} -- Provides access to the call stack as a pair of
946 arrays of classes and method names. The actual implementation returns
947 an empty array, indicating that there are no permissions.
950 @node java.net, java.nio, java.security, Classpath Hooks
953 The @code{java.net} package is heavily reliant on access to the networking
954 facilities of the underlying platform. The VM hooks provide information
955 about the available network interfaces, and access to lookup facilities
956 for network addresses.
959 * java.net.VMInetAddress::
960 * java.net.VMNetworkInterface::
963 @node java.net.VMInetAddress,java.net.VMNetworkInterface,java.net,java.net
964 @subsection @code{java.net.VMInetAddress}
966 @code{VMInetAddress} is a series of @code{static} @code{native} methods
967 which provide access to the platform's lookup facilities. All the methods
968 are implemented by GNU Classpath, making VM implementation optional, and
972 @item @code{getLocalHostname()} -- Wraps the @code{gethostname} function, and
973 falls back on `localhost'.
974 @item @code{lookupInaddrAny()} -- Returns the value of @code{INADDR_ANY}.
975 @item @code{getHostByAddr(byte[])} -- Looks up the hostname based on an IP
977 @item @code{getHostByName(String)} -- The reverse of the last method, it
978 returns the IP addresses which the given host name resolves to.
981 @node java.net.VMNetworkInterface,,java.net.VMInetAddress,java.net
982 @subsection @code{java.net.VMNetworkInterface}
984 @code{VMNetworkInterface} currently consists of a single @code{static}
985 @code{native} method, @code{getInterfaces()}, which retrieves the
986 network interfaces available on the underlying platform as a @code{Vector}.
987 The current GNU Classpath implementation is a native stub.
989 @node java.nio, java.nio.channels, java.net, Classpath Hooks
992 The @code{java.nio} package is part of the New I/O framework added in
993 Java 1.4. This splits I/O into the concepts of @emph{buffers},
994 @emph{charsets}, @emph{channels} and @emph{selectors}, and
995 @code{java.nio} defines the buffer classes. As far as native and VM
996 code is concerned, the new package needs support for low-level efficient
1000 * java.nio.VMDirectByteBuffer::
1003 @node java.nio.VMDirectByteBuffer,,java.nio,java.nio
1004 @subsection @code{java.nio.VMDirectByteBuffer}
1006 A @code{ByteBuffer} maintains a buffer of bytes, and allows it to be
1007 manipulated using primitive operations such as @code{get}, @code{put},
1008 @code{allocate} and @code{free}. A direct buffer avoids intermediate
1009 copying, and uses native data which shouldn't be manipulated by a
1010 garbage collector. The VM class consists of @code{static} @code{native}
1011 methods, all of which are given default implementations by GNU
1015 @item @code{init()} -- Creates an instance of an appropriate
1016 @code{gnu.classpath.RawData} class. This class is not garbage
1017 collected, is created natively and is used in the other methods to reference
1019 @item @code{allocate(int)} -- Allocates the memory for the buffer using
1020 @code{malloc} and returns a reference to the @code{RawData} class.
1021 @item @code{free(RawData)} -- Frees the memory used by the buffer.
1022 @item @code{get(RawData,int)} -- Returns the data at the specified index.
1023 @item @code{get(RawData,int,byte[],int,int)} -- Copies a section of the
1024 data into a byte array using @code{memcpy}.
1025 @item @code{put(RawData,int,byte)} -- Puts the given data in the buffer
1026 at the specified index.
1027 @item @code{adjustAddress(RawData,int)} -- Adjusts the pointer into the buffer.
1028 @item @code{shiftDown(RawData,int,int,int)} -- Moves the content of the buffer
1029 at an offset down to a new offset using @code{memmove}.
1032 @node java.nio.channels, gnu.java.nio, java.nio, Classpath Hooks
1033 @section java.nio.channels
1035 Channels provide the data for the buffers with the New I/O packages.
1036 For example, a channel may wrap a file or a socket. The VM hooks,
1037 at the moment, simply allow the channels to be accessed by @code{java.io}
1041 * java.nio.channels.VMChannels::
1044 @node java.nio.channels.VMChannels,,java.nio.channels,java.nio.channels
1045 @subsection @code{java.nio.channels.VMChannels}
1047 @code{VMChannels} provides the methods that create the channels or
1048 streams. The default implementation is in pure Java and simply wraps
1049 the channels in standard I/O classes from @code{java.io}.
1052 @item @code{createStream(Class,Channel)} -- Creates a @code{FileChannel}
1053 which wraps an instance of the specified stream class, created by reflection.
1054 This method is private, and is used by the other two.
1055 @item @code{newInputStream(ReadableByteChannel)} -- Wraps the channel
1056 in a @code{FileInputStream}.
1057 @item @code{newOutputStream(WritableByteChannel)} -- Wraps the channel
1058 in a @code{FileOutputStream}.
1061 @node gnu.java.nio, Classpath Callbacks, java.nio.channels, Classpath Hooks
1062 @section gnu.java.nio
1064 The @code{gnu.java.nio} class provides Classpath implementations of the
1065 interfaces provided by @code{java.nio}. The VM classes provide the native
1066 support necessary to implement @emph{pipes} and @emph{selectors}.
1069 * gnu.java.nio.VMPipe::
1070 * gnu.java.nio.VMSelector::
1073 @node gnu.java.nio.VMPipe,gnu.java.nio.VMSelector,gnu.java.nio,gnu.java.nio
1074 @subsection @code{gnu.java.nio.VMPipe}
1076 @code{VMPipe} provides the native functionality for a uni-directional pipe
1077 between a source and a destination (sink) channel. It consists of one
1078 @code{static} @code{native} method, @code{init(PipeImpl,SelectorProvider)},
1079 the reference implementation of which is currently a native stub. Ideally,
1080 this should initialise the pipe at the native level.
1082 @node gnu.java.nio.VMSelector,,gnu.java.nio.VMPipe,gnu.java.nio
1083 @subsection @code{gnu.java.nio.VMSelector}
1085 A @code{Selector} selects between multiple @code{SelectableChannel}s based
1086 on their readiness and a key set. The VM hook for the Classpath implementation
1087 of this is @code{VMSelector}, and this allows the actual @code{select()}
1088 operation to be performed. This is represented by the @code{static}
1089 @code{native} method, @code{select(int[],int[],int[],long)}, and a default
1090 implementation of this is provided.
1092 @node Classpath Callbacks, , gnu.java.nio, Classpath Hooks
1093 Some of the classes you implement for the VM will need to call back to
1094 package-private methods in Classpath:
1097 @item @code{java.lang.ThreadGroup.addThread(Thread)}
1098 Call this method from @code{Thread} when a new @code{Thread} is created, to add it to
1101 @item @code{java.lang.ThreadGroup.removeThread(Thread)}
1102 Call this method from @code{Thread} when a @code{Thread} is stopped or destroyed.
1105 @node VM Hooks, JNI Implementation, Classpath Hooks, Top
1106 @comment node-name, next, previous, up
1109 VMs need to do some dirty work; there are some things in the VM that
1110 unfortunately are dependent on the internal structure of various
1111 classes. This is a guide to all of the things the VM itself needs to
1114 Some of the core classes, while being implemented by GNU Classpath,
1115 provide space for state (in the form of a @code{vmdata} object) to be
1116 stored by the VM, and can not be constructed normally.
1119 @item java.lang.Class
1120 @item java.lang.ClassLoader
1123 The default implementations of some VM classes also follow this methodology,
1124 when it is intended that most VMs will keep the default.
1127 @item java.lang.VMThread
1128 @item java.lang.VMThrowable
1131 Several core classes must be completely implemented by the VM for Classpath to
1132 work, although reference implementations are provided. These classes are:
1135 @item java.lang.reflect.Constructor
1136 @item java.lang.reflect.Method
1137 @item java.lang.reflect.Field
1140 The following issues are of note;
1143 @item @code{java.lang.Class} @*
1144 The GNU Classpath implementation of @code{java.lang.Class} provides an
1145 object for storing the internal state of the class maintained by the VM.
1146 This is the only known place where this matters. The class is
1147 constructed with this data by the VM. Some VMs do not create the
1148 @code{Class} object at the point where the class is defined; instead,
1149 they wait until a @code{Class} object is actually used.
1151 @item Array Classes @*
1152 When you are creating an array class, you should set the
1153 @code{ClassLoader} of the array class to the @code{ClassLoader} of its
1154 component type. Whenever you add a class to a @code{ClassLoader}, you
1155 need to notify the @code{ClassLoader} and add the new @code{Class} to
1156 its internal cache of classes. To do this, call
1157 @code{ClassLoader.addVMCreatedClass(Class)}. @emph{Note: this is
1158 written in anticipation of 1.2 support and does not apply just yet.}
1160 @item Primordial Class Loader @*
1161 When the primordial class loader loads a class, it needs to tell
1162 Classpath what it has done in order for security stuff to work right.
1163 To do this, call the static method
1164 @code{ClassLoader.newPrimordialClass(Class)}.
1166 Even the first few core classes need to do this; in order to do it,
1167 simply call this method @emph{after} the initial class loading has been
1168 done. No harm will come, as long as you follow the guidelines in the
1169 @pxref{Initialization} section.
1171 @emph{Note: this is written in anticipation of 1.2 support and does not
1174 @item Top-level Exception Handler @*
1175 Exceptions take care of themselves in Classpath; all you need to do in
1176 the top-level exception handler is call @code{Throwable.printStackTrace()}.
1178 @item Security and Traces @*
1179 There will eventually be a feature in the 1.2 security that keeps the
1180 @code{AccessController} from having to evaluate @emph{all} of the
1181 @code{ProtectionDomain}s every time a security check is made. I think a common
1182 case is a single method doing a lot of things that require security
1183 checks. However, I don't want to bog down the method stack too much, so
1184 this feature of the VM will have the @code{AccessController} for a thread
1185 calling out to the VM to tell it how high it was on the stack when it
1186 made the last security request. Every time the stack goes lower than
1187 that number, the VM will decrement the number. The @code{AccessController}
1188 will remember what the accumulated protection status was at every stack
1189 level (an @code{AccessControlContext}) and use that aggregated information to
1190 do the check. I am not sure, however, whether the savings are
1191 substantial enough to outweigh the integer check and set after every
1192 method call. I will investigate.
1195 I figured I'd put this here because a VM guy might be wondering about it.
1196 We implement @code{ThreadGroup}, but that class is almost entirely
1197 VM-independent. The root @code{ThreadGroup}, a static field called
1198 @code{ThreadGroup.root}, should be initialized by Classpath, but if you wish to
1199 reinitialize it yourself, there should be no harm.
1203 @node JNI Implementation, Miscellaneous VM Requirements, VM Hooks, Top
1204 @comment node-name, next, previous, up
1205 @chapter JNI Implementation
1207 Classpath comes with its own implementation of @file{jni.h}. This
1208 file can be customized by the VM in a few ways, by defining macros
1209 that affect the interpretation of the file. These macros are all
1210 intended for use by a VM which uses GNU Classpath and which wants to
1211 use a single copy of @file{jni.h} for both internal and external use.
1214 @item _CLASSPATH_VM_JNI_TYPES_DEFINED
1215 Some VMs like to define JNI ``object'' types in a special way. If
1216 this macro is defined, the Classpath @file{jni.h} will avoid defining
1217 these types. By default, these types are defined in @file{jni.h}.
1218 The full list of types and macros treated this way is: @samp{jobject},
1219 @samp{jclass}, @samp{jstring}, @samp{jthrowable}, @samp{jweak},
1220 @samp{jarray}, @samp{jobjectArray}, @samp{jbyteArray},
1221 @samp{jshortArray}, @samp{jintArray}, @samp{jlongArray},
1222 @samp{jbooleanArray}, @samp{jcharArray}, @samp{jfloatArray},
1223 @samp{jdoubleArray}, @samp{JNIEnv}, @samp{JavaVM}, @samp{JNI_TRUE}
1224 (macro), @samp{JNI_FALSE} (macro).
1226 @item _CLASSPATH_VM_INTERNAL_TYPES_DEFINED
1227 If the VM has its own definitions for @samp{jfieldID} and
1228 @samp{jmethodID}, then it should define this macro. Otherwise,
1229 @file{jni.h} will provide definitions for these types.
1231 @item _CLASSPATH_JNIIMPEXP
1232 Three functions -- @samp{JNI_GetDefaultJavaVMInitArgs},
1233 @samp{JNI_CreateJavaVM}, and @samp{JNI_GetCreatedJavaVMs} -- must be
1234 marked as @samp{JNIIMPORT} when seen by user code, but most likely
1235 should be marked as @samp{JNIEXPORT} when defined in the VM
1236 implementation. This macro can be defined to one or the other by the
1237 VM as appropriate. If this macro is not defined, it defaults to
1240 @item _CLASSPATH_JNIENV_CONTENTS
1241 A VM can add fields to the @samp{JNIEnv} structure by defining this to
1242 be a sequence of field declarations.
1247 @node Miscellaneous VM Requirements, , JNI Implementation, Top
1248 @comment node-name, next, previous, up
1249 @chapter Miscellaneous VM Requirements
1251 Classpath places a few requirements on the VM that uses it.
1255 * VM Threading Model::
1256 * Boot Library Path Property::
1259 @node JNI Version, VM Threading Model, Miscellaneous VM Requirements, Miscellaneous VM Requirements
1260 @comment node-name, next, previous, up
1261 @section JNI Version
1263 Classpath currently uses only JNI 1.1, except for one JNI 1.2 function
1264 in the JNI Invocation API: GetEnv(). And GetEnv() is only used in the
1265 ``portable native sync'' code, so it's only actually used by Jikes RVM
1268 A future direction will probably be to require that all VMs provide
1269 JNI 1.2. If this poses problems, please raise them on the classpath
1272 @node VM Threading Model, Boot Library Path Property, JNI Version, Miscellaneous VM Requirements
1273 @comment node-name, next, previous, up
1274 @section VM Threading Model
1276 Classpath's AWT peers use GTK+. GTK+ uses GLIB. Normally, Classpath
1277 will initialize GLIB's @dfn{gthreads} to use
1278 the platform's native threading model@footnote{The native threading
1279 model is pthreads on Linux and AIX, the two platforms Classpath
1282 If the Java runtime doesn't use the native threading model, then you
1283 will want Classpath to tell GLIB to use the Java threading primitives
1284 instead. Otherwise, GLIB would use the native threading model to
1285 perform operations such as creating thread-local data, and that just
1286 doesn't work on systems (such as Kaffe in some configurations, and
1287 such as Jikes RVM) that use @i{m}:@i{n} threading.
1289 Historically, enabling the Java threading primitives had been done at
1290 build time, by configuring classpath with the
1291 @option{--portable-native-sync} option. This had bad consequences,
1292 though -- it meant that the prebuild GNU Classpath package distributed
1293 with Debian GNU/Linux would not be usable with VMs that could
1294 otherwise have used it. Instead, we encourage
1295 the use of the Java system property
1296 @code{gnu.classpath.awt.gtk.portable.native.sync}. A VM that wants
1297 GLIB to use the Java threading primitives should modify
1298 @code{VMRuntime.insertSystemProperties()} to include code like the
1302 static void insertSystemProperties(Properties @var{p})
1306 @var{p}.put("gnu.classpath.awt.gtk.portable.native.sync", "true");
1309 So, the configure option
1310 @option{--portable-native-sync} is deprecated, and should go away in a
1311 subsequent release of GNU Classpath.
1313 @node Boot Library Path Property, , VM Threading Model, Miscellaneous VM Requirements
1314 @comment node-name, next, previous, up
1315 @section Boot Library Path Property
1317 As of GNU Classpath 0.15 a system property named @code{gnu.classpath.boot.library.path}
1318 can be set by the VM to specify the directories which contain GNU Classpath's native
1319 libraries. Usually this value is given at configuration time and is then hardcoded
1320 in the VM. However for development purposes it is handy to switch to another installation
1321 by overriding the properties' value on the command line.
1323 A VM that does not support this feature can simply ignore the property.
1325 For compatibility reasons we suggest to set the default value of @code{java.library.path}
1326 to the value of the @code{LD_LIBRARY_PATH} environment if it exists on your platform.