+++ /dev/null
-@\input texinfo @c -*-texinfo-*-
-@setfilename gcj.info
-@settitle Guide to GNU gcj
-
-@c Note: When reading this manual you'll find lots of strange
-@c circumlocutions like ``compiler for the Java language''.
-@c This is necessary due to Sun's restrictions on the use of
-@c the word ``Java'.
-
-@c When this manual is copyrighted.
-@set copyrights-gcj 2001, 2002
-
-@c Versions
-@set version-gcc 3.2.3
-@set which-gcj GCC-@value{version-gcc}
-
-@macro gcctabopt{body}
-@code{\body\}
-@end macro
-
-@ifinfo
-@format
-@dircategory Programming
-@direntry
-* Gcj: (gcj). Ahead-of-time compiler for the Java language
-@end direntry
-
-@dircategory Individual utilities
-@direntry
-* gcjh: (gcj)Invoking gcjh.
- Generate header files from Java class files
-* jv-scan: (gcj)Invoking jv-scan.
- Print information about Java source files
-* jcf-dump: (gcj)Invoking jcf-dump.
- Print information about Java class files
-* gij: (gcj)Invoking gij. GNU interpreter for Java bytecode
-* jv-convert: (gcj)Invoking jv-convert.
- Convert file from one encoding to another
-* rmic: (gcj)Invoking rmic.
- Generate stubs for Remote Method Invocation.
-* rmiregistry: (gcj)Invoking rmiregistry.
- The remote object registry.
-@end direntry
-@end format
-
-@c man begin COPYRIGHT
-Copyright (C) @value{copyrights-gcj} Free Software Foundation, Inc.
-
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
-any later version published by the Free Software Foundation; with the
-Invariant Sections being ``GNU General Public License'', the Front-Cover
-texts being (a) (see below), and with the Back-Cover Texts being (b)
-(see below). A copy of the license is included in the
-@c man end
-section entitled
-``GNU Free Documentation License''.
-@ignore
-@c man begin COPYRIGHT
-man page gfdl(7).
-@c man end
-@end ignore
-
-(a) The FSF's Front-Cover Text is:
-
- A GNU Manual
-
-(b) The FSF's Back-Cover Text is:
-
- You have freedom to copy and modify this GNU Manual, like GNU
- software. Copies published by the Free Software Foundation raise
- funds for GNU development.
-@end ifinfo
-
-@titlepage
-@title GNU gcj
-@author Tom Tromey
-
-@page
-@vskip 0pt plus 1filll
-Copyright @copyright{} @value{copyrights-gcj} Free Software Foundation, Inc.
-@sp 2
-For the @value{which-gcj} Version*
-@sp 1
-Published by the Free Software Foundation @*
-59 Temple Place - Suite 330@*
-Boston, MA 02111-1307, USA@*
-@sp 1
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
-any later version published by the Free Software Foundation; with the
-Invariant Sections being ``GNU General Public License'', the Front-Cover
-texts being (a) (see below), and with the Back-Cover Texts being (b)
-(see below). A copy of the license is included in the section entitled
-``GNU Free Documentation License''.
-
-(a) The FSF's Front-Cover Text is:
-
- A GNU Manual
-
-(b) The FSF's Back-Cover Text is:
-
- You have freedom to copy and modify this GNU Manual, like GNU
- software. Copies published by the Free Software Foundation raise
- funds for GNU development.
-@end titlepage
-@contents
-@page
-
-
-@node Top
-@top Introduction
-
-This manual describes how to use @command{gcj}, the GNU compiler for the
-Java programming language. @command{gcj} can generate both @file{.class}
-files and object files, and it can read both Java source code and
-@file{.class} files.
-
-@menu
-* Copying:: The GNU General Public License
-* GNU Free Documentation License::
- How you can share and copy this manual
-* Invoking gcj:: Compiler options supported by @command{gcj}
-* Compatibility:: Compatibility between gcj and other tools for Java
-* Invoking gcjh:: Generate header files from class files
-* Invoking jv-scan:: Print information about source files
-* Invoking jcf-dump:: Print information about class files
-* Invoking gij:: Interpreting Java bytecodes
-* Invoking jv-convert:: Converting from one encoding to another
-* Invoking rmic:: Generate stubs for Remote Method Invocation.
-* Invoking rmiregistry:: The remote object registry.
-* About CNI:: Description of the Cygnus Native Interface
-* Resources:: Where to look for more information
-@end menu
-
-
-@include gpl.texi
-
-@include fdl.texi
-
-
-@node Invoking gcj
-@chapter Invoking gcj
-
-@c man title gcj Ahead-of-time compiler for the Java language
-
-@ignore
-@c man begin SYNOPSIS gcj
-gcj [@option{-I}@var{dir}@dots{}] [@option{-d} @var{dir}@dots{}]
- [@option{--CLASSPATH}=@var{path}] [@option{--classpath}=@var{path}]
- [@option{-f}@var{option}@dots{}] [@option{--encoding}=@var{name}]
- [@option{--main}=@var{classname}] [@option{-D}@var{name}[=@var{value}]@dots{}]
- [@option{-C}] [@option{--resource} @var{resource-name}] [@option{-d} @var{directory}]
- [@option{-W}@var{warn}@dots{}]
- @var{sourcefile}@dots{}
-@c man end
-@c man begin SEEALSO gcj
-gcc(1), gcjh(1), gij(1), jv-scan(1), jcf-dump(1), gfdl(7),
-and the Info entries for @file{gcj} and @file{gcc}.
-@c man end
-@end ignore
-
-@c man begin DESCRIPTION gcj
-
-As @command{gcj} is just another front end to @command{gcc}, it supports many
-of the same options as gcc. @xref{Option Summary, , Option Summary,
-gcc, Using the GNU Compiler Collection (GCC)}. This manual only documents the
-options specific to @command{gcj}.
-
-@c man end
-
-@menu
-* Input and output files::
-* Input Options:: How gcj finds files
-* Encodings:: Options controlling source file encoding
-* Warnings:: Options controlling warnings specific to gcj
-* Code Generation:: Options controlling the output of gcj
-* Configure-time Options:: Options you won't use
-@end menu
-
-@c man begin OPTIONS gcj
-
-@node Input and output files
-@section Input and output files
-
-A @command{gcj} command is like a @command{gcc} command, in that it
-consists of a number of options and file names. The following kinds
-of input file names are supported:
-
-@table @gcctabopt
-@item @var{file}.java
-Java source files.
-@item @var{file}.class
-Java bytecode files.
-@item @var{file}.zip
-@itemx @var{file}.jar
-An archive containing one or more @code{.class} files, all of
-which are compiled. The archive may be compressed.
-@item @@@var{file}
-A file containing a whitespace-separated list of input file names.
-(Currently, these must all be @code{.java} source files, but that
-may change.)
-Each named file is compiled, just as if it had been on the command line.
-@item @var{library}.a
-@itemx @var{library}.so
-@itemx -l@var{libname}
-Libraries to use when linking. See the @command{gcc} manual.
-@end table
-
-You can specify more than one input file on the @command{gcj} command line,
-in which case they will all be compiled. If you specify a
-@code{-o @var{FILENAME}}
-option, all the input files will be compiled together, producing a
-single output file, named @var{FILENAME}.
-This is allowed even when using @code{-S} or @code{-c},
-but not when using @code{-C} or @code{--resource}.
-(This is an extension beyond the what plain @command{gcc} allows.)
-(If more than one input file is specified, all must currently
-be @code{.java} files, though we hope to fix this.)
-
-@node Input Options
-@section Input Options
-
-@cindex class path
-
-@command{gcj} has options to control where it looks to find files it needs.
-For instance, @command{gcj} might need to load a class that is referenced
-by the file it has been asked to compile. Like other compilers for the
-Java language, @command{gcj} has a notion of a @dfn{class path}. There are
-several options and environment variables which can be used to
-manipulate the class path. When @command{gcj} looks for a given class, it
-searches the class path looking for matching @file{.class} or
-@file{.java} file. @command{gcj} comes with a built-in class path which
-points at the installed @file{libgcj.jar}, a file which contains all the
-standard classes.
-
-In the below, a directory or path component can refer either to an
-actual directory on the filesystem, or to a @file{.zip} or @file{.jar}
-file, which @command{gcj} will search as if it is a directory.
-
-@table @gcctabopt
-@item -I@var{dir}
-All directories specified by @code{-I} are kept in order and prepended
-to the class path constructed from all the other options. Unless
-compatibility with tools like @code{javac} is imported, we recommend
-always using @code{-I} instead of the other options for manipulating the
-class path.
-
-@item --classpath=@var{path}
-This sets the class path to @var{path}, a colon-separated list of paths
-(on Windows-based systems, a semicolon-separate list of paths).
-This does not override the builtin (``boot'') search path.
-
-@item --CLASSPATH=@var{path}
-Deprecated synonym for @code{--classpath}.
-
-@item --bootclasspath=@var{path}
-Where to find the standard builtin classes, such as @code{java.lang.String}.
-
-@item --extdirs=@var{path}
-For each directory in the @var{path}, place the contents of that
-directory at the end of the class path.
-
-@item CLASSPATH
-This is an environment variable which holds a list of paths.
-@end table
-
-The final class path is constructed like so:
-
-@itemize @bullet
-@item
-First come all directories specified via @code{-I}.
-
-@item
-If @option{--classpath} is specified, its value is appended.
-Otherwise, if the @code{CLASSPATH} environment variable is specified,
-then its value is appended.
-Otherwise, the current directory (@code{"."}) is appended.
-
-@item
-If @code{--bootclasspath} was specified, append its value.
-Otherwise, append the built-in system directory, @file{libgcj.jar}.
-
-@item
-Finaly, if @code{--extdirs} was specified, append the contents of the
-specified directories at the end of the class path. Otherwise, append
-the contents of the built-in extdirs at @code{$(prefix)/share/java/ext}.
-@end itemize
-
-The classfile built by @command{gcj} for the class @code{java.lang.Object}
-(and placed in @code{libgcj.jar}) contains a special zero length
-attribute @code{gnu.gcj.gcj-compiled}. The compiler looks for this
-attribute when loading @code{java.lang.Object} and will report an error
-if it isn't found, unless it compiles to bytecode (the option
-@code{-fforce-classes-archive-check} can be used to override this
-behavior in this particular case.)
-
-@table @gcctabopt
-@item -fforce-classes-archive-check
-This forces the compiler to always check for the special zero length
-attribute @code{gnu.gcj.gcj-compiled} in @code{java.lang.Object} and
-issue an error if it isn't found.
-@end table
-
-@node Encodings
-@section Encodings
-
-The Java programming language uses Unicode throughout. In an effort to
-integrate well with other locales, @command{gcj} allows @file{.java} files
-to be written using almost any encoding. @command{gcj} knows how to
-convert these encodings into its internal encoding at compile time.
-
-You can use the @code{--encoding=@var{NAME}} option to specify an
-encoding (of a particular character set) to use for source files. If
-this is not specified, the default encoding comes from your current
-locale. If your host system has insufficient locale support, then
-@command{gcj} assumes the default encoding to be the @samp{UTF-8} encoding
-of Unicode.
-
-To implement @code{--encoding}, @command{gcj} simply uses the host
-platform's @code{iconv} conversion routine. This means that in practice
-@command{gcj} is limited by the capabilities of the host platform.
-
-The names allowed for the argument @code{--encoding} vary from platform
-to platform (since they are not standardized anywhere). However,
-@command{gcj} implements the encoding named @samp{UTF-8} internally, so if
-you choose to use this for your source files you can be assured that it
-will work on every host.
-
-
-@node Warnings
-@section Warnings
-
-@command{gcj} implements several warnings. As with other generic
-@command{gcc} warnings, if an option of the form @code{-Wfoo} enables a
-warning, then @code{-Wno-foo} will disable it. Here we've chosen to
-document the form of the warning which will have an effect -- the
-default being the opposite of what is listed.
-
-@table @gcctabopt
-@item -Wredundant-modifiers
-With this flag, @command{gcj} will warn about redundant modifiers. For
-instance, it will warn if an interface method is declared @code{public}.
-
-@item -Wextraneous-semicolon
-This causes @command{gcj} to warn about empty statements. Empty statements
-have been deprecated.
-
-@item -Wno-out-of-date
-This option will cause @command{gcj} not to warn when a source file is
-newer than its matching class file. By default @command{gcj} will warn
-about this.
-
-@item -Wunused
-This is the same as @command{gcc}'s @code{-Wunused}.
-
-@item -Wall
-This is the same as @code{-Wredundant-modifiers -Wextraneous-semicolon
--Wunused}.
-@end table
-
-
-@node Code Generation
-@section Code Generation
-
-In addition to the many @command{gcc} options controlling code generation,
-@command{gcj} has several options specific to itself.
-
-@table @gcctabopt
-@item --main=@var{CLASSNAME}
-This option is used when linking to specify the name of the class whose
-@code{main} method should be invoked when the resulting executable is
-run. @footnote{The linker by default looks for a global function named
-@code{main}. Since Java does not have global functions, and a
-collection of Java classes may have more than one class with a
-@code{main} method, you need to let the linker know which of those
-@code{main} methods it should invoke when starting the application.}
-
-@item -D@var{name}[=@var{value}]
-This option can only be used with @code{--main}. It defines a system
-property named @var{name} with value @var{value}. If @var{value} is not
-specified then it defaults to the empty string. These system properties
-are initialized at the program's startup and can be retrieved at runtime
-using the @code{java.lang.System.getProperty} method.
-
-@item -C
-This option is used to tell @command{gcj} to generate bytecode
-(@file{.class} files) rather than object code.
-
-@item --resource @var{resource-name}
-This option is used to tell @command{gcj} to compile the contents of a
-given file to object code so it may be accessed at runtime with the core
-protocol handler as @samp{core:/@var{resource-name}}. Note that
-@var{resource-name} is the name of the resource as found at runtime; for
-instance, it could be used in a call to @code{ResourceBundle.getBundle}.
-The actual file name to be compiled this way must be specified
-separately.
-
-@item -d @var{directory}
-When used with @code{-C}, this causes all generated @file{.class} files
-to be put in the appropriate subdirectory of @var{directory}. By
-default they will be put in subdirectories of the current working
-directory.
-
-@item -fno-bounds-check
-By default, @command{gcj} generates code which checks the bounds of all
-array indexing operations. With this option, these checks are omitted, which
-can improve performance for code that uses arrays extensively. Note that this
-can result in unpredictable behavior if the code in question actually does
-violate array bounds constraints. It is safe to use this option if you are
-sure that your code will never throw an @code{ArrayIndexOutOfBoundsException}.
-
-@item -fno-store-check
-Don't generate array store checks. When storing objects into arrays, a runtime
-check is normally generated in order to ensure that the object is assignment
-compatible with the component type of the array (which may not be known
-at compile-time). With this option, these checks are omitted. This can
-improve performance for code which stores objects into arrays frequently.
-It is safe to use this option if you are sure your code will never throw an
-@code{ArrayStoreException}.
-
-@item -fjni
-With @command{gcj} there are two options for writing native methods: CNI
-and JNI@. By default @command{gcj} assumes you are using CNI@. If you are
-compiling a class with native methods, and these methods are implemented
-using JNI, then you must use @code{-fjni}. This option causes
-@command{gcj} to generate stubs which will invoke the underlying JNI
-methods.
-
-@item -fno-optimize-static-class-initialization
-When the optimization level is greather or equal to @code{-O2},
-@command{gcj} will try to optimize the way calls into the runtime are made
-to initialize static classes upon their first use (this optimization
-isn't carried out if @code{-C} was specified.) When compiling to native
-code, @code{-fno-optimize-static-class-initialization} will turn this
-optimization off, regardless of the optimization level in use.
-@end table
-
-
-@node Configure-time Options
-@section Configure-time Options
-
-Some @command{gcj} code generations options affect the resulting ABI, and
-so can only be meaningfully given when @code{libgcj}, the runtime
-package, is configured. @code{libgcj} puts the appropriate options from
-this group into a @samp{spec} file which is read by @command{gcj}. These
-options are listed here for completeness; if you are using @code{libgcj}
-then you won't want to touch these options.
-
-@table @gcctabopt
-@item -fuse-boehm-gc
-This enables the use of the Boehm GC bitmap marking code. In particular
-this causes @command{gcj} to put an object marking descriptor into each
-vtable.
-
-@item -fhash-synchronization
-By default, synchronization data (the data used for @code{synchronize},
-@code{wait}, and @code{notify}) is pointed to by a word in each object.
-With this option @command{gcj} assumes that this information is stored in a
-hash table and not in the object itself.
-
-@item -fuse-divide-subroutine
-On some systems, a library routine is called to perform integer
-division. This is required to get exception handling correct when
-dividing by zero.
-
-@item -fcheck-references
-On some systems it's necessary to insert inline checks whenever
-accessing an object via a reference. On other systems you won't need
-this because null pointer accesses are caught automatically by the
-processor.
-@end table
-
-@c man end
-
-@node Compatibility
-@chapter Compatibility with the Java Platform
-
-As we believe it is important that the Java platform not be fragmented,
-@command{gcj} and @code{libgcj} try to conform to the relevant Java
-specifications. However, limited manpower and incomplete and unclear
-documentation work against us. So, there are caveats to using
-@command{gcj}.
-
-This list of compatibility issues is by no means complete.
-
-@itemize @bullet
-@item
-@command{gcj} implements the JDK 1.1 language. It supports inner classes,
-though these are known to still be buggy. It does not yet support the
-Java 2 @code{strictfp} keyword (it recognizes the keyword but ignores
-it).
-
-@item
-@code{libgcj} is largely compatible with the JDK 1.2 libraries.
-However, @code{libgcj} is missing many packages, most notably
-@code{java.awt}. There are also individual missing classes and methods.
-We currently do not have a list showing differences between
-@code{libgcj} and the Java 2 platform.
-
-@item
-Sometimes the @code{libgcj} implementation of a method or class differs
-from the JDK implementation. This is not always a bug. Still, if it
-affects you, it probably makes sense to report it so that we can discuss
-the appropriate response.
-@end itemize
-
-
-@node Invoking gcjh
-@chapter Invoking gcjh
-
-@c man title gcjh generate header files from Java class files
-
-@c man begin DESCRIPTION gcjh
-
-The @code{gcjh} program is used to generate header files from class
-files. It can generate both CNI and JNI header files, as well as stub
-implementation files which can be used as a basis for implementing the
-required native methods.
-
-@c man end
-
-@ignore
-@c man begin SYNOPSIS gcjh
-gcjh [@option{-stubs}] [@option{-jni}]
- [@option{-add} @var{text}] [@option{-append} @var{text}] [@option{-friend} @var{text}]
- [@option{-preprend} @var{text}]
- [@option{--classpath}=@var{path}] [@option{--CLASSPATH}=@var{path}]
- [@option{-I}@var{dir}@dots{}] [@option{-d} @var{dir}@dots{}]
- [@option{-o} @var{file}] [@option{-td} @var{dir}]
- [@option{-M}] [@option{-MM}] [@option{-MD}] [@option{-MMD}]
- [@option{--version}] [@option{--help}] [@option{-v}] [@option{--verbose}]
- @var{classname}@dots{}
-@c man end
-@c man begin SEEALSO gcjh
-gcc(1), gcj(1), gij(1), jv-scan(1), jcf-dump(1), gfdl(7),
-and the Info entries for @file{gcj} and @file{gcc}.
-@c man end
-@end ignore
-
-@c man begin OPTIONS gcjh
-
-@table @gcctabopt
-@item -stubs
-This causes @code{gcjh} to generate stub files instead of header files.
-By default the stub file will be named after the class, with a suffix of
-@samp{.cc}. In JNI mode, the default output file will have the suffix
-@samp{.c}.
-
-@item -jni
-This tells @code{gcjh} to generate a JNI header or stub. By default,
-CNI headers are generated.
-
-@item -add @var{text}
-Inserts @var{text} into the class body. This is ignored in JNI mode.
-
-@item -append @var{text}
-Inserts @var{text} into the header file after the class declaration.
-This is ignored in JNI mode.
-
-@item -friend @var{text}
-Inserts @var{text} into the class as a @code{friend} declaration.
-This is ignored in JNI mode.
-
-@item -prepend @var{text}
-Inserts @var{text} into the header file before the class declaration.
-This is ignored in JNI mode.
-
-@item --classpath=@var{path}
-@itemx --CLASSPATH=@var{path}
-@itemx -I@var{directory}
-@itemx -d @var{directory}
-@itemx -o @var{file}
-These options are all identical to the corresponding @command{gcj} options.
-
-@item -o @var{file}
-Sets the output file name. This cannot be used if there is more than
-one class on the command line.
-
-@item -td @var{directory}
-Sets the name of the directory to use for temporary files.
-
-@item -M
-Print all dependencies to stdout; suppress ordinary output.
-
-@item -MM
-Print non-system dependencies to stdout; suppress ordinary output.
-
-@item -MD
-Print all dependencies to stdout.
-
-@item -MMD
-Print non-system dependencies to stdout.
-
-@item --help
-Print help about @code{gcjh} and exit. No further processing is done.
-
-@item --version
-Print version information for @code{gcjh} and exit. No further
-processing is done.
-
-@item -v, --verbose
-Print extra information while running.
-@end table
-
-All remaining options are considered to be names of classes.
-
-@c man end
-
-@node Invoking jv-scan
-@chapter Invoking jv-scan
-
-@c man title jv-scan print information about Java source file
-
-@c man begin DESCRIPTION jv-scan
-
-The @code{jv-scan} program can be used to print information about a Java
-source file (@file{.java} file).
-
-@c man end
-
-@ignore
-@c man begin SYNOPSIS jv-scan
-jv-scan [@option{--complexity}] [@option{--encoding}=@var{name}]
- [@option{--print-main}] [@option{--list-class}] [@option{--list-filename}]
- [@option{--version}] [@option{--help}]
- [@option{-o} @var{file}] @var{inputfile}@dots{}
-@c man end
-@c man begin SEEALSO jv-scan
-gcc(1), gcj(1), gcjh(1), gij(1), jcf-dump(1), gfdl(7),
-and the Info entries for @file{gcj} and @file{gcc}.
-@c man end
-@end ignore
-
-@c man begin OPTIONS jv-scan
-
-@table @gcctabopt
-@item --complexity
-This prints a complexity measure, related to cyclomatic complexity, for
-each input file.
-
-@item --encoding=@var{name}
-This works like the corresponding @command{gcj} option.
-
-@item --print-main
-This prints the name of the class in this file containing a @code{main}
-method.
-
-@item --list-class
-This lists the names of all classes defined in the input files.
-
-@item --list-filename
-If @code{--list-class} is given, this option causes @code{jv-scan} to
-also print the name of the file in which each class was found.
-
-@item -o @var{file}
-Print output to the named file.
-
-@item --help
-Print help, then exit.
-
-@item --version
-Print version number, then exit.
-@end table
-
-@c man end
-
-@node Invoking jcf-dump
-@chapter Invoking jcf-dump
-
-@c man title jcf-dump print information about Java class files
-
-@ignore
-@c man begin SYNOPSIS jcf-dump
-jcf-dump [@option{-c}] [@option{--javap}]
- [@option{--classpath}=@var{path}] [@option{--CLASSPATH}=@var{path}]
- [@option{-I}@var{dir}@dots{}] [@option{-o} @var{file}]
- [@option{--version}] [@option{--help}] [@option{-v}] [@option{--verbose}]
- @var{classname}@dots{}
-@c man end
-@c man begin SEEALSO jcf-dump
-gcc(1), gcj(1), gcjh(1), gij(1), jcf-dump(1), gfdl(7),
-and the Info entries for @file{gcj} and @file{gcc}.
-@c man end
-@end ignore
-
-@c man begin DESCRIPTION jcf-dump
-
-This is a class file examiner, similar to @code{javap}. It will print
-information about a number of classes, which are specifed by class name
-or file name.
-
-@c man end
-
-@c man begin OPTIONS jcf-dump
-
-@table @gcctabopt
-@item -c
-Disassemble method bodies. By default method bodies are not printed.
-
-@item --javap
-Generate output in @code{javap} format. The implementation of this
-feature is very incomplete.
-
-@item --classpath=@var{path}
-@itemx --CLASSPATH=@var{path}
-@itemx -I@var{directory}
-@itemx -o @var{file}
-These options as the same as the corresponding @command{gcj} options.
-
-@item --help
-Print help, then exit.
-
-@item --version
-Print version number, then exit.
-
-@item -v, --verbose
-Print extra information while running.
-@end table
-
-@c man end
-
-@node Invoking gij
-@chapter Invoking gij
-
-@c man title gij GNU interpreter for Java bytecode
-
-@ignore
-@c man begin SYNOPSIS gij
-gij [@option{OPTION}] @dots{} @var{JARFILE} [@var{ARGS}@dots{}]
-
-gij [@option{-jar}] [@option{OPTION}] @dots{} @var{CLASS} [@var{ARGS}@dots{}]
- [@option{-D}@var{name}[=@var{value}]@dots{}]
- [@option{-ms=}@var{number}] [@option{-mx=}@var{number}]
- [@option{--version}] [@option{--help}]
-@c man end
-@c man begin SEEALSO gij
-gcc(1), gcj(1), gcjh(1), jv-scan(1), jcf-dump(1), gfdl(7),
-and the Info entries for @file{gcj} and @file{gcc}.
-@c man end
-@end ignore
-
-@c man begin DESCRIPTION gij
-
-@code{gij} is a Java bytecode interpreter included with @code{libgcj}.
-@code{gij} is not available on every platform; porting it requires a
-small amount of assembly programming which has not been done for all the
-targets supported by @command{gcj}.
-
-The primary argument to @code{gij} is the name of a class or, with
-@code{-jar}, a jar file. Options before this argument are interpreted
-by @code{gij}; remaining options are passed to the interpreted program.
-
-If a class name is specified and this class does not have a @code{main}
-method with the appropriate signature (a @code{static void} method with
-a @code{String[]} as its sole argument), then @code{gij} will print an
-error and exit.
-
-If a jar file is specified then @code{gij} will use information in it to
-determine which class' @code{main} method will be invoked.
-
-@code{gij} will invoke the @code{main} method with all the remaining
-command-line options.
-
-Note that @code{gij} is not limited to interpreting code. Because
-@code{libgcj} includes a class loader which can dynamically load shared
-objects, it is possible to give @code{gij} the name of a class which has
-been compiled and put into a shared library on the class path.
-
-@c man end
-
-@c man begin OPTIONS gij
-
-@table @gcctabopt
-@item -D@var{name}[=@var{value}]
-This defines a system property named @var{name} with value @var{value}.
-If @var{value} is not specified then it defaults to the empty string.
-These system properties are initialized at the program's startup and can
-be retrieved at runtime using the @code{java.lang.System.getProperty}
-method.
-
-@item -ms=@var{number}
-This sets the initial heap size.
-
-@item -mx=@var{number}
-This sets the maximum heap size.
-
-@item -jar
-This indicates that the name passed to @code{gij} should be interpreted
-as the name of a jar file, not a class.
-
-@item --help
-Print help, then exit.
-
-@item --version
-Print version number, then exit.
-@end table
-
-@c man end
-
-@node Invoking jv-convert
-@chapter Invoking jv-convert
-
-@c man title jv-convert Convert file from one encoding to another
-
-@c man begin SYNOPSIS jv-convert
-@command{jv-convert} [@option{OPTION}] @dots{} [@var{INPUTFILE} [@var{OUTPUTFILE}]]
-@ignore
-
- [@option{--encoding} @var{name}]
- [@option{--from} @var{name}]
- [@option{--to} @var{name}]
- [@option{-i} @var{file}] [@option{-o} @var{file}]
- [@option{--reverse}] [@option{--help}] [@option{--version}]
-@end ignore
-@c man end
-
-@c man begin DESCRIPTION jv-convert
-
-@command{jv-convert} is a utility included with @code{libgcj} which
-converts a file from one encoding to another. It is similar to the Unix
-@command{iconv} utility.
-
-The encodings supported by @command{jv-convert} are platform-dependent.
-Currently there is no way to get a list of all supported encodings.
-
-@c man end
-
-@c man begin OPTIONS jv-convert
-
-@table @gcctabopt
-@item --encoding @var{name}
-@itemx --from @var{name}
-Use @var{name} as the input encoding. The default is the current
-locale's encoding.
-
-@item --to @var{name}
-Use @var{name} as the output encoding. The default is the
-@code{JavaSrc} encoding; this is ASCII with @samp{\u} escapes for
-non-ASCII characters.
-
-@item -i @var{file}
-Read from @var{file}. The default is to read from standard input.
-
-@item -o @var{file}
-Write to @var{file}. The default is to write to standard output.
-
-@item --reverse
-Swap the input and output encodings.
-
-@item --help
-Print a help message, then exit.
-
-@item --version
-Print version information, then exit.
-@end table
-
-@c man end
-
-@node Invoking rmic
-@chapter Invoking rmic
-
-@c man title rmic Generate stubs for Remote Method Invocation
-
-@c man begin SYNOPSIS rmic
-@command{rmic} [@option{OPTION}] @dots{} @var{class} @dots{}
-@ignore
- [@option{-keep}]
- [@option{-keepgenerated}]
- [@option{-v1.1}]
- [@option{-vcompat}]
- [@option{-v1.2}]
- [@option{-nocompile}]
- [@option{-verbose}]
- [@option{-d} @var{directory}]
- [@option{-help}]
- [@option{-version}]
-@end ignore
-@c man end
-
-@c man begin DESCRIPTION rmic
-
-@command{rmic} is a utility included with @code{libgcj} which generates
-stubs for remote objects.
-
-@c FIXME: Add real information here.
-@c This really isn't much more than the --help output.
-
-Note that this program isn't yet fully compatible with the JDK
-@command{rmic}. Some options, such as @option{-classpath}, are
-recognized but currently ignored. We have left these options
-undocumented for now.
-
-Long options can also be given with a GNU-style leading @samp{--}. For
-instance, @option{--help} is accepted.
-
-@c man end
-
-@c man begin OPTIONS rmic
-
-@table @gcctabopt
-@item -keep
-@itemx -keepgenerated
-By default, @command{rmic} deletes intermediate files. Either of these
-options causes it not to delete such files.
-
-@item -v1.1
-Cause @command{rmic} to create stubs and skeletons for the 1.1
-protocol version.
-
-@item -vcompat
-Cause @command{rmic} to create stubs and skeletons compatible with both
-the 1.1 and 1.2 protocol versions. This is the default.
-
-@item -v1.2
-Cause @command{rmic} to create stubs and skeletons for the 1.2
-protocol version.
-
-@item -nocompile
-Don't compile the generated files.
-
-@item -verbose
-Print information about what @command{rmic} is doing.
-
-@item -d @var{directory}
-Put output files in @var{directory}. By default the files are put in
-the current working directory.
-
-@item -help
-Print a help message, then exit.
-
-@item -version
-Print version information, then exit.
-@end table
-
-@c man end
-
-
-@node Invoking rmiregistry
-@chapter Invoking rmiregistry
-
-@c man title rmiregistry Remote object registry
-
-@c man begin SYNOPSIS rmiregistry
-@command{rmiregistry} [@option{OPTION}] @dots{} [@var{port}]
-@ignore
- [@option{--help}]
- [@option{--version}]
-@end ignore
-@c man end
-
-@c man begin DESCRIPTION rmiregistry
-
-@command{rmiregistry} starts a remote object registry on the current
-host. If no port number is specified, then port 1099 is used.
-
-@c FIXME: Add real information here.
-@c This really isn't much more than the --help output.
-
-@c man end
-
-@c man begin OPTIONS rmiregistry
-
-@table @gcctabopt
-@item --help
-Print a help message, then exit.
-
-@item --version
-Print version information, then exit.
-@end table
-
-@c man end
-
-
-@node About CNI
-@chapter About CNI
-
-This documents CNI, the Cygnus Native Interface,
-which is is a convenient way to write Java native methods using C++.
-This is a more efficient, more convenient, but less portable
-alternative to the standard JNI (Java Native Interface).
-
-@menu
-* Basic concepts:: Introduction to using CNI@.
-* Packages:: How packages are mapped to C++.
-* Primitive types:: Handling Java types in C++.
-* Interfaces:: How Java interfaces map to C++.
-* Objects and Classes:: C++ and Java classes.
-* Class Initialization:: How objects are initialized.
-* Object allocation:: How to create Java objects in C++.
-* Arrays:: Dealing with Java arrays in C++.
-* Methods:: Java methods in C++.
-* Strings:: Information about Java Strings.
-* Mixing with C++:: How CNI can interoperate with C++.
-* Exception Handling:: How exceptions are handled.
-* Synchronization:: Synchronizing between Java and C++.
-* Invocation:: Starting the Java runtime from C++.
-* Reflection:: Using reflection from C++.
-@end menu
-
-
-@node Basic concepts
-@section Basic concepts
-
-In terms of languages features, Java is mostly a subset
-of C++. Java has a few important extensions, plus a powerful standard
-class library, but on the whole that does not change the basic similarity.
-Java is a hybrid object-oriented language, with a few native types,
-in addition to class types. It is class-based, where a class may have
-static as well as per-object fields, and static as well as instance methods.
-Non-static methods may be virtual, and may be overloaded. Overloading is
-resolved at compile time by matching the actual argument types against
-the parameter types. Virtual methods are implemented using indirect calls
-through a dispatch table (virtual function table). Objects are
-allocated on the heap, and initialized using a constructor method.
-Classes are organized in a package hierarchy.
-
-All of the listed attributes are also true of C++, though C++ has
-extra features (for example in C++ objects may be allocated not just
-on the heap, but also statically or in a local stack frame). Because
-@command{gcj} uses the same compiler technology as G++ (the GNU
-C++ compiler), it is possible to make the intersection of the two
-languages use the same ABI (object representation and calling
-conventions). The key idea in CNI is that Java objects are C++
-objects, and all Java classes are C++ classes (but not the other way
-around). So the most important task in integrating Java and C++ is to
-remove gratuitous incompatibilities.
-
-You write CNI code as a regular C++ source file. (You do have to use
-a Java/CNI-aware C++ compiler, specifically a recent version of G++.)
-
-@noindent A CNI C++ source file must have:
-
-@example
-#include <gcj/cni.h>
-@end example
-
-@noindent and then must include one header file for each Java class it uses, e.g.:
-
-@example
-#include <java/lang/Character.h>
-#include <java/util/Date.h>
-#include <java/lang/IndexOutOfBoundsException.h>
-@end example
-
-@noindent These header files are automatically generated by @code{gcjh}.
-
-
-CNI provides some functions and macros to make using Java objects and
-primitive types from C++ easier. In general, these CNI functions and
-macros start with the @code{Jv} prefix, for example the function
-@code{JvNewObjectArray}. This convention is used to avoid conflicts
-with other libraries. Internal functions in CNI start with the prefix
-@code{_Jv_}. You should not call these; if you find a need to, let us
-know and we will try to come up with an alternate solution. (This
-manual lists @code{_Jv_AllocBytes} as an example; CNI should instead
-provide a @code{JvAllocBytes} function.)
-
-
-@subsection Limitations
-
-Whilst a Java class is just a C++ class that doesn't mean that you are
-freed from the shackles of Java, a @acronym{CNI} C++ class must adhere to the
-rules of the Java programming language.
-
-For example: it is not possible to declare a method in a CNI class
-that will take a C string (@code{char*}) as an argument, or to declare a
-member variable of some non-Java datatype.
-
-
-@node Packages
-@section Packages
-
-The only global names in Java are class names, and packages. A
-@dfn{package} can contain zero or more classes, and also zero or more
-sub-packages. Every class belongs to either an unnamed package or a
-package that has a hierarchical and globally unique name.
-
-A Java package is mapped to a C++ @dfn{namespace}. The Java class
-@code{java.lang.String} is in the package @code{java.lang}, which is a
-sub-package of @code{java}. The C++ equivalent is the class
-@code{java::lang::String}, which is in the namespace @code{java::lang}
-which is in the namespace @code{java}.
-
-@noindent Here is how you could express this:
-
-@example
-(// @r{Declare the class(es), possibly in a header file:}
-namespace java @{
- namespace lang @{
- class Object;
- class String;
- ...
- @}
-@}
-
-class java::lang::String : public java::lang::Object
-@{
- ...
-@};
-@end example
-
-@noindent The @code{gcjh} tool automatically generates the nessary namespace
-declarations.
-
-
-@subsection Leaving out package names
-
-Always using the fully-qualified name of a java class can be
-tiresomely verbose. Using the full qualified name also ties the code
-to a single package making code changes necessary should the class
-move from one package to another. The Java @code{package} declaration
-specifies that the following class declarations are in the named
-package, without having to explicitly name the full package
-qualifiers. The @code{package} declaration can be
-followed by zero or more @code{import} declarations, which
-allows either a single class or all the classes in a package to be
-named by a simple identifier. C++ provides something similar with the
-@code{using} declaration and directive.
-
-@noindent In Java:
-
-@example
-import @var{package-name}.@var{class-name};
-@end example
-
-@noindent allows the program text to refer to @var{class-name} as a shorthand for
-the fully qualified name: @code{@var{package-name}.@var{class-name}}.
-
-
-@noindent To achieve the same effect C++, you have to do this:
-
-@example
-using @var{package-name}::@var{class-name};
-@end example
-
-
-@noindent Java can also cause imports on demand, like this:
-
-@example
-import @var{package-name}.*;
-@end example
-
-@noindent Doing this allows any class from the package @var{package-name} to be
-refered to only by its class-name within the program text.
-
-
-@noindent The same effect can be achieved in C++ like this:
-
-@example
-using namespace @var{package-name};
-@end example
-
-
-@node Primitive types
-@section Primitive types
-
-Java provides 8 @dfn{primitives} types which represent integers, floats,
-characters and booleans (and also the void type). C++ has its own
-very similar concrete types. Such types in C++ however are not always
-implemented in the same way (an int might be 16, 32 or 64 bits for example)
-so CNI provides a special C++ type for each primitive Java type:
-
-@multitable @columnfractions .20 .25 .60
-@item @strong{Java type} @tab @strong{C/C++ typename} @tab @strong{Description}
-@item @code{char} @tab @code{jchar} @tab 16 bit Unicode character
-@item @code{boolean} @tab @code{jboolean} @tab logical (true or false) values
-@item @code{byte} @tab @code{jbyte} @tab 8-bit signed integer
-@item @code{short} @tab @code{jshort} @tab 16 bit signed integer
-@item @code{int} @tab @code{jint} @tab 32 bit signed integer
-@item @code{long} @tab @code{jlong} @tab 64 bit signed integer
-@item @code{float} @tab @code{jfloat} @tab 32 bit IEEE floating point number
-@item @code{double} @tab @code{jdouble} @tab 64 bit IEEE floating point number
-@item @code{void} @tab @code{void} @tab no value
-@end multitable
-
-When refering to a Java type You should always use these C++ typenames (e.g.: @code{jint})
-to avoid disappointment.
-
-
-@subsection Reference types associated with primitive types
-
-In Java each primitive type has an associated reference type,
-e.g.: @code{boolean} has an associated @code{java.lang.Boolean} class.
-In order to make working with such classes easier GCJ provides the macro
-@code{JvPrimClass}:
-
-@deffn macro JvPrimClass type
-Return a pointer to the @code{Class} object corresponding to the type supplied.
-
-@example
-JvPrimClass(void) @result{} java.lang.Void.TYPE
-@end example
-
-@end deffn
-
-
-@node Interfaces
-@section Interfaces
-
-A Java class can @dfn{implement} zero or more
-@dfn{interfaces}, in addition to inheriting from
-a single base class.
-
-@acronym{CNI} allows CNI code to implement methods of interfaces.
-You can also call methods through interface references, with some
-limitations.
-
-@acronym{CNI} doesn't understand interface inheritance at all yet. So,
-you can only call an interface method when the declared type of the
-field being called matches the interface which declares that
-method. The workaround is to cast the interface reference to the right
-superinterface.
-
-For example if you have:
-
-@example
-interface A
-@{
- void a();
-@}
-
-interface B extends A
-@{
- void b();
-@}
-@end example
-
-and declare a variable of type @code{B} in C++, you can't call
-@code{a()} unless you cast it to an @code{A} first.
-
-@node Objects and Classes
-@section Objects and Classes
-
-@subsection Classes
-
-All Java classes are derived from @code{java.lang.Object}. C++ does
-not have a unique root class, but we use the C++ class
-@code{java::lang::Object} as the C++ version of the
-@code{java.lang.Object} Java class. All other Java classes are mapped
-into corresponding C++ classes derived from @code{java::lang::Object}.
-
-Interface inheritance (the @code{implements} keyword) is currently not
-reflected in the C++ mapping.
-
-
-@subsection Object fields
-
-Each object contains an object header, followed by the instance fields
-of the class, in order. The object header consists of a single
-pointer to a dispatch or virtual function table. (There may be extra
-fields @emph{in front of} the object, for example for memory
-management, but this is invisible to the application, and the
-reference to the object points to the dispatch table pointer.)
-
-The fields are laid out in the same order, alignment, and size as in
-C++. Specifically, 8-bite and 16-bit native types (@code{byte},
-@code{short}, @code{char}, and @code{boolean}) are @emph{not} widened
-to 32 bits. Note that the Java VM does extend 8-bit and 16-bit types
-to 32 bits when on the VM stack or temporary registers.
-
-If you include the @code{gcjh}-generated header for a
-class, you can access fields of Java classes in the @emph{natural}
-way. For example, given the following Java class:
-
-@example
-public class Int
-@{
- public int i;
- public Integer (int i) @{ this.i = i; @}
- public static zero = new Integer(0);
-@}
-@end example
-
-you can write:
-
-@example
-#include <gcj/cni.h>;
-#include <Int>;
-
-Int*
-mult (Int *p, jint k)
-@{
- if (k == 0)
- return Int::zero; // @r{Static member access.}
- return new Int(p->i * k);
-@}
-@end example
-
-
-@subsection Access specifiers
-
-CNI does not strictly enforce the Java access
-specifiers, because Java permissions cannot be directly mapped
-into C++ permission. Private Java fields and methods are mapped
-to private C++ fields and methods, but other fields and methods
-are mapped to public fields and methods.
-
-
-
-@node Class Initialization
-@section Class Initialization
-
-Java requires that each class be automatically initialized at the time
-of the first active use. Initializing a class involves
-initializing the static fields, running code in class initializer
-methods, and initializing base classes. There may also be
-some implementation specific actions, such as allocating
-@code{String} objects corresponding to string literals in
-the code.
-
-The GCJ compiler inserts calls to @code{JvInitClass} at appropriate
-places to ensure that a class is initialized when required. The C++
-compiler does not insert these calls automatically---it is the
-programmer's responsibility to make sure classes are initialized.
-However, this is fairly painless because of the conventions assumed by
-the Java system.
-
-First, @code{libgcj} will make sure a class is initialized
-before an instance of that object is created. This is one
-of the responsibilities of the @code{new} operation. This is
-taken care of both in Java code, and in C++ code. (When the G++
-compiler sees a @code{new} of a Java class, it will call
-a routine in @code{libgcj} to allocate the object, and that
-routine will take care of initializing the class.) It follows that you can
-access an instance field, or call an instance (non-static)
-method and be safe in the knowledge that the class and all
-of its base classes have been initialized.
-
-Invoking a static method is also safe. This is because the
-Java compiler adds code to the start of a static method to make sure
-the class is initialized. However, the C++ compiler does not
-add this extra code. Hence, if you write a native static method
-using CNI, you are responsible for calling @code{JvInitClass}
-before doing anything else in the method (unless you are sure
-it is safe to leave it out).
-
-Accessing a static field also requires the class of the
-field to be initialized. The Java compiler will generate code
-to call @code{Jv_InitClass} before getting or setting the field.
-However, the C++ compiler will not generate this extra code,
-so it is your responsibility to make sure the class is
-initialized before you access a static field from C++.
-
-
-@node Object allocation
-@section Object allocation
-
-New Java objects are allocated using a
-@dfn{class instance creation expression}, e.g.:
-
-@example
-new @var{Type} ( ... )
-@end example
-
-The same syntax is used in C++. The main difference is that
-C++ objects have to be explicitly deleted; in Java they are
-automatically deleted by the garbage collector.
-Using @acronym{CNI}, you can allocate a new Java object
-using standard C++ syntax and the C++ compiler will allocate
-memory from the garbage collector. If you have overloaded
-constructors, the compiler will choose the correct one
-using standard C++ overload resolution rules.
-
-@noindent For example:
-
-@example
-java::util::Hashtable *ht = new java::util::Hashtable(120);
-@end example
-
-@deftypefun void* _Jv_AllocBytes (jsize @var{size})
-Allocates @var{size} bytes from the heap. The memory is not scanned
-by the garbage collector but it freed if no references to it are discovered.
-@end deftypefun
-
-
-@node Arrays
-@section Arrays
-
-While in many ways Java is similar to C and C++, it is quite different
-in its treatment of arrays. C arrays are based on the idea of pointer
-arithmetic, which would be incompatible with Java's security
-requirements. Java arrays are true objects (array types inherit from
-@code{java.lang.Object}). An array-valued variable is one that
-contains a reference (pointer) to an array object.
-
-Referencing a Java array in C++ code is done using the
-@code{JArray} template, which as defined as follows:
-
-@example
-class __JArray : public java::lang::Object
-@{
-public:
- int length;
-@};
-
-template<class T>
-class JArray : public __JArray
-@{
- T data[0];
-public:
- T& operator[](jint i) @{ return data[i]; @}
-@};
-@end example
-
-
-There are a number of @code{typedef}s which correspond to @code{typedef}s
-from the @acronym{JNI}. Each is the type of an array holding objects
-of the relevant type:
-
-@example
-typedef __JArray *jarray;
-typedef JArray<jobject> *jobjectArray;
-typedef JArray<jboolean> *jbooleanArray;
-typedef JArray<jbyte> *jbyteArray;
-typedef JArray<jchar> *jcharArray;
-typedef JArray<jshort> *jshortArray;
-typedef JArray<jint> *jintArray;
-typedef JArray<jlong> *jlongArray;
-typedef JArray<jfloat> *jfloatArray;
-typedef JArray<jdouble> *jdoubleArray;
-@end example
-
-
-@deftypemethod {template<class T>} T* elements (JArray<T> @var{array})
-This template function can be used to get a pointer to the elements of
-the @code{array}. For instance, you can fetch a pointer to the
-integers that make up an @code{int[]} like so:
-
-@example
-extern jintArray foo;
-jint *intp = elements (foo);
-@end example
-
-The name of this function may change in the future.
-@end deftypemethod
-
-
-@deftypefun jobjectArray JvNewObjectArray (jsize @var{length}, jclass @var{klass}, jobject @var{init})
-Here @code{klass} is the type of elements of the array and
-@code{init} is the initial value put into every slot in the array.
-@end deftypefun
-
-
-@subsection Creating arrays
-
-For each primitive type there is a function which can be used to
-create a new array of that type. The name of the function is of the
-form:
-
-@example
-JvNew@var{Type}Array
-@end example
-
-@noindent For example:
-
-@example
-JvNewBooleanArray
-@end example
-
-@noindent can be used to create an array of Java primitive boolean types.
-
-@noindent The following function definition is the template for all such functions:
-
-@deftypefun jbooleanArray JvNewBooleanArray (jint @var{length})
-Create's an array @var{length} indices long.
-@end deftypefun
-
-@deftypefun jsize JvGetArrayLength (jarray @var{array})
-Returns the length of the @var{array}.
-@end deftypefun
-
-
-@node Methods
-@section Methods
-
-Java methods are mapped directly into C++ methods.
-The header files generated by @code{gcjh}
-include the appropriate method definitions.
-Basically, the generated methods have the same names and
-@emph{corresponding} types as the Java methods,
-and are called in the natural manner.
-
-@subsection Overloading
-
-Both Java and C++ provide method overloading, where multiple
-methods in a class have the same name, and the correct one is chosen
-(at compile time) depending on the argument types.
-The rules for choosing the correct method are (as expected) more complicated
-in C++ than in Java, but given a set of overloaded methods
-generated by @code{gcjh} the C++ compiler will choose
-the expected one.
-
-Common assemblers and linkers are not aware of C++ overloading,
-so the standard implementation strategy is to encode the
-parameter types of a method into its assembly-level name.
-This encoding is called @dfn{mangling},
-and the encoded name is the @dfn{mangled name}.
-The same mechanism is used to implement Java overloading.
-For C++/Java interoperability, it is important that both the Java
-and C++ compilers use the @emph{same} encoding scheme.
-
-@subsection Static methods
-
-Static Java methods are invoked in @acronym{CNI} using the standard
-C++ syntax, using the @code{::} operator rather
-than the @code{.} operator.
-
-@noindent For example:
-
-@example
-jint i = java::lang::Math::round((jfloat) 2.3);
-@end example
-
-@noindent C++ method definition syntax is used to define a static native method.
-For example:
-
-@example
-#include <java/lang/Integer>
-java::lang::Integer*
-java::lang::Integer::getInteger(jstring str)
-@{
- ...
-@}
-@end example
-
-
-@subsection Object Constructors
-
-Constructors are called implicitly as part of object allocation
-using the @code{new} operator.
-
-@noindent For example:
-
-@example
-java::lang::Integer *x = new java::lang::Integer(234);
-@end example
-
-Java does not allow a constructor to be a native method.
-This limitation can be coded round however because a constructor
-can @emph{call} a native method.
-
-
-@subsection Instance methods
-
-Calling a Java instance method from a C++ @acronym{CNI} method is done
-using the standard C++ syntax, e.g.:
-
-@example
-// @r{First create the Java object.}
-java::lang::Integer *x = new java::lang::Integer(234);
-// @r{Now call a method.}
-jint prim_value = x->intValue();
-if (x->longValue == 0)
- ...
-@end example
-
-@noindent Defining a Java native instance method is also done the natural way:
-
-@example
-#include <java/lang/Integer.h>
-
-jdouble
-java::lang:Integer::doubleValue()
-@{
- return (jdouble) value;
-@}
-@end example
-
-
-@subsection Interface methods
-
-In Java you can call a method using an interface reference. This is
-supported, but not completly. @xref{Interfaces}.
-
-
-
-
-@node Strings
-@section Strings
-
-@acronym{CNI} provides a number of utility functions for
-working with Java Java @code{String} objects.
-The names and interfaces are analogous to those of @acronym{JNI}.
-
-
-@deftypefun jstring JvNewString (const char* @var{chars}, jsize @var{len})
-Returns a Java @code{String} object with characters from the C string
-@var{chars} up to the index @var{len} in that array.
-@end deftypefun
-
-@deftypefun jstring JvNewStringLatin1 (const char* @var{bytes}, jsize @var{len})
-Returns a Java @code{String} made up of @var{len} bytes from @var{bytes}.
-@end deftypefun
-
-
-@deftypefun jstring JvNewStringLatin1 (const char* @var{bytes})
-As above but the length of the @code{String} is @code{strlen(@var{bytes})}.
-@end deftypefun
-
-@deftypefun jstring JvNewStringUTF (const char* @var{bytes})
-Returns a @code{String} which is made up of the UTF encoded characters
-present in the C string @var{bytes}.
-@end deftypefun
-
-@deftypefun jchar* JvGetStringChars (jstring @var{str})
-Returns a pointer to an array of characters making up the @code{String} @var{str}.
-@end deftypefun
-
-@deftypefun int JvGetStringUTFLength (jstring @var{str})
-Returns the number of bytes required to encode the contents of the
-@code{String} @var{str} in UTF-8.
-@end deftypefun
-
-@deftypefun jsize JvGetStringUTFRegion (jstring @var{str}, jsize @var{start}, jsize @var{len}, char* @var{buf})
-Puts the UTF-8 encoding of a region of the @code{String} @var{str} into
-the buffer @code{buf}. The region to fetch is marked by @var{start} and @var{len}.
-
-Note that @var{buf} is a buffer, not a C string. It is @emph{not}
-null terminated.
-@end deftypefun
-
-
-@node Mixing with C++
-@section Interoperating with C/C++
-
-Because @acronym{CNI} is designed to represent Java classes and methods it
-cannot be mixed readily with C/C++ types.
-
-One important restriction is that Java classes cannot have non-Java
-type instance or static variables and cannot have methods which take
-non-Java types as arguments or return non-Java types.
-
-@noindent None of the following is possible with CNI:
-
-@example
-
-class ::MyClass : public java::lang::Object
-@{
- char* variable; // @r{char* is not a valid Java type.}
-@}
-
-
-uint
-::SomeClass::someMethod (char *arg)
-@{
- .
- .
- .
-@} // @r{@code{uint} is not a valid Java type, neither is @code{char*}}
-@end example
-
-@noindent Of course, it is ok to use C/C++ types within the scope of a method:
-
-
-@example
-jint
-::SomeClass::otherMethod (jstring str)
-@{
- char *arg = ...
- .
- .
- .
-@}
-@end example
-
-But this restriction can cause a problem so @acronym{CNI} includes the
-@code{gnu.gcj.RawData} class. The @code{RawData} class is a
-@dfn{non-scanned reference} type. In other words variables declared
-of type @code{RawData} can contain any data and are not checked by the
-compiler in any way.
-
-This means that you can put C/C++ data structures (including classes)
-in your @acronym{CNI} classes, as long as you use the appropriate cast.
-
-@noindent Here are some examples:
-
-@example
-
-class ::MyClass : public java::lang::Object
-@{
- gnu.gcj.RawData string;
-
- MyClass ();
- gnu.gcj.RawData getText ();
- void printText ();
-@}
-
-::MyClass::MyClass ()
-@{
- char* text = ...
- string = text;
-@}
-
-gnu.gcj.RawData
-::MyClass::getText ()
-@{
- return string;
-@}
-
-void
-::MyClass::printText ()
-@{
- printf("%s\n", (char*) string);
-@}
-@end example
-
-
-@node Exception Handling
-@section Exception Handling
-
-While C++ and Java share a common exception handling framework,
-things are not yet perfectly integrated. The main issue is that the
-run-time type information facilities of the two
-languages are not integrated.
-
-Still, things work fairly well. You can throw a Java exception from
-C++ using the ordinary @code{throw} construct, and this
-exception can be caught by Java code. Similarly, you can catch an
-exception thrown from Java using the C++ @code{catch}
-construct.
-
-@noindent Here is an example:
-
-@example
-if (i >= count)
- throw new java::lang::IndexOutOfBoundsException();
-@end example
-
-Normally, G++ will automatically detect when you are writing C++
-code that uses Java exceptions, and handle them appropriately.
-However, if C++ code only needs to execute destructors when Java
-exceptions are thrown through it, GCC will guess incorrectly. Sample
-problematic code:
-
-@example
-struct S @{ ~S(); @};
-
-extern void bar(); // @r{Is implemented in Java and may throw exceptions.}
-
-void foo()
-@{
- S s;
- bar();
-@}
-@end example
-
-The usual effect of an incorrect guess is a link failure, complaining of
-a missing routine called @code{__gxx_personality_v0}.
-
-You can inform the compiler that Java exceptions are to be used in a
-translation unit, irrespective of what it might think, by writing
-@code{#pragma GCC java_exceptions} at the head of the
-file. This @code{#pragma} must appear before any
-functions that throw or catch exceptions, or run destructors when
-exceptions are thrown through them.
-
-@node Synchronization
-@section Synchronization
-
-Each Java object has an implicit monitor.
-The Java VM uses the instruction @code{monitorenter} to acquire
-and lock a monitor, and @code{monitorexit} to release it.
-
-The corresponding CNI macros are @code{JvMonitorEnter} and
-@code{JvMonitorExit} (JNI has similar methods @code{MonitorEnter}
-and @code{MonitorExit}).
-
-
-The Java source language does not provide direct access to these primitives.
-Instead, there is a @code{synchronized} statement that does an
-implicit @code{monitorenter} before entry to the block,
-and does a @code{monitorexit} on exit from the block.
-Note that the lock has to be released even when the block is abnormally
-terminated by an exception, which means there is an implicit
-@code{try finally} surrounding synchronization locks.
-
-From C++, it makes sense to use a destructor to release a lock.
-@acronym{CNI} defines the following utility class:
-
-@example
-class JvSynchronize() @{
- jobject obj;
- JvSynchronize(jobject o) @{ obj = o; JvMonitorEnter(o); @}
- ~JvSynchronize() @{ JvMonitorExit(obj); @}
-@};
-@end example
-
-So this Java code:
-
-@example
-synchronized (OBJ)
-@{
- CODE
-@}
-@end example
-
-@noindent might become this C++ code:
-
-@example
-@{
- JvSynchronize dummy (OBJ);
- CODE;
-@}
-@end example
-
-Java also has methods with the @code{synchronized} attribute.
-This is equivalent to wrapping the entire method body in a
-@code{synchronized} statement.
-(Alternatively, an implementation could require the caller to do
-the synchronization. This is not practical for a compiler, because
-each virtual method call would have to test at run-time if
-synchronization is needed.) Since in @command{gcj}
-the @code{synchronized} attribute is handled by the
-method implementation, it is up to the programmer
-of a synchronized native method to handle the synchronization
-(in the C++ implementation of the method).
-In otherwords, you need to manually add @code{JvSynchronize}
-in a @code{native synchornized} method.
-
-@node Invocation
-@section Invocation
-
-CNI permits C++ applications to make calls into Java classes, in addition to
-allowing Java code to call into C++. Several functions, known as the
-@dfn{invocation API}, are provided to support this.
-
-@deftypefun jint JvCreateJavaVM (void* @var{vm_args})
-Initializes the Java runtime. This function performs essential initialization
-of the threads interface, garbage collector, exception handling and other key
-aspects of the runtime. It must be called once by an application with
-a non-Java @code{main()} function, before any other Java or CNI calls are made.
-It is safe, but not recommended, to call @code{JvCreateJavaVM()} more than
-once provided it is only called from a single thread.
-The @var{vmargs} parameter can be used to specify initialization parameters
-for the Java runtime. It may be @code{NULL}.
-This function returns @code{0} upon success, or @code{-1} if the runtime is
-already initialized.
-
-@emph{Note:} In GCJ 3.1, the @code{vm_args} parameter is ignored. It may be
-used in a future release.
-@end deftypefun
-
-@deftypefun java::lang::Thread* JvAttachCurrentThread (jstring @var{name}, java::lang::ThreadGroup* @var{group})
-Registers an existing thread with the Java runtime. This must be called once
-from each thread, before that thread makes any other Java or CNI calls. It
-must be called after @code{JvCreateJavaVM}.
-@var{name} specifies a name for the thread. It may be @code{NULL}, in which
-case a name will be generated.
-@var{group} is the ThreadGroup in which this thread will be a member. If it
-is @code{NULL}, the thread will be a member of the main thread group.
-The return value is the Java @code{Thread} object that represents the thread.
-It is safe to call @code{JvAttachCurrentThread()} more than once from the same
-thread. If the thread is already attached, the call is ignored and the current
-thread object is returned.
-@end deftypefun
-
-@deftypefun jint JvDetachCurrentThread ()
-Unregisters a thread from the Java runtime. This should be called by threads
-that were attached using @code{JvAttachCurrentThread()}, after they have
-finished making calls to Java code. This ensures that any resources associated
-with the thread become eligible for garbage collection.
-This function returns @code{0} upon success, or @code{-1} if the current thread
-is not attached.
-@end deftypefun
-
-@subsection Handling uncaught exceptions
-
-If an exception is thrown from Java code called using the invocation API, and
-no handler for the exception can be found, the runtime will abort the
-application. In order to make the application more robust, it is recommended
-that code which uses the invocation API be wrapped by a top-level try/catch
-block that catches all Java exceptions.
-
-@subsection Example
-
-The following code demonstrates the use of the invocation API. In this
-example, the C++ application initializes the Java runtime and attaches
-itself. The @code{java.lang.System} class is initialized in order to
-access its @code{out} field, and a Java string is printed. Finally, the thread
-is detached from the runtime once it has finished making Java calls. Everything
-is wrapped with a try/catch block to provide a default handler for any uncaught
-exceptions.
-
-The example can be compiled with @command{c++ test.cc -lgcj}.
-
-@example
-// test.cc
-#include <gcj/cni.h>
-#include <java/lang/System.h>
-#include <java/io/PrintStream.h>
-#include <java/lang/Throwable.h>
-
-int main(int argc, char *argv)
-@{
- using namespace java::lang;
-
- try
- @{
- JvCreateJavaVM(NULL);
- JvAttachCurrentThread(NULL, NULL);
-
- String *message = JvNewStringLatin1("Hello from C++");
- JvInitClass(&System.class$);
- System::out->println(message);
-
- JvDetachCurrentThread();
- @}
- catch (Throwable *t)
- @{
- System::err->println(JvNewStringLatin1("Unhandled Java exception:"));
- t->printStackTrace();
- @}
-@}
-@end example
-
-@node Reflection
-@section Reflection
-
-Reflection is possible with CNI code, it functions similarly to how it
-functions with JNI@.
-
-@c clean this up... I mean, what are the types jfieldID and jmethodID in JNI?
-The types @code{jfieldID} and @code{jmethodID}
-are as in JNI@.
-
-@noindent The functions:
-
-@itemize
-@item @code{JvFromReflectedField},
-@item @code{JvFromReflectedMethod},
-@item @code{JvToReflectedField}
-@item @code{JvToFromReflectedMethod}
-@end itemize
-
-@noindent will be added shortly, as will other functions corresponding to JNI@.
-
-
-
-@node Resources
-@chapter Resources
-
-While writing @command{gcj} and @code{libgcj} we have, of course, relied
-heavily on documentation from Sun Microsystems. In particular we have
-used The Java Language Specification (both first and second editions),
-the Java Class Libraries (volumes one and two), and the Java Virtual
-Machine Specification. In addition we've used the online documentation
-at @uref{http://java.sun.com/}.
-
-The current @command{gcj} home page is
-@uref{http://gcc.gnu.org/java/}.
-
-For more information on gcc, see @uref{http://gcc.gnu.org/}.
-
-Some @code{libgcj} testing is done using the Mauve test suite. This is
-a free software Java class library test suite which is being written
-because the JCK is not free. See
-@uref{http://sources.redhat.com/mauve/} for more information.
-
-@bye
projects / msp430-gcc.git / blobdiff