X-Git-Url: https://oss.titaniummirror.com/gitweb?a=blobdiff_plain;f=gcc%2Fjava%2Fgcj.texi;fp=gcc%2Fjava%2Fgcj.texi;h=0000000000000000000000000000000000000000;hb=6fed43773c9b0ce596dca5686f37ac3fc0fa11c0;hp=6a5c00a503cc67b3b084e3e97d7ff42a28bda564;hpb=27b11d56b743098deb193d510b337ba22dc52e5c;p=msp430-gcc.git diff --git a/gcc/java/gcj.texi b/gcc/java/gcj.texi deleted file mode 100644 index 6a5c00a5..00000000 --- a/gcc/java/gcj.texi +++ /dev/null @@ -1,1960 +0,0 @@ -@\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 -@end example - -@noindent and then must include one header file for each Java class it uses, e.g.: - -@example -#include -#include -#include -@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 ; -#include ; - -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 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 *jobjectArray; -typedef JArray *jbooleanArray; -typedef JArray *jbyteArray; -typedef JArray *jcharArray; -typedef JArray *jshortArray; -typedef JArray *jintArray; -typedef JArray *jlongArray; -typedef JArray *jfloatArray; -typedef JArray *jdoubleArray; -@end example - - -@deftypemethod {template} T* elements (JArray @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::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 - -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 -#include -#include -#include - -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