1 \input texinfo @c -*-texinfo-*-
3 @settitle Guide to GNU gcj
5 @c Merge the standard indexes into a single one.
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
19 @c When this manual is copyrighted.
20 @set copyrights-gcj 2001, 2002, 2003, 2004, 2005
23 @set which-gcj GCC-@value{version-GCC}
26 @c man begin COPYRIGHT
27 Copyright @copyright{} @value{copyrights-gcj} Free Software Foundation, Inc.
29 Permission is granted to copy, distribute and/or modify this document
30 under the terms of the GNU Free Documentation License, Version 1.2 or
31 any later version published by the Free Software Foundation; with the
32 Invariant Sections being ``GNU General Public License'', the Front-Cover
33 texts being (a) (see below), and with the Back-Cover Texts being (b)
34 (see below). A copy of the license is included in the
37 ``GNU Free Documentation License''.
39 @c man begin COPYRIGHT
44 @c man begin COPYRIGHT
46 (a) The FSF's Front-Cover Text is:
50 (b) The FSF's Back-Cover Text is:
52 You have freedom to copy and modify this GNU Manual, like GNU
53 software. Copies published by the Free Software Foundation raise
54 funds for GNU development.
60 @dircategory Software development
62 * Gcj: (gcj). Ahead-of-time compiler for the Java language
65 @dircategory Individual utilities
67 * gcjh: (gcj)Invoking gcjh.
68 Generate header files from Java class files
69 * gjnih: (gcj)Invoking gjnih.
70 Generate JNI header files from Java class files
71 * jcf-dump: (gcj)Invoking jcf-dump.
72 Print information about Java class files
73 * gij: (gcj)Invoking gij. GNU interpreter for Java bytecode
74 * gcj-dbtool: (gcj)Invoking gcj-dbtool.
75 Tool for manipulating class file databases.
76 * jv-convert: (gcj)Invoking jv-convert.
77 Convert file from one encoding to another
78 * grmic: (gcj)Invoking grmic.
79 Generate stubs for Remote Method Invocation.
80 * grmiregistry: (gcj)Invoking grmiregistry.
81 The remote object registry.
93 @vskip 0pt plus 1filll
94 For the @value{which-gcj} Version*
96 Published by the Free Software Foundation @*
97 51 Franklin Street, Fifth Floor@*
98 Boston, MA 02110-1301, USA@*
109 This manual describes how to use @command{gcj}, the GNU compiler for the
110 Java programming language. @command{gcj} can generate both @file{.class}
111 files and object files, and it can read both Java source code and
115 * Copying:: The GNU General Public License
116 * GNU Free Documentation License::
117 How you can share and copy this manual
118 * Invoking gcj:: Compiler options supported by @command{gcj}
119 * Compatibility:: Compatibility between gcj and other tools for Java
120 * Invoking gcjh:: Generate header files from class files
121 * Invoking gjnih:: Generate JNI header files from class files
122 * Invoking jcf-dump:: Print information about class files
123 * Invoking gij:: Interpreting Java bytecodes
124 * Invoking gcj-dbtool:: Tool for manipulating class file databases.
125 * Invoking jv-convert:: Converting from one encoding to another
126 * Invoking grmic:: Generate stubs for Remote Method Invocation.
127 * Invoking grmiregistry:: The remote object registry.
128 * About CNI:: Description of the Compiled Native Interface
129 * System properties:: Modifying runtime behavior of the libgcj library
130 * Resources:: Where to look for more information
141 @chapter Invoking gcj
143 @c man title gcj Ahead-of-time compiler for the Java language
146 @c man begin SYNOPSIS gcj
147 gcj [@option{-I}@var{dir}@dots{}] [@option{-d} @var{dir}@dots{}]
148 [@option{--CLASSPATH}=@var{path}] [@option{--classpath}=@var{path}]
149 [@option{-f}@var{option}@dots{}] [@option{--encoding}=@var{name}]
150 [@option{--main}=@var{classname}] [@option{-D}@var{name}[=@var{value}]@dots{}]
151 [@option{-C}] [@option{--resource} @var{resource-name}] [@option{-d} @var{directory}]
152 [@option{-W}@var{warn}@dots{}]
153 @var{sourcefile}@dots{}
155 @c man begin SEEALSO gcj
156 gcc(1), gcjh(1), gjnih(1), gij(1), jcf-dump(1), gfdl(7),
157 and the Info entries for @file{gcj} and @file{gcc}.
161 @c man begin DESCRIPTION gcj
163 As @command{gcj} is just another front end to @command{gcc}, it supports many
164 of the same options as gcc. @xref{Option Summary, , Option Summary,
165 gcc, Using the GNU Compiler Collection (GCC)}. This manual only documents the
166 options specific to @command{gcj}.
171 * Input and output files::
172 * Input Options:: How gcj finds files
173 * Encodings:: Options controlling source file encoding
174 * Warnings:: Options controlling warnings specific to gcj
175 * Linking:: Options for making an executable
176 * Code Generation:: Options controlling the output of gcj
177 * Configure-time Options:: Options you won't use
180 @c man begin OPTIONS gcj
182 @node Input and output files
183 @section Input and output files
185 A @command{gcj} command is like a @command{gcc} command, in that it
186 consists of a number of options and file names. The following kinds
187 of input file names are supported:
190 @item @var{file}.java
192 @item @var{file}.class
195 @itemx @var{file}.jar
196 An archive containing one or more @code{.class} files, all of
197 which are compiled. The archive may be compressed. Files in
198 an archive which don't end with @samp{.class} are treated as
199 resource files; they are compiled into the resulting object file
200 as @samp{core:} URLs.
202 A file containing a whitespace-separated list of input file names.
203 (Currently, these must all be @code{.java} source files, but that
205 Each named file is compiled, just as if it had been on the command line.
206 @item @var{library}.a
207 @itemx @var{library}.so
208 @itemx -l@var{libname}
209 Libraries to use when linking. See the @command{gcc} manual.
212 You can specify more than one input file on the @command{gcj} command line,
213 in which case they will all be compiled. If you specify a
214 @code{-o @var{FILENAME}}
215 option, all the input files will be compiled together, producing a
216 single output file, named @var{FILENAME}.
217 This is allowed even when using @code{-S} or @code{-c},
218 but not when using @code{-C} or @code{--resource}.
219 (This is an extension beyond the what plain @command{gcc} allows.)
220 (If more than one input file is specified, all must currently
221 be @code{.java} files, though we hope to fix this.)
224 @section Input Options
228 @command{gcj} has options to control where it looks to find files it needs.
229 For instance, @command{gcj} might need to load a class that is referenced
230 by the file it has been asked to compile. Like other compilers for the
231 Java language, @command{gcj} has a notion of a @dfn{class path}. There are
232 several options and environment variables which can be used to
233 manipulate the class path. When @command{gcj} looks for a given class, it
234 searches the class path looking for matching @file{.class} or
235 @file{.java} file. @command{gcj} comes with a built-in class path which
236 points at the installed @file{libgcj.jar}, a file which contains all the
239 In the below, a directory or path component can refer either to an
240 actual directory on the filesystem, or to a @file{.zip} or @file{.jar}
241 file, which @command{gcj} will search as if it is a directory.
245 All directories specified by @code{-I} are kept in order and prepended
246 to the class path constructed from all the other options. Unless
247 compatibility with tools like @code{javac} is important, we recommend
248 always using @code{-I} instead of the other options for manipulating the
251 @item --classpath=@var{path}
252 This sets the class path to @var{path}, a colon-separated list of paths
253 (on Windows-based systems, a semicolon-separate list of paths).
254 This does not override the builtin (``boot'') search path.
256 @item --CLASSPATH=@var{path}
257 Deprecated synonym for @code{--classpath}.
259 @item --bootclasspath=@var{path}
260 Where to find the standard builtin classes, such as @code{java.lang.String}.
262 @item --extdirs=@var{path}
263 For each directory in the @var{path}, place the contents of that
264 directory at the end of the class path.
267 This is an environment variable which holds a list of paths.
270 The final class path is constructed like so:
274 First come all directories specified via @code{-I}.
277 If @option{--classpath} is specified, its value is appended.
278 Otherwise, if the @code{CLASSPATH} environment variable is specified,
279 then its value is appended.
280 Otherwise, the current directory (@code{"."}) is appended.
283 If @code{--bootclasspath} was specified, append its value.
284 Otherwise, append the built-in system directory, @file{libgcj.jar}.
287 Finally, if @code{--extdirs} was specified, append the contents of the
288 specified directories at the end of the class path. Otherwise, append
289 the contents of the built-in extdirs at @code{$(prefix)/share/java/ext}.
292 The classfile built by @command{gcj} for the class @code{java.lang.Object}
293 (and placed in @code{libgcj.jar}) contains a special zero length
294 attribute @code{gnu.gcj.gcj-compiled}. The compiler looks for this
295 attribute when loading @code{java.lang.Object} and will report an error
296 if it isn't found, unless it compiles to bytecode (the option
297 @code{-fforce-classes-archive-check} can be used to override this
298 behavior in this particular case.)
301 @item -fforce-classes-archive-check
302 This forces the compiler to always check for the special zero length
303 attribute @code{gnu.gcj.gcj-compiled} in @code{java.lang.Object} and
304 issue an error if it isn't found.
306 @item -fsource=@var{VERSION}
307 This option is used to choose the source version accepted by
308 @command{gcj}. The default is @samp{1.5}.
314 The Java programming language uses Unicode throughout. In an effort to
315 integrate well with other locales, @command{gcj} allows @file{.java} files
316 to be written using almost any encoding. @command{gcj} knows how to
317 convert these encodings into its internal encoding at compile time.
319 You can use the @code{--encoding=@var{NAME}} option to specify an
320 encoding (of a particular character set) to use for source files. If
321 this is not specified, the default encoding comes from your current
322 locale. If your host system has insufficient locale support, then
323 @command{gcj} assumes the default encoding to be the @samp{UTF-8} encoding
326 To implement @code{--encoding}, @command{gcj} simply uses the host
327 platform's @code{iconv} conversion routine. This means that in practice
328 @command{gcj} is limited by the capabilities of the host platform.
330 The names allowed for the argument @code{--encoding} vary from platform
331 to platform (since they are not standardized anywhere). However,
332 @command{gcj} implements the encoding named @samp{UTF-8} internally, so if
333 you choose to use this for your source files you can be assured that it
334 will work on every host.
340 @command{gcj} implements several warnings. As with other generic
341 @command{gcc} warnings, if an option of the form @code{-Wfoo} enables a
342 warning, then @code{-Wno-foo} will disable it. Here we've chosen to
343 document the form of the warning which will have an effect -- the
344 default being the opposite of what is listed.
347 @item -Wredundant-modifiers
348 With this flag, @command{gcj} will warn about redundant modifiers. For
349 instance, it will warn if an interface method is declared @code{public}.
351 @item -Wextraneous-semicolon
352 This causes @command{gcj} to warn about empty statements. Empty statements
353 have been deprecated.
355 @item -Wno-out-of-date
356 This option will cause @command{gcj} not to warn when a source file is
357 newer than its matching class file. By default @command{gcj} will warn
360 @item -Wno-deprecated
361 Warn if a deprecated class, method, or field is referred to.
364 This is the same as @command{gcc}'s @code{-Wunused}.
367 This is the same as @code{-Wredundant-modifiers -Wextraneous-semicolon
375 To turn a Java application into an executable program,
376 you need to link it with the needed libraries, just as for C or C++.
377 The linker by default looks for a global function named @code{main}.
378 Since Java does not have global functions, and a
379 collection of Java classes may have more than one class with a
380 @code{main} method, you need to let the linker know which of those
381 @code{main} methods it should invoke when starting the application.
382 You can do that in any of these ways:
386 Specify the class containing the desired @code{main} method
387 when you link the application, using the @code{--main} flag,
390 Link the Java package(s) into a shared library (dll) rather than an
391 executable. Then invoke the application using the @code{gij} program,
392 making sure that @code{gij} can find the libraries it needs.
394 Link the Java packages(s) with the flag @code{-lgij}, which links
395 in the @code{main} routine from the @code{gij} command.
396 This allows you to select the class whose @code{main} method you
397 want to run when you run the application. You can also use
398 other @code{gij} flags, such as @code{-D} flags to set properties.
399 Using the @code{-lgij} library (rather than the @code{gij} program
400 of the previous mechanism) has some advantages: it is compatible with
401 static linking, and does not require configuring or installing libraries.
404 These @code{gij} options relate to linking an executable:
407 @item --main=@var{CLASSNAME}
408 This option is used when linking to specify the name of the class whose
409 @code{main} method should be invoked when the resulting executable is
412 @item -D@var{name}[=@var{value}]
413 This option can only be used with @code{--main}. It defines a system
414 property named @var{name} with value @var{value}. If @var{value} is not
415 specified then it defaults to the empty string. These system properties
416 are initialized at the program's startup and can be retrieved at runtime
417 using the @code{java.lang.System.getProperty} method.
420 Create an application whose command-line processing is that
421 of the @code{gij} command.
423 This option is an alternative to using @code{--main}; you cannot use both.
426 This option causes linking to be done against a static version of the
427 libgcj runtime library. This option is only available if
428 corresponding linker support exists.
430 @strong{Caution:} Static linking of libgcj may cause essential parts
431 of libgcj to be omitted. Some parts of libgcj use reflection to load
432 classes at runtime. Since the linker does not see these references at
433 link time, it can omit the referred to classes. The result is usually
434 (but not always) a @code{ClassNotFoundException} being thrown at
435 runtime. Caution must be used when using this option. For more
437 @w{@uref{http://gcc.gnu.org/wiki/Statically%20linking%20libgcj}}
440 @node Code Generation
441 @section Code Generation
443 In addition to the many @command{gcc} options controlling code generation,
444 @command{gcj} has several options specific to itself.
449 This option is used to tell @command{gcj} to generate bytecode
450 (@file{.class} files) rather than object code.
452 @item --resource @var{resource-name}
453 This option is used to tell @command{gcj} to compile the contents of a
454 given file to object code so it may be accessed at runtime with the core
455 protocol handler as @samp{core:/@var{resource-name}}. Note that
456 @var{resource-name} is the name of the resource as found at runtime; for
457 instance, it could be used in a call to @code{ResourceBundle.getBundle}.
458 The actual file name to be compiled this way must be specified
461 @item -ftarget=@var{VERSION}
462 This can be used with @option{-C} to choose the version of bytecode
463 emitted by @command{gcj}. The default is @samp{1.5}. When not
464 generating bytecode, this option has no effect.
466 @item -d @var{directory}
467 When used with @code{-C}, this causes all generated @file{.class} files
468 to be put in the appropriate subdirectory of @var{directory}. By
469 default they will be put in subdirectories of the current working
472 @item -fno-bounds-check
473 By default, @command{gcj} generates code which checks the bounds of all
474 array indexing operations. With this option, these checks are omitted, which
475 can improve performance for code that uses arrays extensively. Note that this
476 can result in unpredictable behavior if the code in question actually does
477 violate array bounds constraints. It is safe to use this option if you are
478 sure that your code will never throw an @code{ArrayIndexOutOfBoundsException}.
480 @item -fno-store-check
481 Don't generate array store checks. When storing objects into arrays, a runtime
482 check is normally generated in order to ensure that the object is assignment
483 compatible with the component type of the array (which may not be known
484 at compile-time). With this option, these checks are omitted. This can
485 improve performance for code which stores objects into arrays frequently.
486 It is safe to use this option if you are sure your code will never throw an
487 @code{ArrayStoreException}.
490 With @command{gcj} there are two options for writing native methods: CNI
491 and JNI@. By default @command{gcj} assumes you are using CNI@. If you are
492 compiling a class with native methods, and these methods are implemented
493 using JNI, then you must use @code{-fjni}. This option causes
494 @command{gcj} to generate stubs which will invoke the underlying JNI
498 Don't recognize the @code{assert} keyword. This is for compatibility
499 with older versions of the language specification.
501 @item -fno-optimize-static-class-initialization
502 When the optimization level is greater or equal to @code{-O2},
503 @command{gcj} will try to optimize the way calls into the runtime are made
504 to initialize static classes upon their first use (this optimization
505 isn't carried out if @code{-C} was specified.) When compiling to native
506 code, @code{-fno-optimize-static-class-initialization} will turn this
507 optimization off, regardless of the optimization level in use.
509 @item --disable-assertions[=@var{class-or-package}]
510 Don't include code for checking assertions in the compiled code.
511 If @code{=@var{class-or-package}} is missing disables assertion code
512 generation for all classes, unless overridden by a more
513 specific @code{--enable-assertions} flag.
514 If @var{class-or-package} is a class name, only disables generating
515 assertion checks within the named class or its inner classes.
516 If @var{class-or-package} is a package name, disables generating
517 assertion checks within the named package or a subpackage.
519 By default, assertions are enabled when generating class files
520 or when not optimizing, and disabled when generating optimized binaries.
522 @item --enable-assertions[=@var{class-or-package}]
523 Generates code to check assertions. The option is perhaps misnamed,
524 as you still need to turn on assertion checking at run-time,
525 and we don't support any easy way to do that.
526 So this flag isn't very useful yet, except to partially override
527 @code{--disable-assertions}.
529 @item -findirect-dispatch
530 @command{gcj} has a special binary compatibility ABI, which is enabled
531 by the @code{-findirect-dispatch} option. In this mode, the code
532 generated by @command{gcj} honors the binary compatibility guarantees
533 in the Java Language Specification, and the resulting object files do
534 not need to be directly linked against their dependencies. Instead,
535 all dependencies are looked up at runtime. This allows free mixing of
536 interpreted and compiled code.
538 Note that, at present, @code{-findirect-dispatch} can only be used
539 when compiling @file{.class} files. It will not work when compiling
540 from source. CNI also does not yet work with the binary compatibility
541 ABI. These restrictions will be lifted in some future release.
543 However, if you compile CNI code with the standard ABI, you can call
544 it from code built with the binary compatibility ABI.
546 @item -fbootstrap-classes
547 This option can be use to tell @code{libgcj} that the compiled classes
548 should be loaded by the bootstrap loader, not the system class loader.
549 By default, if you compile a class and link it into an executable, it
550 will be treated as if it was loaded using the system class loader.
551 This is convenient, as it means that things like
552 @code{Class.forName()} will search @samp{CLASSPATH} to find the
555 @item -freduced-reflection
556 This option causes the code generated by @command{gcj} to contain a
557 reduced amount of the class meta-data used to support runtime
558 reflection. The cost of this savings is the loss of
559 the ability to use certain reflection capabilities of the standard
560 Java runtime environment. When set all meta-data except for that
561 which is needed to obtain correct runtime semantics is eliminated.
563 For code that does not use reflection (i.e. the methods in the
564 @code{java.lang.reflect} package), @code{-freduced-reflection}
565 will result in proper operation with a savings in executable code size.
567 JNI (@code{-fjni}) and the binary compatibility ABI
568 (@code{-findirect-dispatch}) do not work properly without full
569 reflection meta-data. Because of this, it is an error to use these options
570 with @code{-freduced-reflection}.
572 @strong{Caution:} If there is no reflection meta-data, code that uses
573 a @code{SecurityManager} may not work properly. Also calling
574 @code{Class.forName()} may fail if the calling method has no
575 reflection meta-data.
580 @node Configure-time Options
581 @section Configure-time Options
583 Some @command{gcj} code generations options affect the resulting ABI, and
584 so can only be meaningfully given when @code{libgcj}, the runtime
585 package, is configured. @code{libgcj} puts the appropriate options from
586 this group into a @samp{spec} file which is read by @command{gcj}. These
587 options are listed here for completeness; if you are using @code{libgcj}
588 then you won't want to touch these options.
592 This enables the use of the Boehm GC bitmap marking code. In particular
593 this causes @command{gcj} to put an object marking descriptor into each
596 @item -fhash-synchronization
597 By default, synchronization data (the data used for @code{synchronize},
598 @code{wait}, and @code{notify}) is pointed to by a word in each object.
599 With this option @command{gcj} assumes that this information is stored in a
600 hash table and not in the object itself.
602 @item -fuse-divide-subroutine
603 On some systems, a library routine is called to perform integer
604 division. This is required to get exception handling correct when
607 @item -fcheck-references
608 On some systems it's necessary to insert inline checks whenever
609 accessing an object via a reference. On other systems you won't need
610 this because null pointer accesses are caught automatically by the
617 @chapter Compatibility with the Java Platform
619 As we believe it is important that the Java platform not be fragmented,
620 @command{gcj} and @code{libgcj} try to conform to the relevant Java
621 specifications. However, limited manpower and incomplete and unclear
622 documentation work against us. So, there are caveats to using
631 @section Standard features not yet supported
633 This list of compatibility issues is by no means complete.
637 @command{gcj} implements the JDK 1.2 language. It supports inner classes
638 and the new 1.4 @code{assert} keyword. It does not yet support the Java 2
639 @code{strictfp} keyword (it recognizes the keyword but ignores it).
642 @code{libgcj} is largely compatible with the JDK 1.2 libraries.
643 However, @code{libgcj} is missing many packages, most notably
644 @code{java.awt}. There are also individual missing classes and methods.
645 We currently do not have a list showing differences between
646 @code{libgcj} and the Java 2 platform.
649 Sometimes the @code{libgcj} implementation of a method or class differs
650 from the JDK implementation. This is not always a bug. Still, if it
651 affects you, it probably makes sense to report it so that we can discuss
652 the appropriate response.
655 @command{gcj} does not currently allow for piecemeal replacement of
656 components within @code{libgcj}. Unfortunately, programmers often want
657 to use newer versions of certain packages, such as those provided by
658 the Apache Software Foundation's Jakarta project. This has forced us
659 to place the @code{org.w3c.dom} and @code{org.xml.sax} packages into
660 their own libraries, separate from @code{libgcj}. If you intend to
661 use these classes, you must link them explicitly with
662 @code{-l-org-w3c-dom} and @code{-l-org-xml-sax}. Future versions of
663 @command{gcj} may not have this restriction.
667 @section Extra features unique to gcj
669 The main feature of @command{gcj} is that it can compile programs written in
670 the Java programming language to native code. Most extensions that have been
671 added are to facilitate this functionality.
675 @command{gcj} makes it easy and efficient to mix code written in Java and C++.
676 @xref{About CNI}, for more info on how to use this in your programs.
679 When you compile your classes into a shared library using
680 @code{-findirect-dispatch} then add them to the system-wide
681 classmap.db file using @code{gcj-dbtool}, they will be automatically
682 loaded by the @code{libgcj} system classloader. This is the new,
683 preferred classname-to-library resolution mechanism. @xref{Invoking
684 gcj-dbtool}, for more information on using the classmap database.
687 The old classname-to-library lookup mechanism is still supported
688 through the @code{gnu.gcj.runtime.VMClassLoader.library_control}
689 property, but it is deprecated and will likely be removed in some
690 future release. When trying to load a class @code{gnu.pkg.SomeClass}
691 the system classloader will first try to load the shared library
692 @file{lib-gnu-pkg-SomeClass.so}, if that fails to load the class then
693 it will try to load @file{lib-gnu-pkg.so} and finally when the class
694 is still not loaded it will try to load @file{lib-gnu.so}. Note that
695 all @samp{.}s will be transformed into @samp{-}s and that searching
696 for inner classes starts with their outermost outer class. If the
697 class cannot be found this way the system classloader tries to use the
698 @code{libgcj} bytecode interpreter to load the class from the standard
699 classpath. This process can be controlled to some degree via the
700 @code{gnu.gcj.runtime.VMClassLoader.library_control} property;
701 @xref{libgcj Runtime Properties}.
704 @code{libgcj} includes a special @samp{gcjlib} URL type. A URL of
705 this form is like a @code{jar} URL, and looks like
706 @samp{gcjlib:/path/to/shared/library.so!/path/to/resource}. An access
707 to one of these URLs causes the shared library to be @code{dlopen()}d,
708 and then the resource is looked for in that library. These URLs are
709 most useful when used in conjunction with @code{java.net.URLClassLoader}.
710 Note that, due to implementation limitations, currently any such URL
711 can be accessed by only one class loader, and libraries are never
712 unloaded. This means some care must be exercised to make sure that
713 a @code{gcjlib} URL is not accessed by more than one class loader at once.
714 In a future release this limitation will be lifted, and such
715 libraries will be mapped privately.
718 A program compiled by @command{gcj} will examine the
719 @env{GCJ_PROPERTIES} environment variable and change its behavior in
720 some ways. In particular @env{GCJ_PROPERTIES} holds a list of
721 assignments to global properties, such as would be set with the
722 @option{-D} option to @command{java}. For instance,
723 @samp{java.compiler=gcj} is a valid (but currently meaningless)
725 @cindex GCJ_PROPERTIES
726 @vindex GCJ_PROPERTIES
732 @chapter Invoking gcjh
734 @c man title gcjh generate header files from Java class files
736 @c man begin DESCRIPTION gcjh
738 The @code{gcjh} program is used to generate header files from class
739 files. It can generate both CNI and JNI header files, as well as stub
740 implementation files which can be used as a basis for implementing the
741 required native methods.
746 @c man begin SYNOPSIS gcjh
747 gcjh [@option{-stubs}] [@option{-jni}]
748 [@option{-force}] [@option{-old}] [@option{-trace}] [@option{-J} @var{option}]
749 [@option{-add} @var{text}] [@option{-append} @var{text}] [@option{-friend} @var{text}]
750 [@option{-preprend} @var{text}]
751 [@option{--classpath}=@var{path}] [@option{--CLASSPATH}=@var{path}]
752 [@option{--bootclasspath}=@var{path}]
753 [@option{-I}@var{dir}@dots{}] [@option{-d} @var{dir}@dots{}]
754 [@option{-o} @var{file}] [@option{-td} @var{dir}]
755 [@option{-M}] [@option{-MM}] [@option{-MD}] [@option{-MMD}]
756 [@option{--version}] [@option{--help}] [@option{-v}] [@option{--verbose}]
757 @var{classname}@dots{}
759 @c man begin SEEALSO gcjh
760 gcc(1), gcj(1), gij(1), jcf-dump(1), gfdl(7),
761 and the Info entries for @file{gcj} and @file{gcc}.
765 @c man begin OPTIONS gcjh
769 This causes @code{gcjh} to generate stub files instead of header files.
770 By default the stub file will be named after the class, with a suffix of
771 @samp{.cc}. In JNI mode, the default output file will have the suffix
775 This tells @code{gcjh} to generate a JNI header or stub. By default,
776 CNI headers are generated.
779 This option forces @code{gcjh} to write the output file.
782 This option is accepted but ignored for compatibility.
785 This option is accepted but ignored for compatibility.
787 @item -J @var{option}
788 This option is accepted but ignored for compatibility.
790 @item -add @var{text}
791 Inserts @var{text} into the class body. This is ignored in JNI mode.
793 @item -append @var{text}
794 Inserts @var{text} into the header file after the class declaration.
795 This is ignored in JNI mode.
797 @item -friend @var{text}
798 Inserts @var{text} into the class as a @code{friend} declaration.
799 This is ignored in JNI mode.
801 @item -prepend @var{text}
802 Inserts @var{text} into the header file before the class declaration.
803 This is ignored in JNI mode.
805 @item --classpath=@var{path}
806 @itemx --CLASSPATH=@var{path}
807 @itemx --bootclasspath=@var{path}
808 @itemx -I@var{directory}
809 @itemx -d @var{directory}
811 These options are all identical to the corresponding @command{gcj} options.
814 Sets the output file name. This cannot be used if there is more than
815 one class on the command line.
817 @item -td @var{directory}
818 Sets the name of the directory to use for temporary files.
821 Print all dependencies to stdout; suppress ordinary output.
824 Print non-system dependencies to stdout; suppress ordinary output.
827 Print all dependencies to stdout.
830 Print non-system dependencies to stdout.
833 Print help about @code{gcjh} and exit. No further processing is done.
836 Print version information for @code{gcjh} and exit. No further
840 Print extra information while running.
843 All remaining options are considered to be names of classes.
848 @chapter Invoking gjnih
850 @c man title gjnih generate JNI header files from Java class files
852 @c man begin DESCRIPTION gjnih
854 The @code{gjnih} program is used to generate JNI header files from class
855 files. Running it is equivalent to running @code{gcjh -jni}.
860 @c man begin SYNOPSIS gjnih
861 gjnih [@option{-stubs}] [@option{-jni}]
862 [@option{-force}] [@option{-old}] [@option{-trace}] [@option{-J} @var{option}]
863 [@option{-add} @var{text}] [@option{-append} @var{text}] [@option{-friend} @var{text}]
864 [@option{-preprend} @var{text}]
865 [@option{--classpath}=@var{path}] [@option{--CLASSPATH}=@var{path}]
866 [@option{--bootclasspath}=@var{path}]
867 [@option{-I}@var{dir}@dots{}] [@option{-d} @var{dir}@dots{}]
868 [@option{-o} @var{file}] [@option{-td} @var{dir}]
869 [@option{-M}] [@option{-MM}] [@option{-MD}] [@option{-MMD}]
870 [@option{--version}] [@option{--help}] [@option{-v}] [@option{--verbose}]
871 @var{classname}@dots{}
873 @c man begin SEEALSO gjnih
874 gcc(1), gcj(1), gcjh(1), gij(1), jcf-dump(1), gfdl(7),
875 and the Info entries for @file{gcj} and @file{gcc}.
879 @c man begin OPTIONS gjnih
883 This causes @code{gjnih} to generate stub files instead of header files.
884 By default the stub file will be named after the class, with a suffix of
888 This option specifies the default behavior which is to generate a JNI
892 This option forces @code{gjnih} to write the output file.
895 This option is accepted but ignored for compatibility.
898 This option is accepted but ignored for compatibility.
900 @item -J @var{option}
901 This option is accepted but ignored for compatibility.
903 @item -add @var{text}
904 Inserts @var{text} into the class body. This is ignored in by
907 @item -append @var{text}
908 Inserts @var{text} into the header file after the class declaration.
909 This is ignored in by @code{gjnih}.
911 @item -friend @var{text}
912 Inserts @var{text} into the class as a @code{friend} declaration.
913 This is ignored by @code{gjnih}.
915 @item -prepend @var{text}
916 Inserts @var{text} into the header file before the class declaration.
917 This is ignored in by @code{gjnih}.
919 @item --classpath=@var{path}
920 @itemx --CLASSPATH=@var{path}
921 @itemx --bootclasspath=@var{path}
922 @itemx -I@var{directory}
923 @itemx -d @var{directory}
925 These options are all identical to the corresponding @command{gcj} options.
928 Sets the output file name. This cannot be used if there is more than
929 one class on the command line.
931 @item -td @var{directory}
932 Sets the name of the directory to use for temporary files.
935 Print all dependencies to stdout; suppress ordinary output.
938 Print non-system dependencies to stdout; suppress ordinary output.
941 Print all dependencies to stdout.
944 Print non-system dependencies to stdout.
947 Print help about @code{gjnih} and exit. No further processing is done.
950 Print version information for @code{gjnih} and exit. No further
954 Print extra information while running.
957 All remaining options are considered to be names of classes.
961 @node Invoking jcf-dump
962 @chapter Invoking jcf-dump
964 @c man title jcf-dump print information about Java class files
967 @c man begin SYNOPSIS jcf-dump
968 jcf-dump [@option{-c}] [@option{--javap}]
969 [@option{--classpath}=@var{path}] [@option{--CLASSPATH}=@var{path}]
970 [@option{-I}@var{dir}@dots{}] [@option{-o} @var{file}]
971 [@option{--version}] [@option{--help}] [@option{-v}] [@option{--verbose}]
972 @var{classname}@dots{}
974 @c man begin SEEALSO jcf-dump
975 gcc(1), gcj(1), gcjh(1), gij(1), jcf-dump(1), gfdl(7),
976 and the Info entries for @file{gcj} and @file{gcc}.
980 @c man begin DESCRIPTION jcf-dump
982 This is a class file examiner, similar to @code{javap}. It will print
983 information about a number of classes, which are specified by class name
988 @c man begin OPTIONS jcf-dump
992 Disassemble method bodies. By default method bodies are not printed.
994 @item --print-constants
995 Print the constant pool. When printing a reference to a constant
996 also print its index in the constant pool.
999 Generate output in @code{javap} format. The implementation of this
1000 feature is very incomplete.
1002 @item --classpath=@var{path}
1003 @itemx --CLASSPATH=@var{path}
1004 @itemx -I@var{directory}
1005 @itemx -o @var{file}
1006 These options as the same as the corresponding @command{gcj} options.
1009 Print help, then exit.
1012 Print version number, then exit.
1015 Print extra information while running.
1016 Implies @code{--print-constants}.
1022 @chapter Invoking gij
1024 @c man title gij GNU interpreter for Java bytecode
1027 @c man begin SYNOPSIS gij
1028 gij [@option{OPTION}] @dots{} @var{JARFILE} [@var{ARGS}@dots{}]
1030 gij [@option{-jar}] [@option{OPTION}] @dots{} @var{CLASS} [@var{ARGS}@dots{}]
1031 [@option{-cp} @var{path}] [@option{-classpath} @var{path}]
1032 [@option{-D}@var{name}[=@var{value}]@dots{}]
1033 [@option{-ms=}@var{number}] [@option{-mx=}@var{number}]
1034 [@option{-X@var{argument}}] [@option{-verbose}] [@option{-verbose:class}]
1035 [@option{--showversion}] [@option{--version}] [@option{--help}][@option{-?}]
1037 @c man begin SEEALSO gij
1038 gcc(1), gcj(1), gcjh(1), jcf-dump(1), gfdl(7),
1039 and the Info entries for @file{gcj} and @file{gcc}.
1043 @c man begin DESCRIPTION gij
1045 @code{gij} is a Java bytecode interpreter included with @code{libgcj}.
1046 @code{gij} is not available on every platform; porting it requires a
1047 small amount of assembly programming which has not been done for all the
1048 targets supported by @command{gcj}.
1050 The primary argument to @code{gij} is the name of a class or, with
1051 @code{-jar}, a jar file. Options before this argument are interpreted
1052 by @code{gij}; remaining options are passed to the interpreted program.
1054 If a class name is specified and this class does not have a @code{main}
1055 method with the appropriate signature (a @code{static void} method with
1056 a @code{String[]} as its sole argument), then @code{gij} will print an
1059 If a jar file is specified then @code{gij} will use information in it to
1060 determine which class' @code{main} method will be invoked.
1062 @code{gij} will invoke the @code{main} method with all the remaining
1063 command-line options.
1065 Note that @code{gij} is not limited to interpreting code. Because
1066 @code{libgcj} includes a class loader which can dynamically load shared
1067 objects, it is possible to give @code{gij} the name of a class which has
1068 been compiled and put into a shared library on the class path.
1072 @c man begin OPTIONS gij
1075 @item -cp @var{path}
1076 @itemx -classpath @var{path}
1077 Set the initial class path. The class path is used for finding
1078 class and resource files. If specified, this option overrides the
1079 @code{CLASSPATH} environment variable. Note that this option is
1080 ignored if @code{-jar} is used.
1082 @item -D@var{name}[=@var{value}]
1083 This defines a system property named @var{name} with value @var{value}.
1084 If @var{value} is not specified then it defaults to the empty string.
1085 These system properties are initialized at the program's startup and can
1086 be retrieved at runtime using the @code{java.lang.System.getProperty}
1089 @item -ms=@var{number}
1090 Equivalent to @code{-Xms}.
1092 @item -mx=@var{number}
1093 Equivalent to @code{-Xmx}.
1096 Do not verify compliance of bytecode with the VM specification. In addition,
1097 this option disables type verification which is otherwise performed on BC-ABI
1101 @itemx -X@var{argument}
1102 Supplying @code{-X} by itself will cause @code{gij} to list all the
1103 supported @code{-X} options. Currently these options are supported:
1106 @item -Xms@var{size}
1107 Set the initial heap size.
1109 @item -Xmx@var{size}
1110 Set the maximum heap size.
1112 @item -Xss@var{size}
1113 Set the thread stack size.
1116 Unrecognized @code{-X} options are ignored, for compatibility with
1120 This indicates that the name passed to @code{gij} should be interpreted
1121 as the name of a jar file, not a class.
1125 Print help, then exit.
1128 Print version number and continue.
1131 Print detailed version information, then exit.
1134 Print version number, then exit.
1137 @itemx -verbose:class
1138 Each time a class is initialized, print a short message on standard error.
1141 @code{gij} also recognizes and ignores the following options, for
1142 compatibility with existing application launch scripts:
1143 @code{-client}, @code{-server}, @code{-hotspot}, @code{-jrockit},
1144 @code{-agentlib}, @code{-agentpath}, @code{-debug}, @code{-d32},
1145 @code{-d64}, @code{-javaagent}, @code{-noclassgc}, @code{-verify},
1146 and @code{-verifyremote}.
1150 @node Invoking gcj-dbtool
1151 @chapter Invoking gcj-dbtool.
1153 @c man title gcj-dbtool Manipulate class file mapping databases for libgcj
1156 @c man begin SYNOPSIS gcj-dbtool
1157 gcj-dbtool @option{OPTION} @var{DBFILE} [@option{MORE}] @dots{}
1159 gcj-dbtool [@option{-0}] [@option{-}] [@option{-n}] [@option{-a}] [@option{-f}]
1160 [@option{-t}] [@option{-l}] [@option{-p} [@var{LIBDIR}]]
1161 [@option{-v}] [@option{-m}] [@option{--version}] [@option{--help}]
1164 @c man begin SEEALSO gij
1165 gcc(1), gcj(1), gcjh(1), jcf-dump(1), gfdl(7),
1166 and the Info entries for @file{gcj} and @file{gcc}.
1170 @c man begin DESCRIPTION gcj-dbtool
1172 @code{gcj-dbtool} is a tool for creating and manipulating class file
1173 mapping databases. @code{libgcj} can use these databases to find a
1174 shared library corresponding to the bytecode representation of a
1175 class. This functionality is useful for ahead-of-time compilation of
1176 a program that has no knowledge of @code{gcj}.
1178 @code{gcj-dbtool} works best if all the jar files added to it are
1179 compiled using @code{-findirect-dispatch}.
1181 Note that @code{gcj-dbtool} is currently available as ``preview
1182 technology''. We believe it is a reasonable way to allow
1183 application-transparent ahead-of-time compilation, but this is an
1184 unexplored area. We welcome your comments.
1188 @c man begin OPTIONS gcj-dbtool
1191 @item -n @var{DBFILE} [@var{SIZE}]
1192 This creates a new database. Currently, databases cannot be resized;
1193 you can choose a larger initial size if desired. The default size is
1196 @item -a @var{DBFILE} @var{JARFILE} @var{LIB}
1197 @itemx -f @var{DBFILE} @var{JARFILE} @var{LIB}
1198 This adds a jar file to the database. For each class file in the jar,
1199 a cryptographic signature of the bytecode representation of the class
1200 is recorded in the database. At runtime, a class is looked up by its
1201 signature and the compiled form of the class is looked for in the
1202 corresponding shared library. The @option{-a} option will verify
1203 that @var{LIB} exists before adding it to the database; @option{-f}
1206 @item [@option{-}][@option{-0}] -m @var{DBFILE} @var{DBFILE},[@var{DBFILE}]
1207 Merge a number of databases. The output database overwrites any
1208 existing database. To add databases into an existing database,
1209 include the destination in the list of sources.
1211 If @option{-} or @option{-0} are used, the list of files to read is
1212 taken from standard input instead of the command line. For
1213 @option{-0}, Input filenames are terminated by a null character
1214 instead of by whitespace. Useful when arguments might contain white
1215 space. The GNU find -print0 option produces input suitable for this
1218 @item -t @var{DBFILE}
1221 @item -l @var{DBFILE}
1222 List the contents of a database.
1225 Print the name of the default database. If there is no default
1226 database, this prints a blank line. If @var{LIBDIR} is specified, use
1227 it instead of the default library directory component of the database
1231 Print a help message, then exit.
1235 Print version information, then exit.
1241 @node Invoking jv-convert
1242 @chapter Invoking jv-convert
1244 @c man title jv-convert Convert file from one encoding to another
1246 @c man begin SYNOPSIS jv-convert
1247 @command{jv-convert} [@option{OPTION}] @dots{} [@var{INPUTFILE} [@var{OUTPUTFILE}]]
1250 [@option{--encoding} @var{name}]
1251 [@option{--from} @var{name}]
1252 [@option{--to} @var{name}]
1253 [@option{-i} @var{file}] [@option{-o} @var{file}]
1254 [@option{--reverse}] [@option{--help}] [@option{--version}]
1258 @c man begin DESCRIPTION jv-convert
1260 @command{jv-convert} is a utility included with @code{libgcj} which
1261 converts a file from one encoding to another. It is similar to the Unix
1262 @command{iconv} utility.
1264 The encodings supported by @command{jv-convert} are platform-dependent.
1265 Currently there is no way to get a list of all supported encodings.
1269 @c man begin OPTIONS jv-convert
1272 @item --encoding @var{name}
1273 @itemx --from @var{name}
1274 Use @var{name} as the input encoding. The default is the current
1277 @item --to @var{name}
1278 Use @var{name} as the output encoding. The default is the
1279 @code{JavaSrc} encoding; this is ASCII with @samp{\u} escapes for
1280 non-ASCII characters.
1283 Read from @var{file}. The default is to read from standard input.
1286 Write to @var{file}. The default is to write to standard output.
1289 Swap the input and output encodings.
1292 Print a help message, then exit.
1295 Print version information, then exit.
1300 @node Invoking grmic
1301 @chapter Invoking grmic
1303 @c man title grmic Generate stubs for Remote Method Invocation
1305 @c man begin SYNOPSIS grmic
1306 @command{grmic} [@option{OPTION}] @dots{} @var{class} @dots{}
1309 [@option{-keepgenerated}]
1313 [@option{-nocompile}]
1315 [@option{-d} @var{directory}]
1321 @c man begin DESCRIPTION grmic
1323 @command{grmic} is a utility included with @code{libgcj} which generates
1324 stubs for remote objects.
1326 @c FIXME: Add real information here.
1327 @c This really isn't much more than the --help output.
1329 Note that this program isn't yet fully compatible with the JDK
1330 @command{grmic}. Some options, such as @option{-classpath}, are
1331 recognized but currently ignored. We have left these options
1332 undocumented for now.
1334 Long options can also be given with a GNU-style leading @samp{--}. For
1335 instance, @option{--help} is accepted.
1339 @c man begin OPTIONS grmic
1343 @itemx -keepgenerated
1344 By default, @command{grmic} deletes intermediate files. Either of these
1345 options causes it not to delete such files.
1348 Cause @command{grmic} to create stubs and skeletons for the 1.1
1352 Cause @command{grmic} to create stubs and skeletons compatible with both
1353 the 1.1 and 1.2 protocol versions. This is the default.
1356 Cause @command{grmic} to create stubs and skeletons for the 1.2
1360 Don't compile the generated files.
1363 Print information about what @command{grmic} is doing.
1365 @item -d @var{directory}
1366 Put output files in @var{directory}. By default the files are put in
1367 the current working directory.
1370 Print a help message, then exit.
1373 Print version information, then exit.
1379 @node Invoking grmiregistry
1380 @chapter Invoking grmiregistry
1382 @c man title grmiregistry Remote object registry
1384 @c man begin SYNOPSIS grmiregistry
1385 @command{grmic} [@option{OPTION}] @dots{} [@var{port}]
1388 [@option{--version}]
1392 @c man begin DESCRIPTION grmiregistry
1394 @command{grmiregistry} starts a remote object registry on the current
1395 host. If no port number is specified, then port 1099 is used.
1397 @c FIXME: Add real information here.
1398 @c This really isn't much more than the --help output.
1402 @c man begin OPTIONS grmiregistry
1406 Print a help message, then exit.
1409 Print version information, then exit.
1418 This documents CNI, the Compiled Native Interface,
1419 which is is a convenient way to write Java native methods using C++.
1420 This is a more efficient, more convenient, but less portable
1421 alternative to the standard JNI (Java Native Interface).
1424 * Basic concepts:: Introduction to using CNI@.
1425 * Packages:: How packages are mapped to C++.
1426 * Primitive types:: Handling primitive Java types in C++.
1427 * Reference types:: Handling Java reference types in C++.
1428 * Interfaces:: How Java interfaces map to C++.
1429 * Objects and Classes:: C++ and Java classes.
1430 * Class Initialization:: How objects are initialized.
1431 * Object allocation:: How to create Java objects in C++.
1432 * Memory allocation:: How to allocate and free memory.
1433 * Arrays:: Dealing with Java arrays in C++.
1434 * Methods:: Java methods in C++.
1435 * Strings:: Information about Java Strings.
1436 * Mixing with C++:: How CNI can interoperate with C++.
1437 * Exception Handling:: How exceptions are handled.
1438 * Synchronization:: Synchronizing between Java and C++.
1439 * Invocation:: Starting the Java runtime from C++.
1440 * Reflection:: Using reflection from C++.
1444 @node Basic concepts
1445 @section Basic concepts
1447 In terms of languages features, Java is mostly a subset
1448 of C++. Java has a few important extensions, plus a powerful standard
1449 class library, but on the whole that does not change the basic similarity.
1450 Java is a hybrid object-oriented language, with a few native types,
1451 in addition to class types. It is class-based, where a class may have
1452 static as well as per-object fields, and static as well as instance methods.
1453 Non-static methods may be virtual, and may be overloaded. Overloading is
1454 resolved at compile time by matching the actual argument types against
1455 the parameter types. Virtual methods are implemented using indirect calls
1456 through a dispatch table (virtual function table). Objects are
1457 allocated on the heap, and initialized using a constructor method.
1458 Classes are organized in a package hierarchy.
1460 All of the listed attributes are also true of C++, though C++ has
1461 extra features (for example in C++ objects may be allocated not just
1462 on the heap, but also statically or in a local stack frame). Because
1463 @command{gcj} uses the same compiler technology as G++ (the GNU
1464 C++ compiler), it is possible to make the intersection of the two
1465 languages use the same ABI (object representation and calling
1466 conventions). The key idea in CNI is that Java objects are C++
1467 objects, and all Java classes are C++ classes (but not the other way
1468 around). So the most important task in integrating Java and C++ is to
1469 remove gratuitous incompatibilities.
1471 You write CNI code as a regular C++ source file. (You do have to use
1472 a Java/CNI-aware C++ compiler, specifically a recent version of G++.)
1474 @noindent A CNI C++ source file must have:
1477 #include <gcj/cni.h>
1480 @noindent and then must include one header file for each Java class it uses, e.g.:
1483 #include <java/lang/Character.h>
1484 #include <java/util/Date.h>
1485 #include <java/lang/IndexOutOfBoundsException.h>
1488 @noindent These header files are automatically generated by @code{gcjh}.
1491 CNI provides some functions and macros to make using Java objects and
1492 primitive types from C++ easier. In general, these CNI functions and
1493 macros start with the @code{Jv} prefix, for example the function
1494 @code{JvNewObjectArray}. This convention is used to avoid conflicts
1495 with other libraries. Internal functions in CNI start with the prefix
1496 @code{_Jv_}. You should not call these; if you find a need to, let us
1497 know and we will try to come up with an alternate solution.
1500 @subsection Limitations
1502 Whilst a Java class is just a C++ class that doesn't mean that you are
1503 freed from the shackles of Java, a @acronym{CNI} C++ class must adhere to the
1504 rules of the Java programming language.
1506 For example: it is not possible to declare a method in a CNI class
1507 that will take a C string (@code{char*}) as an argument, or to declare a
1508 member variable of some non-Java datatype.
1514 The only global names in Java are class names, and packages. A
1515 @dfn{package} can contain zero or more classes, and also zero or more
1516 sub-packages. Every class belongs to either an unnamed package or a
1517 package that has a hierarchical and globally unique name.
1519 A Java package is mapped to a C++ @dfn{namespace}. The Java class
1520 @code{java.lang.String} is in the package @code{java.lang}, which is a
1521 sub-package of @code{java}. The C++ equivalent is the class
1522 @code{java::lang::String}, which is in the namespace @code{java::lang}
1523 which is in the namespace @code{java}.
1525 @noindent Here is how you could express this:
1528 (// @r{Declare the class(es), possibly in a header file:}
1537 class java::lang::String : public java::lang::Object
1543 @noindent The @code{gcjh} tool automatically generates the necessary namespace
1547 @subsection Leaving out package names
1549 Always using the fully-qualified name of a java class can be
1550 tiresomely verbose. Using the full qualified name also ties the code
1551 to a single package making code changes necessary should the class
1552 move from one package to another. The Java @code{package} declaration
1553 specifies that the following class declarations are in the named
1554 package, without having to explicitly name the full package
1555 qualifiers. The @code{package} declaration can be
1556 followed by zero or more @code{import} declarations, which
1557 allows either a single class or all the classes in a package to be
1558 named by a simple identifier. C++ provides something similar with the
1559 @code{using} declaration and directive.
1564 import @var{package-name}.@var{class-name};
1567 @noindent allows the program text to refer to @var{class-name} as a shorthand for
1568 the fully qualified name: @code{@var{package-name}.@var{class-name}}.
1571 @noindent To achieve the same effect C++, you have to do this:
1574 using @var{package-name}::@var{class-name};
1578 @noindent Java can also cause imports on demand, like this:
1581 import @var{package-name}.*;
1584 @noindent Doing this allows any class from the package @var{package-name} to be
1585 referred to only by its class-name within the program text.
1588 @noindent The same effect can be achieved in C++ like this:
1591 using namespace @var{package-name};
1595 @node Primitive types
1596 @section Primitive types
1598 Java provides 8 @dfn{primitives} types which represent integers, floats,
1599 characters and booleans (and also the void type). C++ has its own
1600 very similar concrete types. Such types in C++ however are not always
1601 implemented in the same way (an int might be 16, 32 or 64 bits for example)
1602 so CNI provides a special C++ type for each primitive Java type:
1604 @multitable @columnfractions .20 .25 .60
1605 @item @strong{Java type} @tab @strong{C/C++ typename} @tab @strong{Description}
1606 @item @code{char} @tab @code{jchar} @tab 16 bit Unicode character
1607 @item @code{boolean} @tab @code{jboolean} @tab logical (true or false) values
1608 @item @code{byte} @tab @code{jbyte} @tab 8-bit signed integer
1609 @item @code{short} @tab @code{jshort} @tab 16 bit signed integer
1610 @item @code{int} @tab @code{jint} @tab 32 bit signed integer
1611 @item @code{long} @tab @code{jlong} @tab 64 bit signed integer
1612 @item @code{float} @tab @code{jfloat} @tab 32 bit IEEE floating point number
1613 @item @code{double} @tab @code{jdouble} @tab 64 bit IEEE floating point number
1614 @item @code{void} @tab @code{void} @tab no value
1617 When referring to a Java type You should always use these C++ typenames (e.g.: @code{jint})
1618 to avoid disappointment.
1621 @subsection Reference types associated with primitive types
1623 In Java each primitive type has an associated reference type,
1624 e.g.: @code{boolean} has an associated @code{java.lang.Boolean.TYPE} class.
1625 In order to make working with such classes easier GCJ provides the macro
1628 @deffn macro JvPrimClass type
1629 Return a pointer to the @code{Class} object corresponding to the type supplied.
1632 JvPrimClass(void) @result{} java.lang.Void.TYPE
1638 @node Reference types
1639 @section Reference types
1641 A Java reference type is treated as a class in C++. Classes and
1642 interfaces are handled this way. A Java reference is translated to a
1643 C++ pointer, so for instance a Java @code{java.lang.String} becomes,
1644 in C++, @code{java::lang::String *}.
1646 CNI provides a few built-in typedefs for the most common classes:
1647 @multitable @columnfractions .30 .25 .60
1648 @item @strong{Java type} @tab @strong{C++ typename} @tab @strong{Description}
1649 @item @code{java.lang.Object} @tab @code{jobject} @tab Object type
1650 @item @code{java.lang.String} @tab @code{jstring} @tab String type
1651 @item @code{java.lang.Class} @tab @code{jclass} @tab Class type
1657 Every Java class or interface has a corresponding @code{Class}
1658 instance. These can be accessed in CNI via the static @code{class$}
1659 field of a class. The @code{class$} field is of type @code{Class}
1660 (and not @code{Class *}), so you will typically take the address of
1664 Here is how you can refer to the class of @code{String}, which in
1665 Java would be written @code{String.class}:
1668 using namespace java::lang;
1669 doSomething (&String::class$);
1676 A Java class can @dfn{implement} zero or more
1677 @dfn{interfaces}, in addition to inheriting from
1678 a single base class.
1680 @acronym{CNI} allows CNI code to implement methods of interfaces.
1681 You can also call methods through interface references, with some
1684 @acronym{CNI} doesn't understand interface inheritance at all yet. So,
1685 you can only call an interface method when the declared type of the
1686 field being called matches the interface which declares that
1687 method. The workaround is to cast the interface reference to the right
1690 For example if you have:
1698 interface B extends A
1704 and declare a variable of type @code{B} in C++, you can't call
1705 @code{a()} unless you cast it to an @code{A} first.
1707 @node Objects and Classes
1708 @section Objects and Classes
1712 All Java classes are derived from @code{java.lang.Object}. C++ does
1713 not have a unique root class, but we use the C++ class
1714 @code{java::lang::Object} as the C++ version of the
1715 @code{java.lang.Object} Java class. All other Java classes are mapped
1716 into corresponding C++ classes derived from @code{java::lang::Object}.
1718 Interface inheritance (the @code{implements} keyword) is currently not
1719 reflected in the C++ mapping.
1722 @subsection Object fields
1724 Each object contains an object header, followed by the instance fields
1725 of the class, in order. The object header consists of a single
1726 pointer to a dispatch or virtual function table. (There may be extra
1727 fields @emph{in front of} the object, for example for memory
1728 management, but this is invisible to the application, and the
1729 reference to the object points to the dispatch table pointer.)
1731 The fields are laid out in the same order, alignment, and size as in
1732 C++. Specifically, 8-bit and 16-bit native types (@code{byte},
1733 @code{short}, @code{char}, and @code{boolean}) are @emph{not} widened
1734 to 32 bits. Note that the Java VM does extend 8-bit and 16-bit types
1735 to 32 bits when on the VM stack or temporary registers.
1737 If you include the @code{gcjh}-generated header for a
1738 class, you can access fields of Java classes in the @emph{natural}
1739 way. For example, given the following Java class:
1745 public Int (int i) @{ this.i = i; @}
1746 public static Int zero = new Int(0);
1753 #include <gcj/cni.h>;
1757 mult (Int *p, jint k)
1760 return Int::zero; // @r{Static member access.}
1761 return new Int(p->i * k);
1766 @subsection Access specifiers
1768 CNI does not strictly enforce the Java access
1769 specifiers, because Java permissions cannot be directly mapped
1770 into C++ permission. Private Java fields and methods are mapped
1771 to private C++ fields and methods, but other fields and methods
1772 are mapped to public fields and methods.
1776 @node Class Initialization
1777 @section Class Initialization
1779 Java requires that each class be automatically initialized at the time
1780 of the first active use. Initializing a class involves
1781 initializing the static fields, running code in class initializer
1782 methods, and initializing base classes. There may also be
1783 some implementation specific actions, such as allocating
1784 @code{String} objects corresponding to string literals in
1787 The GCJ compiler inserts calls to @code{JvInitClass} at appropriate
1788 places to ensure that a class is initialized when required. The C++
1789 compiler does not insert these calls automatically---it is the
1790 programmer's responsibility to make sure classes are initialized.
1791 However, this is fairly painless because of the conventions assumed by
1794 First, @code{libgcj} will make sure a class is initialized before an
1795 instance of that object is created. This is one of the
1796 responsibilities of the @code{new} operation. This is taken care of
1797 both in Java code, and in C++ code. When G++ sees a @code{new} of a
1798 Java class, it will call a routine in @code{libgcj} to allocate the
1799 object, and that routine will take care of initializing the class.
1800 Note however that this does not happen for Java arrays; you must
1801 allocate those using the appropriate CNI function. It follows that
1802 you can access an instance field, or call an instance (non-static)
1803 method and be safe in the knowledge that the class and all of its base
1804 classes have been initialized.
1806 Invoking a static method is also safe. This is because the
1807 Java compiler adds code to the start of a static method to make sure
1808 the class is initialized. However, the C++ compiler does not
1809 add this extra code. Hence, if you write a native static method
1810 using CNI, you are responsible for calling @code{JvInitClass}
1811 before doing anything else in the method (unless you are sure
1812 it is safe to leave it out).
1814 Accessing a static field also requires the class of the
1815 field to be initialized. The Java compiler will generate code
1816 to call @code{JvInitClass} before getting or setting the field.
1817 However, the C++ compiler will not generate this extra code,
1818 so it is your responsibility to make sure the class is
1819 initialized before you access a static field from C++.
1822 @node Object allocation
1823 @section Object allocation
1825 New Java objects are allocated using a
1826 @dfn{class instance creation expression}, e.g.:
1829 new @var{Type} ( ... )
1832 The same syntax is used in C++. The main difference is that
1833 C++ objects have to be explicitly deleted; in Java they are
1834 automatically deleted by the garbage collector.
1835 Using @acronym{CNI}, you can allocate a new Java object
1836 using standard C++ syntax and the C++ compiler will allocate
1837 memory from the garbage collector. If you have overloaded
1838 constructors, the compiler will choose the correct one
1839 using standard C++ overload resolution rules.
1841 @noindent For example:
1844 java::util::Hashtable *ht = new java::util::Hashtable(120);
1848 @node Memory allocation
1849 @section Memory allocation
1851 When allocating memory in @acronym{CNI} methods it is best to handle
1852 out-of-memory conditions by throwing a Java exception. These
1853 functions are provided for that purpose:
1855 @deftypefun void* JvMalloc (jsize @var{size})
1856 Calls malloc. Throws @code{java.lang.OutOfMemoryError} if allocation
1860 @deftypefun void* JvRealloc (void* @var{ptr}, jsize @var{size})
1861 Calls realloc. Throws @code{java.lang.OutOfMemoryError} if
1865 @deftypefun void JvFree (void* @var{ptr})
1872 While in many ways Java is similar to C and C++, it is quite different
1873 in its treatment of arrays. C arrays are based on the idea of pointer
1874 arithmetic, which would be incompatible with Java's security
1875 requirements. Java arrays are true objects (array types inherit from
1876 @code{java.lang.Object}). An array-valued variable is one that
1877 contains a reference (pointer) to an array object.
1879 Referencing a Java array in C++ code is done using the
1880 @code{JArray} template, which as defined as follows:
1883 class __JArray : public java::lang::Object
1890 class JArray : public __JArray
1894 T& operator[](jint i) @{ return data[i]; @}
1899 There are a number of @code{typedef}s which correspond to @code{typedef}s
1900 from the @acronym{JNI}. Each is the type of an array holding objects
1901 of the relevant type:
1904 typedef __JArray *jarray;
1905 typedef JArray<jobject> *jobjectArray;
1906 typedef JArray<jboolean> *jbooleanArray;
1907 typedef JArray<jbyte> *jbyteArray;
1908 typedef JArray<jchar> *jcharArray;
1909 typedef JArray<jshort> *jshortArray;
1910 typedef JArray<jint> *jintArray;
1911 typedef JArray<jlong> *jlongArray;
1912 typedef JArray<jfloat> *jfloatArray;
1913 typedef JArray<jdouble> *jdoubleArray;
1917 @deftypemethod {template<class T>} T* elements (JArray<T> @var{array})
1918 This template function can be used to get a pointer to the elements of
1919 the @code{array}. For instance, you can fetch a pointer to the
1920 integers that make up an @code{int[]} like so:
1923 extern jintArray foo;
1924 jint *intp = elements (foo);
1927 The name of this function may change in the future.
1931 @deftypefun jobjectArray JvNewObjectArray (jsize @var{length}, jclass @var{klass}, jobject @var{init})
1932 This creates a new array whose elements have reference type.
1933 @code{klass} is the type of elements of the array and
1934 @code{init} is the initial value put into every slot in the array.
1938 using namespace java::lang;
1939 JArray<String *> *array
1940 = (JArray<String *> *) JvNewObjectArray(length, &String::class$, NULL);
1944 @subsection Creating arrays
1946 For each primitive type there is a function which can be used to
1947 create a new array of that type. The name of the function is of the
1951 JvNew@var{Type}Array
1954 @noindent For example:
1960 @noindent can be used to create an array of Java primitive boolean types.
1962 @noindent The following function definition is the template for all such functions:
1964 @deftypefun jbooleanArray JvNewBooleanArray (jint @var{length})
1965 Create's an array @var{length} indices long.
1968 @deftypefun jsize JvGetArrayLength (jarray @var{array})
1969 Returns the length of the @var{array}.
1976 Java methods are mapped directly into C++ methods.
1977 The header files generated by @code{gcjh}
1978 include the appropriate method definitions.
1979 Basically, the generated methods have the same names and
1980 @emph{corresponding} types as the Java methods,
1981 and are called in the natural manner.
1983 @subsection Overloading
1985 Both Java and C++ provide method overloading, where multiple
1986 methods in a class have the same name, and the correct one is chosen
1987 (at compile time) depending on the argument types.
1988 The rules for choosing the correct method are (as expected) more complicated
1989 in C++ than in Java, but given a set of overloaded methods
1990 generated by @code{gcjh} the C++ compiler will choose
1993 Common assemblers and linkers are not aware of C++ overloading,
1994 so the standard implementation strategy is to encode the
1995 parameter types of a method into its assembly-level name.
1996 This encoding is called @dfn{mangling},
1997 and the encoded name is the @dfn{mangled name}.
1998 The same mechanism is used to implement Java overloading.
1999 For C++/Java interoperability, it is important that both the Java
2000 and C++ compilers use the @emph{same} encoding scheme.
2002 @subsection Static methods
2004 Static Java methods are invoked in @acronym{CNI} using the standard
2005 C++ syntax, using the @code{::} operator rather
2006 than the @code{.} operator.
2008 @noindent For example:
2011 jint i = java::lang::Math::round((jfloat) 2.3);
2014 @noindent C++ method definition syntax is used to define a static native method.
2018 #include <java/lang/Integer>
2019 java::lang::Integer*
2020 java::lang::Integer::getInteger(jstring str)
2027 @subsection Object Constructors
2029 Constructors are called implicitly as part of object allocation
2030 using the @code{new} operator.
2032 @noindent For example:
2035 java::lang::Integer *x = new java::lang::Integer(234);
2038 Java does not allow a constructor to be a native method.
2039 This limitation can be coded round however because a constructor
2040 can @emph{call} a native method.
2043 @subsection Instance methods
2045 Calling a Java instance method from a C++ @acronym{CNI} method is done
2046 using the standard C++ syntax, e.g.:
2049 // @r{First create the Java object.}
2050 java::lang::Integer *x = new java::lang::Integer(234);
2051 // @r{Now call a method.}
2052 jint prim_value = x->intValue();
2053 if (x->longValue == 0)
2057 @noindent Defining a Java native instance method is also done the natural way:
2060 #include <java/lang/Integer.h>
2063 java::lang:Integer::doubleValue()
2065 return (jdouble) value;
2070 @subsection Interface methods
2072 In Java you can call a method using an interface reference. This is
2073 supported, but not completely. @xref{Interfaces}.
2081 @acronym{CNI} provides a number of utility functions for
2082 working with Java Java @code{String} objects.
2083 The names and interfaces are analogous to those of @acronym{JNI}.
2086 @deftypefun jstring JvNewString (const char* @var{chars}, jsize @var{len})
2087 Returns a Java @code{String} object with characters from the C string
2088 @var{chars} up to the index @var{len} in that array.
2091 @deftypefun jstring JvNewStringLatin1 (const char* @var{bytes}, jsize @var{len})
2092 Returns a Java @code{String} made up of @var{len} bytes from @var{bytes}.
2096 @deftypefun jstring JvNewStringLatin1 (const char* @var{bytes})
2097 As above but the length of the @code{String} is @code{strlen(@var{bytes})}.
2100 @deftypefun jstring JvNewStringUTF (const char* @var{bytes})
2101 Returns a @code{String} which is made up of the UTF encoded characters
2102 present in the C string @var{bytes}.
2105 @deftypefun jchar* JvGetStringChars (jstring @var{str})
2106 Returns a pointer to an array of characters making up the @code{String} @var{str}.
2109 @deftypefun int JvGetStringUTFLength (jstring @var{str})
2110 Returns the number of bytes required to encode the contents of the
2111 @code{String} @var{str} in UTF-8.
2114 @deftypefun jsize JvGetStringUTFRegion (jstring @var{str}, jsize @var{start}, jsize @var{len}, char* @var{buf})
2115 Puts the UTF-8 encoding of a region of the @code{String} @var{str} into
2116 the buffer @code{buf}. The region to fetch is marked by @var{start} and @var{len}.
2118 Note that @var{buf} is a buffer, not a C string. It is @emph{not}
2123 @node Mixing with C++
2124 @section Interoperating with C/C++
2126 Because @acronym{CNI} is designed to represent Java classes and methods it
2127 cannot be mixed readily with C/C++ types.
2129 One important restriction is that Java classes cannot have non-Java
2130 type instance or static variables and cannot have methods which take
2131 non-Java types as arguments or return non-Java types.
2133 @noindent None of the following is possible with CNI:
2137 class ::MyClass : public java::lang::Object
2139 char* variable; // @r{char* is not a valid Java type.}
2144 ::SomeClass::someMethod (char *arg)
2149 @} // @r{@code{uint} is not a valid Java type, neither is @code{char*}}
2152 @noindent Of course, it is ok to use C/C++ types within the scope of a method:
2157 ::SomeClass::otherMethod (jstring str)
2168 The above restriction can be problematic, so @acronym{CNI} includes the
2169 @code{gnu.gcj.RawData} class. The @code{RawData} class is a
2170 @dfn{non-scanned reference} type. In other words variables declared
2171 of type @code{RawData} can contain any data and are not checked by the
2172 compiler or memory manager in any way.
2174 This means that you can put C/C++ data structures (including classes)
2175 in your @acronym{CNI} classes, as long as you use the appropriate cast.
2177 @noindent Here are some examples:
2181 class ::MyClass : public java::lang::Object
2183 gnu.gcj.RawData string;
2186 gnu.gcj.RawData getText ();
2190 ::MyClass::MyClass ()
2197 ::MyClass::getText ()
2203 ::MyClass::printText ()
2205 printf("%s\n", (char*) string);
2210 @subsection RawDataManaged
2212 @code{gnu.gcj.RawDataManaged} is another type used to indicate special data used
2213 by native code. Unlike the @code{RawData} type, fields declared as
2214 @code{RawDataManaged} will be "marked" by the memory manager and
2215 considered for garbage collection.
2217 Native data which is allocated using CNI's @code{JvAllocBytes()}
2218 function and stored in a @code{RawDataManaged} will be automatically
2219 freed when the Java object it is associated with becomes unreachable.
2221 @subsection Native memory allocation
2223 @deftypefun void* JvAllocBytes (jsize @var{size})
2224 Allocates @var{size} bytes from the heap. The memory returned is zeroed.
2225 This memory is not scanned for pointers by the garbage collector, but will
2226 be freed if no references to it are discovered.
2228 This function can be useful if you need to associate some native data with a
2229 Java object. Using a CNI's special @code{RawDataManaged} type, native data
2230 allocated with @code{JvAllocBytes} will be automatically freed when the Java
2231 object itself becomes unreachable.
2234 @subsection Posix signals
2236 On Posix based systems the @code{libgcj} library uses several signals
2237 internally. @acronym{CNI} code should not attempt to use the same
2238 signals as doing so may cause @code{libgcj} and/or the @acronym{CNI}
2241 SIGSEGV is used on many systems to generate
2242 @code{NullPointerExceptions}. SIGCHLD is used internally by
2243 @code{Runtime.exec()}. Several other signals (that vary from platform to
2244 platform) can be used by the memory manager and by
2245 @code{Thread.interrupt()}.
2247 @node Exception Handling
2248 @section Exception Handling
2250 While C++ and Java share a common exception handling framework,
2251 things are not yet perfectly integrated. The main issue is that the
2252 run-time type information facilities of the two
2253 languages are not integrated.
2255 Still, things work fairly well. You can throw a Java exception from
2256 C++ using the ordinary @code{throw} construct, and this
2257 exception can be caught by Java code. Similarly, you can catch an
2258 exception thrown from Java using the C++ @code{catch}
2261 @noindent Here is an example:
2265 throw new java::lang::IndexOutOfBoundsException();
2268 Normally, G++ will automatically detect when you are writing C++
2269 code that uses Java exceptions, and handle them appropriately.
2270 However, if C++ code only needs to execute destructors when Java
2271 exceptions are thrown through it, GCC will guess incorrectly. Sample
2275 struct S @{ ~S(); @};
2277 extern void bar(); // @r{Is implemented in Java and may throw exceptions.}
2286 The usual effect of an incorrect guess is a link failure, complaining of
2287 a missing routine called @code{__gxx_personality_v0}.
2289 You can inform the compiler that Java exceptions are to be used in a
2290 translation unit, irrespective of what it might think, by writing
2291 @code{#pragma GCC java_exceptions} at the head of the
2292 file. This @code{#pragma} must appear before any
2293 functions that throw or catch exceptions, or run destructors when
2294 exceptions are thrown through them.
2296 @node Synchronization
2297 @section Synchronization
2299 Each Java object has an implicit monitor.
2300 The Java VM uses the instruction @code{monitorenter} to acquire
2301 and lock a monitor, and @code{monitorexit} to release it.
2303 The corresponding CNI macros are @code{JvMonitorEnter} and
2304 @code{JvMonitorExit} (JNI has similar methods @code{MonitorEnter}
2305 and @code{MonitorExit}).
2308 The Java source language does not provide direct access to these primitives.
2309 Instead, there is a @code{synchronized} statement that does an
2310 implicit @code{monitorenter} before entry to the block,
2311 and does a @code{monitorexit} on exit from the block.
2312 Note that the lock has to be released even when the block is abnormally
2313 terminated by an exception, which means there is an implicit
2314 @code{try finally} surrounding synchronization locks.
2316 From C++, it makes sense to use a destructor to release a lock.
2317 @acronym{CNI} defines the following utility class:
2320 class JvSynchronize() @{
2322 JvSynchronize(jobject o) @{ obj = o; JvMonitorEnter(o); @}
2323 ~JvSynchronize() @{ JvMonitorExit(obj); @}
2336 @noindent might become this C++ code:
2340 JvSynchronize dummy (OBJ);
2345 Java also has methods with the @code{synchronized} attribute.
2346 This is equivalent to wrapping the entire method body in a
2347 @code{synchronized} statement.
2348 (Alternatively, an implementation could require the caller to do
2349 the synchronization. This is not practical for a compiler, because
2350 each virtual method call would have to test at run-time if
2351 synchronization is needed.) Since in @command{gcj}
2352 the @code{synchronized} attribute is handled by the
2353 method implementation, it is up to the programmer
2354 of a synchronized native method to handle the synchronization
2355 (in the C++ implementation of the method).
2356 In other words, you need to manually add @code{JvSynchronize}
2357 in a @code{native synchronized} method.
2362 CNI permits C++ applications to make calls into Java classes, in addition to
2363 allowing Java code to call into C++. Several functions, known as the
2364 @dfn{invocation API}, are provided to support this.
2366 @deftypefun jint JvCreateJavaVM (JvVMInitArgs* @var{vm_args})
2368 Initializes the Java runtime. This function performs essential initialization
2369 of the threads interface, garbage collector, exception handling and other key
2370 aspects of the runtime. It must be called once by an application with
2371 a non-Java @code{main()} function, before any other Java or CNI calls are made.
2372 It is safe, but not recommended, to call @code{JvCreateJavaVM()} more than
2373 once provided it is only called from a single thread.
2374 The @var{vmargs} parameter can be used to specify initialization parameters
2375 for the Java runtime. It may be @code{NULL}.
2377 JvVMInitArgs represents a list of virtual machine initialization
2378 arguments. @code{JvCreateJavaVM()} ignores the version field.
2381 typedef struct JvVMOption
2383 // a VM initialization option
2385 // extra information associated with this option
2389 typedef struct JvVMInitArgs
2391 // for compatibility with JavaVMInitArgs
2394 // number of VM initialization options
2397 // an array of VM initialization options
2398 JvVMOption* options;
2400 // true if the option parser should ignore unrecognized options
2401 jboolean ignoreUnrecognized;
2405 @code{JvCreateJavaVM()} returns @code{0} upon success, or @code{-1} if
2406 the runtime is already initialized.
2408 @emph{Note:} In GCJ 3.1, the @code{vm_args} parameter is ignored. It
2409 is recognized and used as of release 4.0.
2412 @deftypefun java::lang::Thread* JvAttachCurrentThread (jstring @var{name}, java::lang::ThreadGroup* @var{group})
2413 Registers an existing thread with the Java runtime. This must be called once
2414 from each thread, before that thread makes any other Java or CNI calls. It
2415 must be called after @code{JvCreateJavaVM}.
2416 @var{name} specifies a name for the thread. It may be @code{NULL}, in which
2417 case a name will be generated.
2418 @var{group} is the ThreadGroup in which this thread will be a member. If it
2419 is @code{NULL}, the thread will be a member of the main thread group.
2420 The return value is the Java @code{Thread} object that represents the thread.
2421 It is safe to call @code{JvAttachCurrentThread()} more than once from the same
2422 thread. If the thread is already attached, the call is ignored and the current
2423 thread object is returned.
2426 @deftypefun jint JvDetachCurrentThread ()
2427 Unregisters a thread from the Java runtime. This should be called by threads
2428 that were attached using @code{JvAttachCurrentThread()}, after they have
2429 finished making calls to Java code. This ensures that any resources associated
2430 with the thread become eligible for garbage collection.
2431 This function returns @code{0} upon success, or @code{-1} if the current thread
2435 @subsection Handling uncaught exceptions
2437 If an exception is thrown from Java code called using the invocation API, and
2438 no handler for the exception can be found, the runtime will abort the
2439 application. In order to make the application more robust, it is recommended
2440 that code which uses the invocation API be wrapped by a top-level try/catch
2441 block that catches all Java exceptions.
2445 The following code demonstrates the use of the invocation API. In this
2446 example, the C++ application initializes the Java runtime and attaches
2447 itself. The @code{java.lang.System} class is initialized in order to
2448 access its @code{out} field, and a Java string is printed. Finally, the thread
2449 is detached from the runtime once it has finished making Java calls. Everything
2450 is wrapped with a try/catch block to provide a default handler for any uncaught
2453 The example can be compiled with @command{c++ -c test.cc; gcj test.o}.
2457 #include <gcj/cni.h>
2458 #include <java/lang/System.h>
2459 #include <java/io/PrintStream.h>
2460 #include <java/lang/Throwable.h>
2462 int main(int argc, char *argv[])
2464 using namespace java::lang;
2468 JvCreateJavaVM(NULL);
2469 JvAttachCurrentThread(NULL, NULL);
2471 String *message = JvNewStringLatin1("Hello from C++");
2472 JvInitClass(&System::class$);
2473 System::out->println(message);
2475 JvDetachCurrentThread();
2477 catch (Throwable *t)
2479 System::err->println(JvNewStringLatin1("Unhandled Java exception:"));
2480 t->printStackTrace();
2488 Reflection is possible with CNI code, it functions similarly to how it
2489 functions with JNI@.
2491 @c clean this up... I mean, what are the types jfieldID and jmethodID in JNI?
2492 The types @code{jfieldID} and @code{jmethodID}
2495 @noindent The functions:
2498 @item @code{JvFromReflectedField},
2499 @item @code{JvFromReflectedMethod},
2500 @item @code{JvToReflectedField}
2501 @item @code{JvToFromReflectedMethod}
2504 @noindent will be added shortly, as will other functions corresponding to JNI@.
2507 @node System properties
2508 @chapter System properties
2510 The runtime behavior of the @code{libgcj} library can be modified by setting
2511 certain system properties. These properties can be compiled into the program
2512 using the @code{-D@var{name}[=@var{value}]} option to @command{gcj} or by
2513 setting them explicitly in the program by calling the
2514 @code{java.lang.System.setProperty()} method. Some system properties are only
2515 used for informational purposes (like giving a version number or a user name).
2516 A program can inspect the current value of a property by calling the
2517 @code{java.lang.System.getProperty()} method.
2520 * Standard Properties:: Standard properties supported by @code{libgcj}
2521 * GNU Classpath Properties:: Properties found in Classpath based libraries
2522 * libgcj Runtime Properties:: Properties specific to @code{libgcj}
2525 @node Standard Properties
2526 @section Standard Properties
2528 The following properties are normally found in all implementations of the core
2529 libraries for the Java language.
2534 The @code{libgcj} version number.
2537 Set to @samp{The Free Software Foundation, Inc.}
2539 @item java.vendor.url
2540 Set to @uref{http://gcc.gnu.org/java/}.
2543 The directory where @code{gcj} was installed. Taken from the @code{--prefix}
2544 option given to @command{configure}.
2546 @item java.class.version
2547 The class format version number supported by the libgcj byte code interpreter.
2548 (Currently @samp{46.0})
2550 @item java.vm.specification.version
2551 The Virtual Machine Specification version implemented by @code{libgcj}.
2552 (Currently @samp{1.0})
2554 @item java.vm.specification.vendor
2555 The name of the Virtual Machine specification designer.
2557 @item java.vm.specification.name
2558 The name of the Virtual Machine specification
2559 (Set to @samp{Java Virtual Machine Specification}).
2561 @item java.vm.version
2562 The @command{gcj} version number.
2564 @item java.vm.vendor
2565 Set to @samp{The Free Software Foundation, Inc.}
2568 Set to @samp{GNU libgcj}.
2570 @item java.specification.version
2571 The Runtime Environment specification version implemented by @code{libgcj}.
2572 (Currently set to @samp{1.3})
2574 @item java.specification.vendor
2575 The Runtime Environment specification designer.
2577 @item java.specification.name
2578 The name of the Runtime Environment specification
2579 (Set to @samp{Java Platform API Specification}).
2581 @item java.class.path
2582 The paths (jar files, zip files and directories) used for finding class files.
2584 @item java.library.path
2585 Directory path used for finding native libraries.
2587 @item java.io.tmpdir
2588 The directory used to put temporary files in.
2591 Name of the Just In Time compiler to use by the byte code interpreter.
2592 Currently not used in @code{libgcj}.
2595 Directories containing jar files with extra libraries. Will be used when
2598 @item java.protocol.handler.pkgs
2599 A @samp{|} separated list of package names that is used to find classes that
2600 implement handlers for @code{java.net.URL}.
2602 @item java.rmi.server.codebase
2603 A list of URLs that is used by the @code{java.rmi.server.RMIClassLoader}
2604 to load classes from.
2607 A list of class names that will be loaded by the @code{java.sql.DriverManager}
2610 @item file.separator
2611 The separator used in when directories are included in a filename
2612 (normally @samp{/} or @samp{\} ).
2615 The default character encoding used when converting platform native files to
2616 Unicode (usually set to @samp{8859_1}).
2618 @item path.separator
2619 The standard separator used when a string contains multiple paths
2620 (normally @samp{:} or @samp{;}), the string is usually not a valid character
2621 to use in normal directory names.)
2623 @item line.separator
2624 The default line separator used on the platform (normally @samp{\n}, @samp{\r}
2625 or a combination of those two characters).
2627 @item policy.provider
2628 The class name used for the default policy provider returned by
2629 @code{java.security.Policy.getPolicy}.
2632 The name of the user running the program. Can be the full name, the login name
2633 or empty if unknown.
2636 The default directory to put user specific files in.
2639 The current working directory from which the program was started.
2642 The default language as used by the @code{java.util.Locale} class.
2645 The default region as used by the @code{java.util.Local} class.
2648 The default variant of the language and region local used.
2651 The default timezone as used by the @code{java.util.TimeZone} class.
2654 The operating system/kernel name that the program runs on.
2657 The hardware that we are running on.
2660 The version number of the operating system/kernel.
2662 @item awt.appletWarning
2663 The string to display when an untrusted applet is displayed.
2664 Returned by @code{java.awt.Window.getWarningString()} when the window is
2668 The class name used for initializing the default @code{java.awt.Toolkit}.
2669 Defaults to @code{gnu.awt.gtk.GtkToolkit}.
2671 @item http.proxyHost
2672 Name of proxy host for http connections.
2674 @item http.proxyPort
2675 Port number to use when a proxy host is in use.
2679 @node GNU Classpath Properties
2680 @section GNU Classpath Properties
2682 @code{libgcj} is based on the GNU Classpath (Essential Libraries for Java) a
2683 GNU project to create free core class libraries for use with virtual machines
2684 and compilers for the Java language. The following properties are common to
2685 libraries based on GNU Classpath.
2689 @item gcj.dumpobject
2690 Enables printing serialization debugging by the @code{java.io.ObjectInput} and
2691 @code{java.io.ObjectOutput} classes when set to something else then the empty
2692 string. Only used when running a debug build of the library.
2694 @item gnu.classpath.vm.shortname
2695 This is a succinct name of the virtual machine. For @code{libgcj},
2696 this will always be @samp{libgcj}.
2698 @item gnu.classpath.home.url
2699 A base URL used for finding system property files (e.g.,
2700 @file{classpath.security}). By default this is a @samp{file:} URL
2701 pointing to the @file{lib} directory under @samp{java.home}.
2705 @node libgcj Runtime Properties
2706 @section libgcj Runtime Properties
2708 The following properties are specific to the @code{libgcj} runtime and will
2709 normally not be found in other core libraries for the java language.
2713 @item java.fullversion
2714 The combination of @code{java.vm.name} and @code{java.vm.version}.
2717 Same as @code{java.fullversion}.
2720 Used by the @code{java.net.DatagramSocket} class when set to something else
2721 then the empty string. When set all newly created @code{DatagramSocket}s will
2722 try to load a class @code{java.net.[impl.prefix]DatagramSocketImpl} instead of
2723 the normal @code{java.net.PlainDatagramSocketImpl}.
2725 @item gnu.gcj.progname
2726 The class or binary name that was used to invoke the program. This will be
2727 the name of the "main" class in the case where the @code{gij} front end is
2728 used, or the program binary name in the case where an application is compiled
2731 @item gnu.gcj.user.realname
2732 The real name of the user, as taken from the password file. This may
2733 not always hold only the user's name (as some sites put extra
2734 information in this field). Also, this property is not available on
2737 @item gnu.gcj.runtime.NameFinder.use_addr2line
2738 Whether an external process, @command{addr2line}, should be used to determine
2739 line number information when tracing the stack. Setting this to @code{false}
2740 may suppress line numbers when printing stack traces and when using
2741 the java.util.logging infrastructure. However, performance may improve
2742 significantly for applications that print stack traces or make logging calls
2745 @item gnu.gcj.runtime.NameFinder.show_raw
2746 Whether the address of a stack frame should be printed when the line
2747 number is unavailable. Setting this to @code{true} will cause the name
2748 of the object and the offset within that object to be printed when no
2749 line number is available. This allows for off-line decoding of
2750 stack traces if necessary debug information is available. The default
2751 is @code{false}, no raw addresses are printed.
2753 @item gnu.gcj.runtime.NameFinder.remove_unknown
2754 Whether stack frames for non-java code should be included in a stack
2755 trace. The default value is @code{true}, stack frames for non-java
2756 code are suppressed. Setting this to @code{false} will cause any
2757 non-java stack frames to be printed in addition to frames for the java
2760 @item gnu.gcj.runtime.VMClassLoader.library_control
2761 This controls how shared libraries are automatically loaded by the
2762 built-in class loader. If this property is set to @samp{full}, a full
2763 search is done for each requested class. If this property is set to
2764 @samp{cache}, then any failed lookups are cached and not tried again.
2765 If this property is set to @samp{never} (the default), then lookups
2766 are never done. For more information, @xref{Extensions}.
2768 @item gnu.gcj.runtime.endorsed.dirs
2769 This is like the standard @code{java.endorsed.dirs}, property, but
2770 specifies some extra directories which are searched after the standard
2771 endorsed directories. This is primarily useful for telling
2772 @code{libgcj} about additional libraries which are ordinarily
2773 incorporated into the JDK, and which should be loaded by the bootstrap
2774 class loader, but which are not yet part of @code{libgcj} itself for
2777 @item gnu.gcj.jit.compiler
2778 @c FIXME we should probably have a whole node on this...
2779 This is the full path to @command{gcj} executable which should be
2780 used to compile classes just-in-time when
2781 @code{ClassLoader.defineClass} is called. If not set, @command{gcj}
2782 will not be invoked by the runtime; this can also be controlled via
2783 @code{Compiler.disable}.
2785 @item gnu.gcj.jit.options
2786 This is a space-separated string of options which should be passed to
2787 @command{gcj} when in JIT mode. If not set, a sensible default is
2790 @item gnu.gcj.jit.cachedir
2791 This is the directory where cached shared library files are
2792 stored. If not set, JIT compilation is disabled. This should never
2793 be set to a directory that is writable by any other user.
2795 @item gnu.gcj.precompiled.db.path
2796 This is a sequence of file names, each referring to a file created by
2797 @command{gcj-dbtool}. These files will be used by @code{libgcj} to
2798 find shared libraries corresponding to classes that are loaded from
2799 bytecode. @code{libgcj} often has a built-in default database; it
2800 can be queried using @code{gcj-dbtool -p}.
2808 While writing @command{gcj} and @code{libgcj} we have, of course, relied
2809 heavily on documentation from Sun Microsystems. In particular we have
2810 used The Java Language Specification (both first and second editions),
2811 the Java Class Libraries (volumes one and two), and the Java Virtual
2812 Machine Specification. In addition we've used the online documentation
2813 at @uref{http://java.sun.com/}.
2815 The current @command{gcj} home page is
2816 @uref{http://gcc.gnu.org/java/}.
2818 For more information on gcc, see @uref{http://gcc.gnu.org/}.
2820 Some @code{libgcj} testing is done using the Mauve test suite. This is
2821 a free software Java class library test suite which is being written
2822 because the JCK is not free. See
2823 @uref{http://sources.redhat.com/mauve/} for more information.