* configure: Regenerated.
[official-gcc.git] / gcc / java / gcj.texi
blob01acf4344cbb1a7fb1d75d3e84e40f1558a20b1c
1 \input texinfo @c -*-texinfo-*-
2 @setfilename gcj.info
3 @settitle Guide to GNU gcj
5 @c Merge the standard indexes into a single one.
6 @syncodeindex fn cp
7 @syncodeindex vr cp
8 @syncodeindex ky cp
9 @syncodeindex pg cp
10 @syncodeindex tp cp
12 @include gcc-common.texi
14 @c Note: When reading this manual you'll find lots of strange
15 @c circumlocutions like ``compiler for the Java language''.
16 @c This is necessary due to Sun's restrictions on the use of
17 @c the word ``Java'.
19 @c When this manual is copyrighted.
20 @set copyrights-gcj 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2010
22 @copying
23 @c man begin COPYRIGHT
24 Copyright @copyright{} @value{copyrights-gcj} Free Software Foundation, Inc.
26 Permission is granted to copy, distribute and/or modify this document
27 under the terms of the GNU Free Documentation License, Version 1.3 or
28 any later version published by the Free Software Foundation; with no
29 Invariant Sections, the Front-Cover Texts being (a) (see below), and
30 with the Back-Cover Texts being (b) (see below).
31 A copy of the license is included in the
32 @c man end
33 section entitled ``GNU Free Documentation License''.
34 @ignore
35 @c man begin COPYRIGHT
36 man page gfdl(7).
37 @c man end
38 @end ignore
40 @c man begin COPYRIGHT
42 (a) The FSF's Front-Cover Text is:
44      A GNU Manual
46 (b) The FSF's Back-Cover Text is:
48      You have freedom to copy and modify this GNU Manual, like GNU
49      software.  Copies published by the Free Software Foundation raise
50      funds for GNU development.
51 @c man end
52 @end copying
54 @ifinfo
55 @format
56 @dircategory Software development
57 @direntry
58 * Gcj: (gcj).               Ahead-of-time compiler for the Java language
59 @end direntry
61 @dircategory Individual utilities
62 @direntry
63 * jcf-dump: (gcj)Invoking jcf-dump.
64                             Print information about Java class files
65 * gij: (gcj)Invoking gij.   GNU interpreter for Java bytecode
66 * gcj-dbtool: (gcj)Invoking gcj-dbtool.
67                             Tool for manipulating class file databases.
68 * jv-convert: (gcj)Invoking jv-convert.
69                             Convert file from one encoding to another
70 * grmic: (gcj)Invoking grmic.
71                             Generate stubs for Remote Method Invocation.
72 * gc-analyze: (gcj)Invoking gc-analyze.
73                             Analyze Garbage Collector (GC) memory dumps.
74 * aot-compile: (gcj)Invoking aot-compile.
75                             Compile bytecode to native and generate databases.
76 * rebuild-gcj-db: (gcj)Invoking rebuild-gcj-db.
77                             Merge the per-solib databases made by aot-compile
78                             into one system-wide database.
79 @end direntry
80 @end format
82 @insertcopying
83 @end ifinfo
85 @titlepage
86 @title GNU gcj
87 @versionsubtitle
88 @author Tom Tromey
90 @page
91 @vskip 0pt plus 1filll
92 Published by the Free Software Foundation @*
93 51 Franklin Street, Fifth Floor@*
94 Boston, MA 02110-1301, USA@*
95 @sp 1
96 @insertcopying
97 @end titlepage
98 @contents
99 @page
102 @node Top
103 @top Introduction
105 This manual describes how to use @command{gcj}, the GNU compiler for the
106 Java programming language.  @command{gcj} can generate both @file{.class}
107 files and object files, and it can read both Java source code and
108 @file{.class} files.
110 @menu
111 * Copying::             The GNU General Public License
112 * GNU Free Documentation License::
113                         How you can share and copy this manual
114 * Invoking gcj::        Compiler options supported by @command{gcj}
115 * Compatibility::       Compatibility between gcj and other tools for Java
116 * Invoking jcf-dump::   Print information about class files
117 * Invoking gij::        Interpreting Java bytecodes
118 * Invoking gcj-dbtool:: Tool for manipulating class file databases.
119 * Invoking jv-convert:: Converting from one encoding to another
120 * Invoking grmic::      Generate stubs for Remote Method Invocation.
121 * Invoking gc-analyze:: Analyze Garbage Collector (GC) memory dumps.
122 * Invoking aot-compile:: Compile bytecode to native and generate databases.
123 * Invoking rebuild-gcj-db:: Merge the per-solib databases made by aot-compile
124                             into one system-wide database.
125 * About CNI::           Description of the Compiled Native Interface
126 * System properties::   Modifying runtime behavior of the libgcj library
127 * Resources::           Where to look for more information
128 * Index::               Index.
129 @end menu
132 @include gpl_v3.texi
134 @include fdl.texi
137 @node Invoking gcj
138 @chapter Invoking gcj
140 @c man title gcj Ahead-of-time compiler for the Java language
142 @ignore
143 @c man begin SYNOPSIS gcj
144 gcj [@option{-I}@var{dir}@dots{}] [@option{-d} @var{dir}@dots{}]
145     [@option{--CLASSPATH}=@var{path}] [@option{--classpath}=@var{path}]
146     [@option{-f}@var{option}@dots{}] [@option{--encoding}=@var{name}]
147     [@option{--main}=@var{classname}] [@option{-D}@var{name}[=@var{value}]@dots{}]
148     [@option{-C}] [@option{--resource} @var{resource-name}] [@option{-d} @var{directory}]
149     [@option{-W}@var{warn}@dots{}]
150     @var{sourcefile}@dots{}
151 @c man end
152 @c man begin SEEALSO gcj
153 gcc(1), gcjh(1), gjnih(1), gij(1), jcf-dump(1), gfdl(7),
154 and the Info entries for @file{gcj} and @file{gcc}.
155 @c man end
156 @end ignore
158 @c man begin DESCRIPTION gcj
160 As @command{gcj} is just another front end to @command{gcc}, it supports many
161 of the same options as gcc.  @xref{Option Summary, , Option Summary,
162 gcc, Using the GNU Compiler Collection (GCC)}.  This manual only documents the
163 options specific to @command{gcj}.
165 @c man end
167 @menu
168 * Input and output files::
169 * Input Options::               How gcj finds files
170 * Encodings::                   Options controlling source file encoding
171 * Warnings::                    Options controlling warnings specific to gcj
172 * Linking::                     Options for making an executable
173 * Code Generation::             Options controlling the output of gcj
174 * Configure-time Options::      Options you won't use
175 @end menu
177 @c man begin OPTIONS gcj
179 @node Input and output files
180 @section Input and output files
182 A @command{gcj} command is like a @command{gcc} command, in that it
183 consists of a number of options and file names.  The following kinds
184 of input file names are supported:
186 @table @gcctabopt
187 @item @var{file}.java
188 Java source files.
189 @item @var{file}.class
190 Java bytecode files.
191 @item @var{file}.zip
192 @itemx @var{file}.jar
193 An archive containing one or more @code{.class} files, all of
194 which are compiled.  The archive may be compressed.  Files in
195 an archive which don't end with @samp{.class} are treated as
196 resource files; they are compiled into the resulting object file
197 as @samp{core:} URLs.
198 @item @@@var{file}
199 A file containing a whitespace-separated list of input file names.
200 (Currently, these must all be @code{.java} source files, but that
201 may change.)
202 Each named file is compiled, just as if it had been on the command line.
203 @item @var{library}.a
204 @itemx @var{library}.so
205 @itemx -l@var{libname}
206 Libraries to use when linking.  See the @command{gcc} manual.
207 @end table
209 You can specify more than one input file on the @command{gcj} command line,
210 in which case they will all be compiled.  If you specify a
211 @code{-o @var{FILENAME}}
212 option, all the input files will be compiled together, producing a
213 single output file, named @var{FILENAME}.
214 This is allowed even when using @code{-S} or @code{-c},
215 but not when using @code{-C} or @code{--resource}.
216 (This is an extension beyond the what plain @command{gcc} allows.)
217 (If more than one input file is specified, all must currently
218 be @code{.java} files, though we hope to fix this.)
220 @node Input Options
221 @section Input Options
223 @cindex class path
225 @command{gcj} has options to control where it looks to find files it needs.
226 For instance, @command{gcj} might need to load a class that is referenced
227 by the file it has been asked to compile.  Like other compilers for the
228 Java language, @command{gcj} has a notion of a @dfn{class path}.  There are
229 several options and environment variables which can be used to
230 manipulate the class path.  When @command{gcj} looks for a given class, it
231 searches the class path looking for matching @file{.class} or
232 @file{.java} file.  @command{gcj} comes with a built-in class path which
233 points at the installed @file{libgcj.jar}, a file which contains all the
234 standard classes.
236 In the text below, a directory or path component can refer either to an
237 actual directory on the filesystem, or to a @file{.zip} or @file{.jar}
238 file, which @command{gcj} will search as if it is a directory.
240 @table @gcctabopt
241 @item -I@var{dir}
242 All directories specified by @code{-I} are kept in order and prepended
243 to the class path constructed from all the other options.  Unless
244 compatibility with tools like @code{javac} is important, we recommend
245 always using @code{-I} instead of the other options for manipulating the
246 class path.
248 @item --classpath=@var{path}
249 This sets the class path to @var{path}, a colon-separated list of paths
250 (on Windows-based systems, a semicolon-separate list of paths).
251 This does not override the builtin (``boot'') search path.
253 @item --CLASSPATH=@var{path}
254 Deprecated synonym for @code{--classpath}.
256 @item --bootclasspath=@var{path}
257 Where to find the standard builtin classes, such as @code{java.lang.String}.
259 @item --extdirs=@var{path}
260 For each directory in the @var{path}, place the contents of that
261 directory at the end of the class path.
263 @item CLASSPATH
264 This is an environment variable which holds a list of paths.
265 @end table
267 The final class path is constructed like so:
269 @itemize @bullet
270 @item
271 First come all directories specified via @code{-I}.
273 @item
274 If @option{--classpath} is specified, its value is appended.
275 Otherwise, if the @code{CLASSPATH} environment variable is specified,
276 then its value is appended.
277 Otherwise, the current directory (@code{"."}) is appended.
279 @item
280 If @code{--bootclasspath} was specified, append its value.
281 Otherwise, append the built-in system directory, @file{libgcj.jar}.
283 @item
284 Finally, if @code{--extdirs} was specified, append the contents of the
285 specified directories at the end of the class path.  Otherwise, append
286 the contents of the built-in extdirs at @code{$(prefix)/share/java/ext}.
287 @end itemize
289 The classfile built by @command{gcj} for the class @code{java.lang.Object}
290 (and placed in @code{libgcj.jar}) contains a special zero length
291 attribute @code{gnu.gcj.gcj-compiled}. The compiler looks for this
292 attribute when loading @code{java.lang.Object} and will report an error
293 if it isn't found, unless it compiles to bytecode (the option
294 @code{-fforce-classes-archive-check} can be used to override this
295 behavior in this particular case.)
297 @table @gcctabopt
298 @item -fforce-classes-archive-check
299 This forces the compiler to always check for the special zero length
300 attribute @code{gnu.gcj.gcj-compiled} in @code{java.lang.Object} and
301 issue an error if it isn't found.
303 @item -fsource=@var{VERSION}
304 This option is used to choose the source version accepted by
305 @command{gcj}.  The default is @samp{1.5}.
306 @end table
308 @node Encodings
309 @section Encodings
311 The Java programming language uses Unicode throughout.  In an effort to
312 integrate well with other locales, @command{gcj} allows @file{.java} files
313 to be written using almost any encoding.  @command{gcj} knows how to
314 convert these encodings into its internal encoding at compile time.
316 You can use the @code{--encoding=@var{NAME}} option to specify an
317 encoding (of a particular character set) to use for source files.  If
318 this is not specified, the default encoding comes from your current
319 locale.  If your host system has insufficient locale support, then
320 @command{gcj} assumes the default encoding to be the @samp{UTF-8} encoding
321 of Unicode.
323 To implement @code{--encoding}, @command{gcj} simply uses the host
324 platform's @code{iconv} conversion routine.  This means that in practice
325 @command{gcj} is limited by the capabilities of the host platform.
327 The names allowed for the argument @code{--encoding} vary from platform
328 to platform (since they are not standardized anywhere).  However,
329 @command{gcj} implements the encoding named @samp{UTF-8} internally, so if
330 you choose to use this for your source files you can be assured that it
331 will work on every host.
334 @node Warnings
335 @section Warnings
337 @command{gcj} implements several warnings.  As with other generic
338 @command{gcc} warnings, if an option of the form @code{-Wfoo} enables a
339 warning, then @code{-Wno-foo} will disable it.  Here we've chosen to
340 document the form of the warning which will have an effect -- the
341 default being the opposite of what is listed.
343 @table @gcctabopt
344 @item -Wredundant-modifiers
345 With this flag, @command{gcj} will warn about redundant modifiers.  For
346 instance, it will warn if an interface method is declared @code{public}.
348 @item -Wextraneous-semicolon
349 This causes @command{gcj} to warn about empty statements.  Empty statements
350 have been deprecated.
352 @item -Wno-out-of-date
353 This option will cause @command{gcj} not to warn when a source file is
354 newer than its matching class file.  By default @command{gcj} will warn
355 about this.
357 @item -Wno-deprecated
358 Warn if a deprecated class, method, or field is referred to.
360 @item -Wunused
361 This is the same as @command{gcc}'s @code{-Wunused}.
363 @item -Wall
364 This is the same as @code{-Wredundant-modifiers -Wextraneous-semicolon
365 -Wunused}.
366 @end table
369 @node Linking
370 @section Linking
372 To turn a Java application into an executable program,
373 you need to link it with the needed libraries, just as for C or C++.
374 The linker by default looks for a global function named @code{main}.
375 Since Java does not have global functions, and a
376 collection of Java classes may have more than one class with a
377 @code{main} method, you need to let the linker know which of those
378 @code{main} methods it should invoke when starting the application.
379 You can do that in any of these ways:
381 @itemize @bullet
382 @item
383 Specify the class containing the desired @code{main} method
384 when you link the application, using the @code{--main} flag,
385 described below.
386 @item
387 Link the Java package(s) into a shared library (dll) rather than an
388 executable.  Then invoke the application using the @code{gij} program,
389 making sure that @code{gij} can find the libraries it needs.
390 @item
391 Link the Java packages(s) with the flag @code{-lgij}, which links
392 in the @code{main} routine from the @code{gij} command.
393 This allows you to select the class whose @code{main} method you
394 want to run when you run the application.  You can also use
395 other @code{gij} flags, such as @code{-D} flags to set properties.
396 Using the @code{-lgij} library (rather than the @code{gij} program
397 of the previous mechanism) has some advantages: it is compatible with
398 static linking, and does not require configuring or installing libraries.
399 @end itemize
401 These @code{gij} options relate to linking an executable:
403 @table @gcctabopt
404 @item --main=@var{CLASSNAME}
405 This option is used when linking to specify the name of the class whose
406 @code{main} method should be invoked when the resulting executable is
407 run.
409 @item -D@var{name}[=@var{value}]
410 This option can only be used with @code{--main}.  It defines a system
411 property named @var{name} with value @var{value}.  If @var{value} is not
412 specified then it defaults to the empty string.  These system properties
413 are initialized at the program's startup and can be retrieved at runtime
414 using the @code{java.lang.System.getProperty} method.
416 @item -lgij
417 Create an application whose command-line processing is that
418 of the @code{gij} command.
420 This option is an alternative to using @code{--main}; you cannot use both.
422 @item -static-libgcj
423 This option causes linking to be done against a static version of the
424 libgcj runtime library.  This option is only available if
425 corresponding linker support exists.
427 @strong{Caution:} Static linking of libgcj may cause essential parts
428 of libgcj to be omitted.  Some parts of libgcj use reflection to load
429 classes at runtime.  Since the linker does not see these references at
430 link time, it can omit the referred to classes.  The result is usually
431 (but not always) a @code{ClassNotFoundException} being thrown at
432 runtime. Caution must be used when using this option.  For more
433 details see:
434 @w{@uref{http://gcc.gnu.org/wiki/Statically%20linking%20libgcj}}
435 @end table
437 @node Code Generation
438 @section Code Generation
440 In addition to the many @command{gcc} options controlling code generation,
441 @command{gcj} has several options specific to itself.
443 @table @gcctabopt
445 @item -C
446 This option is used to tell @command{gcj} to generate bytecode
447 (@file{.class} files) rather than object code.
449 @item --resource @var{resource-name}
450 This option is used to tell @command{gcj} to compile the contents of a
451 given file to object code so it may be accessed at runtime with the core
452 protocol handler as @samp{core:/@var{resource-name}}.  Note that
453 @var{resource-name} is the name of the resource as found at runtime; for
454 instance, it could be used in a call to @code{ResourceBundle.getBundle}.
455 The actual file name to be compiled this way must be specified
456 separately.
458 @item -ftarget=@var{VERSION}
459 This can be used with @option{-C} to choose the version of bytecode
460 emitted by @command{gcj}.  The default is @samp{1.5}.  When not
461 generating bytecode, this option has no effect.
463 @item -d @var{directory}
464 When used with @code{-C}, this causes all generated @file{.class} files
465 to be put in the appropriate subdirectory of @var{directory}.  By
466 default they will be put in subdirectories of the current working
467 directory.
469 @item -fno-bounds-check
470 By default, @command{gcj} generates code which checks the bounds of all
471 array indexing operations.  With this option, these checks are omitted, which
472 can improve performance for code that uses arrays extensively.  Note that this 
473 can result in unpredictable behavior if the code in question actually does 
474 violate array bounds constraints.  It is safe to use this option if you are 
475 sure that your code will never throw an @code{ArrayIndexOutOfBoundsException}.
477 @item -fno-store-check
478 Don't generate array store checks.  When storing objects into arrays, a runtime
479 check is normally generated in order to ensure that the object is assignment
480 compatible with the component type of the array (which may not be known
481 at compile-time).  With this option, these checks are omitted.  This can 
482 improve performance for code which stores objects into arrays frequently.
483 It is safe to use this option if you are sure your code will never throw an 
484 @code{ArrayStoreException}.
486 @item -fjni
487 With @command{gcj} there are two options for writing native methods: CNI
488 and JNI@.  By default @command{gcj} assumes you are using CNI@.  If you are
489 compiling a class with native methods, and these methods are implemented
490 using JNI, then you must use @code{-fjni}.  This option causes
491 @command{gcj} to generate stubs which will invoke the underlying JNI
492 methods.
494 @item -fno-assert
495 Don't recognize the @code{assert} keyword.  This is for compatibility
496 with older versions of the language specification.
498 @item -fno-optimize-static-class-initialization
499 When the optimization level is greater or equal to @code{-O2},
500 @command{gcj} will try to optimize the way calls into the runtime are made
501 to initialize static classes upon their first use (this optimization
502 isn't carried out if @code{-C} was specified.) When compiling to native
503 code, @code{-fno-optimize-static-class-initialization} will turn this
504 optimization off, regardless of the optimization level in use.
506 @item --disable-assertions[=@var{class-or-package}]
507 Don't include code for checking assertions in the compiled code.
508 If @code{=@var{class-or-package}} is missing disables assertion code
509 generation for all classes, unless overridden by a more
510 specific @code{--enable-assertions} flag.
511 If @var{class-or-package} is a class name, only disables generating
512 assertion checks within the named class or its inner classes.
513 If @var{class-or-package} is a package name, disables generating
514 assertion checks within the named package or a subpackage.
516 By default, assertions are enabled when generating class files
517 or when not optimizing, and disabled when generating optimized binaries.
519 @item --enable-assertions[=@var{class-or-package}]
520 Generates code to check assertions.  The option is perhaps misnamed,
521 as you still need to turn on assertion checking at run-time,
522 and we don't support any easy way to do that.
523 So this flag isn't very useful yet, except to partially override
524 @code{--disable-assertions}.
526 @item -findirect-dispatch
527 @command{gcj} has a special binary compatibility ABI, which is enabled
528 by the @code{-findirect-dispatch} option.  In this mode, the code
529 generated by @command{gcj} honors the binary compatibility guarantees
530 in the Java Language Specification, and the resulting object files do
531 not need to be directly linked against their dependencies.  Instead,
532 all dependencies are looked up at runtime.  This allows free mixing of
533 interpreted and compiled code.
535 Note that, at present, @code{-findirect-dispatch} can only be used
536 when compiling @file{.class} files.  It will not work when compiling
537 from source.  CNI also does not yet work with the binary compatibility
538 ABI.  These restrictions will be lifted in some future release.
540 However, if you compile CNI code with the standard ABI, you can call
541 it from code built with the binary compatibility ABI.
543 @item -fbootstrap-classes
544 This option can be use to tell @code{libgcj} that the compiled classes
545 should be loaded by the bootstrap loader, not the system class loader.
546 By default, if you compile a class and link it into an executable, it
547 will be treated as if it was loaded using the system class loader.
548 This is convenient, as it means that things like
549 @code{Class.forName()} will search @samp{CLASSPATH} to find the
550 desired class.
552 @item -freduced-reflection
553 This option causes the code generated by @command{gcj} to contain a
554 reduced amount of the class meta-data used to support runtime
555 reflection. The cost of this savings is the loss of
556 the ability to use certain reflection capabilities of the standard
557 Java runtime environment. When set all meta-data except for that
558 which is needed to obtain correct runtime semantics is eliminated.
560 For code that does not use reflection (i.e. serialization, RMI, CORBA
561 or call methods in the @code{java.lang.reflect} package),
562 @code{-freduced-reflection} will result in proper operation with a
563 savings in executable code size.
565 JNI (@code{-fjni}) and the binary compatibility ABI
566 (@code{-findirect-dispatch}) do not work properly without full
567 reflection meta-data.  Because of this, it is an error to use these options
568 with @code{-freduced-reflection}.
570 @strong{Caution:} If there is no reflection meta-data, code that uses
571 a @code{SecurityManager} may not work properly.  Also calling
572 @code{Class.forName()} may fail if the calling method has no
573 reflection meta-data.
575 @end table
578 @node Configure-time Options
579 @section Configure-time Options
581 Some @command{gcj} code generations options affect the resulting ABI, and
582 so can only be meaningfully given when @code{libgcj}, the runtime
583 package, is configured.  @code{libgcj} puts the appropriate options from
584 this group into a @samp{spec} file which is read by @command{gcj}.  These
585 options are listed here for completeness; if you are using @code{libgcj}
586 then you won't want to touch these options.
588 @table @gcctabopt
589 @item -fuse-boehm-gc
590 This enables the use of the Boehm GC bitmap marking code.  In particular
591 this causes @command{gcj} to put an object marking descriptor into each
592 vtable.
594 @item -fhash-synchronization
595 By default, synchronization data (the data used for @code{synchronize},
596 @code{wait}, and @code{notify}) is pointed to by a word in each object.
597 With this option @command{gcj} assumes that this information is stored in a
598 hash table and not in the object itself.
600 @item -fuse-divide-subroutine
601 On some systems, a library routine is called to perform integer
602 division.  This is required to get exception handling correct when
603 dividing by zero.
605 @item -fcheck-references
606 On some systems it's necessary to insert inline checks whenever
607 accessing an object via a reference.  On other systems you won't need
608 this because null pointer accesses are caught automatically by the
609 processor.
611 @item -fuse-atomic-builtins
612 On some systems, gcc can generate code for built-in atomic operations.
613 Use this option to force gcj to use these builtins when compiling Java
614 code.  Where this capability is present it should be automatically
615 detected, so you won't usually need to use this option.
617 @end table
619 @c man end
621 @node Compatibility
622 @chapter Compatibility with the Java Platform
624 As we believe it is important that the Java platform not be fragmented,
625 @command{gcj} and @code{libgcj} try to conform to the relevant Java
626 specifications.  However, limited manpower and incomplete and unclear
627 documentation work against us.  So, there are caveats to using
628 @command{gcj}.
630 @menu
631 * Limitations::                 
632 * Extensions::                  
633 @end menu
635 @node Limitations
636 @section Standard features not yet supported
638 This list of compatibility issues is by no means complete.
640 @itemize @bullet
641 @item
642 @command{gcj} implements the JDK 1.2 language.  It supports inner classes
643 and the new 1.4 @code{assert} keyword.  It does not yet support the Java 2
644 @code{strictfp} keyword (it recognizes the keyword but ignores it).  
646 @item
647 @code{libgcj} is largely compatible with the JDK 1.2 libraries.
648 However, @code{libgcj} is missing many packages, most notably
649 @code{java.awt}.  There are also individual missing classes and methods.
650 We currently do not have a list showing differences between
651 @code{libgcj} and the Java 2 platform.
653 @item
654 Sometimes the @code{libgcj} implementation of a method or class differs
655 from the JDK implementation.  This is not always a bug.  Still, if it
656 affects you, it probably makes sense to report it so that we can discuss
657 the appropriate response.
659 @item
660 @command{gcj} does not currently allow for piecemeal replacement of
661 components within @code{libgcj}. Unfortunately, programmers often want
662 to use newer versions of certain packages, such as those provided by
663 the Apache Software Foundation's Jakarta project.  This has forced us
664 to place the @code{org.w3c.dom} and @code{org.xml.sax} packages into
665 their own libraries, separate from @code{libgcj}.  If you intend to
666 use these classes, you must link them explicitly with
667 @code{-l-org-w3c-dom} and @code{-l-org-xml-sax}.  Future versions of
668 @command{gcj} may not have this restriction.
669 @end itemize
671 @node Extensions
672 @section Extra features unique to gcj
674 The main feature of @command{gcj} is that it can compile programs written in
675 the Java programming language to native code.  Most extensions that have been
676 added are to facilitate this functionality.
678 @itemize @bullet
679 @item
680 @command{gcj} makes it easy and efficient to mix code written in Java and C++.
681 @xref{About CNI}, for more info on how to use this in your programs.
683 @item
684 When you compile your classes into a shared library using
685 @code{-findirect-dispatch} then add them to the system-wide
686 classmap.db file using @code{gcj-dbtool}, they will be automatically
687 loaded by the @code{libgcj} system classloader.  This is the new,
688 preferred classname-to-library resolution mechanism.  @xref{Invoking
689 gcj-dbtool}, for more information on using the classmap database.
691 @item
692 The old classname-to-library lookup mechanism is still supported
693 through the @code{gnu.gcj.runtime.VMClassLoader.library_control}
694 property, but it is deprecated and will likely be removed in some
695 future release.  When trying to load a class @code{gnu.pkg.SomeClass}
696 the system classloader will first try to load the shared library
697 @file{lib-gnu-pkg-SomeClass.so}, if that fails to load the class then
698 it will try to load @file{lib-gnu-pkg.so} and finally when the class
699 is still not loaded it will try to load @file{lib-gnu.so}.  Note that
700 all @samp{.}s will be transformed into @samp{-}s and that searching
701 for inner classes starts with their outermost outer class.  If the
702 class cannot be found this way the system classloader tries to use the
703 @code{libgcj} bytecode interpreter to load the class from the standard
704 classpath.  This process can be controlled to some degree via the
705 @code{gnu.gcj.runtime.VMClassLoader.library_control} property;
706 @xref{libgcj Runtime Properties}.
708 @item
709 @code{libgcj} includes a special @samp{gcjlib} URL type.  A URL of
710 this form is like a @code{jar} URL, and looks like
711 @samp{gcjlib:/path/to/shared/library.so!/path/to/resource}.  An access
712 to one of these URLs causes the shared library to be @code{dlopen()}d,
713 and then the resource is looked for in that library.  These URLs are
714 most useful when used in conjunction with @code{java.net.URLClassLoader}.
715 Note that, due to implementation limitations, currently any such URL
716 can be accessed by only one class loader, and libraries are never
717 unloaded.  This means some care must be exercised to make sure that
718 a @code{gcjlib} URL is not accessed by more than one class loader at once.
719 In a future release this limitation will be lifted, and such
720 libraries will be mapped privately.
722 @item
723 A program compiled by @command{gcj} will examine the
724 @env{GCJ_PROPERTIES} environment variable and change its behavior in
725 some ways.  In particular @env{GCJ_PROPERTIES} holds a list of
726 assignments to global properties, such as would be set with the
727 @option{-D} option to @command{java}.  For instance,
728 @samp{java.compiler=gcj} is a valid (but currently meaningless)
729 setting.
730 @cindex GCJ_PROPERTIES
731 @vindex GCJ_PROPERTIES
733 @end itemize
736 @node Invoking jcf-dump
737 @chapter Invoking jcf-dump
739 @c man title jcf-dump print information about Java class files
741 @ignore
742 @c man begin SYNOPSIS jcf-dump
743 jcf-dump [@option{-c}] [@option{--javap}]
744     [@option{--classpath}=@var{path}] [@option{--CLASSPATH}=@var{path}]
745     [@option{-I}@var{dir}@dots{}] [@option{-o} @var{file}]
746     [@option{--version}] [@option{--help}] [@option{-v}] [@option{--verbose}]
747     @var{classname}@dots{}
748 @c man end
749 @c man begin SEEALSO jcf-dump
750 gcc(1), gcj(1), gcjh(1), gij(1), jcf-dump(1), gfdl(7),
751 and the Info entries for @file{gcj} and @file{gcc}.
752 @c man end
753 @end ignore
755 @c man begin DESCRIPTION jcf-dump
757 This is a class file examiner, similar to @code{javap}.  It will print
758 information about a number of classes, which are specified by class name
759 or file name.
761 @c man end
763 @c man begin OPTIONS jcf-dump
765 @table @gcctabopt
766 @item -c
767 Disassemble method bodies.  By default method bodies are not printed.
769 @item --print-constants
770 Print the constant pool.  When printing a reference to a constant
771 also print its index in the constant pool.
773 @item --javap
774 Generate output in @code{javap} format.  The implementation of this
775 feature is very incomplete.
777 @item --classpath=@var{path}
778 @itemx --CLASSPATH=@var{path}
779 @itemx -I@var{directory}
780 @itemx -o @var{file}
781 These options as the same as the corresponding @command{gcj} options.
783 @item --help
784 Print help, then exit.
786 @item --version
787 Print version number, then exit.
789 @item -v, --verbose
790 Print extra information while running.
791 Implies @code{--print-constants}.
792 @end table
794 @c man end
796 @node Invoking gij
797 @chapter Invoking gij
799 @c man title gij GNU interpreter for Java bytecode
801 @ignore
802 @c man begin SYNOPSIS gij
803 gij [@option{OPTION}] @dots{} @var{JARFILE} [@var{ARGS}@dots{}]
805 gij [@option{-jar}] [@option{OPTION}] @dots{} @var{CLASS} [@var{ARGS}@dots{}]
806   [@option{-cp} @var{path}] [@option{-classpath} @var{path}]
807   [@option{-D}@var{name}[=@var{value}]@dots{}]
808   [@option{-ms=}@var{number}] [@option{-mx=}@var{number}]
809   [@option{-X@var{argument}}] [@option{-verbose}] [@option{-verbose:class}]
810   [@option{--showversion}] [@option{--version}] [@option{--help}][@option{-?}]
811 @c man end
812 @c man begin SEEALSO gij
813 gcc(1), gcj(1), gcjh(1), jcf-dump(1), gfdl(7),
814 and the Info entries for @file{gcj} and @file{gcc}.
815 @c man end
816 @end ignore
818 @c man begin DESCRIPTION gij
820 @code{gij} is a Java bytecode interpreter included with @code{libgcj}.
821 @code{gij} is not available on every platform; porting it requires a
822 small amount of assembly programming which has not been done for all the
823 targets supported by @command{gcj}.
825 The primary argument to @code{gij} is the name of a class or, with
826 @code{-jar}, a jar file.  Options before this argument are interpreted
827 by @code{gij}; remaining options are passed to the interpreted program.
829 If a class name is specified and this class does not have a @code{main}
830 method with the appropriate signature (a @code{static void} method with
831 a @code{String[]} as its sole argument), then @code{gij} will print an
832 error and exit.
834 If a jar file is specified then @code{gij} will use information in it to
835 determine which class' @code{main} method will be invoked.
837 @code{gij} will invoke the @code{main} method with all the remaining
838 command-line options.
840 Note that @code{gij} is not limited to interpreting code.  Because
841 @code{libgcj} includes a class loader which can dynamically load shared
842 objects, it is possible to give @code{gij} the name of a class which has
843 been compiled and put into a shared library on the class path.
845 @c man end
847 @c man begin OPTIONS gij
849 @table @gcctabopt
850 @item -cp @var{path}
851 @itemx -classpath @var{path}
852 Set the initial class path.  The class path is used for finding
853 class and resource files.  If specified, this option overrides the
854 @code{CLASSPATH} environment variable.  Note that this option is
855 ignored if @code{-jar} is used.
857 @item -D@var{name}[=@var{value}]
858 This defines a system property named @var{name} with value @var{value}.
859 If @var{value} is not specified then it defaults to the empty string.
860 These system properties are initialized at the program's startup and can
861 be retrieved at runtime using the @code{java.lang.System.getProperty}
862 method.
864 @item -ms=@var{number}
865 Equivalent to @code{-Xms}.
867 @item -mx=@var{number}
868 Equivalent to @code{-Xmx}.
870 @item -noverify
871 Do not verify compliance of bytecode with the VM specification. In addition,
872 this option disables type verification which is otherwise performed on BC-ABI
873 compiled code.
875 @item -X
876 @itemx -X@var{argument}
877 Supplying @code{-X} by itself will cause @code{gij} to list all the
878 supported @code{-X} options.  Currently these options are supported:
880 @table @gcctabopt
881 @item -Xms@var{size}
882 Set the initial heap size.
884 @item -Xmx@var{size}
885 Set the maximum heap size.
887 @item -Xss@var{size}
888 Set the thread stack size.
889 @end table
891 Unrecognized @code{-X} options are ignored, for compatibility with
892 other runtimes.
894 @item -jar
895 This indicates that the name passed to @code{gij} should be interpreted
896 as the name of a jar file, not a class.
898 @item --help
899 @itemx -?
900 Print help, then exit.
902 @item --showversion
903 Print version number and continue.
905 @item --fullversion
906 Print detailed version information, then exit.
908 @item --version
909 Print version number, then exit.
911 @item -verbose
912 @itemx -verbose:class
913 Each time a class is initialized, print a short message on standard error.
914 @end table
916 @code{gij} also recognizes and ignores the following options, for
917 compatibility with existing application launch scripts:
918 @code{-client}, @code{-server}, @code{-hotspot}, @code{-jrockit},
919 @code{-agentlib}, @code{-agentpath}, @code{-debug}, @code{-d32},
920 @code{-d64}, @code{-javaagent}, @code{-noclassgc}, @code{-verify},
921 and @code{-verifyremote}.
923 @c man end
925 @node Invoking gcj-dbtool
926 @chapter Invoking gcj-dbtool.
928 @c man title gcj-dbtool Manipulate class file mapping databases for libgcj
930 @ignore
931 @c man begin SYNOPSIS gcj-dbtool
932 gcj-dbtool @option{OPTION} @var{DBFILE} [@option{MORE}] @dots{}
934 gcj-dbtool [@option{-0}] [@option{-}] [@option{-n}] [@option{-a}] [@option{-f}]
935   [@option{-t}] [@option{-l}] [@option{-p} [@var{LIBDIR}]]
936   [@option{-v}] [@option{-m}] [@option{--version}] [@option{--help}]
938 @c man end
939 @c man begin SEEALSO gcj-dbtool
940 gcc(1), gcj(1), gcjh(1), jcf-dump(1), gfdl(7),
941 and the Info entries for @file{gcj} and @file{gcc}.
942 @c man end
943 @end ignore
945 @c man begin DESCRIPTION gcj-dbtool
947 @code{gcj-dbtool} is a tool for creating and manipulating class file
948 mapping databases.  @code{libgcj} can use these databases to find a
949 shared library corresponding to the bytecode representation of a
950 class.  This functionality is useful for ahead-of-time compilation of
951 a program that has no knowledge of @code{gcj}.
953 @code{gcj-dbtool} works best if all the jar files added to it are
954 compiled using @code{-findirect-dispatch}.
956 Note that @code{gcj-dbtool} is currently available as ``preview
957 technology''.  We believe it is a reasonable way to allow
958 application-transparent ahead-of-time compilation, but this is an
959 unexplored area.  We welcome your comments.
961 @c man end
963 @c man begin OPTIONS gcj-dbtool
965 @table @gcctabopt
966 @item -n @var{DBFILE} [@var{SIZE}]
967 This creates a new database.  Currently, databases cannot be resized;
968 you can choose a larger initial size if desired.  The default size is
969 32,749.
971 @item -a @var{DBFILE} @var{JARFILE} @var{LIB}
972 @itemx -f @var{DBFILE} @var{JARFILE} @var{LIB}
973 This adds a jar file to the database.  For each class file in the jar,
974 a cryptographic signature of the bytecode representation of the class
975 is recorded in the database.  At runtime, a class is looked up by its
976 signature and the compiled form of the class is looked for in the
977 corresponding shared library.  The @option{-a} option will verify
978 that @var{LIB} exists before adding it to the database; @option{-f}
979 skips this check.
981 @item [@option{-}][@option{-0}] -m @var{DBFILE} @var{DBFILE},[@var{DBFILE}]
982 Merge a number of databases.  The output database overwrites any
983 existing database.  To add databases into an existing database,
984 include the destination in the list of sources.
986 If @option{-} or @option{-0} are used, the list of files to read is
987 taken from standard input instead of the command line.  For
988 @option{-0}, Input filenames are terminated by a null character
989 instead of by whitespace.  Useful when arguments might contain white
990 space.  The GNU find -print0 option produces input suitable for this
991 mode.
993 @item -t @var{DBFILE}
994 Test a database.
996 @item -l @var{DBFILE}
997 List the contents of a database.
999 @item -p
1000 Print the name of the default database.  If there is no default
1001 database, this prints a blank line.  If @var{LIBDIR} is specified, use
1002 it instead of the default library directory component of the database
1003 name.
1005 @item --help
1006 Print a help message, then exit.
1008 @item --version
1009 @itemx -v
1010 Print version information, then exit.
1012 @end table
1014 @c man end
1016 @node Invoking jv-convert
1017 @chapter Invoking jv-convert
1019 @c man title jv-convert Convert file from one encoding to another
1021 @c man begin SYNOPSIS jv-convert
1022 @command{jv-convert} [@option{OPTION}] @dots{} [@var{INPUTFILE} [@var{OUTPUTFILE}]]
1023 @ignore
1025   [@option{--encoding} @var{name}]
1026   [@option{--from} @var{name}]
1027   [@option{--to} @var{name}]
1028   [@option{-i} @var{file}] [@option{-o} @var{file}]
1029   [@option{--reverse}] [@option{--help}] [@option{--version}]
1030 @end ignore
1031 @c man end
1033 @c man begin DESCRIPTION jv-convert
1035 @command{jv-convert} is a utility included with @code{libgcj} which
1036 converts a file from one encoding to another.  It is similar to the Unix
1037 @command{iconv} utility.
1039 The encodings supported by @command{jv-convert} are platform-dependent.
1040 Currently there is no way to get a list of all supported encodings.
1042 @c man end
1044 @c man begin OPTIONS jv-convert
1046 @table @gcctabopt
1047 @item --encoding @var{name}
1048 @itemx --from @var{name}
1049 Use @var{name} as the input encoding.  The default is the current
1050 locale's encoding.
1052 @item --to @var{name}
1053 Use @var{name} as the output encoding.  The default is the
1054 @code{JavaSrc} encoding; this is ASCII with @samp{\u} escapes for
1055 non-ASCII characters.
1057 @item -i @var{file}
1058 Read from @var{file}.  The default is to read from standard input.
1060 @item -o @var{file}
1061 Write to @var{file}.  The default is to write to standard output.
1063 @item --reverse
1064 Swap the input and output encodings.
1066 @item --help
1067 Print a help message, then exit.
1069 @item --version
1070 Print version information, then exit.
1071 @end table
1073 @c man end
1075 @node Invoking grmic
1076 @chapter Invoking grmic
1078 @c man title grmic Generate stubs for Remote Method Invocation
1080 @c man begin SYNOPSIS grmic
1081 @command{grmic} [@option{OPTION}] @dots{} @var{class} @dots{}
1082 @ignore
1083   [@option{-keep}]
1084   [@option{-keepgenerated}]
1085   [@option{-v1.1}]
1086   [@option{-vcompat}]
1087   [@option{-v1.2}]
1088   [@option{-nocompile}]
1089   [@option{-verbose}]
1090   [@option{-d} @var{directory}]
1091   [@option{-help}]
1092   [@option{-version}]
1093 @end ignore
1094 @c man end
1096 @c man begin DESCRIPTION grmic
1098 @command{grmic} is a utility included with @code{libgcj} which generates
1099 stubs for remote objects.
1101 @c FIXME: Add real information here.
1102 @c This really isn't much more than the --help output.
1104 Note that this program isn't yet fully compatible with the JDK
1105 @command{grmic}.  Some options, such as @option{-classpath}, are
1106 recognized but currently ignored.  We have left these options
1107 undocumented for now.
1109 Long options can also be given with a GNU-style leading @samp{--}.  For
1110 instance, @option{--help} is accepted.
1112 @c man end
1114 @c man begin OPTIONS grmic
1116 @table @gcctabopt
1117 @item -keep
1118 @itemx -keepgenerated
1119 By default, @command{grmic} deletes intermediate files.  Either of these
1120 options causes it not to delete such files.
1122 @item -v1.1
1123 Cause @command{grmic} to create stubs and skeletons for the 1.1
1124 protocol version.
1126 @item -vcompat
1127 Cause @command{grmic} to create stubs and skeletons compatible with both
1128 the 1.1 and 1.2 protocol versions.  This is the default.
1130 @item -v1.2
1131 Cause @command{grmic} to create stubs and skeletons for the 1.2
1132 protocol version.
1134 @item -nocompile
1135 Don't compile the generated files.
1137 @item -verbose
1138 Print information about what @command{grmic} is doing.
1140 @item -d @var{directory}
1141 Put output files in @var{directory}.  By default the files are put in
1142 the current working directory.
1144 @item -help
1145 Print a help message, then exit.
1147 @item -version
1148 Print version information, then exit.
1149 @end table
1151 @c man end
1154 @node Invoking gc-analyze
1155 @chapter Invoking gc-analyze
1157 @c man title gc-analyze Analyze Garbage Collector (GC) memory dumps
1159 @c man begin SYNOPSIS gc-analyze
1160 @command{gc-analyze} [@option{OPTION}] @dots{} [@var{file}]
1161 @ignore
1162   [@option{-v}]
1163   [@option{--verbose}]
1164   [@option{-p} @var{tool-prefix}]
1165   [@option{-d} @var{directory}]
1166   [@option{--version}]
1167   [@option{--help}]
1168 @end ignore
1169 @c man end
1171 @c man begin DESCRIPTION gc-analyze
1173 @command{gc-analyze} prints an analysis of a GC memory dump to
1174 standard out.
1176 The memory dumps may be created by calling
1177 @code{gnu.gcj.util.GCInfo.enumerate(String namePrefix)} from java
1178 code.  A memory dump will be created on an out of memory condition if
1179 @code{gnu.gcj.util.GCInfo.setOOMDump(String namePrefix)} is called
1180 before the out of memory occurs.
1182 Running this program will create two files: @file{TestDump001} and
1183 @file{TestDump001.bytes}.
1185 @example
1186 import gnu.gcj.util.*;
1187 import java.util.*;
1189 public class GCDumpTest
1191     static public void main(String args[])
1192     @{
1193         ArrayList<String> l = new ArrayList<String>(1000);
1195         for (int i = 1; i < 1500; i++) @{
1196             l.add("This is string #" + i);
1197         @}
1198         GCInfo.enumerate("TestDump");
1199     @}
1201 @end example
1203 The memory dump may then be displayed by running:
1205 @example
1206 gc-analyze -v TestDump001
1207 @end example
1209 @c FIXME: Add real information here.
1210 @c This really isn't much more than the --help output.
1212 @c man end
1214 @c man begin OPTIONS gc-analyze
1216 @table @gcctabopt
1217 @item --verbose
1218 @itemx -v
1219 Verbose output.
1221 @item -p @var{tool-prefix}
1222 Prefix added to the names of the @command{nm} and @command{readelf} commands.
1224 @item -d @var{directory}
1225 Directory that contains the executable and shared libraries used when
1226 the dump was generated.
1228 @item --help
1229 Print a help message, then exit.
1231 @item --version
1232 Print version information, then exit.
1233 @end table
1235 @c man end
1237 @node Invoking aot-compile
1238 @chapter Invoking aot-compile
1240 @c man title aot-compile Compile bytecode to native and generate databases
1242 @ignore
1244 @c man begin SYNOPSIS aot-compile
1245 aot-compile [@option{OPTION}] @dots{} @var{SRCDIR} @var{DSTDIR}
1247 aot-compile [@option{-M, --make}=@var{PATH}] [@option{-C, --gcj}=@var{PATH}]
1248   [@option{-D, --dbtool}=@var{PATH}] [@option{-m, --makeflags}=@var{FLAGS}] 
1249   [@option{-c, --gcjflags}=@var{FLAGS}] [@option{-l, --ldflags}=@var{FLAGS}] 
1250   [@option{-e, --exclude}=@var{PATH}]
1251 @c man end
1253 @c man begin SEEALSO aot-compile
1254 gcc(1), gcj(1), gcjh(1), jcf-dump(1), gfdl(7),
1255 and the Info entries for @file{gcj} and @file{gcc}.
1256 @c man end
1258 @end ignore
1260 @c man begin DESCRIPTION aot-compile
1261 @code{aot-compile} is a script that searches a directory for Java bytecode
1262 (as class files, or in jars) and uses @code{gcj} to compile it to native
1263 code and generate the databases from it.
1264 @c man end
1266 @c man begin OPTIONS aot-compile
1267 @table @gcctabopt
1268 @item -M, --make=@var{PATH}
1269 Specify the path to the @code{make} executable to use.
1271 @item -C, --gcj=@var{PATH}
1272 Specify the path to the @code{gcj} executable to use.
1274 @item -D, --dbtool=@var{PATH}
1275 Specify the path to the @code{gcj-dbtool} executable to use.
1277 @item -m, --makeflags=@var{FLAGS}
1278 Specify flags to pass to @code{make} during the build.
1280 @item -c, --gcjflags=@var{FLAGS}
1281 Specify flags to pass to @code{gcj} during compilation, in addition to
1282 '-fPIC -findirect-dispatch -fjni'.
1284 @item -l, --ldflags=@var{FLAGS}
1285 Specify flags to pass to @code{gcj} during linking, in addition to
1286 '-Wl,-Bsymbolic'.
1288 @item -e, --exclude=@var{PATH}
1289 Do not compile @var{PATH}.
1291 @end table
1293 @c man end
1295 @node Invoking rebuild-gcj-db
1296 @chapter Invoking rebuild-gcj-db
1298 @c man title rebuild-gcj-db Merge the per-solib databases made by aot-compile into one system-wide database.
1299 @ignore
1301 @c man begin SYNOPSIS rebuild-gcj-db
1302 rebuild-gcj-db
1303 @c man end
1305 @c man begin SEEALSO rebuild-gcj-db
1306 gcc(1), gcj(1), gcjh(1), jcf-dump(1), gfdl(7),
1307 and the Info entries for @file{gcj} and @file{gcc}.
1308 @c man end
1310 @end ignore
1312 @c man begin DESCRIPTION rebuild-gcj-db
1313 @code{rebuild-gcj-db} is a script that merges the per-solib databases made by
1314 @code{aot-compile} into one system-wide database so @code{gij} can find the 
1315 solibs.
1316 @c man end
1318 @node About CNI
1319 @chapter About CNI
1321 This documents CNI, the Compiled Native Interface,
1322 which is is a convenient way to write Java native methods using C++.
1323 This is a more efficient, more convenient, but less portable
1324 alternative to the standard JNI (Java Native Interface).
1326 @menu
1327 * Basic concepts::              Introduction to using CNI@.
1328 * Packages::                    How packages are mapped to C++.
1329 * Primitive types::             Handling primitive Java types in C++.
1330 * Reference types::             Handling Java reference types in C++.
1331 * Interfaces::                  How Java interfaces map to C++.
1332 * Objects and Classes::         C++ and Java classes.
1333 * Class Initialization::        How objects are initialized.
1334 * Object allocation::           How to create Java objects in C++.
1335 * Memory allocation::           How to allocate and free memory.
1336 * Arrays::                      Dealing with Java arrays in C++.
1337 * Methods::                     Java methods in C++.
1338 * Strings::                     Information about Java Strings.
1339 * Mixing with C++::             How CNI can interoperate with C++.
1340 * Exception Handling::          How exceptions are handled.
1341 * Synchronization::             Synchronizing between Java and C++.
1342 * Invocation::                  Starting the Java runtime from C++.
1343 * Reflection::                  Using reflection from C++.
1344 @end menu
1347 @node Basic concepts
1348 @section Basic concepts
1350 In terms of languages features, Java is mostly a subset
1351 of C++.  Java has a few important extensions, plus a powerful standard
1352 class library, but on the whole that does not change the basic similarity.
1353 Java is a hybrid object-oriented language, with a few native types,
1354 in addition to class types.  It is class-based, where a class may have
1355 static as well as per-object fields, and static as well as instance methods.
1356 Non-static methods may be virtual, and may be overloaded.  Overloading is
1357 resolved at compile time by matching the actual argument types against
1358 the parameter types.  Virtual methods are implemented using indirect calls
1359 through a dispatch table (virtual function table).  Objects are
1360 allocated on the heap, and initialized using a constructor method.
1361 Classes are organized in a package hierarchy.
1363 All of the listed attributes are also true of C++, though C++ has
1364 extra features (for example in C++ objects may be allocated not just
1365 on the heap, but also statically or in a local stack frame).  Because
1366 @command{gcj} uses the same compiler technology as G++ (the GNU
1367 C++ compiler), it is possible to make the intersection of the two
1368 languages use the same ABI (object representation and calling
1369 conventions).  The key idea in CNI is that Java objects are C++
1370 objects, and all Java classes are C++ classes (but not the other way
1371 around).  So the most important task in integrating Java and C++ is to
1372 remove gratuitous incompatibilities.
1374 You write CNI code as a regular C++ source file.  (You do have to use
1375 a Java/CNI-aware C++ compiler, specifically a recent version of G++.)
1377 @noindent A CNI C++ source file must have:
1379 @example
1380 #include <gcj/cni.h>
1381 @end example
1383 @noindent and then must include one header file for each Java class it uses, e.g.:
1385 @example
1386 #include <java/lang/Character.h>
1387 #include <java/util/Date.h>
1388 #include <java/lang/IndexOutOfBoundsException.h>
1389 @end example
1391 @noindent These header files are automatically generated by @code{gcjh}.
1394 CNI provides some functions and macros to make using Java objects and
1395 primitive types from C++ easier.  In general, these CNI functions and
1396 macros start with the @code{Jv} prefix, for example the function
1397 @code{JvNewObjectArray}.  This convention is used to avoid conflicts
1398 with other libraries.  Internal functions in CNI start with the prefix
1399 @code{_Jv_}.  You should not call these; if you find a need to, let us
1400 know and we will try to come up with an alternate solution.
1403 @subsection Limitations
1405 Whilst a Java class is just a C++ class that doesn't mean that you are
1406 freed from the shackles of Java, a @acronym{CNI} C++ class must adhere to the
1407 rules of the Java programming language.
1409 For example: it is not possible to declare a method in a CNI class
1410 that will take a C string (@code{char*}) as an argument, or to declare a
1411 member variable of some non-Java datatype.
1414 @node Packages
1415 @section Packages
1417 The only global names in Java are class names, and packages.  A
1418 @dfn{package} can contain zero or more classes, and also zero or more
1419 sub-packages.  Every class belongs to either an unnamed package or a
1420 package that has a hierarchical and globally unique name.
1422 A Java package is mapped to a C++ @dfn{namespace}.  The Java class
1423 @code{java.lang.String} is in the package @code{java.lang}, which is a
1424 sub-package of @code{java}.  The C++ equivalent is the class
1425 @code{java::lang::String}, which is in the namespace @code{java::lang}
1426 which is in the namespace @code{java}.
1428 @noindent Here is how you could express this:
1430 @example
1431 (// @r{Declare the class(es), possibly in a header file:}
1432 namespace java @{
1433   namespace lang @{
1434     class Object;
1435     class String;
1436     ...
1437   @}
1440 class java::lang::String : public java::lang::Object
1442   ...
1444 @end example
1446 @noindent The @code{gcjh} tool automatically generates the necessary namespace
1447 declarations.
1450 @subsection Leaving out package names
1452 Always using the fully-qualified name of a java class can be
1453 tiresomely verbose.  Using the full qualified name also ties the code
1454 to a single package making code changes necessary should the class
1455 move from one package to another.  The Java @code{package} declaration
1456 specifies that the following class declarations are in the named
1457 package, without having to explicitly name the full package
1458 qualifiers.  The @code{package} declaration can be
1459 followed by zero or more @code{import} declarations, which
1460 allows either a single class or all the classes in a package to be
1461 named by a simple identifier.  C++ provides something similar with the
1462 @code{using} declaration and directive.
1464 @noindent In Java:
1466 @example
1467 import @var{package-name}.@var{class-name};
1468 @end example
1470 @noindent allows the program text to refer to @var{class-name} as a shorthand for 
1471 the fully qualified name: @code{@var{package-name}.@var{class-name}}.
1474 @noindent To achieve the same effect C++, you have to do this:
1476 @example
1477 using @var{package-name}::@var{class-name};
1478 @end example
1481 @noindent Java can also cause imports on demand, like this:
1483 @example
1484 import @var{package-name}.*;
1485 @end example
1487 @noindent Doing this allows any class from the package @var{package-name} to be
1488 referred to only by its class-name within the program text.
1491 @noindent The same effect can be achieved in C++ like this:
1493 @example
1494 using namespace @var{package-name};
1495 @end example
1498 @node Primitive types
1499 @section Primitive types
1501 Java provides 8 @dfn{primitives} types which represent integers, floats, 
1502 characters and booleans (and also the void type).  C++ has its own
1503 very similar concrete types.  Such types in C++ however are not always
1504 implemented in the same way (an int might be 16, 32 or 64 bits for example) 
1505 so CNI provides a special C++ type for each primitive Java type:
1507 @multitable @columnfractions .20 .25 .60
1508 @item @strong{Java type}   @tab @strong{C/C++ typename} @tab @strong{Description}
1509 @item @code{char}        @tab @code{jchar}          @tab 16 bit Unicode character
1510 @item @code{boolean}     @tab @code{jboolean}       @tab logical (true or false) values
1511 @item @code{byte}        @tab @code{jbyte}          @tab 8-bit signed integer
1512 @item @code{short}       @tab @code{jshort}         @tab 16 bit signed integer
1513 @item @code{int}         @tab @code{jint}           @tab 32 bit signed integer
1514 @item @code{long}        @tab @code{jlong}          @tab 64 bit signed integer
1515 @item @code{float}       @tab @code{jfloat}         @tab 32 bit IEEE floating point number
1516 @item @code{double}      @tab @code{jdouble}        @tab 64 bit IEEE floating point number
1517 @item @code{void}        @tab @code{void}           @tab no value
1518 @end multitable
1520 When referring to a Java type You should always use these C++ typenames (e.g.: @code{jint})
1521 to avoid disappointment.
1524 @subsection Reference types associated with primitive types
1526 In Java each primitive type has an associated reference type, 
1527 e.g.: @code{boolean} has an associated @code{java.lang.Boolean.TYPE} class.
1528 In order to make working with such classes easier GCJ provides the macro
1529 @code{JvPrimClass}:
1531 @deffn macro JvPrimClass type
1532 Return a pointer to the @code{Class} object corresponding to the type supplied.
1534 @example
1535 JvPrimClass(void) @result{} java.lang.Void.TYPE
1536 @end example
1538 @end deffn
1541 @node Reference types
1542 @section Reference types
1544 A Java reference type is treated as a class in C++.  Classes and
1545 interfaces are handled this way.  A Java reference is translated to a
1546 C++ pointer, so for instance a Java @code{java.lang.String} becomes,
1547 in C++, @code{java::lang::String *}.
1549 CNI provides a few built-in typedefs for the most common classes:
1550 @multitable @columnfractions .30 .25 .60
1551 @item @strong{Java type} @tab @strong{C++ typename} @tab @strong{Description}
1552 @item @code{java.lang.Object} @tab @code{jobject} @tab Object type
1553 @item @code{java.lang.String} @tab @code{jstring} @tab String type
1554 @item @code{java.lang.Class} @tab @code{jclass} @tab Class type
1555 @end multitable
1556 @cindex jobject
1557 @cindex jstring
1558 @cindex jclass
1560 Every Java class or interface has a corresponding @code{Class}
1561 instance.  These can be accessed in CNI via the static @code{class$}
1562 field of a class.  The @code{class$} field is of type @code{Class}
1563 (and not @code{Class *}), so you will typically take the address of
1565 @cindex class$
1567 Here is how you can refer to the class of @code{String}, which in
1568 Java would be written @code{String.class}:
1570 @example
1571 using namespace java::lang;
1572 doSomething (&String::class$);
1573 @end example
1576 @node Interfaces
1577 @section Interfaces
1579 A Java class can @dfn{implement} zero or more
1580 @dfn{interfaces}, in addition to inheriting from
1581 a single base class. 
1583 @acronym{CNI} allows CNI code to implement methods of interfaces.
1584 You can also call methods through interface references, with some
1585 limitations.
1587 @acronym{CNI} doesn't understand interface inheritance at all yet.  So,
1588 you can only call an interface method when the declared type of the
1589 field being called matches the interface which declares that
1590 method.  The workaround is to cast the interface reference to the right
1591 superinterface.
1593 For example if you have: 
1595 @example 
1596 interface A 
1597 @{ 
1598   void a(); 
1599 @} 
1601 interface B extends A 
1602 @{ 
1603   void b(); 
1604 @} 
1605 @end example
1607 and declare a variable of type @code{B} in C++, you can't call
1608 @code{a()} unless you cast it to an @code{A} first.
1610 @node Objects and Classes
1611 @section Objects and Classes
1613 @subsection Classes
1615 All Java classes are derived from @code{java.lang.Object}.  C++ does
1616 not have a unique root class, but we use the C++ class
1617 @code{java::lang::Object} as the C++ version of the
1618 @code{java.lang.Object} Java class.  All other Java classes are mapped
1619 into corresponding C++ classes derived from @code{java::lang::Object}.
1621 Interface inheritance (the @code{implements} keyword) is currently not
1622 reflected in the C++ mapping.
1625 @subsection Object fields
1627 Each object contains an object header, followed by the instance fields
1628 of the class, in order.  The object header consists of a single
1629 pointer to a dispatch or virtual function table.  (There may be extra
1630 fields @emph{in front of} the object, for example for memory
1631 management, but this is invisible to the application, and the
1632 reference to the object points to the dispatch table pointer.)
1634 The fields are laid out in the same order, alignment, and size as in
1635 C++.  Specifically, 8-bit and 16-bit native types (@code{byte},
1636 @code{short}, @code{char}, and @code{boolean}) are @emph{not} widened
1637 to 32 bits.  Note that the Java VM does extend 8-bit and 16-bit types
1638 to 32 bits when on the VM stack or temporary registers.
1640 If you include the @code{gcjh}-generated header for a
1641 class, you can access fields of Java classes in the @emph{natural}
1642 way.  For example, given the following Java class:
1644 @example
1645 public class Int
1647   public int i;
1648   public Int (int i) @{ this.i = i; @}
1649   public static Int zero = new Int(0);
1651 @end example
1653 you can write:
1655 @example
1656 #include <gcj/cni.h>;
1657 #include <Int>;
1659 Int*
1660 mult (Int *p, jint k)
1662   if (k == 0)
1663     return Int::zero;  // @r{Static member access.}
1664   return new Int(p->i * k);
1666 @end example
1669 @subsection Access specifiers
1671 CNI does not strictly enforce the Java access
1672 specifiers, because Java permissions cannot be directly mapped
1673 into C++ permission.  Private Java fields and methods are mapped
1674 to private C++ fields and methods, but other fields and methods
1675 are mapped to public fields and methods.
1679 @node Class Initialization
1680 @section Class Initialization
1682 Java requires that each class be automatically initialized at the time 
1683 of the first active use.  Initializing a class involves 
1684 initializing the static fields, running code in class initializer 
1685 methods, and initializing base classes.  There may also be 
1686 some implementation specific actions, such as allocating 
1687 @code{String} objects corresponding to string literals in
1688 the code.
1690 The GCJ compiler inserts calls to @code{JvInitClass} at appropriate
1691 places to ensure that a class is initialized when required.  The C++
1692 compiler does not insert these calls automatically---it is the
1693 programmer's responsibility to make sure classes are initialized.
1694 However, this is fairly painless because of the conventions assumed by
1695 the Java system.
1697 First, @code{libgcj} will make sure a class is initialized before an
1698 instance of that object is created.  This is one of the
1699 responsibilities of the @code{new} operation.  This is taken care of
1700 both in Java code, and in C++ code.  When G++ sees a @code{new} of a
1701 Java class, it will call a routine in @code{libgcj} to allocate the
1702 object, and that routine will take care of initializing the class.
1703 Note however that this does not happen for Java arrays; you must
1704 allocate those using the appropriate CNI function.  It follows that
1705 you can access an instance field, or call an instance (non-static)
1706 method and be safe in the knowledge that the class and all of its base
1707 classes have been initialized.
1709 Invoking a static method is also safe.  This is because the
1710 Java compiler adds code to the start of a static method to make sure
1711 the class is initialized.  However, the C++ compiler does not
1712 add this extra code.  Hence, if you write a native static method
1713 using CNI, you are responsible for calling @code{JvInitClass}
1714 before doing anything else in the method (unless you are sure
1715 it is safe to leave it out).
1717 Accessing a static field also requires the class of the
1718 field to be initialized.  The Java compiler will generate code
1719 to call @code{JvInitClass} before getting or setting the field.
1720 However, the C++ compiler will not generate this extra code,
1721 so it is your responsibility to make sure the class is
1722 initialized before you access a static field from C++.
1725 @node Object allocation
1726 @section Object allocation
1728 New Java objects are allocated using a
1729 @dfn{class instance creation expression}, e.g.:
1731 @example
1732 new @var{Type} ( ... )
1733 @end example
1735 The same syntax is used in C++.  The main difference is that
1736 C++ objects have to be explicitly deleted; in Java they are
1737 automatically deleted by the garbage collector.
1738 Using @acronym{CNI}, you can allocate a new Java object
1739 using standard C++ syntax and the C++ compiler will allocate
1740 memory from the garbage collector.  If you have overloaded
1741 constructors, the compiler will choose the correct one
1742 using standard C++ overload resolution rules.  
1744 @noindent For example:
1746 @example
1747 java::util::Hashtable *ht = new java::util::Hashtable(120);
1748 @end example
1751 @node Memory allocation
1752 @section Memory allocation
1754 When allocating memory in @acronym{CNI} methods it is best to handle
1755 out-of-memory conditions by throwing a Java exception.  These
1756 functions are provided for that purpose:
1758 @deftypefun void* JvMalloc (jsize @var{size})
1759 Calls malloc.  Throws @code{java.lang.OutOfMemoryError} if allocation
1760 fails.
1761 @end deftypefun
1763 @deftypefun void* JvRealloc (void* @var{ptr}, jsize @var{size})
1764 Calls realloc.  Throws @code{java.lang.OutOfMemoryError} if
1765 reallocation fails.
1766 @end deftypefun
1768 @deftypefun void JvFree (void* @var{ptr})
1769 Calls free.
1770 @end deftypefun
1772 @node Arrays
1773 @section Arrays
1775 While in many ways Java is similar to C and C++, it is quite different
1776 in its treatment of arrays.  C arrays are based on the idea of pointer
1777 arithmetic, which would be incompatible with Java's security
1778 requirements.  Java arrays are true objects (array types inherit from
1779 @code{java.lang.Object}).  An array-valued variable is one that
1780 contains a reference (pointer) to an array object.
1782 Referencing a Java array in C++ code is done using the
1783 @code{JArray} template, which as defined as follows:
1785 @example
1786 class __JArray : public java::lang::Object
1788 public:
1789   int length;
1792 template<class T>
1793 class JArray : public __JArray
1795   T data[0];
1796 public:
1797   T& operator[](jint i) @{ return data[i]; @}
1799 @end example
1802 There are a number of @code{typedef}s which correspond to @code{typedef}s 
1803 from the @acronym{JNI}.  Each is the type of an array holding objects
1804 of the relevant type:
1806 @example
1807 typedef __JArray *jarray;
1808 typedef JArray<jobject> *jobjectArray;
1809 typedef JArray<jboolean> *jbooleanArray;
1810 typedef JArray<jbyte> *jbyteArray;
1811 typedef JArray<jchar> *jcharArray;
1812 typedef JArray<jshort> *jshortArray;
1813 typedef JArray<jint> *jintArray;
1814 typedef JArray<jlong> *jlongArray;
1815 typedef JArray<jfloat> *jfloatArray;
1816 typedef JArray<jdouble> *jdoubleArray;
1817 @end example
1820 @deftypemethod {template<class T>} T* elements (JArray<T> @var{array})
1821 This template function can be used to get a pointer to the elements of
1822 the @code{array}.  For instance, you can fetch a pointer to the
1823 integers that make up an @code{int[]} like so:
1825 @example
1826 extern jintArray foo;
1827 jint *intp = elements (foo);
1828 @end example
1830 The name of this function may change in the future.
1831 @end deftypemethod
1834 @deftypefun jobjectArray JvNewObjectArray (jsize @var{length}, jclass @var{klass}, jobject @var{init})
1835 This creates a new array whose elements have reference type.
1836 @code{klass} is the type of elements of the array and
1837 @code{init} is the initial value put into every slot in the array.
1838 @end deftypefun
1840 @example
1841 using namespace java::lang;
1842 JArray<String *> *array
1843   = (JArray<String *> *) JvNewObjectArray(length, &String::class$, NULL);
1844 @end example
1847 @subsection Creating arrays
1849 For each primitive type there is a function which can be used to
1850 create a new array of that type.  The name of the function is of the
1851 form:
1853 @example
1854 JvNew@var{Type}Array
1855 @end example
1857 @noindent For example:
1859 @example
1860 JvNewBooleanArray
1861 @end example
1863 @noindent can be used to create an array of Java primitive boolean types.
1865 @noindent The following function definition is the template for all such functions:
1867 @deftypefun jbooleanArray JvNewBooleanArray (jint @var{length})
1868 Creates an array @var{length} indices long.
1869 @end deftypefun
1871 @deftypefun jsize JvGetArrayLength (jarray @var{array})
1872 Returns the length of the @var{array}.
1873 @end deftypefun
1876 @node Methods
1877 @section Methods
1879 Java methods are mapped directly into C++ methods.
1880 The header files generated by @code{gcjh}
1881 include the appropriate method definitions.
1882 Basically, the generated methods have the same names and
1883 @emph{corresponding} types as the Java methods,
1884 and are called in the natural manner.
1886 @subsection Overloading
1888 Both Java and C++ provide method overloading, where multiple
1889 methods in a class have the same name, and the correct one is chosen
1890 (at compile time) depending on the argument types.
1891 The rules for choosing the correct method are (as expected) more complicated
1892 in C++ than in Java, but given a set of overloaded methods
1893 generated by @code{gcjh} the C++ compiler will choose
1894 the expected one.
1896 Common assemblers and linkers are not aware of C++ overloading,
1897 so the standard implementation strategy is to encode the
1898 parameter types of a method into its assembly-level name.
1899 This encoding is called @dfn{mangling},
1900 and the encoded name is the @dfn{mangled name}.
1901 The same mechanism is used to implement Java overloading.
1902 For C++/Java interoperability, it is important that both the Java
1903 and C++ compilers use the @emph{same} encoding scheme.
1905 @subsection Static methods
1907 Static Java methods are invoked in @acronym{CNI} using the standard
1908 C++ syntax, using the @code{::} operator rather
1909 than the @code{.} operator.  
1911 @noindent For example:
1913 @example
1914 jint i = java::lang::Math::round((jfloat) 2.3);
1915 @end example
1917 @noindent C++ method definition syntax is used to define a static native method.
1918 For example:
1920 @example
1921 #include <java/lang/Integer>
1922 java::lang::Integer*
1923 java::lang::Integer::getInteger(jstring str)
1925   ...
1927 @end example
1930 @subsection Object Constructors
1932 Constructors are called implicitly as part of object allocation
1933 using the @code{new} operator.  
1935 @noindent For example:
1937 @example
1938 java::lang::Integer *x = new java::lang::Integer(234);
1939 @end example
1941 Java does not allow a constructor to be a native method.
1942 This limitation can be coded round however because a constructor
1943 can @emph{call} a native method.
1946 @subsection Instance methods
1948 Calling a Java instance method from a C++ @acronym{CNI} method is done 
1949 using the standard C++ syntax, e.g.:
1951 @example
1952 // @r{First create the Java object.}
1953 java::lang::Integer *x = new java::lang::Integer(234);
1954 // @r{Now call a method.}
1955 jint prim_value = x->intValue();
1956 if (x->longValue == 0) 
1957   ...
1958 @end example
1960 @noindent Defining a Java native instance method is also done the natural way:
1962 @example
1963 #include <java/lang/Integer.h>
1965 jdouble
1966 java::lang:Integer::doubleValue()
1968   return (jdouble) value;
1970 @end example
1973 @subsection Interface methods
1975 In Java you can call a method using an interface reference.  This is
1976 supported, but not completely.  @xref{Interfaces}.
1981 @node Strings
1982 @section Strings
1984 @acronym{CNI} provides a number of utility functions for
1985 working with Java Java @code{String} objects.
1986 The names and interfaces are analogous to those of @acronym{JNI}.
1989 @deftypefun jstring JvNewString (const jchar* @var{chars}, jsize @var{len})
1990 Returns a Java @code{String} object with characters from the array of 
1991 Unicode characters @var{chars} up to the index @var{len} in that array.
1992 @end deftypefun
1994 @deftypefun jstring JvNewStringLatin1 (const char* @var{bytes}, jsize @var{len})
1995 Returns a Java @code{String} made up of @var{len} bytes from @var{bytes}.
1996 @end deftypefun
1999 @deftypefun jstring JvNewStringLatin1 (const char* @var{bytes})
2000 As above but the length of the @code{String} is @code{strlen(@var{bytes})}.
2001 @end deftypefun
2003 @deftypefun jstring JvNewStringUTF (const char* @var{bytes})
2004 Returns a @code{String} which is made up of the UTF encoded characters
2005 present in the C string @var{bytes}.
2006 @end deftypefun
2008 @deftypefun jchar* JvGetStringChars (jstring @var{str})
2009 Returns a pointer to an array of characters making up the @code{String} @var{str}.
2010 @end deftypefun
2012 @deftypefun int JvGetStringUTFLength (jstring @var{str})
2013 Returns the number of bytes required to encode the contents of the
2014 @code{String} @var{str} in UTF-8.
2015 @end deftypefun
2017 @deftypefun jsize JvGetStringUTFRegion (jstring @var{str}, jsize @var{start}, jsize @var{len}, char* @var{buf})
2018 Puts the UTF-8 encoding of a region of the @code{String} @var{str} into 
2019 the buffer @code{buf}.  The region to fetch is marked by @var{start} and @var{len}.
2021 Note that @var{buf} is a buffer, not a C string.  It is @emph{not} 
2022 null terminated.
2023 @end deftypefun
2026 @node Mixing with C++
2027 @section Interoperating with C/C++
2029 Because @acronym{CNI} is designed to represent Java classes and methods it
2030 cannot be mixed readily with C/C++ types.
2032 One important restriction is that Java classes cannot have non-Java
2033 type instance or static variables and cannot have methods which take
2034 non-Java types as arguments or return non-Java types.
2036 @noindent None of the following is possible with CNI:
2038 @example
2040 class ::MyClass : public java::lang::Object
2042    char* variable;  // @r{char* is not a valid Java type.}
2046 uint
2047 ::SomeClass::someMethod (char *arg)
2049   .
2050   .
2051   .
2052 @}   // @r{@code{uint} is not a valid Java type, neither is @code{char*}}
2053 @end example
2055 @noindent Of course, it is ok to use C/C++ types within the scope of a method:
2058 @example
2059 jint
2060 ::SomeClass::otherMethod (jstring str)
2062    char *arg = ...
2063    .
2064    .
2065    .
2067 @end example
2069 @subsection RawData
2071 The above restriction can be problematic, so @acronym{CNI} includes the
2072 @code{gnu.gcj.RawData} class.  The @code{RawData} class is a
2073 @dfn{non-scanned reference} type.  In other words variables declared
2074 of type @code{RawData} can contain any data and are not checked by the
2075 compiler or memory manager in any way.
2077 This means that you can put C/C++ data structures (including classes)
2078 in your @acronym{CNI} classes, as long as you use the appropriate cast.
2080 @noindent Here are some examples:
2082 @example
2084 class ::MyClass : public java::lang::Object
2086    gnu.gcj.RawData string;
2088    MyClass ();
2089    gnu.gcj.RawData getText ();
2090    void printText ();
2093 ::MyClass::MyClass ()
2095    char* text = ...
2096    string = text;
2099 gnu.gcj.RawData
2100 ::MyClass::getText ()
2102    return string;
2105 void
2106 ::MyClass::printText ()
2108   printf("%s\n", (char*) string);
2110 @end example
2113 @subsection RawDataManaged
2115 @code{gnu.gcj.RawDataManaged} is another type used to indicate special data used 
2116 by native code. Unlike the @code{RawData} type, fields declared as 
2117 @code{RawDataManaged} will be "marked" by the memory manager and 
2118 considered for garbage collection.  
2120 Native data which is allocated using CNI's @code{JvAllocBytes()}
2121 function and stored in a @code{RawDataManaged} will be automatically 
2122 freed when the Java object it is associated with becomes unreachable.
2124 @subsection Native memory allocation
2126 @deftypefun void* JvAllocBytes (jsize @var{size})
2127 Allocates @var{size} bytes from the heap.  The memory returned is zeroed.
2128 This memory is not scanned for pointers by the garbage collector, but will 
2129 be freed if no references to it are discovered.
2131 This function can be useful if you need to associate some native data with a
2132 Java object. Using a CNI's special @code{RawDataManaged} type, native data 
2133 allocated with @code{JvAllocBytes} will be automatically freed when the Java 
2134 object itself becomes unreachable.
2135 @end deftypefun
2137 @subsection Posix signals
2139 On Posix based systems the @code{libgcj} library uses several signals
2140 internally.  @acronym{CNI} code should not attempt to use the same
2141 signals as doing so may cause @code{libgcj} and/or the @acronym{CNI}
2142 code to fail.
2144 SIGSEGV is used on many systems to generate
2145 @code{NullPointerExceptions}.  SIGCHLD is used internally by
2146 @code{Runtime.exec()}.  Several other signals (that vary from platform to
2147 platform) can be used by the memory manager and by
2148 @code{Thread.interrupt()}.
2150 @node Exception Handling
2151 @section Exception Handling
2153 While C++ and Java share a common exception handling framework,
2154 things are not yet perfectly integrated.  The main issue is that the
2155 run-time type information facilities of the two
2156 languages are not integrated.
2158 Still, things work fairly well.  You can throw a Java exception from
2159 C++ using the ordinary @code{throw} construct, and this
2160 exception can be caught by Java code.  Similarly, you can catch an
2161 exception thrown from Java using the C++ @code{catch}
2162 construct.
2164 @noindent Here is an example:
2166 @example
2167 if (i >= count)
2168    throw new java::lang::IndexOutOfBoundsException();
2169 @end example
2171 Normally, G++ will automatically detect when you are writing C++
2172 code that uses Java exceptions, and handle them appropriately.
2173 However, if C++ code only needs to execute destructors when Java
2174 exceptions are thrown through it, GCC will guess incorrectly.  Sample
2175 problematic code:
2177 @example
2178 struct S @{ ~S(); @};
2180 extern void bar();    // @r{Is implemented in Java and may throw exceptions.}
2182 void foo()
2184   S s;
2185   bar();
2187 @end example
2189 The usual effect of an incorrect guess is a link failure, complaining of
2190 a missing routine called @code{__gxx_personality_v0}.
2192 You can inform the compiler that Java exceptions are to be used in a
2193 translation unit, irrespective of what it might think, by writing
2194 @code{#pragma GCC java_exceptions} at the head of the
2195 file.  This @code{#pragma} must appear before any
2196 functions that throw or catch exceptions, or run destructors when
2197 exceptions are thrown through them.
2199 @node Synchronization
2200 @section Synchronization
2202 Each Java object has an implicit monitor.
2203 The Java VM uses the instruction @code{monitorenter} to acquire
2204 and lock a monitor, and @code{monitorexit} to release it.
2206 The corresponding CNI macros are @code{JvMonitorEnter} and 
2207 @code{JvMonitorExit} (JNI has similar  methods @code{MonitorEnter}
2208 and @code{MonitorExit}).  
2211 The Java source language does not provide direct access to these primitives.
2212 Instead, there is a @code{synchronized} statement that does an
2213 implicit @code{monitorenter} before entry to the block,
2214 and does a @code{monitorexit} on exit from the block.
2215 Note that the lock has to be released even when the block is abnormally
2216 terminated by an exception, which means there is an implicit
2217 @code{try finally} surrounding synchronization locks.
2219 From C++, it makes sense to use a destructor to release a lock.
2220 @acronym{CNI} defines the following utility class:
2222 @example
2223 class JvSynchronize() @{
2224   jobject obj;
2225   JvSynchronize(jobject o) @{ obj = o; JvMonitorEnter(o); @}
2226   ~JvSynchronize() @{ JvMonitorExit(obj); @}
2228 @end example
2230 So this Java code:
2232 @example
2233 synchronized (OBJ)
2235    CODE
2237 @end example
2239 @noindent might become this C++ code:
2241 @example
2243    JvSynchronize dummy (OBJ);
2244    CODE;
2246 @end example
2248 Java also has methods with the @code{synchronized} attribute.
2249 This is equivalent to wrapping the entire method body in a
2250 @code{synchronized} statement.
2251 (Alternatively, an implementation could require the caller to do
2252 the synchronization.  This is not practical for a compiler, because
2253 each virtual method call would have to test at run-time if
2254 synchronization is needed.)  Since in @command{gcj}
2255 the @code{synchronized} attribute is handled by the
2256 method implementation, it is up to the programmer
2257 of a synchronized native method to handle the synchronization
2258 (in the C++ implementation of the method).
2259 In other words, you need to manually add @code{JvSynchronize}
2260 in a @code{native synchronized} method.
2262 @node Invocation
2263 @section Invocation
2265 CNI permits C++ applications to make calls into Java classes, in addition to
2266 allowing Java code to call into C++. Several functions, known as the 
2267 @dfn{invocation API}, are provided to support this.
2269 @deftypefun jint JvCreateJavaVM (JvVMInitArgs* @var{vm_args})
2271 Initializes the Java runtime. This function performs essential initialization
2272 of the threads interface, garbage collector, exception handling and other key
2273 aspects of the runtime. It must be called once by an application with
2274 a non-Java @code{main()} function, before any other Java or CNI calls are made.
2275 It is safe, but not recommended, to call @code{JvCreateJavaVM()} more than
2276 once provided it is only called from a single thread.
2277 The @var{vmargs} parameter can be used to specify initialization parameters 
2278 for the Java runtime. It may be @code{NULL}.
2280 JvVMInitArgs represents a list of virtual machine initialization
2281 arguments. @code{JvCreateJavaVM()} ignores the version field.
2283 @example
2284 typedef struct JvVMOption
2286   // a VM initialization option
2287   char* optionString;
2288   // extra information associated with this option
2289   void* extraInfo;
2290 @} JvVMOption;
2292 typedef struct JvVMInitArgs
2294   // for compatibility with JavaVMInitArgs
2295   jint version;
2297   // number of VM initialization options
2298   jint nOptions;
2300   // an array of VM initialization options
2301   JvVMOption* options;
2303   // true if the option parser should ignore unrecognized options
2304   jboolean ignoreUnrecognized;
2305 @} JvVMInitArgs;
2306 @end example
2308 @code{JvCreateJavaVM()} returns @code{0} upon success, or @code{-1} if
2309 the runtime is already initialized.
2311 @emph{Note:} In GCJ 3.1, the @code{vm_args} parameter is ignored. It
2312 is recognized and used as of release 4.0.
2313 @end deftypefun
2315 @deftypefun java::lang::Thread* JvAttachCurrentThread (jstring @var{name}, java::lang::ThreadGroup* @var{group})
2316 Registers an existing thread with the Java runtime.  This must be called once
2317 from each thread, before that thread makes any other Java or CNI calls. It
2318 must be called after @code{JvCreateJavaVM}.
2319 @var{name} specifies a name for the thread. It may be @code{NULL}, in which 
2320 case a name will be generated.
2321 @var{group} is the ThreadGroup in which this thread will be a member. If it
2322 is @code{NULL}, the thread will be a member of the main thread group.
2323 The return value is the Java @code{Thread} object that represents the thread.
2324 It is safe to call @code{JvAttachCurrentThread()} more than once from the same
2325 thread. If the thread is already attached, the call is ignored and the current
2326 thread object is returned.
2327 @end deftypefun
2329 @deftypefun jint JvDetachCurrentThread ()
2330 Unregisters a thread from the Java runtime. This should be called by threads
2331 that were attached using @code{JvAttachCurrentThread()}, after they have 
2332 finished making calls to Java code. This ensures that any resources associated
2333 with the thread become eligible for garbage collection.
2334 This function returns @code{0} upon success, or @code{-1} if the current thread
2335 is not attached.
2336 @end deftypefun
2338 @subsection Handling uncaught exceptions
2340 If an exception is thrown from Java code called using the invocation API, and
2341 no handler for the exception can be found, the runtime will abort the
2342 application. In order to make the application more robust, it is recommended 
2343 that code which uses the invocation API be wrapped by a top-level try/catch 
2344 block that catches all Java exceptions.
2346 @subsection Example
2348 The following code demonstrates the use of the invocation API. In this
2349 example, the C++ application initializes the Java runtime and attaches
2350 itself. The @code{java.lang.System} class is initialized in order to
2351 access its @code{out} field, and a Java string is printed. Finally, the thread
2352 is detached from the runtime once it has finished making Java calls. Everything
2353 is wrapped with a try/catch block to provide a default handler for any uncaught 
2354 exceptions.
2356 The example can be compiled with @command{c++ -c test.cc; gcj test.o}.
2358 @example
2359 // test.cc
2360 #include <gcj/cni.h>
2361 #include <java/lang/System.h>
2362 #include <java/io/PrintStream.h>
2363 #include <java/lang/Throwable.h>
2365 int main(int argc, char *argv[])
2367   using namespace java::lang;
2369   try
2370   @{
2371     JvCreateJavaVM(NULL);
2372     JvAttachCurrentThread(NULL, NULL);
2374     String *message = JvNewStringLatin1("Hello from C++");
2375     JvInitClass(&System::class$);
2376     System::out->println(message);
2378     JvDetachCurrentThread();
2379   @}
2380   catch (Throwable *t)
2381   @{
2382     System::err->println(JvNewStringLatin1("Unhandled Java exception:"));
2383     t->printStackTrace();
2384   @}
2386 @end example
2388 @node Reflection
2389 @section Reflection
2391 Reflection is possible with CNI code, it functions similarly to how it
2392 functions with JNI@.
2394 @c clean this up...  I mean, what are the types jfieldID and jmethodID in JNI?
2395 The types @code{jfieldID} and @code{jmethodID}
2396 are as in JNI@.
2398 @noindent The functions:
2400 @itemize
2401 @item @code{JvFromReflectedField},
2402 @item @code{JvFromReflectedMethod},
2403 @item @code{JvToReflectedField}
2404 @item @code{JvToFromReflectedMethod}
2405 @end itemize
2407 @noindent will be added shortly, as will other functions corresponding to JNI@.
2410 @node System properties
2411 @chapter System properties
2413 The runtime behavior of the @code{libgcj} library can be modified by setting
2414 certain system properties.  These properties can be compiled into the program
2415 using the @code{-D@var{name}[=@var{value}]} option to @command{gcj} or by
2416 setting them explicitly in the program by calling the
2417 @code{java.lang.System.setProperty()} method.  Some system properties are only
2418 used for informational purposes (like giving a version number or a user name).
2419 A program can inspect the current value of a property by calling the
2420 @code{java.lang.System.getProperty()} method.
2422 @menu
2423 * Standard Properties::         Standard properties supported by @code{libgcj}
2424 * GNU Classpath Properties::    Properties found in Classpath based libraries
2425 * libgcj Runtime Properties::   Properties specific to @code{libgcj}
2426 @end menu
2428 @node Standard Properties
2429 @section Standard Properties
2431 The following properties are normally found in all implementations of the core
2432 libraries for the Java language.
2434 @table @gcctabopt
2436 @item java.version
2437 The @code{libgcj} version number.
2439 @item java.vendor
2440 Set to @samp{The Free Software Foundation, Inc.}
2442 @item java.vendor.url
2443 Set to @uref{http://gcc.gnu.org/java/}.
2445 @item java.home
2446 The directory where @code{gcj} was installed.  Taken from the @code{--prefix}
2447 option given to @command{configure}.
2449 @item java.class.version
2450 The class format version number supported by the libgcj byte code interpreter.
2451 (Currently @samp{46.0})
2453 @item java.vm.specification.version
2454 The Virtual Machine Specification version implemented by @code{libgcj}.
2455 (Currently @samp{1.0})
2457 @item java.vm.specification.vendor
2458 The name of the Virtual Machine specification designer.
2460 @item java.vm.specification.name
2461 The name of the Virtual Machine specification
2462 (Set to @samp{Java Virtual Machine Specification}).
2464 @item java.vm.version
2465 The @command{gcj} version number.
2467 @item java.vm.vendor
2468 Set to @samp{The Free Software Foundation, Inc.}
2470 @item java.vm.name
2471 Set to @samp{GNU libgcj}.
2473 @item java.specification.version
2474 The Runtime Environment specification version implemented by @code{libgcj}.
2475 (Currently set to @samp{1.3})
2477 @item java.specification.vendor
2478 The Runtime Environment specification designer.
2480 @item java.specification.name
2481 The name of the Runtime Environment specification
2482 (Set to @samp{Java Platform API Specification}).
2484 @item java.class.path
2485 The paths (jar files, zip files and directories) used for finding class files.
2487 @item java.library.path
2488 Directory path used for finding native libraries.
2490 @item java.io.tmpdir
2491 The directory used to put temporary files in.
2493 @item java.compiler
2494 Name of the Just In Time compiler to use by the byte code interpreter.
2495 Currently not used in @code{libgcj}.
2497 @item java.ext.dirs
2498 Directories containing jar files with extra libraries.  Will be used when
2499 resolving classes.
2501 @item java.protocol.handler.pkgs
2502 A @samp{|} separated list of package names that is used to find classes that
2503 implement handlers for @code{java.net.URL}.
2505 @item java.rmi.server.codebase
2506 A list of URLs that is used by the @code{java.rmi.server.RMIClassLoader}
2507 to load classes from.
2509 @item jdbc.drivers
2510 A list of class names that will be loaded by the @code{java.sql.DriverManager}
2511 when it starts up.
2513 @item file.separator
2514 The separator used in when directories are included in a filename
2515 (normally @samp{/} or @samp{\} ).
2517 @item file.encoding
2518 The default character encoding used when converting platform native files to
2519 Unicode (usually set to @samp{8859_1}).
2521 @item path.separator
2522 The standard separator used when a string contains multiple paths
2523 (normally @samp{:} or @samp{;}), the string is usually not a valid character
2524 to use in normal directory names.)
2526 @item line.separator
2527 The default line separator used on the platform (normally @samp{\n}, @samp{\r}
2528 or a combination of those two characters).
2530 @item policy.provider
2531 The class name used for the default policy provider returned by
2532 @code{java.security.Policy.getPolicy}.
2534 @item user.name
2535 The name of the user running the program.  Can be the full name, the login name
2536 or empty if unknown.
2538 @item user.home
2539 The default directory to put user specific files in.
2541 @item user.dir
2542 The current working directory from which the program was started.
2544 @item user.language
2545 The default language as used by the @code{java.util.Locale} class.
2547 @item user.region
2548 The default region as used by the @code{java.util.Local} class.
2550 @item user.variant
2551 The default variant of the language and region local used.
2553 @item user.timezone
2554 The default timezone as used by the @code{java.util.TimeZone} class.
2556 @item os.name
2557 The operating system/kernel name that the program runs on.
2559 @item os.arch
2560 The hardware that we are running on.
2562 @item os.version
2563 The version number of the operating system/kernel.
2565 @item awt.appletWarning
2566 The string to display when an untrusted applet is displayed.
2567 Returned by @code{java.awt.Window.getWarningString()} when the window is
2568 ``insecure''.
2570 @item awt.toolkit
2571 The class name used for initializing the default @code{java.awt.Toolkit}. 
2572 Defaults to @code{gnu.awt.gtk.GtkToolkit}.
2574 @item http.proxyHost
2575 Name of proxy host for http connections.
2577 @item http.proxyPort
2578 Port number to use when a proxy host is in use.
2580 @end table
2582 @node GNU Classpath Properties
2583 @section GNU Classpath Properties
2585 @code{libgcj} is based on the GNU Classpath (Essential Libraries for Java) a
2586 GNU project to create free core class libraries for use with virtual machines
2587 and compilers for the Java language.  The following properties are common to
2588 libraries based on GNU Classpath.
2590 @table @gcctabopt
2592 @item gcj.dumpobject
2593 Enables printing serialization debugging by the @code{java.io.ObjectInput} and
2594 @code{java.io.ObjectOutput} classes when set to something else then the empty
2595 string.  Only used when running a debug build of the library.
2597 @item gnu.classpath.vm.shortname
2598 This is a succinct name of the virtual machine.  For @code{libgcj},
2599 this will always be @samp{libgcj}.
2601 @item gnu.classpath.home.url
2602 A base URL used for finding system property files (e.g.,
2603 @file{classpath.security}).  By default this is a @samp{file:} URL
2604 pointing to the @file{lib} directory under @samp{java.home}.
2606 @end table
2608 @node libgcj Runtime Properties
2609 @section libgcj Runtime Properties
2611 The following properties are specific to the @code{libgcj} runtime and will
2612 normally not be found in other core libraries for the java language.
2614 @table @gcctabopt
2616 @item java.fullversion
2617 The combination of @code{java.vm.name} and @code{java.vm.version}.
2619 @item java.vm.info
2620 Same as @code{java.fullversion}.
2622 @item impl.prefix
2623 Used by the @code{java.net.DatagramSocket} class when set to something else
2624 then the empty string.  When set all newly created @code{DatagramSocket}s will
2625 try to load a class @code{java.net.[impl.prefix]DatagramSocketImpl} instead of
2626 the normal @code{java.net.PlainDatagramSocketImpl}.
2628 @item gnu.gcj.progname
2629 The class or binary name that was used to invoke the program. This will be
2630 the name of the "main" class in the case where the @code{gij} front end is
2631 used, or the program binary name in the case where an application is compiled 
2632 to a native binary.
2634 @item gnu.gcj.user.realname
2635 The real name of the user, as taken from the password file.  This may
2636 not always hold only the user's name (as some sites put extra
2637 information in this field).  Also, this property is not available on
2638 all platforms.
2640 @item gnu.gcj.runtime.NameFinder.use_addr2line
2641 Whether an external process, @command{addr2line}, should be used to determine
2642 line number information when tracing the stack. Setting this to @code{false} 
2643 may suppress line numbers when printing stack traces and when using
2644 the java.util.logging infrastructure. However, performance may improve
2645 significantly for applications that print stack traces or make logging calls
2646 frequently.
2648 @item gnu.gcj.runtime.NameFinder.show_raw
2649 Whether the address of a stack frame should be printed when the line
2650 number is unavailable. Setting this to @code{true} will cause the name
2651 of the object and the offset within that object to be printed when no
2652 line number is available.  This allows for off-line decoding of
2653 stack traces if necessary debug information is available.  The default
2654 is @code{false}, no raw addresses are printed.
2656 @item gnu.gcj.runtime.NameFinder.remove_unknown
2657 Whether stack frames for non-java code should be included in a stack
2658 trace.  The default value is @code{true}, stack frames for non-java
2659 code are suppressed.  Setting this to @code{false} will cause any
2660 non-java stack frames to be printed in addition to frames for the java
2661 code.
2663 @item gnu.gcj.runtime.VMClassLoader.library_control
2664 This controls how shared libraries are automatically loaded by the
2665 built-in class loader.  If this property is set to @samp{full}, a full
2666 search is done for each requested class.  If this property is set to
2667 @samp{cache}, then any failed lookups are cached and not tried again.
2668 If this property is set to @samp{never} (the default), then lookups
2669 are never done.  For more information, @xref{Extensions}.
2671 @item gnu.gcj.runtime.endorsed.dirs
2672 This is like the standard @code{java.endorsed.dirs}, property, but
2673 specifies some extra directories which are searched after the standard
2674 endorsed directories.  This is primarily useful for telling
2675 @code{libgcj} about additional libraries which are ordinarily
2676 incorporated into the JDK, and which should be loaded by the bootstrap
2677 class loader, but which are not yet part of @code{libgcj} itself for
2678 some reason.
2680 @item gnu.gcj.jit.compiler
2681 @c FIXME we should probably have a whole node on this...
2682 This is the full path to @command{gcj} executable which should be
2683 used to compile classes just-in-time when
2684 @code{ClassLoader.defineClass} is called.  If not set, @command{gcj}
2685 will not be invoked by the runtime; this can also be controlled via
2686 @code{Compiler.disable}.
2688 @item gnu.gcj.jit.options
2689 This is a space-separated string of options which should be passed to
2690 @command{gcj} when in JIT mode.  If not set, a sensible default is
2691 chosen.
2693 @item gnu.gcj.jit.cachedir
2694 This is the directory where cached shared library files are
2695 stored.  If not set, JIT compilation is disabled.  This should never
2696 be set to a directory that is writable by any other user.
2698 @item gnu.gcj.precompiled.db.path
2699 This is a sequence of file names, each referring to a file created by
2700 @command{gcj-dbtool}.  These files will be used by @code{libgcj} to
2701 find shared libraries corresponding to classes that are loaded from
2702 bytecode.  @code{libgcj} often has a built-in default database; it
2703 can be queried using @code{gcj-dbtool -p}.
2705 @end table
2708 @node Resources
2709 @chapter Resources
2711 While writing @command{gcj} and @code{libgcj} we have, of course, relied
2712 heavily on documentation from Sun Microsystems.  In particular we have
2713 used The Java Language Specification (both first and second editions),
2714 the Java Class Libraries (volumes one and two), and the Java Virtual
2715 Machine Specification.  In addition we've used the online documentation
2716 at @uref{http://java.sun.com/}.
2718 The current @command{gcj} home page is
2719 @uref{http://gcc.gnu.org/java/}.
2721 For more information on gcc, see @uref{http://gcc.gnu.org/}.
2723 Some @code{libgcj} testing is done using the Mauve test suite.  This is
2724 a free software Java class library test suite which is being written
2725 because the JCK is not free.  See
2726 @uref{http://sources.redhat.com/mauve/} for more information.
2729 @node Index
2730 @unnumbered Index
2732 @printindex cp
2734 @bye