vmintegration.texinfo

gcc的组建

or deprecated functionality.

@itemize @bullet
@item Mandatory Instance Methods
@itemize @bullet
@item @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.
@item @code{interrupt()} -- The VM should interrupt the running thread and
throw an appropriate exception.
@item @code{isInterrupted()} -- Checks the interrupted state of the thread.
@item @code{suspend()} -- The thread should be suspended until resumed.
@item @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.
@item @code{nativeSetPriority(int)} -- Called by @code{setPriority}
to allow the setting to flow down to the native thread.
@item @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.
@end itemize
@item Mandatory Class Methods
@itemize @bullet
@item @code{currentThread()} -- Return a reference to the thread currently
being executed.
@item @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.
@item @code{interrupted()} -- A shortcut to obtaining the interrupted state
of the current thread.
@end itemize
@item Other Methods
@itemize @bullet
@item @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.
@end itemize
@end itemize

@node gnu.classpath, java.util, java.lang, Classpath Hooks
@section @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.

@menu
* gnu.classpath.VMStackWalker::
* gnu.classpath.VMSystemProperties::
@end menu

@node gnu.classpath.VMStackWalker,gnu.classpath.VMSystemProperties,gnu.classpath,gnu.classpath
@subsection @code{gnu.classpath.VMStackWalker}

@code{VMStackWalker} provides access to the class context or stack.  The
default implementation consists of a @code{native} @code{static} method,
@code{getClassContext()}, 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.

@itemize @bullet
@item @code{getClassContext()} -- The VM should return an array of
@code{Class} 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.
@item @code{getCallingClass()} -- A Java-based helper method which returns
the @code{Class} object which contains the method that called the method
accessing @code{getCallingClass()}. 
@item @code{getCallingClassLoader()} -- Like the last, but returning the class
loader of the class.
@end itemize

@node gnu.classpath.VMSystemProperties,,gnu.classpath.VMStackWalker,gnu.classpath
@subsection @code{gnu.classpath.VMSystemProperties}

@code{VMSystemProperties} 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.

@itemize @bullet
@item @code{preInit(Properties)} -- Allows the VM to add properties
@emph{before} 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.  
@item @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.
@end itemize

@node java.util, java.io, gnu.classpath, Classpath Hooks
@section 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.

@menu
* java.util.VMTimeZone::
@end menu

@node java.util.VMTimeZone,,java.util,java.util
@subsection @code{java.util.VMTimeZone}

@code{VMTimeZone} 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,
@code{/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.

@node java.io, java.security, java.util, Classpath Hooks
@section 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

@itemize @bullet
@item File and directory queries and manipulation
@item Serialization of objects
@end itemize

The first corresponds directly to most of the @code{File} class, while
the latter underlies the functionality provided by the
@code{ObjectInputStream} and @code{ObjectOutputStream}.  More low-level I/O
is provided by @ref{java.nio}.

@menu
* java.io.VMFile::
* java.io.VMObjectInputStream::
* java.io.VMObjectStreamClass::
@end menu

@node java.io.VMFile,java.io.VMObjectInputStream,java.io,java.io
@subsection @code{java.io.VMFile}

@code{VMFile} 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
@code{VMFile} 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
@code{static} @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.

@itemize @bullet
@item Native Methods
@itemize @bullet
@item @code{lastModified(String)} -- The native method should return a
@code{long} value that represents the last modified date of the file.
@item @code{setReadOnly(String)} -- Sets the file's permissions to read only,
in whichever way this is realised by the platform.
@item @code{create(String)} -- Create the named file.
@item @code{list(String)} -- The native method opens the named directory,
reads the contents and returns them as a Java @code{String} array.
@item @code{renameTo(String,String)} -- Renames the first file to the second.
@item @code{length(String)} -- Returns a @code{long} value representing
the file size.
@item @code{exists(String)} -- Tests for the existence of the named file
or directory.
@item @code{delete(String)} -- Deletes the file or directory.
@item @code{setLastModified(String,long)} -- Change the last modified time.
@item @code{mkdir(String)} -- Creates the named directory.
@item @code{isFile(String)} -- Tests that the named path references a file.
@item @code{canWrite(String)} -- Tests that the file can be written to.
This method is @code{synchronized}, so the object is locked during the check.
@item @code{canRead(String)} -- Complement of the last method.
@item @code{isDirectory(String)} -- Tests that the named path references
a directory.
@end itemize
@item Java Helper Methods
@itemize @bullet
@item @code{canWriteDirectory(File)} -- Checks that the directory can be
written to, by trying to create a temporary file in it.
@item @code{listRoots()} -- Returns the root of a GNU filesystem i.e. `/'
in an array.
@item @code{isHidden(String)} -- Checks whether the file starts with `.',
which is how files are hidden on UNIX-style systems.
@item @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.
@item @code{getCanonicalForm(String)} -- This converts a UNIX path to
its canonical form by removing the `.' and `..' sections that occur within.
@end itemize
@end itemize

@node java.io.VMObjectInputStream,java.io.VMObjectStreamClass,java.io.VMFile,java.io
@subsection @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}.
@code{allocateObject(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.

@node java.io.VMObjectStreamClass,,java.io.VMObjectInputStream,java.io
@subsection @code{java.io.VMObjectStreamClass}

@code{VMObjectStreamClass} 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.

@node java.security, java.net, java.io, Classpath Hooks
@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.

@menu
* java.security.VMAccessController::
@end menu

@node java.security.VMAccessController,,java.security,java.security
@subsection @code{java.security.VMAccessController}

The @code{AccessController} is used to perform privileged actions.  Its
hook class, @code{VMAccessController}, maintains the
@code{AccessControlContext} 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
@item @code{pushContext(AccessControlContext)} -- Adds a new context to the
stack for the current thread.  This is called before a privileged action
takes place.
@item @code{popContext()} -- Removes the top context from the stack.  This
is performed after the privileged action takes place.
@item @code{getContext()} -- Either derives a context based on the 
@code{ProtectionDomain}s of the call stack (see the next method) or returns
the top of the context stack.
@item @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

@node java.net, java.nio, java.security, Classpath Hooks
@section 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.

@menu
* java.net.VMInetAddress::
* java.net.VMNetworkInterface::
@end menu

@node java.net.VMInetAddress,java.net.VMNetworkInterface,java.net,java.net
@subsection @code{java.net.VMInetAddress}

@code{VMInetAddress} 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:

@itemize @bullet
@item @code{getLocalHostname()} -- Wraps the @code{gethostname} function, and
falls back on `localhost'.
@item @code{lookupInaddrAny()} -- Returns the value of @code{INADDR_ANY}.
@item @code{getHostByAddr(byte[])} -- Looks up the hostname based on an IP
address.
@item @code{getHostByName(String)} -- The reverse of the last method, it
returns the IP addresses which the given host name resolves to.
@end itemize

@node java.net.VMNetworkInterface,,java.net.VMInetAddress,java.net
@subsection @code{java.net.VMNetworkInterface}

@code{VMNetworkInterface} currently consists of a single @code{static}
@code{native} 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.

@node java.nio, java.nio.channels, java.net, Classpath Hooks
@section 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},
@emph{charsets}, @emph{channels} and @emph{selectors}, and
@code{java.nio} defines the buffer classes.  As far as native and VM
code is concerned, the new package needs support for low-level efficient
buffer operations.

@menu
* java.nio.VMDirectByteBuffer::
@end menu

@node java.nio.VMDirectByteBuffer,,java.nio,java.nio
@subsection @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},
@code{allocate} and @code{free}.  A direct buffer avoids intermediate
copying, and uses native data which shouldn't be manipulated by a