hacking.texinfo

linux下建立JAVA虚拟机的源码KAFFE

documentation for the Java platform itself.)
@item
@uref{http://java.sun.com/products/jdk/1.2/docs/guide/jvmdi/jvmdi.html,JVMDI spec - 1.2},
@uref{http://java.sun.com/products/jdk/1.2/docs/guide/jni/jni-12.html,JNI spec - 1.2}
(sometimes gives clues about unspecified things in 1.1; if
it was not specified accurately in 1.1, then use the spec
for 1.2; also, we are using JVMDI in this project.)
@item
@uref{http://java.sun.com/products/jdk/1.2/docs/api/frame.html,Sun's javadoc - 1.2}
(sometimes gives clues about unspecified things in 1.1; if
it was not specified accurately in 1.1, then use the spec
for 1.2)
@item
@uref{http://developer.java.sun.com/developer/bugParade/index.html,The
Bug Parade}: I have obtained a ton of useful information about how
things do work and how they *should* work from the Bug Parade just by
searching for related bugs.  The submitters are very careful about their
use of the spec.  And if something is unspecified, usually you can find
a request for specification or a response indicating how Sun thinks it
should be specified here.
@end enumerate

You'll notice that in this document, white papers and specification
papers are more canonical than the JavaDoc documentation.  This is true
in general.


@node Naming Conventions, Character Conversions, Specification Sources, Top
@comment node-name, next, previous, up
@chapter Directory and File Naming Conventions

The Classpath directory structure is laid out in the following manner:

@example
classpath
 |
 |---->java
 |       |
 |       |-->awt
 |       |-->io
 |       |-->lang
 |       |-->util
 |       |     |
 |       |     |--->zip
 |       |     |--->jar
 |       |-->net
 |       |-->etc
 |
 |---->gnu
 |       |
 |       |-->java
 |             |
 |             |-->awt
 |             |-->lang
 |             |-->util
 |             |     |
 |             |     |-->zip
 |             |-->etc
 |
 |---->native
         |
         |-->jni
         |    |-->classpath
         |    |-->gtk-peer
         |    |-->java-io
         |    |-->java-lang
         |    |-->java-net
         |    |-->java-util
         |    |-->etc
         |-->cni
  
@end example

Here is a brief description of the toplevel directories and their contents.

@table @b

@item java
Contains the source code to the Java packages that make up the core
class library.  Because this is the public interface to Java, it is
important that the public classes, interfaces, methods, and variables
are exactly the same as specified in Sun's documentation.  The directory
structure is laid out just like the java package names.  For example,
the class java.util.zip would be in the directory java-util.

@item gnu/java
Internal classes (roughly analogous to Sun's sun.* classes) should go
under the @file{gnu/java} directory.  Classes related to a particular public
Java package should go in a directory named like that package.  For
example, classes related to java.util.zip should go under a directory
@file{gnu/java/util/zip}.  Sub-packages under the main package name are
allowed.  For classes spanning multiple public Java packages, pick an
appropriate name and see what everybody else thinks.

@item native
This directory holds native code needed by the public Java packages.
Each package has its own subdirectory, which is the ``flattened'' name
of the package.  For example, native method implementations for
java.util.zip should go in @file{native/classpath/java-util}.  Classpath
actually includes an all Java version of the zip classes, so no native
code is required.

@end table

Each person working on a package get's his or her own ``directory
space'' underneath each of the toplevel directories.  In addition to the
general guidelines above, the following standards should be followed:

@itemize @bullet

@item
Classes that need to load native code should load a library with the
same name as the flattened package name, with all hyphens removed.  For
example, the native library name specified in LoadLibrary for
java-util would be ``javautil''.

@item
Each package has its own shared library for native code (if any).

@item
The main native method implementation for a given method in class should
go in a file with the same name as the class with a ``.c'' extension.
For example, the JNI implementation of the native methods in
java.net.InetAddress would go in @file{native/jni/java-net/InetAddress.c}.
``Internal'' native functions called from the main native method can
reside in files of any name.
@end itemize

@node Character Conversions, Localization, Naming Conventions, Top
@comment node-name, next, previous, up
@chapter Character Conversions

Java uses the Unicode character encoding system internally.  This is a
sixteen bit (two byte) collection of characters encompassing most of the
world's written languages.  However, Java programs must often deal with
outside interfaces that are byte (eight bit) oriented.  For example, a
Unix file, a stream of data from a network socket, etc.  Beginning with
Java 1.1, the @code{Reader} and @code{Writer} classes provide functionality
for dealing with character oriented streams.  The classes 
@code{InputStreamReader} and @code{OutputStreamWriter} bridge the gap
between byte streams and character streams by converting bytes to 
Unicode characters and vice versa.

In Classpath, @code{InputStreamReader} and @code{OutputStreamWriter}
rely on an internal class called @code{gnu.java.io.EncodingManager} to load
translaters that perform the actual conversion.  There are two types of
converters, encoders and decoders.  Encoders are subclasses of
@code{gnu.java.io.encoder.Encoder}.  This type of converter takes a Java
(Unicode) character stream or buffer and converts it to bytes using
a specified encoding scheme.  Decoders are a subclass of 
@code{gnu.java.io.decoder.Decoder}.  This type of converter takes a 
byte stream or buffer and converts it to Unicode characters.  The
@code{Encoder} and @code{Decoder} classes are subclasses of
@code{Writer} and @code{Reader} respectively, and so can be used in
contexts that require character streams, but the Classpath implementation
currently does not make use of them in this fashion.

The @code{EncodingManager} class searches for requested encoders and
decoders by name.  Since encoders and decoders are separate in Classpath,
it is possible to have a decoder without an encoder for a particular 
encoding scheme, or vice versa.  @code{EncodingManager} searches the
package path specified by the @code{file.encoding.pkg} property.  The
name of the encoder or decoder is appended to the search path to
produce the required class name.  Note that @code{EncodingManager} knows
about the default system encoding scheme, which it retrieves from the
system property @code{file.encoding}, and it will return the proper
translator for the default encoding if no scheme is specified.  Also, the 
Classpath standard translator library, which is the @code{gnu.java.io} package, 
is automatically appended to the end of the path.

For efficiency, @code{EncodingManager} maintains a cache of translators
that it has loaded.  This eliminates the need to search for a commonly
used translator each time it is requested.

Finally, @code{EncodingManager} supports aliasing of encoding scheme names.
For example, the ISO Latin-1 encoding scheme can be referred to as
''8859_1'' or ''ISO-8859-1''.  @code{EncodingManager} searches for 
aliases by looking for the existence of a system property called
@code{gnu.java.io.encoding_scheme_alias.<encoding name>}.  If such a
property exists.  The value of that property is assumed to be the
canonical name of the encoding scheme, and a translator with that name is 
looked up instead of one with the original name.

Here is an example of how @code{EncodingManager} works.  A class requests
a decoder for the ''UTF-8'' encoding scheme by calling
@code{EncodingManager.getDecoder("UTF-8")}.  First, an alias is searched
for by looking for the system property 
@code{gnu.java.io.encoding_scheme_alias.UTF-8}.  In our example, this
property exists and has the value ''UTF8''.  That is the actual
decoder that will be searched for.  Next, @code{EncodingManager} looks
in its cache for this translator.  Assuming it does not find it, it
searches the translator path, which is this example consists only of
the default @code{gnu.java.io}.  The ''decoder'' package name is 
appended since we are looking for a decoder.  (''encoder'' would be 
used if we were looking for an encoder).  Then name name of the translator
is appended.  So @code{EncodingManager} attempts to load a translator
class called @code{gnu.java.io.decoder.UTF8}.  If that class is found,
an instance of it is returned.  If it is not found, a
@code{UnsupportedEncodingException}.

To write a new translator, it is only necessary to subclass 
@code{Encoder} and/or @code{Decoder}.  Only a handful of abstract
methods need to be implemented.  In general, no methods need to be
overridden.  The needed methods calculate the number of bytes/chars
that the translation will generate, convert buffers to/from bytes,
and read/write a requested number of characters to/from a stream.

Many common encoding schemes use only eight bits to encode characters.
Writing a translator for these encodings is very easy.  There are 
abstract translator classes @code{gnu.java.io.decode.DecoderEightBitLookup}
and @code{gnu.java.io.encode.EncoderEightBitLookup}.  These classes
implement all of the necessary methods.  All that is necessary to
create a lookup table array that maps bytes to Unicode characters and
set the class variable @code{lookup_table} equal to it in a static
initializer.  Also, a single constructor that takes an appropriate
stream as an argument must be supplied.  These translators are
exceptionally easy to create and there are several of them supplied
in the Classpath distribution.

Writing multi-byte or variable-byte encodings is more difficult, but
often not especially challenging.  The Classpath distribution ships with
translators for the UTF8 encoding scheme which uses from one to three
bytes to encode Unicode characters.  This can serve as an example of
how to write such a translator.

Many more translators are needed.  All major character encodings should
eventually be supported.

@node Localization,  , Character Conversions, Top
@comment node-name, next, previous, up
@chapter Localization

There are many parts of the Java standard runtime library that must
be customized to the particular locale the program is being run in.
These include the parsing and display of dates, times, and numbers;
sorting words alphabetically; breaking sentences into words, etc.
In general, Classpath uses general classes for performing these tasks,
and customizes their behavior with configuration data specific to a
given locale.

@menu
* String Collation::            Sorting strings in different locales
* Break Iteration::             Breaking up text into words, sentences, and lines
* Date Formatting and Parsing::  Locale specific date handling
* Decimal/Currency Formatting and Parsing::  Local specific number handling
@end menu

In Classpath, all locale specific data is stored in a 
@code{ListResourceBundle} class in the package @code{gnu/java/locale}.
The basename of the bundle is @code{LocaleInformation}.  See the
documentation for the @code{java.util.ResourceBundle} class for details
on how the specific locale classes should be named.

@code{ListResourceBundle}'s are used instead of 
@code{PropertyResourceBundle}'s because data more complex than simple
strings need to be provided to configure certain Classpath components.
Because @code{ListResourceBundle} allows an arbitrary Java object to
be associated with a given configuration option, it provides the
needed flexibility to accomodate Classpath's needs.

Each Java library component that can be localized requires that certain
configuration options be specified in the resource bundle for it.  It is
important that each and every option be supplied for a specific 
component or a critical runtime error will most likely result.

As a standard, each option should be assigned a name that is a string.
If the value is stored in a class or instance variable, then the option
should name should have the name name as the variable.  Also, the value
associated with each option should be a Java object with the same name
as the option name (unless a simple scalar value is used).  Here is an
example:

A class loads a value for the @code{format_string} variable from the
resource bundle in the specified locale.  Here is the code in the
library class:

@example
  ListResourceBundle lrb = 
    ListResourceBundle.getBundle ("gnu/java/locale/LocaleInformation", locale);
  String format_string = lrb.getString ("format_string");
@end example

In the actual resource bundle class, here is how the configuration option
gets defined:

@example
/**
  * This is the format string used for displaying values
  */
private static final String format_string = "%s %d %i";

private static final Object[][] contents =
@{
  @{ "format_string", format_string @}
@};
@end example

Note that each variable should be @code{private}, @code{final}, and
@code{static}.  Each variable should also have a description of what it
does as a documentation comment.  The @code{getContents()} method returns
the @code{contents} array.

There are many functional areas of the standard class library that are
configured using this mechanism.  A given locale does not need to support
each functional area.  But if a functional area is supported, then all
of the specified entries for that area must be supplied.  In order to
determine which functional areas are supported, there is a special key
that is queried by the affected class or classes.  If this key exists, 
and has a value that is a @code{Boolean} object wrappering the
@code{true} value, then full support is assumed.  Otherwise it is
assumed that no support exists for this functional area.  Every class
using resources for configuration must use this scheme and define a special
scheme that indicates the functional area is supported.  Simply checking
for the resource bundle's existence is not sufficient to ensure that a
given functional area is supported.

The following sections define the functional areas that use resources
for locale specific configuration in GNU Classpath.  Please refer to the 
documentation for the classes mentioned for details on how these values 
are