Index: doc/vmintegration.texinfo
===================================================================
RCS file: /cvsroot/classpath/classpath/doc/vmintegration.texinfo,v
retrieving revision 1.17
diff -u -3 -p -u -r1.17 vmintegration.texinfo
--- doc/vmintegration.texinfo	24 Apr 2005 19:28:29 -0000	1.17
+++ doc/vmintegration.texinfo	30 Jun 2005 13:26:41 -0000
@@ -110,7 +110,7 @@ provides a Java 1.1 compatible environme
 The Electrical File VM continues to be listed as a Mozilla project
 though development has been somewhat quiet.  A number of concepts from
 EF were expected at one point to be rolled into Japhar, but that
-development has not occured as of yet.
+development has not occurred as of yet.
 
 @item @uref{http://latte.snu.ac.kr/,LaTTe}
 This VM project so far supports only Sun UltraSparc processors using the
@@ -175,42 +175,881 @@ The initialization order is currently do
 @comment node-name, next, previous, up
 @chapter Classpath Hooks
 
-Several core classes must be implemented by the VM for Classpath to
-work.  These classes are:
+The primary method of interaction between Classpath and the VM is via
+the helper classes, which are named after the relevant core library
+class, but include an additional `VM' prefix.  The library classes from
+Classpath call out to these to get certain VM-specific dirty work done.
+A reference copy of each VM class exists.  The majority consist of a
+series of static methods, some of which are simply declared
address@hidden, and some which provide a default implementation.  VMs may
+either use these as is, or create their own local variations.  When
+using the default implementations, the VM is responsible for
+implementing any of the code marked as @code{native} which corresponds
+to functionality they wish their VM to provide.  When using their own
+versions of the classes, VM implementors may choose to change the mix of
+native and non-native methods from that below, so as to best suit their
+implementation.
+
address@hidden
+* java.lang::
+* gnu.classpath::
+* java.util::
+* java.io::
+* java.security::
+* java.net::
+* java.nio::
+* java.nio.channels::
+* gnu.java.nio::
+* Classpath Callbacks::
address@hidden menu
+
address@hidden java.lang, gnu.classpath, Classpath Hooks, Classpath Hooks
address@hidden  node-name,  next,  previous,  up
+
address@hidden @code{java.lang}
+
address@hidden is the core Java package, being imported automatically by all
+classes.  It includes basic classes as @code{Object} and @code{String}.
+A VM must implement at least some parts of this package in order to
+become operable.
+
address@hidden
+* java.lang.VMClass::
+* java.lang.VMObject::
+* java.lang.VMClassLoader::
+* java.lang.VMSystem::
+* java.lang.VMThrowable::
+* java.lang.VMCompiler::
+* java.lang.VMDouble::
+* java.lang.VMFloat::
+* java.lang.VMProcess::
+* java.lang.VMRuntime::
+* java.lang.VMString::
+* java.lang.VMThread::
address@hidden menu
+
address@hidden java.lang.VMClass, java.lang.VMObject ,java.lang,java.lang
address@hidden @code{java.lang.VMClass}
+
+The core class, @code{java.lang.Class}, and the corresponding VM class,
address@hidden, provide two main functions within GNU Classpath.
+
address@hidden
address@hidden For basic VM operation, @code{java.lang.Class} provides the link between
+the Java-based representation of a class it embodies and the VM's own
+internal structure for a class.  @xref{VM Hooks}.
+
address@hidden As far as the user is concerned, the main function of
address@hidden is as an entry point to the reflection
+facilities, and so it also provides this functionality, backed by the
+VM class.
address@hidden enumerate
+
+This VM class lists the following methods, organized by the version of the
+Java specification in which they occur.  All are @code{native}, unless
+otherwise specified, and pertain to reflection.  As a result, the VM only
+needs to implement these methods in order to provide reflection support,
+and then only to the degree required.
 
 @itemize @bullet
address@hidden java.lang.Class
address@hidden java.lang.Runtime
address@hidden java.lang.Thread
address@hidden java.lang.reflect.Constructor
address@hidden java.lang.reflect.Method
address@hidden java.lang.reflect.Field
address@hidden 1.0
address@hidden @bullet
address@hidden @code{isInterface(Class)} -- This is simply a property test, and matches
+the presence of an appropriate flag within the class file.
address@hidden @code{getName(Class)} -- Returns the fully-qualified name of the class.
address@hidden @code{getSuperclass(Class)} -- Returns a @code{Class} instance which
+represents the superclass.  Again, the class file contains an element directly
+relating to this.  @code{null} is returned for primitives, interfaces and
address@hidden
address@hidden @code{getInterfaces(Class)} -- Same as the above, but the implemented
+or extended interfaces rather than the superclass.  An empty array should
+be returned, rather than @code{null}.
address@hidden @code{getDeclaredClasses(Class,boolean)} -- Returns the internal classes
+this instance declares directly.  The flag determines whether or not the
+VM should filter out non-public classes.
address@hidden @code{getDeclaredFields(Class,boolean)} -- The same for fields.
address@hidden @code{getDeclaredMethods(Class,boolean)} -- And for methods.
address@hidden @code{getDeclaredConstructors(Class,boolean)} -- And constructors.
address@hidden @code{getClassLoader(Class)} -- Returns the @code{ClassLoader} instance
+which is responsible for the specified class.
address@hidden @code{forName(String)} -- The VM should create a @code{Class} instance
+corresponding to the named class.  As noted in @ref{VM Hooks}, the internal
+content of the instance is the responsibility of the VM.
address@hidden @code{isArray(Class)} -- Another property test, corresponding to a
+class file flag.
address@hidden @code{initialize(Class)} -- The VM should initialize the class fully,
+if it has not already done so.
address@hidden @code{loadArrayClass(String,ClassLoader)} -- This is called if
address@hidden returns @code{null} and the string specifies an array class.
+The specified array class should be loaded with the supplied class loader.
address@hidden @code{throwException(Throwable)} -- The VM should throw the supplied
+checked exception, without declaring it.
address@hidden itemize
address@hidden 1.1
address@hidden @bullet
address@hidden @code{isInstance(Class,Object)} -- This is a reflection-based equivalent
+of the @code{instanceof} operator.
address@hidden @code{isAssignableFrom(Class,Class)} -- Mainly a shorthand for the above,
+removing the need to create an instance to test assignability.  
address@hidden @code{isPrimitive(Class)} -- Returns true if this class is simply
+a representation of one of the primitive types: @code{boolean}, @code{byte},
address@hidden, @code{short}, @code{int}, @code{long}, @code{float},
address@hidden and @code{void}.
address@hidden @code{getComponentType(Class)} -- Produces a @code{Class} instance which
+represents the type of the members of the array the class instance represents.
+Classes which don't represent an array type return @code{null}.
address@hidden @code{getModifiers(Class,boolean)} -- Returns an integer which encodes
+the class' modifiers, such as @code{public}.  Again, this relates to
+information stored in the class file.
address@hidden @code{getDeclaringClass(Class)} -- Returns the class that declared
+an inner or member class, or @code{null} if the instance refers to a top-level
+class.
address@hidden itemize
address@hidden itemize
+
address@hidden java.lang.VMObject, java.lang.VMClassLoader, java.lang.VMClass, java.lang
address@hidden @code{java.lang.VMObject}
+
address@hidden is the bridge between the low level @code{Object} facilities
+such as making a clone, getting the class of the object and the wait/notify
+semantics.  This is accomplished using the following @code{native}
+methods.
+
address@hidden @bullet
address@hidden @code{getClass(Object)} -- Returns the @code{Class} instance for the
+object.  @code{Class} objects are produced by the VM, as described in
address@hidden Hooks}.
address@hidden @code{clone(Cloneable)} -- The VM should produce a low-level clone of the
+specified object, creating a field-by-field shallow copy of the original.
+The only difference between the two is that the new object should still be
address@hidden, even if the original is not.
address@hidden @code{notify(Object)} -- The VM should choose one of the threads waiting
+for a lock on the specified object arbitrarily, and wake it.  If the current
+thread does not currently hold the lock on the object, then an
address@hidden should be thrown.
address@hidden @code{notifyAll(Object)} -- Same as the above, but all threads are
+awakened.
address@hidden @code{wait(Object,long,int)} -- The VM should set the current thread
+into a waiting state, which persists until it receives a notify signal or the
+specified time (in milliseconds and nanoseconds) is exceeded.  The nanoseconds
+restriction may be ignored if such granularity is not available, and a
address@hidden should be thrown if the current thread
+doesn't own the object.
address@hidden itemize
+
address@hidden java.lang.VMClassLoader, java.lang.VMSystem, java.lang.VMObject, java.lang
address@hidden @code{java.lang.VMClassLoader}
address@hidden provides methods for defining and resolving core and
+primitive classes, as well as handling resources, packages and assertions.
+The class is a mixture of @code{native} methods and Java-based
+implementations, with some of the latter being @emph{stubs}.
+
address@hidden @bullet
address@hidden Native Methods
address@hidden @bullet
address@hidden @code{defineClass(ClassLoader,String,byte[],int,int,ProtectionDomain)}
+-- The VM should create a @code{Class} instance from the supplied byte array.
address@hidden @code{resolveClass(Class)} -- Resolve references to other classes in the
+supplied class.
address@hidden @code{loadClass(name,boolean)} -- Load a class using the bootstrap
+loader.
address@hidden @code{getPrimitiveClass(char)} -- The VM should provide a @code{Class}
+implementation for one of the primitive classes.  The supplied character
+matches the JNI code for the primitive class e.g. `B' for byte and
+`Z' for boolean.
address@hidden itemize
address@hidden Java Methods
address@hidden @bullet
address@hidden @code{getResource(String)} -- The default implementation calls
address@hidden and returns the first element in the returned enumeration,
+or @code{null} if there are no elements.
address@hidden @code{getResources(String)} -- By default, this compiles a list of
+URLs via the boot class path.  Any matching files within a zip file are added,
+and directories on the boot class path are automatically converted to file
+URLs that refer to join the directory with the resource name (whether or not
+it actually exists).
address@hidden @code{getPackage(String)} -- Always returns null, which may be suitable
+if the VM does not wish to return a @code{Package} implementation. Otherwise,
+it may be necessary to make this a @code{native} method.
address@hidden @code{getPackages()} -- As with the last, a default stub implementation
+exists (returning an empty array) which may be replaced if support is
+required. 
address@hidden @code{defaultAssertionStatus()} -- A stub which can be implemented
+by VMs providing assertion support.  At present, it always returns @code{true}.
address@hidden @code{packageAssertionStatus()} -- Much the same status as the above.
+The method should return a map converting package names to boolean status
+values.  The stub implementation provides an empty map.
address@hidden @code{classAssertionStatus()} -- Same as the last, but for classes.
address@hidden @code{getSystemClassLoader()} -- The default calls @code{ClassLoader}
+to create a new auxillary class loader with a system and extension class
+loader.  The VM may wish to replace it if it wishes to supply its own custom
+system class loader.
address@hidden itemize
address@hidden itemize
address@hidden java.lang.VMSystem, java.lang.VMThrowable, java.lang.VMClassLoader, java.lang
address@hidden @code{java.lang.VMSystem}
address@hidden handles the default I/O streams, provides access to the
+system clock and environment variables and provides methods for
address@hidden and the @code{identityHashCode} of an
address@hidden  It consists of @code{native} methods, but the default
+implementation also provides some helper methods to simplify stream
+creation.  
+
address@hidden @bullet
address@hidden Native Methods
address@hidden @bullet
address@hidden @code{arraycopy(Object,int,Object,int,int)} -- The VM should copy
+a specified number of array objects from one array to another, with 
+appropriate checks for compatible typing, available elements and space.
+The VM should be able to perform this more efficiently using native code
+and direct memory manipulation than would have been achieved by using Java.
address@hidden @code{identityHashCode(Object)} -- This is the hashcode for
address@hidden, which relates to the actual location of the object in memory.
address@hidden @code{setIn(InputStream)} -- Set the system input stream.
address@hidden @code{setOut(PrintStream)} -- Set the system output stream.
address@hidden @code{setErr(PrintStream)} -- Set the system error stream.
address@hidden @code{currentTimeMillis()} -- Gets the system time in milliseconds.
address@hidden @code{getenv(String)} -- Returns the value of the specified environment
+variable.
address@hidden itemize
address@hidden Java Methods
address@hidden @bullet
address@hidden @code{makeStandardInputStream()} -- Helps provide the functionality of
address@hidden by wrapping the appropriate file descriptor in a buffered
+file input stream.  VMs may choose to create the stream from the descriptor
+differently rather than using this method.
address@hidden @code{makeStandardOutputStream()} -- Helps provide the functionality of
address@hidden by wrapping the appropriate file descriptor in a buffered
+file output stream.  VMs may choose to create the stream from the descriptor
+differently rather than using this method.
address@hidden @code{makeStandardErrorStream()} -- Helps provide the functionality of
address@hidden by wrapping the appropriate file descriptor in a buffered
+file output stream.  VMs may choose to create the stream from the descriptor
+differently rather than using this method.
address@hidden itemize
address@hidden itemize
+
+Classpath also provides native implementations of
+
address@hidden @bullet
address@hidden @code{setIn(InputStream)} 
address@hidden @code{setOut(PrintStream)} 
address@hidden @code{setErr(PrintStream)} 
address@hidden @code{currentTimeMillis()} 
address@hidden @code{getenv(String)}
address@hidden itemize
+
+making a VM implementation optional.
+
address@hidden java.lang.VMThrowable, java.lang.VMCompiler, java.lang.VMSystem, java.lang
address@hidden @code{java.lang.VMThrowable}
address@hidden is used to hold the VM state of a throwable, created either
+when a @code{Throwable} is created or the @code{fillInStackTrace()} method is
+called (i.e. when the actual stack trace is needed, as a lot of exceptions are
+never actually used).  The actual class has two @code{native} methods,
+one (@code{fillInStackTrace()}) being a method of the class used to obtain
+instances, and the other an instance method, @code{getStackTrace()}.
address@hidden @bullet
address@hidden @code{fillInStackTrace(Throwable)} -- The VM should return the current
+execution state of the @code{Throwable} in the form of a @code{VMThrowable}
+instance.  The VM may also return @code{null} if it does not support this
+functionality.
address@hidden @code{getStackTrace()} -- This is used to create a real
address@hidden array for the exception, using the state data
+stored during creation of the instance.
address@hidden itemize
+
address@hidden java.lang.VMCompiler, java.lang.VMDouble, java.lang.VMThrowable, java.lang
address@hidden @code{java.lang.VMCompiler}
+
address@hidden provides an interface for VMs which wish to provide
+JIT compilation support.  The default implementation is simply a series
+of stubs. The property, @code{java.compiler}, should point to a library
+containing the function @code{java_lang_Compiler_start()} if such support
+is to be provided.
+
address@hidden @bullet
address@hidden @code{compileClass(Class)} -- Invoke the compiler to compile the specific
+class, returning @code{true} if successful.
address@hidden @code{compileClasses(String)} -- The compiler should compile the classes
+matching the specified string, again returning @code{true} on success.
address@hidden @code{command(Object)} -- The object represents a command given to the
+compiler, and is specific to the compiler implementation.
address@hidden @code{enable} -- Enable the operation of the compiler.
address@hidden @code{disable} -- Disable compiler operation.
address@hidden itemize
+
address@hidden java.lang.VMDouble, java.lang.VMFloat, java.lang.VMCompiler, java.lang
address@hidden @code{java.lang.VMDouble}
+
address@hidden provides native support for the conversion and parsing
+of doubles.
+
address@hidden @bullet
address@hidden @code{doubleToLongBits(double)} -- Converts the double to the IEEE 754
+bit layout, collapsing NaNs to @code{0x7ff8000000000000L}.
address@hidden @code{doubleToRawLongBits(double)} -- Same as the above, but preserves
+NaNs.
address@hidden @code{longBitsToDouble(long)} -- This is the inverse of the last method,
+preserving NaNs so that the output of one can be fed into the other without
+data loss.
address@hidden @code{toString(double,boolean)} -- Converts the double to a string,
+giving a shorter value if the flag @code{isFloat} is @code{true}, indicating
+that the conversion was requested by @code{java.lang.Float} rather than
address@hidden
address@hidden @code{initIDs} -- Used by JNI-based solutions to initialize the cache
+of the static field IDs.  The default @code{VMDouble} implementation has a
+static initializer which loads the JNI library and calls this method.
address@hidden @code{parseDouble} -- Turn the string into a usable double value.
address@hidden itemize
+
+Classpath provides native implementations of all these, making VM
+implementation optional.
+
address@hidden java.lang.VMFloat, java.lang.VMProcess, java.lang.VMDouble, java.lang
address@hidden @code{java.lang.VMFloat}
+
address@hidden provides native support for the conversion of floats.
+
address@hidden @bullet
address@hidden @code{floatToIntBits(float)} -- Converts the float to the IEEE 754
+bit layout, collapsing NaNs to @code{0x7fc00000}.
address@hidden @code{floatToRawIntBits(float)} -- Same as the above, but preserves
+NaNs.
address@hidden @code{intBitsToFloat(int)} -- This is the inverse of the last method,
+preserving NaNs so that the output of one can be fed into the other without
+data loss.
address@hidden itemize
+
+Classpath provides native implementations of all these, making VM
+implementation optional.
+
address@hidden java.lang.VMProcess, java.lang.VMRuntime, java.lang.VMFloat, java.lang
address@hidden @code{java.lang.VMProcess}
+
address@hidden handles the execution of external processes.  In the
+default implementation, threads are spawned and reaped by @code{ProcessThread}.
+A constructor creates a new @code{VMProcess}, which extends rather than
+complements @code{Process}, using an array of arguments, an array of
+environment variables and a working directory.  The instance maintains
+system input, output and error streams linked to the external process.
+Three @code{native} methods are used, and implementations are provided
+for all three by Classpath, making VM implementation optional.  These use
+the POSIX functions, @code{fork()}, @code{waitpid()} and @code{kill()}.
+
address@hidden @bullet
address@hidden @code{nativeSpawn(String[],String[],File)} -- The VM should create a
+new process which uses the specified command-line arguments, environment
+variables and working directory.  Unlike the other two methods, this
+method is linked to an instance, and must call @code{setProcessInfo()} with
+the results before returning.
address@hidden @code{nativeReap()} -- This is called to perform a reap of any
+zombie processes, and should not block, instead returning a boolean as to
+whether reaping actually took place.
address@hidden @code{nativeKill(long)} -- The VM should terminate the specified PID.
address@hidden itemize
+
address@hidden java.lang.VMRuntime, java.lang.VMString, java.lang.VMProcess, java.lang
address@hidden @code{java.lang.VMRuntime}
+
+The @code{VMRuntime} class provides a series of native methods
+which divulge information about the runtime or invoke certain
+operations.  This includes retrieving the amount of available memory,
+and scheduling the garbage collector.  There are two exceptions: the
address@hidden method, which allows the VM to put in its own
+shutdown hooks when @code{Runtime.addShutdownHook()} is first invoked,
+and @code{exec(String[],String[],File)} which spawns an external process.
+These are Java-based static methods instead.  The first is simply a stub by
+default, while the second simply links to the functionality of
address@hidden (and should be changed if a different @code{Process}
+implementation is used).
+
address@hidden @bullet
address@hidden @code{availableProcessors()} -- Returns the number of processors 
+available to the VM.
address@hidden @code{freeMemory()} -- Returns the amount of memory the VM has available
+on the heap for allocating.
address@hidden @code{totalMemory()} -- Returns the size of the heap.
address@hidden @code{maxMemory()} -- Returns the maximum memory block the VM will
+attempt to allocate.  May be simply @code{Long.MAX_VALUE} (8 exabytes!)
address@hidden @code{gc()} -- Allows users to explicitly invoke the garbage collector.
+This is a suggestion to the VM, rather than a command, and the garbage
+collector should run anyway @emph{without} it being invoked.
address@hidden @code{runFinalization()} -- Like the above, but related to the
+finalilzation of objects rather than the garbage collector.
address@hidden @code{runFinalizationForExit()} -- Called immediately prior to VM
+shutdown in order to finalize all objects (including `live' ones)
address@hidden @code{traceInstructions(boolean)} -- This turns on and off the optional
+VM functionality of printing a trace of executed bytecode instructions.
address@hidden @code{traceMethodCalls(boolean)} -- This turns on and off the optional
+VM functionality of printing a trace of methods called.
address@hidden @code{runFinalizersOnExit(boolean)} -- A toggleable setting for
+running the finalization process at exit.
address@hidden @code{exit(int)} -- The VM should shutdown with the specified exit code.
address@hidden @code{nativeLoad(String,ClassLoader)} -- Attempts to load a file,
+returning an integer which is non-zero for success.  Nothing happens if the
+file has already been loaded.
address@hidden @code{mapLibraryName(String)} -- The VM should map the system-independent
+library name supplied to the platform-dependent equivalent (e.g. a @code{.so}
+or @code{.dll} file)
address@hidden itemize
+
address@hidden java.lang.VMString, java.lang.VMThread, java.lang.VMRuntime, java.lang
address@hidden @code{java.lang.VMString}
address@hidden is responsible for handling interned strings.  If two strings
+are equal (using the @code{equals()} method), then the results of calling
+the @code{intern()} method on each of them makes them equal
+(using @code{==}).  Thus, the same string object is always returned by
address@hidden if the two strings are equal.  The default implementation
+is Java-based and implements @code{intern(String)} by maintaining a
address@hidden which links the strings to their @code{WeakReference}.
+A new mapping is created for each new string being @code{intern}ed.  
+A VM may implement this differently by implementing this method,
+which is @code{static} and the only one in @code{VMString}.
+
address@hidden java.lang.VMThread,, java.lang.VMString, java.lang
address@hidden @code{java.lang.VMThread}
+
address@hidden provides the link between Java's threads and the platform
+threading support.  A @code{VMThread} is created via a private constructor
+and linked to a @code{Thread} instance.  This occurs when the @code{Thread}
+instance is started by the static @code{create(Thread,long)} method (the second
+argument requests a certain stack size, usually zero).  The thread itself is
+executed via the @code{run()} method, which handles any problems with the
+running of the thread and its eventual death.
+
address@hidden provides the following accessors and mutators for accessing
+the thread state via @code{VMThread},
+
address@hidden @bullet
address@hidden @code{getName()}
address@hidden @code{setName(String)}
address@hidden @code{getPriority()}
address@hidden @code{setPriotity(int)}
address@hidden @code{isDaemon()}
address@hidden itemize
+
+all of which refer to the @code{Thread} instance. @code{setPriority(int)} also
+calls the appropriate native method.  @code{stop(Throwable)} similarly wraps
+a native method, merely adding in a check for the state of the thread.
+
+The default implementation also provides Java-based implementations of
address@hidden(long,int)}, @code{sleep(long,int)} and
address@hidden(Object)}.  @code{join} and @code{sleep} simply wait for
+the appropriate amount of time, with @code{join} additionally waiting
+for the thread instance to become @code{null}.  @code{holdsLock} simply
+checks if an object is locked by the current thread by trying to invoke
+the @code{notify} method, and catching the failing exception if this is
+not the case.
+
+The remainder of the class is a series of @code{native} methods, some of
+which are mandatory for VM implementation and others which provide optional
+or deprecated functionality.
+
address@hidden @bullet
address@hidden Mandatory Instance Methods
address@hidden @bullet
address@hidden @code{start(long)} -- The VM should create the native thread and start
+it running using the @code{run} method of the @code{VMThread} instance on
+which this method is called.
address@hidden @code{interrupt()} -- The VM should interrupt the running thread and
+throw an appropriate exception.
address@hidden @code{isInterrupted()} -- Checks the interrupted state of the thread.
address@hidden @code{suspend()} -- The thread should be suspended until resumed.
address@hidden @code{resume()} -- The thread should be resumed from its suspended state.
+This pair of methods are deprecated, due to the possibility of a deadlock
+occuring when a thread with locks is suspended.
address@hidden @code{nativeSetPriority(int)} -- Called by @code{setPriority}
+to allow the setting to flow down to the native thread.
address@hidden @code{nativeStop(Throwable)} -- The VM should stop the thread abnormally
+and throw the specified exception.  This is clearly deprecated, due to the
+ambiguous state an abruptly-stopped thread may leave.
address@hidden itemize
address@hidden Mandatory Class Methods
address@hidden @bullet
address@hidden @code{currentThread()} -- Return a reference to the thread currently
+being executed.
address@hidden @code{yield()} -- The VM should allow some other thread to run.
+The current thread maintains its locks even though it stops executing for
+the time being.
address@hidden @code{interrupted()} -- A shortcut to obtaining the interrupted state
+of the current thread.
address@hidden itemize
address@hidden Other Methods
address@hidden @bullet
address@hidden @code{countStackFrames()} -- Returns a count of the number of stack
+frames in the thread.  This depends on the deprecated method @code{suspend()}
+having returned true, and is thus deprecated as a result.
address@hidden itemize
address@hidden itemize
+
address@hidden gnu.classpath, java.util, java.lang, Classpath Hooks
address@hidden @code{gnu.classpath}
+
+The @code{gnu.classpath} package provides Classpath-specific functionality,
+primarily relating to the features in @code{java.lang}.  At present, this
+includes the context of a class (the stack) and the system properties.
+
address@hidden
+* gnu.classpath.VMStackWalker::
+* gnu.classpath.VMSystemProperties::
address@hidden menu
+
address@hidden gnu.classpath.VMStackWalker,gnu.classpath.VMSystemProperties,gnu.classpath,gnu.classpath
address@hidden @code{gnu.classpath.VMStackWalker}
+
address@hidden provides access to the class context or stack.  The
+default implementation consists of a @code{native} @code{static} method,
address@hidden()}, which obtains the class context, and two helper
+methods which obtain the calling class (the 3rd element in the context array)
+and its class loader, respectively.
+
address@hidden @bullet
address@hidden @code{getClassContext()} -- The VM should return an array of
address@hidden objects, each of which relates to the method currently being
+executed at that point on the stack.  Thus, the first item (index 0) is the
+class that contains this method.
address@hidden @code{getCallingClass()} -- A Java-based helper method which returns
+the @code{Class} object which contains the method that called the method
+accessing @code{getCallingClass()}. 
address@hidden @code{getCallingClassLoader()} -- Like the last, but returning the class
+loader of the class.
address@hidden itemize
+
address@hidden gnu.classpath.VMSystemProperties,,gnu.classpath.VMStackWalker,gnu.classpath
address@hidden @code{gnu.classpath.VMSystemProperties}
+
address@hidden allows the VM to hook into the property creation
+process, both before and after the system properties are added by GNU
+Classpath.  The default implementation assumes that the VM will add its
+properties first, by making the pre-initialisation method @code{native},
+and that the Classpath properties may then be altered by a Java-based
+post-initialisation method.
+
+As these methods are called as part of the bootstrap process, caution should
+be used as to what classes are used, and properties should only be set
+using @code{Properties.setProperty()}.  Specifically, I/O classes should be
+avoided at this early stage.
+
address@hidden @bullet
address@hidden @code{preInit(Properties)} -- Allows the VM to add properties
address@hidden the Classpath properties are added. The default implementation
+includes a full list of properties that @emph{must} be added by the VM, but
+additional VM-specific ones may also be added.  
address@hidden @code{postInit(Properties)} -- Same as the last, but called after the
+Classpath properties have been added.  The main purpose of this is to allow
+the VM to alter the properties added by GNU Classpath to suit it.
address@hidden itemize
+
address@hidden java.util, java.io, gnu.classpath, Classpath Hooks
address@hidden java.util
+
+The @code{java.util} VM hooks provide links between the mix of functionality
+present in that package, which includes collections, date and time handling
+and parsing.  At present, there is only one hook, which connects GNU Classpath
+to the timezone information provided by the underlying platform.
+
address@hidden
+* java.util.VMTimeZone::
address@hidden menu
+
address@hidden java.util.VMTimeZone,,java.util,java.util
address@hidden @code{java.util.VMTimeZone}
+
address@hidden joins @code{TimeZone} to the platform timezone information
+via the static method, @code{getDefaultTimeZoneId()}.  The VM hook is
+expected to return a @code{TimeZone} instance that represents the current
+timezone in use by the platform.  The default implementation provides
+this functionality for POSIX or GNU-like systems, and VMs that want this
+functionality can keep this implementation and implement the native
+method, @code{getSystemTimeZoneId()}.  This method is only called when
+obtaining the timezone name from the @code{TZ} environment variable,
address@hidden/etc/timezone} and @code{/etc/localtime} all fail.  This fallback
+mechanism also means that a system which doesn't provide the above three
+methods, but does provide a timezone in string form, can still use this
+implementation.
+
address@hidden java.io, java.security, java.util, Classpath Hooks
address@hidden java.io
+
+The @code{java.io} package is heavily reliant on access to the I/O facilities
+of the underlying platform.  As far as its VM hooks go, they provide two
+areas of functionality to GNU Classpath, these being
+
address@hidden @bullet
address@hidden File and directory queries and manipulation
address@hidden Serialization of objects
address@hidden itemize
+
+The first corresponds directly to most of the @code{File} class, while
+the latter underlies the functionality provided by the
address@hidden and @code{ObjectOutputStream}.  More low-level I/O
+is provided by @ref{java.nio}.
+
address@hidden
+* java.io.VMFile::
+* java.io.VMObjectInputStream::
+* java.io.VMObjectStreamClass::
address@hidden menu
+
address@hidden java.io.VMFile,java.io.VMObjectInputStream,java.io,java.io
address@hidden @code{java.io.VMFile}
+
address@hidden allows GNU Classpath's @code{File} representations to
+probe and modify the file system using the native functions of the
+platform.  The default implementation (which consists of both a
address@hidden class and the native methods) is primarily UNIX-centric,
+working with POSIX functions and assuming case-sensitive filenames,
+without the restriction of the 8.3 format.  It consists mainly of
address@hidden @code{native} methods, with a few Java helper methods.
+The native methods represent the file as a string containing its path,
+rather than using the object itself.
+
address@hidden @bullet
address@hidden Native Methods
address@hidden @bullet
address@hidden @code{lastModified(String)} -- The native method should return a
address@hidden value that represents the last modified date of the file.
address@hidden @code{setReadOnly(String)} -- Sets the file's permissions to read only,
+in whichever way this is realised by the platform.
address@hidden @code{create(String)} -- Create the named file.
address@hidden @code{list(String)} -- The native method opens the named directory,
+reads the contents and returns them as a Java @code{String} array.
address@hidden @code{renameTo(String,String)} -- Renames the first file to the second.
address@hidden @code{length(String)} -- Returns a @code{long} value representing
+the file size.
address@hidden @code{exists(String)} -- Tests for the existence of the named file
+or directory.
address@hidden @code{delete(String)} -- Deletes the file or directory.
address@hidden @code{setLastModified(String,long)} -- Change the last modified time.
address@hidden @code{mkdir(String)} -- Creates the named directory.
address@hidden @code{isFile(String)} -- Tests that the named path references a file.
address@hidden @code{canWrite(String)} -- Tests that the file can be written to.
+This method is @code{synchronized}, so the object is locked during the check.
address@hidden @code{canRead(String)} -- Complement of the last method.
address@hidden @code{isDirectory(String)} -- Tests that the named path references
+a directory.
address@hidden itemize
address@hidden Java Helper Methods
address@hidden @bullet
address@hidden @code{canWriteDirectory(File)} -- Checks that the directory can be
+written to, by trying to create a temporary file in it.
address@hidden @code{listRoots()} -- Returns the root of a GNU filesystem i.e. `/'
+in an array.
address@hidden @code{isHidden(String)} -- Checks whether the file starts with `.',
+which is how files are hidden on UNIX-style systems.
address@hidden @code{getName(String)} -- Pulls the actual filename from the end of
+the path, by breaking off the characters after the last occurrence of the
+platform's file separator.
address@hidden @code{getCanonicalForm(String)} -- This converts a UNIX path to
+its canonical form by removing the `.' and `..' sections that occur within.
 @end itemize
address@hidden itemize
+
address@hidden java.io.VMObjectInputStream,java.io.VMObjectStreamClass,java.io.VMFile,java.io
address@hidden @code{java.io.VMObjectInputStream}
+
+This class consists of two methods which provide functionality used in
+deserializing an object.  @code{currentClassLoader()} provides the first
+user-defined class loader from the class context
+(@xref{gnu.classpath.VMStackWalker},) via a @code{PrivilegedAction}.
address@hidden(Class,Class,Constructor)} is a @code{native} method
+(a reference implementation is provided) which creates an object but
+calls the constructor of another class, which is a superclass of the
+object's class.
+
address@hidden java.io.VMObjectStreamClass,,java.io.VMObjectInputStream,java.io
address@hidden @code{java.io.VMObjectStreamClass}
+
address@hidden is a series of @code{static} @code{native}
+methods that provide some of the groundwork for @code{ObjectStreamClass}
+and @code{ObjectStreamField}.  @code{hasClassInitializer(Class)} works
+with the former, and checks for the presence of a static initializer.
+The remaining methods are of the form @code{setXXXNative(Field,Object,XXX)}
+and support @code{ObjectStreamField}.  One exists for each of the main types
+(boolean, float, double, long, int, short, char, byte and object) and is used
+to set the specified field in the supplied instance to the given value.
+
+A default implementation is provided for all of them, so a VM implementation
+is optional.
+
address@hidden java.security, java.net, java.io, Classpath Hooks
address@hidden java.security
+
+The @code{java.security} package provides support for Java's security
+architecture.  At present, @code{VMAccessController} represents the sole
+VM hook for this.
 
-You also need to implement some helper classes in java.lang that classes
-from Classpath call out to to get certain VM-specific dirty work done:
address@hidden
+* java.security.VMAccessController::
address@hidden menu
+
address@hidden java.security.VMAccessController,,java.security,java.security
address@hidden @code{java.security.VMAccessController}
+
+The @code{AccessController} is used to perform privileged actions.  Its
+hook class, @code{VMAccessController}, maintains the
address@hidden and the default implementation is purely
+Java-based.  The VM may choose to replace this with their own.
+The methods in the reference version are as follows:
 
 @itemize @bullet
address@hidden @code{java.lang.VMObject}
-is the bridge between the low level @code{Object} facilities such
-as making a clone, getting the class of the object and the wait/notify
-semantics.
address@hidden @code{java.lang.VMClassLoader}
-provides methods for defining and resolving core and primitive classes.
address@hidden @code{java.lang.VMSystem}
-is used to initialize the @code{System} properties, the @code{System.arraycopy}
-method and the @code{identityHashCode} of an @code{Object}.
address@hidden @code{java.lang.VMSecurityManager}
-provides the class context (stack trace) of the currently
-executing thread and a way to get the currently active @code{ClassLoader}.
address@hidden @code{java.lang.VMThrowable}
-used to hold the VM state of a throwable, created when a @code{Throwable} is
-created or the @code{fillInStacktrace()} method is called, when the actual stack
-trace is needed (a lot of exceptions are never actually used), the
address@hidden()} method is used to create a real @code{StackTraceElement} array
-for the exception.
address@hidden @code{pushContext(AccessControlContext)} -- Adds a new context to the
+stack for the current thread.  This is called before a privileged action
+takes place.
address@hidden @code{popContext()} -- Removes the top context from the stack.  This
+is performed after the privileged action takes place.
address@hidden @code{getContext()} -- Either derives a context based on the 
address@hidden of the call stack (see the next method) or returns
+the top of the context stack.
address@hidden @code{getStack()} -- Provides access to the call stack as a pair of
+arrays of classes and method names.  The actual implementation returns
+an empty array, indicating that there are no permissions.
 @end itemize
 
address@hidden java.net, java.nio, java.security, Classpath Hooks
address@hidden java.net
+
+The @code{java.net} package is heavily reliant on access to the networking
+facilities of the underlying platform.  The VM hooks provide information
+about the available network interfaces, and access to lookup facilities
+for network addresses.
+
address@hidden
+* java.net.VMInetAddress::
+* java.net.VMNetworkInterface::
address@hidden menu
+
address@hidden java.net.VMInetAddress,java.net.VMNetworkInterface,java.net,java.net
address@hidden @code{java.net.VMInetAddress}
+
address@hidden is a series of @code{static} @code{native} methods
+which provide access to the platform's lookup facilities.  All the methods
+are implemented by GNU Classpath, making VM implementation optional, and
+are as follows:
+
address@hidden @bullet
address@hidden @code{getLocalHostname()} -- Wraps the @code{gethostname} function, and
+falls back on `localhost'.
address@hidden @code{lookupInaddrAny()} -- Returns the value of @code{INADDR_ANY}.
address@hidden @code{getHostByAddr(byte[])} -- Looks up the hostname based on an IP
+address.
address@hidden @code{getHostByName(String)} -- The reverse of the last method, it
+returns the IP addresses which the given host name resolves to.
address@hidden itemize
+
address@hidden java.net.VMNetworkInterface,,java.net.VMInetAddress,java.net
address@hidden @code{java.net.VMNetworkInterface}
+
address@hidden currently consists of a single @code{static}
address@hidden method, @code{getInterfaces()}, which retrieves the
+network interfaces available on the underlying platform as a @code{Vector}.
+The current GNU Classpath implementation is a native stub.
+
address@hidden java.nio, java.nio.channels, java.net, Classpath Hooks
address@hidden java.nio
+
+The @code{java.nio} package is part of the New I/O framework added in
+Java 1.4.  This splits I/O into the concepts of @emph{buffers},
address@hidden, @emph{channels} and @emph{selectors}, and
address@hidden defines the buffer classes.  As far as native and VM
+code is concerned, the new package needs support for low-level efficient
+buffer operations.
+
address@hidden
+* java.nio.VMDirectByteBuffer::
address@hidden menu
+
address@hidden java.nio.VMDirectByteBuffer,,java.nio,java.nio
address@hidden @code{java.nio.VMDirectByteBuffer}
+
+A @code{ByteBuffer} maintains a buffer of bytes, and allows it to be
+manipulated using primitive operations such as @code{get}, @code{put},
address@hidden and @code{free}.  A direct buffer avoids intermediate
+copying, and uses native data which shouldn't be manipulated by a
+garbage collector.  The VM class consists of @code{static} @code{native}
+methods, all of which are given default implementations by GNU
+Classpath.
+
address@hidden @bullet
address@hidden @code{init()} -- Creates an instance of an appropriate
address@hidden class.  This class is not garbage
+collected, is created natively and is used in the other methods to reference
+the buffered data.
address@hidden @code{allocate(int)} -- Allocates the memory for the buffer using
address@hidden and returns a reference to the @code{RawData} class.
address@hidden @code{free(RawData)} -- Frees the memory used by the buffer.
address@hidden @code{get(RawData,int)}  -- Returns the data at the specified index.
address@hidden @code{get(RawData,int,byte[],int,int)} -- Copies a section of the
+data into a byte array using @code{memcpy}.
address@hidden @code{put(RawData,int,byte)} -- Puts the given data in the buffer
+at the specified index.
address@hidden @code{adjustAddress(RawData,int)} -- Adjusts the pointer into the buffer.
address@hidden @code{shiftDown(RawData,int,int,int)} -- Moves the content of the buffer
+at an offset down to a new offset using @code{memmove}.
address@hidden itemize
+ 
address@hidden java.nio.channels, gnu.java.nio, java.nio, Classpath Hooks
address@hidden java.nio.channels
+
+Channels provide the data for the buffers with the New I/O packages.
+For example, a channel may wrap a file or a socket.  The VM hooks,
+at the moment, simply allow the channels to be accessed by @code{java.io}
+streams.
+
address@hidden
+* java.nio.channels.VMChannels::
address@hidden menu
+
address@hidden java.nio.channels.VMChannels,,java.nio.channels,java.nio.channels
address@hidden @code{java.nio.channels.VMChannels}
+
address@hidden provides the methods that create the channels or
+streams.  The default implementation is in pure Java and simply wraps
+the channels in standard I/O classes from @code{java.io}.
+
address@hidden @bullet
address@hidden @code{createStream(Class,Channel)} -- Creates a @code{FileChannel}
+which wraps an instance of the specified stream class, created by reflection.
+This method is private, and is used by the other two.
address@hidden @code{newInputStream(ReadableByteChannel)} -- Wraps the channel
+in a @code{FileInputStream}.
address@hidden @code{newOutputStream(WritableByteChannel)} -- Wraps the channel
+in a @code{FileOutputStream}.
address@hidden itemize
+
address@hidden gnu.java.nio, Classpath Callbacks, java.nio.channels, Classpath Hooks
address@hidden gnu.java.nio
+
+The @code{gnu.java.nio} class provides Classpath implementations of the
+interfaces provided by @code{java.nio}.  The VM classes provide the native
+support necessary to implement @emph{pipes} and @emph{selectors}.
+
address@hidden
+* gnu.java.nio.VMPipe::
+* gnu.java.nio.VMSelector::
address@hidden menu
+
address@hidden gnu.java.nio.VMPipe,gnu.java.nio.VMSelector,gnu.java.nio,gnu.java.nio
address@hidden @code{gnu.java.nio.VMPipe}
+
address@hidden provides the native functionality for a uni-directional pipe
+between a source and a destination (sink) channel.  It consists of one 
address@hidden @code{native} method, @code{init(PipeImpl,SelectorProvider)},
+the reference implementation of which is currently a native stub.  Ideally,
+this should initialise the pipe at the native level.
+
address@hidden gnu.java.nio.VMSelector,,gnu.java.nio.VMPipe,gnu.java.nio
address@hidden @code{gnu.java.nio.VMSelector}
+
+A @code{Selector} selects between multiple @code{SelectableChannel}s based
+on their readiness and a key set.  The VM hook for the Classpath implementation
+of this is @code{VMSelector}, and this allows the actual @code{select()}
+operation to be performed.  This is represented by the @code{static}
address@hidden method, @code{select(int[],int[],int[],long)}, and a default
+implementation of this is provided.
+
address@hidden Classpath Callbacks, , gnu.java.nio, Classpath Hooks
 Some of the classes you implement for the VM will need to call back to
 package-private methods in Classpath:
 
@@ -221,10 +1060,8 @@ the group.
 
 @item @code{java.lang.ThreadGroup.removeThread(Thread)}
 Call this method from @code{Thread} when a @code{Thread} is stopped or destroyed.
-
 @end itemize
 
-
 @node VM Hooks, JNI Implementation, Classpath Hooks, Top
 @comment node-name, next, previous, up
 @chapter VM Hooks
@@ -234,22 +1071,51 @@ unfortunately are dependent on the inter
 classes.  This is a guide to all of the things the VM itself needs to
 know about classes.
 
+Some of the core classes, while being implemented by GNU Classpath,
+provide space for state (in the form of a @code{vmdata} object) to be
+stored by the VM, and can not be constructed normally.
+
address@hidden @bullet
address@hidden java.lang.Class
address@hidden java.lang.ClassLoader
address@hidden itemize
+
+The default implementations of some VM classes also follow this methodology,
+when it is intended that most VMs will keep the default.
+
address@hidden @bullet
address@hidden java.lang.VMThread
address@hidden java.lang.VMThrowable
address@hidden itemize
+
+Several core classes must be completely implemented by the VM for Classpath to
+work, although reference implementations are provided.  These classes are:
+
address@hidden @bullet
address@hidden java.lang.reflect.Constructor
address@hidden java.lang.reflect.Method
address@hidden java.lang.reflect.Field
address@hidden itemize
+
+The following issues are of note;
+
 @itemize @bullet
 @item @code{java.lang.Class} @*
-You, the VM, get to create this @code{Class}, so you may define the internal
-structure any way you wish.  You probably have code somewhere to
-translate your internal class structure into a @code{Class} object.  That is
-the only known place where this matters.  Some VMs do not create the
address@hidden object at the point where the class is defined; instead, they wait
-until a @code{Class} object is actually used.
+The GNU Classpath implementation of @code{java.lang.Class} provides an
+object for storing the internal state of the class maintained by the VM.
+This is the only known place where this matters.  The class is
+constructed with this data by the VM.  Some VMs do not create the
address@hidden object at the point where the class is defined; instead,
+they wait until a @code{Class} object is actually used.
 
 @item Array Classes @*
-When you are creating an array class, you should set the @code{ClassLoader} of
-the array class to the @code{ClassLoader} of its component type.  Whenever you
-add a class to a @code{ClassLoader}, you need to notify the @code{ClassLoader} and
-add the new @code{Class} to its internal cache of classes.  To do this, call
address@hidden(Class)}.  @emph{Note: this is written in
-anticipation of 1.2 support and does not apply just yet.}
+When you are creating an array class, you should set the
address@hidden of the array class to the @code{ClassLoader} of its
+component type.  Whenever you add a class to a @code{ClassLoader}, you
+need to notify the @code{ClassLoader} and add the new @code{Class} to
+its internal cache of classes.  To do this, call
address@hidden(Class)}.  @emph{Note: this is
+written in anticipation of 1.2 support and does not apply just yet.}
 
 @item Primordial Class Loader @*
 When the primordial class loader loads a class, it needs to tell
@@ -422,3 +1288,4 @@ to the value of the @code{LD_LIBRARY_PAT
 @bye
 
 
+