2006-05-01 Andrew John Hughes <gnu_andrew@member.fsf.org>

	* Merge HEAD-->generics-branch for the period
	2006-04-13 to 2006-05-01.

1 files changed, 129 insertions, 65 deletions

diff --git a/doc/vmintegration.texinfo b/doc/vmintegration.texinfo
index 0164f7c83..a784e6fad 100644
--- a/doc/vmintegration.texinfo
+++ b/doc/vmintegration.texinfo
@@ -201,6 +201,7 @@ implementation.
 * java.nio.channels::
 * gnu.java.nio::
 * java.lang.reflect::
+* gnu.java.lang::
 * Classpath Callbacks::
 @end menu
 
@@ -227,7 +228,6 @@ become operable.
 * java.lang.VMRuntime::
 * java.lang.VMString::
 * java.lang.VMThread::
-* java.lang.VMInstrumentationImpl::
 * java.lang.VMMath::
 @end menu
 
@@ -275,9 +275,12 @@ VM should filter out non-public classes.
 @item @code{getDeclaredConstructors(Class,boolean)} -- And constructors.
 @item @code{getClassLoader(Class)} -- Returns the @code{ClassLoader} instance
 which is responsible for the specified class.
-@item @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.
+@item @code{forName(String, boolean, ClassLoader)} -- 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.  The supplied class loader is recorded as that
+which loaded the class, and the boolean specifies whether or not to
+run the class initializer.
 @item @code{isArray(Class)} -- Another property test, corresponding to a
 class file flag.
 @item @code{initialize(Class)} -- The VM should initialize the class fully,
@@ -308,15 +311,44 @@ information stored in the class file.
 an inner or member class, or @code{null} if the instance refers to a top-level
 class.
 @end itemize
+@item 1.5
+@itemize @bullet
+@item @code{isSynthetic(Class)} -- Returns true if the flags for this class
+mark it as synthetic.
+@item @code{isAnnotation(Class)} -- Returns true if the flags for this class
+mark it as an annotation.
+@item @code{isEnum(Class)} -- Returns true if the flags for this class
+mark it as an enumeration.
+@item @code{getSimpleName(Class)} -- Returns the simple name of the class.
+A default implementation is provided, but a more efficient version may instead
+be provided by the VM.
+@item @code{getCanonicalName(Class)} -- Returns the canonical name of the
+class.  A default implementation is provided, but a more efficient
+version may instead be provided by the VM.
+@item @code{getEnclosingClass(Class)} -- Returns the immediately enclosing
+class (null for a top-level class).
+@item @code{getEnclosingConstructor(Class)} -- Returns the constructor
+which immediately encloses the supplied class.
+@item @code{getEnclosingMethod(Class)} -- Returns the method
+which immediately encloses the supplied class.
+@item @code{getClassSignature(Class)} -- Returns the generic signature of
+the class or null if there isn't one.
+@item @code{isAnonymousClass(Class)} -- Returns true if the class is an
+anonymous class.
+@item @code{isLocalClass(Class)} -- Returns true if the class is an
+local class.
+@item @code{isMemberClass(Class)} -- Returns true if the class is an
+member class.
+@end itemize
 @end itemize
 
 @node java.lang.VMObject, java.lang.VMClassLoader, java.lang.VMClass, java.lang
 @subsection @code{java.lang.VMObject}
 
-@code{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.  This is accomplished using the following @code{native}
-methods.
+@code{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.  This is accomplished using the following
+@code{native} methods.
 
 @itemize @bullet
 @item @code{getClass(Object)} -- Returns the @code{Class} instance for the
@@ -414,13 +446,15 @@ and direct memory manipulation than would have been achieved by using Java.
 @item @code{currentTimeMillis()} -- Gets the system time in milliseconds.
 @item @code{getenv(String)} -- Returns the value of the specified environment
 variable.
+@item @code{getenv()} -- Returns a list of `name=value' pairs which correspond
+to the environment variables.
 @end itemize
 @item Java Methods
 @itemize @bullet
 @item @code{makeStandardInputStream()} -- Helps provide the functionality of
-@code{System.in} 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.
+@code{System.in} 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.
 @item @code{makeStandardOutputStream()} -- Helps provide the functionality of
 @code{System.out} by wrapping the appropriate file descriptor in a buffered
 file output stream.  VMs may choose to create the stream from the descriptor
@@ -541,11 +575,14 @@ for all three by Classpath, making VM implementation optional.  These use
 the POSIX functions, @code{fork()}, @code{waitpid()} and @code{kill()}.
 
 @itemize @bullet
-@item @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.
+@item @code{nativeSpawn(String[],String[],File,boolean)} -- 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.  The
+boolean argument maps to the @code{redirectErrorStream} property of
+@code{java.lang.ProcessBuilder}.  When true, the output and error streams
+are merged.
 @item @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.
@@ -610,7 +647,7 @@ 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}.
 
-@node java.lang.VMThread,java.lang.VMInstrumentationImpl, java.lang.VMString, java.lang
+@node java.lang.VMThread, java.lang.VMMath, java.lang.VMString, java.lang
 @subsection @code{java.lang.VMThread}
 
 @code{VMThread} provides the link between Java's threads and the platform
@@ -686,49 +723,7 @@ having returned true, and is thus deprecated as a result.
 @end itemize
 @end itemize
 
-@node java.lang.VMInstrumentationImpl, java.lang.VMMath, java.lang.VMThread, java.lang
-@subsection @code{java.lang.VMInstrumentationImpl}
-
-The @code{java.lang.VMInstrumentationImpl} and
-@code{java.lang.InstrumentationImpl} classes provide an implementation of the
-@code{java.lang.instrument.Instrument} interface. This interface is for java
-1.5 and is only in the generics branch.
-A @code{InstrumentationImpl} object should be created by the VM when agents
-are given in the command line (see the @code{java.lang.instrument} package
-documentation). The VM has to set the static field
-@code{VMClassLoader.instrumenter} to this object. The VM should implement the
-static native methods of the @code{VMInstrumentationImpl} class.
-
-@itemize @bullet
-@item @code{isRedefineClassesSupported()} -- Returns true if the JVM supports
-class redefinition.
-@item @code{redefineClasses()} -- Gives a set of classes with new bytecodes.
-The VM must redefine the classes by reading the new bytecodes.
-@item @code{getAllLoadedClass()} -- Returns an array of all loaded classes.
-@item @code{getInitiatedClass()} -- Returns an array of all classes loaded
-by a specific class loader.
-@item @code{getObjectSize()} -- Gives the size of an object.
-@end itemize
-
-Instrumentation allows to modify the bytecode of a class before it gets read
-by the VM. In GNU Classpath, the @code{ClassLoader.defineClass} method calls
-the @code{VMClassLoader.defineClassWithTransformers} method which first checks
-if @code{VMClassLoader.instrumenter} is @code{null}. If it's the case, it
-directly calls @code{VMClassLoader.defineClass}. If it's not the case, the
-method calls at first the @code{InstrumentationImpl.callTransformers} method,
-which calls each transformer registered to the @code{InstrumentationImpl}
-object and returns a new bytecode array. Then, it calls the
-@code{VMClassLoader.defineClass} method with this new bytecode array.
-
-The second use of instrumentation is to redefine a class after it has been
-loaded by the VM. This is done in the Java application by calling the
-@code{Instrumentation.redefineClasses} method of the standard interface on
-a @code{Instrumentation} object. The @code{InstrumentationImpl.redefineClasses}
-method calls the @code{VMInstrumentationImpl.redefineClasses} native method
-which must be implemented by the VM. The implementation should call the
-@code{InstrumentationImpl.callTransformers} method.
-
-@node java.lang.VMMath, , java.lang.VMInstrumentationImpl, java.lang
+@node java.lang.VMMath,, java.lang.VMThread, java.lang
 @subsection @code{java.lang.VMMath}
 
 The @code{VMMath} class provides a series of native methods
@@ -1004,14 +999,14 @@ is optional.
 @section 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.
+architecture.  
 
 @menu
 * java.security.VMAccessController::
+* java.security.VMSecureRandom::
 @end menu
 
-@node java.security.VMAccessController,,java.security,java.security
+@node java.security.VMAccessController,java.security.VMSecureRandom,java.security,java.security
 @subsection @code{java.security.VMAccessController}
 
 The @code{AccessController} is used to perform privileged actions.  Its
@@ -1034,6 +1029,23 @@ arrays of classes and method names.  The actual implementation returns
 an empty array, indicating that there are no permissions.
 @end itemize
 
+@node java.security.VMSecureRandom,,java.security.VMAccessController,java.security
+@subsection @code{java.security.VMSecureRandom}
+
+The @code{VMSecureRandom} class is used to provide access to
+cryptographically secure random numbers.  The default implementation
+of the class runs eight threads that increment counters in a tight
+loop, and XORs each counter to produce one byte of seed data. This is
+not very efficient, and is not guaranteed to be random (the thread
+scheduler is probably deterministic, after all). VM implementors
+should provide a version of this class, which implements the method
+@code{generateSeed(byte[],int,int)}, so that it fills the buffer using
+a random seed from a system facility, such as a system entropy
+gathering device or hardware random number generator.  The parameters
+are the usual set of buffer, offset and length and the method returns
+the number of bytes actually generated, which may be less than that
+requested.
+
 @node java.net, java.nio, java.security, Classpath Hooks
 @section java.net
 
@@ -1176,7 +1188,7 @@ operation to be performed.  This is represented by the @code{static}
 @code{native} method, @code{select(int[],int[],int[],long)}, and a default
 implementation of this is provided.
 
-@node java.lang.reflect, Classpath Callbacks, gnu.java.nio, Classpath Hooks
+@node java.lang.reflect, gnu.java.lang, gnu.java.nio, Classpath Hooks
 @section @code{java.lang.reflect}
 @code{java.lang.reflect} provides the interface to Java's reflection
 facilities.  Via reflection, programmers can obtain type information about
@@ -1194,7 +1206,59 @@ which the VM uses to generate a new non-primitive array of a
 particular class and size.  The default implementation simply passes
 the job down to the standard JNI function, @code{NewObjectArray}.
 
-@node Classpath Callbacks, , java.lang.reflect, Classpath Hooks
+@node gnu.java.lang, Classpath Callbacks, java.lang.reflect, Classpath Hooks
+@section @code{gnu.java.lang}
+
+@code{gnu.java.lang} provides VM interfaces for the GNU
+implementations of features in java.lang.  Currently, this includes the
+implementation of instrumentation.
+
+@menu
+* gnu.java.lang.VMInstrumentationImpl::
+@end menu
+
+@node gnu.java.lang.VMInstrumentationImpl,,,gnu.java.lang
+@subsection @code{gnu.java.lang.VMInstrumentationImpl}
+
+The @code{gnu.java.lang.VMInstrumentationImpl} and
+@code{gnu.java.lang.InstrumentationImpl} classes provide an implementation of the
+@code{java.lang.instrument.Instrument} interface. 
+A @code{InstrumentationImpl} object should be created by the VM when agents
+are given in the command line (see the @code{java.lang.instrument} package
+documentation). The VM has to set the static field
+@code{VMClassLoader.instrumenter} to this object. The VM should implement the
+static native methods of the @code{VMInstrumentationImpl} class.
+
+@itemize @bullet
+@item @code{isRedefineClassesSupported()} -- Returns true if the JVM supports
+class redefinition.
+@item @code{redefineClasses()} -- Gives a set of classes with new bytecodes.
+The VM must redefine the classes by reading the new bytecodes.
+@item @code{getAllLoadedClass()} -- Returns an array of all loaded classes.
+@item @code{getInitiatedClass()} -- Returns an array of all classes loaded
+by a specific class loader.
+@item @code{getObjectSize()} -- Gives the size of an object.
+@end itemize
+
+Instrumentation allows to modify the bytecode of a class before it gets read
+by the VM. In GNU Classpath, the @code{ClassLoader.defineClass} method calls
+the @code{VMClassLoader.defineClassWithTransformers} method which first checks
+if @code{VMClassLoader.instrumenter} is @code{null}. If it's the case, it
+directly calls @code{VMClassLoader.defineClass}. If it's not the case, the
+method calls at first the @code{InstrumentationImpl.callTransformers} method,
+which calls each transformer registered to the @code{InstrumentationImpl}
+object and returns a new bytecode array. Then, it calls the
+@code{VMClassLoader.defineClass} method with this new bytecode array.
+
+The second use of instrumentation is to redefine a class after it has been
+loaded by the VM. This is done in the Java application by calling the
+@code{Instrumentation.redefineClasses} method of the standard interface on
+a @code{Instrumentation} object. The @code{InstrumentationImpl.redefineClasses}
+method calls the @code{VMInstrumentationImpl.redefineClasses} native method
+which must be implemented by the VM. The implementation should call the
+@code{InstrumentationImpl.callTransformers} method.
+
+@node Classpath Callbacks, , gnu.java.lang, Classpath Hooks
 Some of the classes you implement for the VM will need to call back to
 package-private methods in Classpath: