2412 lines
79 KiB
Plaintext
2412 lines
79 KiB
Plaintext
\input texinfo @c -*-texinfo-*-
|
|
@setfilename gcj.info
|
|
@settitle Guide to GNU gcj
|
|
|
|
@include gcc-common.texi
|
|
|
|
@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 which-gcj GCC-@value{version-GCC}
|
|
|
|
@copying
|
|
@c man begin COPYRIGHT
|
|
Copyright @copyright{} @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.2 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
|
|
|
|
@c man begin COPYRIGHT
|
|
|
|
(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.
|
|
@c man end
|
|
@end copying
|
|
|
|
@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
|
|
* grmic: (gcj)Invoking grmic.
|
|
Generate stubs for Remote Method Invocation.
|
|
* grmiregistry: (gcj)Invoking grmiregistry.
|
|
The remote object registry.
|
|
@end direntry
|
|
@end format
|
|
|
|
@insertcopying
|
|
@end ifinfo
|
|
|
|
@titlepage
|
|
@title GNU gcj
|
|
@author Tom Tromey
|
|
|
|
@page
|
|
@vskip 0pt plus 1filll
|
|
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
|
|
@insertcopying
|
|
@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 grmic:: Generate stubs for Remote Method Invocation.
|
|
* Invoking grmiregistry:: The remote object registry.
|
|
* About CNI:: Description of the Compiled Native Interface
|
|
* System properties:: Modifying runtime behavior of the libgcj library
|
|
* 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
|
|
* Linking:: Options for making an executable
|
|
* 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. Files in
|
|
an archive which don't end with @samp{.class} are treated as
|
|
resource files; they are compiled into the resulting object file
|
|
as @samp{core:} URLs.
|
|
@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 important, 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
|
|
Finally, 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 -Wno-deprecated
|
|
Warn if a deprecated class, method, or field is referred to.
|
|
|
|
@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 Linking
|
|
@section Linking
|
|
|
|
To turn a Java application into an executable program,
|
|
you need to link it with the needed libraries, just as for C or C++.
|
|
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.
|
|
You can do that in any of these ways:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Specify the class containing the desired @code{main} method
|
|
when you link the application, using the @code{--main} flag,
|
|
described below.
|
|
@item
|
|
Link the Java package(s) into a shared library (dll) rather than an
|
|
executable. Then invoke the application using the @code{gij} program,
|
|
making sure that @code{gij} can find the libraries it needs.
|
|
@item
|
|
Link the Java packages(s) with the flag @code{-lgij}, which links
|
|
in the @code{main} routine from the @code{gij} command.
|
|
This allows you to select the class whose @code{main} method you
|
|
want to run when you run the application. You can also use
|
|
other @code{gij} flags, such as @code{-D} flags to set properties.
|
|
Using the @code{-lgij} library (rather than the @code{gij} program
|
|
of the previous mechanism) has some advantages: it is compatible with
|
|
static linking, and does not require configuring or installing libraries.
|
|
@end itemize
|
|
|
|
These @code{gij} options relate to linking an executable:
|
|
|
|
@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.
|
|
|
|
@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 -lgij
|
|
Create an application whose command-line processing is that
|
|
of the @code{gij} command.
|
|
|
|
This option is an alternative to using @code{--main}; you cannot use both.
|
|
@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 -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-assert
|
|
Don't recognize the @code{assert} keyword. This is for compatibility
|
|
with older versions of the language specification.
|
|
|
|
@item -fno-optimize-static-class-initialization
|
|
When the optimization level is greater 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.
|
|
|
|
@item --disable-assertions[=@var{class-or-package}]
|
|
Don't include code for checking assertions in the compiled code.
|
|
If @code{=@var{class-or-package}} is missing disables assertion code
|
|
generation for all classes, unless overridden by a more
|
|
specific @code{--enable-assertions} flag.
|
|
If @var{class-or-package} is a class name, only disables generating
|
|
assertion checks within the named class or its inner classes.
|
|
If @var{class-or-package} is a package name, disables generating
|
|
assertion checks within the named package or a subpackage.
|
|
|
|
By default, assertions are enabled when generating class files
|
|
or when not optimizing, and disabled when generating optimized binaries.
|
|
|
|
@item --enable-assertions[=@var{class-or-package}]
|
|
Generates code to check assertions. The option is perhaps misnamed,
|
|
as you still need to turn on assertion checking at run-time,
|
|
and we don't support any easy way to do that.
|
|
So this flag isn't very useful yet, except to partially override
|
|
@code{--disable-assertions}.
|
|
|
|
@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}.
|
|
|
|
@menu
|
|
* Limitations::
|
|
* Extensions::
|
|
@end menu
|
|
|
|
@node Limitations
|
|
@section Standard features not yet supported
|
|
|
|
This list of compatibility issues is by no means complete.
|
|
|
|
@itemize @bullet
|
|
@item
|
|
@command{gcj} implements the JDK 1.2 language. It supports inner classes
|
|
and the new 1.4 @code{assert} keyword. 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.
|
|
|
|
@item
|
|
@command{gcj} does not currently allow for piecemeal replacement of
|
|
components within @code{libgcj}. Unfortunately, programmers often want
|
|
to use newer versions of certain packages, such as those provided by
|
|
the Apache Software Foundation's Jakarta project. This has forced us
|
|
to place the @code{org.w3c.dom} and @code{org.xml.sax} packages into
|
|
their own libraries, separate from @code{libgcj}. If you intend to
|
|
use these classes, you must link them explicitly with
|
|
@code{-l-org-w3c-dom} and @code{-l-org-xml-sax}. Future versions of
|
|
@command{gcj} may not have this restriction.
|
|
@end itemize
|
|
|
|
@node Extensions
|
|
@section Extra features unique to gcj
|
|
|
|
The main feature of @command{gcj} is that it can compile programs written in
|
|
the Java programming language to native code. Most extensions that have been
|
|
added are to facilitate this functionality.
|
|
|
|
@itemize @bullet
|
|
@item
|
|
@command{gcj} makes it easy and efficient to mix code written in Java and C++.
|
|
@xref{About CNI}, for more info on how to use this in your programs.
|
|
|
|
@item
|
|
When you compile your classes into a shared library they can be automatically
|
|
loaded by the @code{libgcj} system classloader. When trying to load a class
|
|
@code{gnu.pkg.SomeClass} the system classloader will first try to load the
|
|
shared library @file{lib-gnu-pkg-SomeClass.so}, if that fails to load the
|
|
class then it will try to load @file{lib-gnu-pkg.so} and finally when the
|
|
class is still not loaded it will try to load @file{lib-gnu.so}. Note that
|
|
all @samp{.}s will be transformed into @samp{-}s and that searching
|
|
for inner classes starts with their outermost outer class. If the class
|
|
cannot be found this way the system classloader tries to use
|
|
the @code{libgcj} bytecode interpreter to load the class from the standard
|
|
classpath. This process can be controlled to some degree via the
|
|
@code{gnu.gcj.runtime.VMClassLoader.library_control} property;
|
|
@xref{libgcj Runtime Properties}.
|
|
|
|
@item
|
|
@code{libgcj} includes a special @samp{gcjlib} URL type. A URL of
|
|
this form is like a @code{jar} URL, and looks like
|
|
@samp{gcjlib:/path/to/shared/library.so!/path/to/resource}. An access
|
|
to one of these URLs causes the shared library to be @code{dlopen()}d,
|
|
and then the resource is looked for in that library. These URLs are
|
|
most useful when used in conjunction with @code{java.net.URLClassLoader}.
|
|
Note that, due to implementation limitations, currently any such URL
|
|
can be accessed by only one class loader, and libraries are never
|
|
unloaded. This means some care must be exercised to make sure that
|
|
a @code{gcjlib} URL is not accessed by more than one class loader at once.
|
|
In a future release this limitation will be lifted, and such
|
|
libraries will be mapped privately.
|
|
|
|
@item
|
|
A program compiled by @command{gcj} will examine the
|
|
@env{GCJ_PROPERTIES} environment variable and change its behavior in
|
|
some ways. In particular @env{GCJ_PROPERTIES} holds a list of
|
|
assignments to global properties, such as would be set with the
|
|
@option{-D} option to @command{java}. For instance,
|
|
@samp{java.compiler=gcj} is a valid (but currently meaningless)
|
|
setting.
|
|
@cindex GCJ_PROPERTIES
|
|
@vindex GCJ_PROPERTIES
|
|
|
|
@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{--no-assert}] [@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 --no-assert
|
|
Don't recognize the @code{assert} keyword, for backwards compatibility
|
|
with older versions of the language specification.
|
|
|
|
@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 specified 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 --print-constants
|
|
Print the constant pool. When printing a reference to a constant
|
|
also print its index in the constant pool.
|
|
|
|
@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.
|
|
Implies @code{--print-constants}.
|
|
@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{-cp} @var{path}] [@option{-classpath} @var{path}]
|
|
[@option{-D}@var{name}[=@var{value}]@dots{}]
|
|
[@option{-ms=}@var{number}] [@option{-mx=}@var{number}]
|
|
[@option{-X@var{argument}]
|
|
[@option{--showversion}] [@option{--version}] [@option{--help}][@option{-?}]
|
|
@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 -cp @var{path}
|
|
@itemx -classpath @var{path}
|
|
Set the initial class path. The class path is used for finding
|
|
class and resource files. If specified, this option overrides the
|
|
@code{CLASSPATH} environment variable. Note that this option is
|
|
ignored if @code{-jar} is used.
|
|
|
|
@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 -X
|
|
@itemx -X@var{argument}
|
|
Supplying @code{-X} by itself will cause @code{gij} to list all the
|
|
supported @code{-X} options. Currently there are none. Unrecognized
|
|
@code{-X} options are ignored, for compatibility with other runtimes.
|
|
|
|
@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
|
|
@itemx -?
|
|
Print help, then exit.
|
|
|
|
@item --showversion
|
|
Print version number and continue.
|
|
|
|
@item --version
|
|
Print version number, then exit.
|
|
|
|
@item -verbose:class
|
|
Each time a class is initialized, print a short message on standard error.
|
|
@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 grmic
|
|
@chapter Invoking grmic
|
|
|
|
@c man title grmic Generate stubs for Remote Method Invocation
|
|
|
|
@c man begin SYNOPSIS grmic
|
|
@command{grmic} [@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 grmic
|
|
|
|
@command{grmic} 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{grmic}. 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 grmic
|
|
|
|
@table @gcctabopt
|
|
@item -keep
|
|
@itemx -keepgenerated
|
|
By default, @command{grmic} deletes intermediate files. Either of these
|
|
options causes it not to delete such files.
|
|
|
|
@item -v1.1
|
|
Cause @command{grmic} to create stubs and skeletons for the 1.1
|
|
protocol version.
|
|
|
|
@item -vcompat
|
|
Cause @command{grmic} 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{grmic} 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{grmic} 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 grmiregistry
|
|
@chapter Invoking grmiregistry
|
|
|
|
@c man title grmiregistry Remote object registry
|
|
|
|
@c man begin SYNOPSIS grmiregistry
|
|
@command{grmic} [@option{OPTION}] @dots{} [@var{port}]
|
|
@ignore
|
|
[@option{--help}]
|
|
[@option{--version}]
|
|
@end ignore
|
|
@c man end
|
|
|
|
@c man begin DESCRIPTION grmiregistry
|
|
|
|
@command{grmiregistry} 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 grmiregistry
|
|
|
|
@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 Compiled Native Interface,
|
|
which is is a convenient way to write Java native methods using C++.
|
|
This is a more efficient, more convenient, but less portable
|
|
alternative to the standard JNI (Java Native Interface).
|
|
|
|
@menu
|
|
* Basic concepts:: Introduction to using CNI@.
|
|
* Packages:: How packages are mapped to C++.
|
|
* Primitive types:: Handling Java types in C++.
|
|
* Interfaces:: How Java interfaces map to C++.
|
|
* Objects and Classes:: C++ and Java classes.
|
|
* Class Initialization:: How objects are initialized.
|
|
* Object allocation:: How to create Java objects in C++.
|
|
* Arrays:: Dealing with Java arrays in C++.
|
|
* Methods:: Java methods in C++.
|
|
* Strings:: Information about Java Strings.
|
|
* Mixing with C++:: How CNI can interoperate with C++.
|
|
* Exception Handling:: How exceptions are handled.
|
|
* Synchronization:: Synchronizing between Java and C++.
|
|
* Invocation:: Starting the Java runtime from C++.
|
|
* Reflection:: Using reflection from C++.
|
|
@end menu
|
|
|
|
|
|
@node Basic concepts
|
|
@section Basic concepts
|
|
|
|
In terms of languages features, Java is mostly a subset
|
|
of C++. Java has a few important extensions, plus a powerful standard
|
|
class library, but on the whole that does not change the basic similarity.
|
|
Java is a hybrid object-oriented language, with a few native types,
|
|
in addition to class types. It is class-based, where a class may have
|
|
static as well as per-object fields, and static as well as instance methods.
|
|
Non-static methods may be virtual, and may be overloaded. Overloading is
|
|
resolved at compile time by matching the actual argument types against
|
|
the parameter types. Virtual methods are implemented using indirect calls
|
|
through a dispatch table (virtual function table). Objects are
|
|
allocated on the heap, and initialized using a constructor method.
|
|
Classes are organized in a package hierarchy.
|
|
|
|
All of the listed attributes are also true of C++, though C++ has
|
|
extra features (for example in C++ objects may be allocated not just
|
|
on the heap, but also statically or in a local stack frame). Because
|
|
@command{gcj} uses the same compiler technology as G++ (the GNU
|
|
C++ compiler), it is possible to make the intersection of the two
|
|
languages use the same ABI (object representation and calling
|
|
conventions). The key idea in CNI is that Java objects are C++
|
|
objects, and all Java classes are C++ classes (but not the other way
|
|
around). So the most important task in integrating Java and C++ is to
|
|
remove gratuitous incompatibilities.
|
|
|
|
You write CNI code as a regular C++ source file. (You do have to use
|
|
a Java/CNI-aware C++ compiler, specifically a recent version of G++.)
|
|
|
|
@noindent A CNI C++ source file must have:
|
|
|
|
@example
|
|
#include <gcj/cni.h>
|
|
@end example
|
|
|
|
@noindent and then must include one header file for each Java class it uses, e.g.:
|
|
|
|
@example
|
|
#include <java/lang/Character.h>
|
|
#include <java/util/Date.h>
|
|
#include <java/lang/IndexOutOfBoundsException.h>
|
|
@end example
|
|
|
|
@noindent These header files are automatically generated by @code{gcjh}.
|
|
|
|
|
|
CNI provides some functions and macros to make using Java objects and
|
|
primitive types from C++ easier. In general, these CNI functions and
|
|
macros start with the @code{Jv} prefix, for example the function
|
|
@code{JvNewObjectArray}. This convention is used to avoid conflicts
|
|
with other libraries. Internal functions in CNI start with the prefix
|
|
@code{_Jv_}. You should not call these; if you find a need to, let us
|
|
know and we will try to come up with an alternate solution.
|
|
|
|
|
|
@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 necessary 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
|
|
referred 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 referring 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 G++ 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.
|
|
Note however that this does not happen for Java arrays; you must
|
|
allocate those using the appropriate CNI function. 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
|
|
|
|
|
|
@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 completely. @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
|
|
|
|
@subsection RawData
|
|
|
|
The above restriction can be problematic, 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 or memory manager 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
|
|
|
|
|
|
@subsection RawDataManaged
|
|
|
|
@code{gnu.gcj.RawDataManaged} is another type used to indicate special data used
|
|
by native code. Unlike the @code{RawData} type, fields declared as
|
|
@code{RawDataManaged} will be "marked" by the memory manager and
|
|
considered for garbage collection.
|
|
|
|
Native data which is allocated using CNI's @code{JvAllocBytes()}
|
|
function and stored in a @code{RawDataManaged} will be automatically
|
|
freed when the Java object it is associated with becomes unreachable.
|
|
|
|
@subsection Native memory allocation
|
|
|
|
@deftypefun void* JvAllocBytes (jsize @var{size})
|
|
Allocates @var{size} bytes from the heap. The memory returned is zeroed.
|
|
This memory is not scanned for pointers by the garbage collector, but will
|
|
be freed if no references to it are discovered.
|
|
|
|
This function can be useful if you need to associate some native data with a
|
|
Java object. Using a CNI's special @code{RawDataManaged} type, native data
|
|
allocated with @code{JvAllocBytes} will be automatically freed when the Java
|
|
object itself becomes unreachable.
|
|
@end deftypefun
|
|
|
|
@subsection Posix signals
|
|
|
|
On Posix based systems the @code{libgcj} library uses several signals
|
|
internally. @acronym{CNI} code should not attempt to use the same
|
|
signals as doing so may cause @code{libgcj} and/or the @acronym{CNI}
|
|
code to fail.
|
|
|
|
SIGSEGV is used on many systems to generate
|
|
@code{NullPointerExceptions}. SIGCHLD is used internally by
|
|
@code{Runtime.exec()}. Several other signals (that vary from platform to
|
|
platform) can be used by the memory manager and by
|
|
@code{Thread.interrupt()}.
|
|
|
|
@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 other words, you need to manually add @code{JvSynchronize}
|
|
in a @code{native synchronized} method.
|
|
|
|
@node Invocation
|
|
@section Invocation
|
|
|
|
CNI permits C++ applications to make calls into Java classes, in addition to
|
|
allowing Java code to call into C++. Several functions, known as the
|
|
@dfn{invocation API}, are provided to support this.
|
|
|
|
@deftypefun jint JvCreateJavaVM (void* @var{vm_args})
|
|
Initializes the Java runtime. This function performs essential initialization
|
|
of the threads interface, garbage collector, exception handling and other key
|
|
aspects of the runtime. It must be called once by an application with
|
|
a non-Java @code{main()} function, before any other Java or CNI calls are made.
|
|
It is safe, but not recommended, to call @code{JvCreateJavaVM()} more than
|
|
once provided it is only called from a single thread.
|
|
The @var{vmargs} parameter can be used to specify initialization parameters
|
|
for the Java runtime. It may be @code{NULL}.
|
|
This function returns @code{0} upon success, or @code{-1} if the runtime is
|
|
already initialized.
|
|
|
|
@emph{Note:} In GCJ 3.1, the @code{vm_args} parameter is ignored. It may be
|
|
used in a future release.
|
|
@end deftypefun
|
|
|
|
@deftypefun java::lang::Thread* JvAttachCurrentThread (jstring @var{name}, java::lang::ThreadGroup* @var{group})
|
|
Registers an existing thread with the Java runtime. This must be called once
|
|
from each thread, before that thread makes any other Java or CNI calls. It
|
|
must be called after @code{JvCreateJavaVM}.
|
|
@var{name} specifies a name for the thread. It may be @code{NULL}, in which
|
|
case a name will be generated.
|
|
@var{group} is the ThreadGroup in which this thread will be a member. If it
|
|
is @code{NULL}, the thread will be a member of the main thread group.
|
|
The return value is the Java @code{Thread} object that represents the thread.
|
|
It is safe to call @code{JvAttachCurrentThread()} more than once from the same
|
|
thread. If the thread is already attached, the call is ignored and the current
|
|
thread object is returned.
|
|
@end deftypefun
|
|
|
|
@deftypefun jint JvDetachCurrentThread ()
|
|
Unregisters a thread from the Java runtime. This should be called by threads
|
|
that were attached using @code{JvAttachCurrentThread()}, after they have
|
|
finished making calls to Java code. This ensures that any resources associated
|
|
with the thread become eligible for garbage collection.
|
|
This function returns @code{0} upon success, or @code{-1} if the current thread
|
|
is not attached.
|
|
@end deftypefun
|
|
|
|
@subsection Handling uncaught exceptions
|
|
|
|
If an exception is thrown from Java code called using the invocation API, and
|
|
no handler for the exception can be found, the runtime will abort the
|
|
application. In order to make the application more robust, it is recommended
|
|
that code which uses the invocation API be wrapped by a top-level try/catch
|
|
block that catches all Java exceptions.
|
|
|
|
@subsection Example
|
|
|
|
The following code demonstrates the use of the invocation API. In this
|
|
example, the C++ application initializes the Java runtime and attaches
|
|
itself. The @code{java.lang.System} class is initialized in order to
|
|
access its @code{out} field, and a Java string is printed. Finally, the thread
|
|
is detached from the runtime once it has finished making Java calls. Everything
|
|
is wrapped with a try/catch block to provide a default handler for any uncaught
|
|
exceptions.
|
|
|
|
The example can be compiled with @command{c++ test.cc -lgcj}.
|
|
|
|
@example
|
|
// test.cc
|
|
#include <gcj/cni.h>
|
|
#include <java/lang/System.h>
|
|
#include <java/io/PrintStream.h>
|
|
#include <java/lang/Throwable.h>
|
|
|
|
int main(int argc, char *argv)
|
|
@{
|
|
using namespace java::lang;
|
|
|
|
try
|
|
@{
|
|
JvCreateJavaVM(NULL);
|
|
JvAttachCurrentThread(NULL, NULL);
|
|
|
|
String *message = JvNewStringLatin1("Hello from C++");
|
|
JvInitClass(&System::class$);
|
|
System::out->println(message);
|
|
|
|
JvDetachCurrentThread();
|
|
@}
|
|
catch (Throwable *t)
|
|
@{
|
|
System::err->println(JvNewStringLatin1("Unhandled Java exception:"));
|
|
t->printStackTrace();
|
|
@}
|
|
@}
|
|
@end example
|
|
|
|
@node Reflection
|
|
@section Reflection
|
|
|
|
Reflection is possible with CNI code, it functions similarly to how it
|
|
functions with JNI@.
|
|
|
|
@c clean this up... I mean, what are the types jfieldID and jmethodID in JNI?
|
|
The types @code{jfieldID} and @code{jmethodID}
|
|
are as in JNI@.
|
|
|
|
@noindent The functions:
|
|
|
|
@itemize
|
|
@item @code{JvFromReflectedField},
|
|
@item @code{JvFromReflectedMethod},
|
|
@item @code{JvToReflectedField}
|
|
@item @code{JvToFromReflectedMethod}
|
|
@end itemize
|
|
|
|
@noindent will be added shortly, as will other functions corresponding to JNI@.
|
|
|
|
|
|
@node System properties
|
|
@chapter System properties
|
|
|
|
The runtime behavior of the @code{libgcj} library can be modified by setting
|
|
certain system properties. These properties can be compiled into the program
|
|
using the @code{-D@var{name}[=@var{value}]} option to @command{gcj} or by
|
|
setting them explicitly in the program by calling the
|
|
@code{java.lang.System.setProperty()} method. Some system properties are only
|
|
used for informational purposes (like giving a version number or a user name).
|
|
A program can inspect the current value of a property by calling the
|
|
@code{java.lang.System.getProperty()} method.
|
|
|
|
@menu
|
|
* Standard Properties:: Standard properties supported by @code{libgcj}
|
|
* GNU Classpath Properties:: Properties found in Classpath based libraries
|
|
* libgcj Runtime Properties:: Properties specific to @code{libgcj}
|
|
@end menu
|
|
|
|
@node Standard Properties
|
|
@section Standard Properties
|
|
|
|
The following properties are normally found in all implementations of the core
|
|
libraries for the Java language.
|
|
|
|
@table @gcctabopt
|
|
|
|
@item java.version
|
|
The @code{libgcj} version number.
|
|
|
|
@item java.vendor
|
|
Set to @samp{The Free Software Foundation, Inc.}
|
|
|
|
@item java.vendor.url
|
|
Set to @uref{http://gcc.gnu.org/java/}.
|
|
|
|
@item java.home
|
|
The directory where @code{gcj} was installed. Taken from the @code{--prefix}
|
|
option given to @command{configure}.
|
|
|
|
@item java.class.version
|
|
The class format version number supported by the libgcj byte code interpreter.
|
|
(Currently @samp{46.0})
|
|
|
|
@item java.vm.specification.version
|
|
The Virtual Machine Specification version implemented by @code{libgcj}.
|
|
(Currently @samp{1.0})
|
|
|
|
@item java.vm.specification.vendor
|
|
The name of the Virtual Machine specification designer.
|
|
|
|
@item java.vm.specification.name
|
|
The name of the Virtual Machine specification
|
|
(Set to @samp{Java Virtual Machine Specification}).
|
|
|
|
@item java.vm.version
|
|
The @command{gcj} version number.
|
|
|
|
@item java.vm.vendor
|
|
Set to @samp{The Free Software Foundation, Inc.}
|
|
|
|
@item java.vm.name
|
|
Set to @samp{GNU libgcj}.
|
|
|
|
@item java.specification.version
|
|
The Runtime Environment specification version implemented by @code{libgcj}.
|
|
(Currently set to @samp{1.3})
|
|
|
|
@item java.specification.vendor
|
|
The Runtime Environment specification designer.
|
|
|
|
@item java.specification.name
|
|
The name of the Runtime Environment specification
|
|
(Set to @samp{Java Platform API Specification}).
|
|
|
|
@item java.class.path
|
|
The paths (jar files, zip files and directories) used for finding class files.
|
|
|
|
@item java.library.path
|
|
Directory path used for finding native libraries.
|
|
|
|
@item java.io.tmpdir
|
|
The directory used to put temporary files in.
|
|
|
|
@item java.compiler
|
|
Name of the Just In Time compiler to use by the byte code interpreter.
|
|
Currently not used in @code{libgcj}.
|
|
|
|
@item java.ext.dirs
|
|
Directories containing jar files with extra libraries. Will be used when
|
|
resolving classes. Currently not used in @code{libgcj}.
|
|
|
|
@item java.protocol.handler.pkgs
|
|
A @samp{|} separated list of package names that is used to find classes that
|
|
implement handlers for @code{java.net.URL}.
|
|
|
|
@item java.rmi.server.codebase
|
|
A list of URLs that is used by the @code{java.rmi.server.RMIClassLoader}
|
|
to load classes from.
|
|
|
|
@item jdbc.drivers
|
|
A list of class names that will be loaded by the @code{java.sql.DriverManager}
|
|
when it starts up.
|
|
|
|
@item file.separator
|
|
The separator used in when directories are included in a filename
|
|
(normally @samp{/} or @samp{\} ).
|
|
|
|
@item file.encoding
|
|
The default character encoding used when converting platform native files to
|
|
Unicode (usually set to @samp{8859_1}).
|
|
|
|
@item path.separator
|
|
The standard separator used when a string contains multiple paths
|
|
(normally @samp{:} or @samp{;}), the string is usually not a valid character
|
|
to use in normal directory names.)
|
|
|
|
@item line.separator
|
|
The default line separator used on the platform (normally @samp{\n}, @samp{\r}
|
|
or a combination of those two characters).
|
|
|
|
@item policy.provider
|
|
The class name used for the default policy provider returned by
|
|
@code{java.security.Policy.getPolicy}.
|
|
|
|
@item user.name
|
|
The name of the user running the program. Can be the full name, the login name
|
|
or empty if unknown.
|
|
|
|
@item user.home
|
|
The default directory to put user specific files in.
|
|
|
|
@item user.dir
|
|
The current working directory from which the program was started.
|
|
|
|
@item user.language
|
|
The default language as used by the @code{java.util.Locale} class.
|
|
|
|
@item user.region
|
|
The default region as used by the @code{java.util.Local} class.
|
|
|
|
@item user.variant
|
|
The default variant of the language and region local used.
|
|
|
|
@item user.timezone
|
|
The default timezone as used by the @code{java.util.TimeZone} class.
|
|
|
|
@item os.name
|
|
The operating system/kernel name that the program runs on.
|
|
|
|
@item os.arch
|
|
The hardware that we are running on.
|
|
|
|
@item os.version
|
|
The version number of the operating system/kernel.
|
|
|
|
@item awt.appletWarning
|
|
The string to display when an untrusted applet is displayed.
|
|
Returned by @code{java.awt.Window.getWarningString()} when the window is
|
|
``insecure''.
|
|
|
|
@item awt.toolkit
|
|
The class name used for initializing the default @code{java.awt.Toolkit}.
|
|
Defaults to @code{gnu.awt.gtk.GtkToolkit}.
|
|
|
|
@item http.proxyHost
|
|
Name of proxy host for http connections.
|
|
|
|
@item http.proxyPort
|
|
Port number to use when a proxy host is in use.
|
|
|
|
@end table
|
|
|
|
@node GNU Classpath Properties
|
|
@section GNU Classpath Properties
|
|
|
|
@code{libgcj} is based on the GNU Classpath (Essential Libraries for Java) a
|
|
GNU project to create free core class libraries for use with virtual machines
|
|
and compilers for the Java language. The following properties are common to
|
|
libraries based on GNU Classpath.
|
|
|
|
@table @gcctabopt
|
|
|
|
@item gcj.dumpobject
|
|
Enables printing serialization debugging by the @code{java.io.ObjectInput} and
|
|
@code{java.io.ObjectOutput} classes when set to something else then the empty
|
|
string. Only used when running a debug build of the library.
|
|
|
|
@item gnu.classpath.vm.shortname
|
|
This is a succint name of the virtual machine. For @code{libgcj},
|
|
this will always be @samp{libgcj}.
|
|
|
|
@item gnu.classpath.home.url
|
|
A base URL used for finding system property files (e.g.,
|
|
@file{classpath.security}). By default this is a @samp{file:} URL
|
|
pointing to the @file{lib} directory under @samp{java.home}.
|
|
|
|
@end table
|
|
|
|
@node libgcj Runtime Properties
|
|
@section libgcj Runtime Properties
|
|
|
|
The following properties are specific to the @code{libgcj} runtime and will
|
|
normally not be found in other core libraries for the java language.
|
|
|
|
@table @gcctabopt
|
|
|
|
@item java.fullversion
|
|
The combination of @code{java.vm.name} and @code{java.vm.version}.
|
|
|
|
@item java.vm.info
|
|
Same as @code{java.fullversion}.
|
|
|
|
@item impl.prefix
|
|
Used by the @code{java.net.DatagramSocket} class when set to something else
|
|
then the empty string. When set all newly created @code{DatagramSocket}s will
|
|
try to load a class @code{java.net.[impl.prefix]DatagramSocketImpl} instead of
|
|
the normal @code{java.net.PlainDatagramSocketImpl}.
|
|
|
|
@item gnu.gcj.progname
|
|
The name that was used to invoked the program.
|
|
|
|
@item gnu.gcj.runtime.NameFinder.demangle
|
|
Whether names in a stack trace should be demangled. Defaults to @code{true}.
|
|
|
|
@item gnu.gcj.runtime.NameFinder.sanitize
|
|
Whether calls to initialize exceptions and starting the runtime system
|
|
should be removed from the stack trace. Only done when names are
|
|
demangled. Defaults to @code{true}.
|
|
|
|
@item gnu.gcj.runtime.NameFinder.remove_unknown
|
|
Whether calls to unknown functions (class and method names are unknown)
|
|
should be removed from the stack trace. Only done when the stack is
|
|
sanitized. Ignored if this means no stack trace information would be
|
|
available anymore. Defaults to @code{true}.
|
|
|
|
@item gnu.gcj.runtime.NameFinder.remove_interpreter
|
|
Whether runtime interpreter calls (methods in the @code{_Jv_InterpMethod} class
|
|
and functions starting with @samp{ffi_}) should be removed from the stack
|
|
trace. Only done when the stack is sanitized. Defaults to @code{true}.
|
|
|
|
|
|
@item gnu.gcj.runtime.NameFinder.use_addr2line
|
|
Whether an external process (@command{addr2line} or @command{addr2name.awk})
|
|
should be used as fallback to convert the addresses to function names when
|
|
the runtime is unable to do it through @code{dladdr}.
|
|
|
|
@item gnu.gcj.runtime.VMClassLoader.library_control
|
|
This controls how shared libraries are automatically loaded by the
|
|
built-in class loader. By default, or if this property is set to
|
|
@samp{full}, a full search is done for each requested class. If this
|
|
property is set to @samp{cache}, then any failed lookups are cached
|
|
and not tried again. If this property is set to @samp{never}, then
|
|
lookups are never done. For more information, @xref{Extensions}.
|
|
|
|
@end table
|
|
|
|
|
|
@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
|