| @\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.1 |
| @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 |
| @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 @code{gcj}, the GNU compiler for the |
| Java programming language. @code{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 @code{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 |
| * 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{-R} @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 @code{gcj} is just another front end to @code{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 @code{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 @code{gcj} command is like a @code{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 @code{gcc} manual. |
| @end table |
| |
| You can specify more than one input file on the @code{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{-R}. |
| (This is an extension beyond the what plain @code{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 |
| |
| @code{gcj} has options to control where it looks to find files it needs. |
| For instance, @code{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, @code{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 @code{gcj} looks for a given class, it |
| searches the class path looking for matching @file{.class} or |
| @file{.java} file. @code{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 @code{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 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 |
| Finally, if @code{--bootclasspath} was specified, append its value. |
| Otherwise, append the built-in system directory, @file{libgcj.jar}. |
| @end itemize |
| |
| The classfile built by @code{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, @code{gcj} allows @file{.java} files |
| to be written using almost any encoding. @code{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 |
| @code{gcj} assumes the default encoding to be the @samp{UTF-8} encoding |
| of Unicode. |
| |
| To implement @code{--encoding}, @code{gcj} simply uses the host |
| platform's @code{iconv} conversion routine. This means that in practice |
| @code{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, |
| @code{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 |
| |
| @code{gcj} implements several warnings. As with other generic |
| @code{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, @code{gcj} will warn about redundant modifiers. For |
| instance, it will warn if an interface method is declared @code{public}. |
| |
| @item -Wextraneous-semicolon |
| This causes @code{gcj} to warn about empty statements. Empty statements |
| have been deprecated. |
| |
| @item -Wno-out-of-date |
| This option will cause @code{gcj} not to warn when a source file is |
| newer than its matching class file. By default @code{gcj} will warn |
| about this. |
| |
| @item -Wunused |
| This is the same as @code{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 @code{gcc} options controlling code generation, |
| @code{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 @code{gcj} to generate bytecode |
| (@file{.class} files) rather than object code. |
| |
| @item -R @var{resource-name} |
| This option is used to tell @code{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 @var{core:/resource-name}. |
| |
| @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, @code{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 @code{gcj} there are two options for writing native methods: CNI |
| and JNI@. By default @code{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 |
| @code{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}, |
| @code{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 @code{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 @code{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 @code{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 @code{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, |
| @code{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 |
| @code{gcj}. |
| |
| This list of compatibility issues is by no means complete. |
| |
| @itemize @bullet |
| @item |
| @code{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 @code{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 @code{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 @code{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 @code{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 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++. |
| * 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 |
| @code{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{GcjRaw} class. The @code{GcjRaw} class is a @dfn{non-scanned reference} |
| type. In other words variables declared of type @code{GcjRaw} 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 |
| @{ |
| GcjRaw string; |
| |
| MyClass (); |
| GcjRaw getText (); |
| void printText (); |
| @} |
| |
| ::MyClass::MyClass () |
| @{ |
| char* text = ... |
| string = text; |
| @} |
| |
| GcjRaw |
| ::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 @code{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 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 @code{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 @code{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 |