1 \input texinfo @c -*-texinfo-*-
4 @setfilename cp-hacking.info
5 @settitle GNU Classpath Hacker's Guide
11 This file contains important information you will need to know if you
12 are going to hack on the GNU Classpath project code.
14 Copyright (C) 1998,1999,2000,2001,2002,2003,2004,2005,2007 Free Software Foundation, Inc.
17 @dircategory GNU Libraries
19 * Classpath Hacking: (cp-hacking). GNU Classpath Hacker's Guide
25 @title GNU Classpath Hacker's Guide
27 @author Paul N. Fisher
29 @author C. Brian Jones
30 @author Mark J. Wielaard
33 @vskip 0pt plus 1filll
34 Copyright @copyright{} 1998,1999,2000,2001,2002,2003,2004 Free Software Foundation, Inc.
36 Permission is granted to make and distribute verbatim copies of
37 this document provided the copyright notice and this permission notice
38 are preserved on all copies.
40 Permission is granted to copy and distribute modified versions of this
41 document under the conditions for verbatim copying, provided that the
42 entire resulting derived work is distributed under the terms of a
43 permission notice identical to this one.
45 Permission is granted to copy and distribute translations of this manual
46 into another language, under the above conditions for modified versions,
47 except that this permission notice may be stated in a translation
48 approved by the Free Software Foundation.
53 @node Top, Introduction, (dir), (dir)
54 @top GNU Classpath Hacker's Guide
56 This document contains important information you'll want to know if
57 you want to hack on GNU Classpath, Essential Libraries for Java, to
58 help create free core class libraries for use with virtual machines
59 and compilers for the java programming language.
63 * Introduction:: An introduction to the GNU Classpath project
64 * Requirements:: Very important rules that must be followed
65 * Volunteering:: So you want to help out
66 * Project Goals:: Goals of the GNU Classpath project
67 * Needed Tools and Libraries:: A list of programs and libraries you will need
68 * Installation:: Installation instructions
69 * Building and running with the X AWT peers:: Building and running with the X AWT peers
70 * Misc. Notes:: Miscellaneous notes
71 * Programming Standards:: Standards to use when writing code
72 * Hacking Code:: Working on code, Working with others
73 * Programming Goals:: What to consider when writing code
74 * API Compatibility:: How to handle serialization and deprecated methods
75 * Specification Sources:: Where to find class library specs
76 * Naming Conventions:: How files and directories are named
77 * Character Conversions:: Working on Character conversions
78 * Localization:: How to handle localization/internationalization
81 --- The Detailed Node Listing ---
85 * Source Code Style Guide::
87 Working on the code, Working with others
90 * Writing ChangeLogs::
94 * Writing ChangeLogs::
98 * Portability:: Writing Portable Software
99 * Utility Classes:: Reusing Software
100 * Robustness:: Writing Robust Software
101 * Java Efficiency:: Writing Efficient Java
102 * Native Efficiency:: Writing Efficient JNI
103 * Security:: Writing Secure Software
107 * Serialization:: Serialization
108 * Deprecated Methods:: Deprecated methods
112 * String Collation:: Sorting strings in different locales
113 * Break Iteration:: Breaking up text into words, sentences, and lines
114 * Date Formatting and Parsing:: Locale specific date handling
115 * Decimal/Currency Formatting and Parsing:: Local specific number handling
120 @node Introduction, Requirements, Top, Top
121 @comment node-name, next, previous, up
122 @chapter Introduction
124 The GNU Classpath Project is a dedicated to providing a 100% free,
125 clean room implementation of the standard core class libraries for
126 compilers and runtime environments for the java programming language.
127 It offers free software developers an alternative core library
128 implementation upon which larger java-like programming environments
129 can be build. The GNU Classpath Project was started in the Spring of
130 1998 as an official Free Software Foundation project. Most of the
131 volunteers working on GNU Classpath do so in their spare time, but a
132 couple of projects based on GNU Classpath have paid programmers to
133 improve the core libraries. We appreciate everyone's efforts in the
134 past to improve and help the project and look forward to future
135 contributions by old and new members alike.
137 @node Requirements, Volunteering, Introduction, Top
138 @comment node-name, next, previous, up
139 @chapter Requirements
141 Although GNU Classpath is following an open development model where input
142 from developers is welcome, there are certain base requirements that
143 need to be met by anyone who wants to contribute code to this project.
144 They are mostly dictated by legal requirements and are not arbitrary
145 restrictions chosen by the GNU Classpath team.
147 You will need to adhere to the following things if you want to donate
148 code to the GNU Classpath project:
152 @strong{Never under any circumstances refer to proprietary code while
153 working on GNU Classpath.} It is best if you have never looked at
154 alternative proprietary core library code at all. To reduce
155 temptation, it would be best if you deleted the @file{src.zip} file
156 from your proprietary JDK distribution (note that recent versions of
157 GNU Classpath and the compilers and environments build on it are
158 mature enough to not need any proprietary implementation at all when
159 working on GNU Classpath, except in exceptional cases where you need
160 to test compatibility issues pointed out by users). If you have
161 signed Sun's non-disclosure statement, then you unfortunately cannot
162 work on Classpath code at all. If you have any reason to believe that
163 your code might be ``tainted'', please say something on the mailing
164 list before writing anything. If it turns out that your code was not
165 developed in a clean room environment, we could be very embarrassed
166 someday in court. Please don't let that happen.
169 @strong{Never decompile proprietary class library implementations.} While
170 the wording of the license in Sun's Java 2 releases has changed, it is
171 not acceptable, under any circumstances, for a person working on
172 GNU Classpath to decompile Sun's class libraries. Allowing the use of
173 decompilation in the GNU Classpath project would open up a giant can of
174 legal worms, which we wish to avoid.
177 Classpath is licensed under the terms of the
178 @uref{http://www.fsf.org/copyleft/gpl.html,GNU General Public
179 License}, with a special exception included to allow linking with
180 non-GPL licensed works as long as no other license would restrict such
181 linking. To preserve freedom for all users and to maintain uniform
182 licensing of Classpath, we will not accept code into the main
183 distribution that is not licensed under these terms. The exact
184 wording of the license of the current version of GNU Classpath can be
185 found online from the
186 @uref{http://www.gnu.org/software/classpath/license.html, GNU
187 Classpath license page} and is of course distributed with current
188 snapshot release from @uref{ftp://ftp.gnu.org/gnu/classpath/} or by
189 obtaining a copy of the current CVS tree.
192 GNU Classpath is GNU software and this project is being officially sponsored
193 by the @uref{http://www.fsf.org/,Free Software Foundation}. Because of
194 this, the FSF will hold copyright to all code developed as part of
195 GNU Classpath. This will allow them to pursue copyright violators in court,
196 something an individual developer may neither have the time nor
197 resources to do. Everyone contributing code to GNU Classpath will need to
198 sign a copyright assignment statement. Additionally, if you are
199 employed as a programmer, your employer may need to sign a copyright
200 waiver disclaiming all interest in the software. This may sound harsh,
201 but unfortunately, it is the only way to ensure that the code you write
202 is legally yours to distribute.
205 @node Volunteering, Project Goals, Requirements, Top
206 @comment node-name, next, previous, up
207 @chapter Volunteering to Help
209 The GNU Classpath project needs volunteers to help us out. People are
210 needed to write unimplemented core packages, to test GNU Classpath on
211 free software programs written in the java programming language, to
212 test it on various platforms, and to port it to platforms that are
213 currently unsupported.
215 While pretty much all contributions are welcome (but see
216 @pxref{Requirements}) it is always preferable that volunteers do the
217 whole job when volunteering for a task. So when you volunteer to write
218 a Java package, please be willing to do the following:
222 Implement a complete drop-in replacement for the particular package.
223 That means implementing any ``internal'' classes. For example, in the
224 java.net package, there are non-public classes for implementing sockets.
225 Without those classes, the public socket interface is useless. But do
226 not feel obligated to completely implement all of the functionality at
227 once. For example, in the java.net package, there are different types
228 of protocol handlers for different types of URL's. Not all of these
229 need to be written at once.
232 Please write complete and thorough API documentation comments for
233 every public and protected method and variable. These should be
234 superior to Sun's and cover everything about the item being
238 Please write a regression test package that can be used to run tests
239 of your package's functionality. GNU Classpath uses the
240 @uref{http://sources.redhat.com/mauve/,Mauve project} for testing the
241 functionality of the core class libraries. The Classpath Project is
242 fast approaching the point in time where all modifications to the
243 source code repository will require appropriate test cases in Mauve to
244 ensure correctness and prevent regressions.
247 Writing good documentation, tests and fixing bugs should be every
248 developer's top priority in order to reach the elusive release of
251 @node Project Goals, Needed Tools and Libraries, Volunteering, Top
252 @comment node-name, next, previous, up
253 @chapter Project Goals
255 The goal of the Classpath project is to produce a
256 @uref{http://www.fsf.org/philosophy/free-sw.html,free} implementation of
257 the standard class library for Java. However, there are other more
258 specific goals as to which platforms should be supported.
260 Classpath is targeted to support the following operating systems:
264 Free operating systems. This includes GNU/Linux, GNU/Hurd, and the free
268 Other Unix-like operating systems.
271 Platforms which currently have no Java support at all.
274 Other platforms such as MS-Windows.
277 While free operating systems are the top priority, the other priorities
278 can shift depending on whether or not there is a volunteer to port
279 Classpath to those platforms and to test releases.
281 Eventually we hope the Classpath will support all JVM's that provide
282 JNI or CNI support. However, the top priority is free JVM's. A small
283 list of Compiler/VM environments that are currently actively
284 incorporating GNU Classpath is below. A more complete overview of
285 projects based on GNU classpath can be found online at
286 @uref{http://www.gnu.org/software/classpath/stories.html,the GNU
287 Classpath stories page}.
291 @uref{http://gcc.gnu.org/java/,GCJ}
293 @uref{http://jamvm.sourceforge.net/,jamvm}
295 @uref{http://kissme.sourceforge.net/,Kissme}
297 @uref{http://www.ibm.com/developerworks/oss/jikesrvm/,Jikes RVM}
299 @uref{http://www.sablevm.org/,SableVM}
301 @uref{http://www.kaffe.org/,Kaffe}
304 As with OS platform support, this priority list could change if a
305 volunteer comes forward to port, maintain, and test releases for a
306 particular JVM. Since gcj is part of the GNU Compiler Collective it
307 is one of the most important targets. But since it doesn't currently
308 work out of the box with GNU Classpath it is currently not the easiest
309 target. When hacking on GNU Classpath the easiest is to use
310 compilers and runtime environments that that work out of the box with
311 it, such as the jikes compiler and the runtime environments jamvm and
312 kissme. But you can also work directly with targets like gcj and
313 kaffe that have their own copy of GNU Classpath currently. In that
314 case changes have to be merged back into GNU Classpath proper though,
315 which is sometimes more work. SableVM is starting to migrate from an
316 integrated GNU Classpath version to being usable with GNU Classpath
320 The initial target version for Classpath is the 1.1 spec. Higher
321 versions can be implemented (and have been implemented, including lots
322 of 1.4 functionality) if desired, but please do not create classes
323 that depend on features in those packages unless GNU Classpath already
324 contains those features. GNU Classpath has been free of any
325 proprietary dependencies for a long time now and we like to keep it
326 that way. But finishing, polishing up, documenting, testing and
327 debugging current functionality is of higher priority then adding new
330 @node Needed Tools and Libraries, Installation, Project Goals, Top
331 @comment node-name, next, previous, up
332 @chapter Needed Tools and Libraries
334 If you want to hack on Classpath, you should at least download and
335 install the following tools. And try to familiarize yourself with
336 them. Although in most cases having these tools installed will be all
337 you really need to know about them. Also note that when working on
338 (snapshot) releases only GCC 3.3+ (plus a free VM from the list above
339 and the libraries listed below) is needed. The other tools are only
340 needed when working directly on the CVS version.
348 Eclipse Compiler for Java 3.1+
363 All of these tools are available from
364 @uref{ftp://gnudist.gnu.org/pub/gnu/,gnudist.gnu.org} via anonymous
365 ftp, except CVS which is available from
366 @uref{http://www.cvshome.org/,www.cvshome.org} and the Eclipse
367 Compiler for Java, which is available from
368 @uref{http://www.eclipse.org/jdt/core,www.eclipse.org/jdt/core}.
370 Except for the Eclipse Compiler for Java, they are fully documented
371 with texinfo manuals. Texinfo can be browsed with the Emacs editor,
372 or with the text editor of your choice, or transformed into nicely
373 printable Postscript.
375 Here is a brief description of the purpose of those tools.
380 GNU make ("gmake") is required for building Classpath.
383 The GNU Compiler Collection. This contains a C compiler (gcc) for
384 compiling the native C code and a compiler for the java programming
385 language (gcj). You will need at least gcc version 2.95 or higher
386 in order to compile the native code. There is currently no
387 released version of gcj that can compile the Java 1.5 programming
388 language used by GNU Classpath.
391 The Eclipse Compiler for Java. This is a compiler for the Java 1.5
392 programming language. It translates source code to bytecode. The
393 Eclipse Foundation makes ``ecj.jar'' available as the JDT Core Batch
397 A version control system that maintains a centralized Internet
398 repository of all code in the Classpath system.
401 This tool automatically creates @file{Makefile.in} files from
402 @file{Makefile.am} files. The @file{Makefile.in} is turned into a
403 @file{Makefile} by @command{autoconf}.
405 Why use this? Because it automatically generates every makefile
406 target you would ever want (@option{clean}, @option{install},
407 @option{dist}, etc) in full compliance with the GNU coding standards.
408 It also simplifies Makefile creation in a number of ways that cannot
409 be described here. Read the docs for more info.
412 Automatically configures a package for the platform on which it is
413 being built and generates the Makefile for that platform.
416 Handles all of the zillions of hairy platform specific options needed
417 to build shared libraries.
420 The free GNU replacement for the standard Unix macro processor.
421 Proprietary m4 programs are broken and so GNU m4 is required for
422 autoconf to work though knowing a lot about GNU m4 is not required to
426 Larry Wall's scripting language. It is used internally by automake.
429 Manuals and documentation (like this guide) are written in texinfo.
430 Texinfo is the official documentation format of the GNU project.
431 Texinfo uses a single source file to produce output in a number of formats,
432 both online and printed (dvi, info, html, xml, etc.). This means that
433 instead of writing different documents for online information and another
434 for a printed manual, you need write only one document. And when the work
435 is revised, you need revise only that one document.
439 For any build environment involving native libraries, recent
440 versions of @command{autoconf}, @command{automake}, and @command{libtool}
441 are required if changes are made that require rebuilding @file{configure},
442 @file{Makefile.in}, @file{aclocal.m4}, or @file{config.h.in}.
444 When working from CVS you can run those tools by executing
445 @command{autogen.sh} in the source directory.
447 For building the Java bytecode (.class files), you can select
448 which compiler should be employed using @option{--with-javac} or
449 @option{--with-ecj} as argument to @command{configure};
450 the present default is @command{ecj}.
452 Instead of @command{ecj}, you can also use @command{javac}, which is
454 @uref{https://openjdk.dev.java.net/compiler, openjdk.dev.java.net/compiler}.
456 For compiling the native AWT libraries you need to have the following
457 libraries installed (unless @option{--disable-gtk-peer} is used as an argument
458 to @command{configure}):
462 @uref{http://www.gtk.org/,GTK+} is a multi-platform toolkit for
463 creating graphical user interfaces. It is used as the basis of the
464 GNU desktop project GNOME.
467 @uref{http://www.gnome.org/start/,gdk-pixbuf} is a GNOME library for
471 @uref{http://www.x.org,www.x.org} hosts the XTest Extension (libXtst).
472 It is necessary for GdkRobot support in java.awt.
476 There is a bug in earlier versions of at-spi, atk, and gail, which are
477 used for GNOME accessibility. Prior to version 1.18.0 of these packages,
478 gtk graphical applications should be run without accessibility (clear the
479 GTK_MODULES environment variable).
481 For building the Qt AWT peer JNI native libraries you have to
482 specify @option{--enable-qt-peer} and need the following library:
486 @uref{http://www.trolltech.com/products/qt,Qt} version 4.0.1 or higher.
487 The Qt library is a cross-platform graphics toolkit.
491 Please note that at the moment most operating systems do not
492 ship Qt version 4.0.1 by default. We recommend using GNU Classpath' Qt
493 support only for its developers and bug reporters. See
494 @uref{http://developer.classpath.org/mediation/ClasspathShowcase, the wiki}
495 for details on how to get it to work.
497 For building the X AWT peers you have to specify where to find the
498 Escher library on your system using the @option{--with-escher=ABS.PATH} option.
499 You will need the following library:
503 @uref{http://escher.sourceforge.net,Escher} version 0.2.3 or higher.
504 The Escher library is an implementation of X protocol and associated
505 libraries written in the Java programming language.
509 For building the ALSA midi provider code you will need
510 the following library:
515 @uref{http://www.alsa-project.org,ALSA} libraries.
517 The ALSA project provides sound device drivers and associated
518 libraries for the Linux kernel.
522 Building the ALSA midi provider code can be disabled by passing
523 @option{--disable-alsa} to @command{configure}.
525 For building the DSSI midi synthesizer provider code you will
526 need the following libraries:
530 @uref{http://dssi.sourceforge.net,DSSI} library for audio
534 @uref{http://plugin.org.uk/liblo/,liblo}, the Lightweight OSC
538 @uref{http://www.ladspa.org,LADSPA}, the Linux Audio Developer's
542 @uref{http://jackit.sourceforge.net,JACK}, a low latency audio
546 @uref{http://www.mega-nerd.com/libsndfile/,libsndfile}, an audio
550 @uref{http://www.fluidsynth.org/,fluidsynth}, a real-time SoundFont
555 The GConf-based backend for java.util.prefs needs the following
560 @uref{http://www.gnome.org/projects/gconf/,GConf} version 2.11.2
561 (or higher). GConf is used for storing desktop and application
562 configuration settings in GNOME.
566 For building @command{gcjwebplugin} you'll need the Mozilla plugin
567 support headers and libraries, which are available at
568 @uref{http://www.mozilla.org,www.mozilla.org}.
570 For enabling the com.sun.tools.javac support in tools.zip you
571 will a need jar file containing the Eclipse Java Compiler.
572 Otherwise com.sun.tools.javac will not be included in @file{tools.zip}.
574 For building the xmlj JAXP implementation (disabled by default,
575 use @command{configure --enable-xmlj}) you need the following libraries:
579 @uref{http://www.xmlsoft.org/,libxml2} version 2.6.8 or higher.
581 The libxml2 library is the XML C library for the Gnome desktop.
584 @uref{http://www.xmlsoft.org/XSLT/,libxslt} version 1.1.11 or higher.
586 The libxslt library if the XSLT C library for the Gnome desktop.
589 GNU Classpath comes with a couple of libraries included in the source
590 that are not part of GNU Classpath proper, but that have been included
591 to provide certain needed functionality. All these external libraries
592 should be clearly marked as such. In general we try to use as much as
593 possible the clean upstream versions of these sources. That way
594 merging in new versions will be easiest. You should always try to get
595 bug fixes to these files accepted upstream first. Currently we
596 include the following 'external' libraries. Most of these sources are
597 included in the @file{external} directory. That directory also
598 contains a @file{README} file explaining how to import newer versions.
603 Can be found in @file{external/jaxp}. Provides javax.xml, org.w3c and
604 org.xml packages. Upstream is
605 @uref{http://www.gnu.org/software/classpathx/,GNU ClasspathX}.
608 Can be found in @file{native/fdlibm}. Provides native implementations
609 of some of the Float and Double operations. Upstream is
610 @uref{http://gcc.gnu.org/java/,libgcj}, they sync again with the
611 'real' upstream @uref{http://www.netlib.org/fdlibm/readme}. See also
612 java.lang.StrictMath.
616 @node Installation, Building and running with the X AWT peers, Needed Tools and Libraries, Top
617 @comment node-name, next, previous, up
618 @chapter Installation instructions
620 This package was designed to use the GNU standard for configuration
621 and makefiles. To build and install do the following:
626 Run the @command{configure} script to configure the package. There are
627 various options you might want to pass to @command{configure} to control how the
628 package is built. Consider the following options, @command{configure --help}
629 gives a complete list.
634 compile Java source (default=@option{yes}).
638 compile JNI source (default=@option{yes}).
640 @item --enable-gtk-peer
642 compile GTK native peers (default=@option{yes}).
644 @item --enable-qt-peer
646 compile Qt4 native peers (default=@option{no}).
648 @item --enable-default-toolkit
650 fully qualified class name of default AWT toolkit (default=@option{no}).
654 compile native libxml/xslt library (default=@option{no}).
656 @item --enable-load-library
658 enable to use JNI native methods (default=@option{yes}).
660 @item --enable-local-sockets
662 enable build of local Unix sockets.
665 define what to install @option{(zip|flat|both|none)} (default=@option{zip}).
667 @item --with-escher=/path/to/escher
669 enable build of the X/Escher peers, with
670 the escher library at @file{/path/to/escher}, either
671 in the form of a JAR file, or a directory
672 containing the .class files of Escher.
674 @item --enable-Werror
676 whether to compile C code with @option{-Werror} which turns
677 any compiler warning into a compilation failure
678 (default=@option{no}).
682 generate documentation using @command{gjdoc} (default=@option{no}).
686 Regenerate the parsers with @command{jay}, must be given the
687 path to the @command{jay} executable
689 @item --with-glibj-zip=ABS.PATH
691 use prebuilt glibj.zip class library
693 @item --with-ecj-jar=ABS.PATH
695 specify jar file containing the Eclipse Java Compiler
699 For more flags run @command{configure --help}.
703 Type @command{gmake} to build the package. There is no longer a
704 dependency problem and we aim to keep it that way.
708 Type @command{gmake install} to install everything. This may require
709 being the superuser. The default install path is /usr/local/classpath
710 you may change it by giving @command{configure} the
711 @option{--prefix=<path>} option.
715 Report bugs to @email{classpath@@gnu.org} or much better to the
716 GNU Classpath bug tracker at
717 @uref{http://savannah.gnu.org/support/?func=addsupport&group=classpath,Savannah}.
721 Once installed, GNU Classpath is ready to be used by any VM that supports
722 using the official version of GNU Classpath. Simply ensure that
723 @file{/usr/local/classpath/share/classpath} is in your @env{CLASSPATH} environment
724 variable. You'll also have to set your @env{LD_LIBRARY_PATH}
725 variable (or similar system configuration) to include the Classpath
726 native libraries in @file{/usr/local/classpath/lib/classpath}.
728 *NOTE* All example paths assume the default prefix is used with @command{configure}.
729 If you don't know what this means then the examples are correct.
732 LD_LIBRARY_PATH=/usr/local/classpath/lib/classpath
733 CLASSPATH=/usr/local/classpath/share/classpath/glibj.zip:.
734 export LD_LIBRARY_PATH CLASSPATH
737 More information about the VMs that use GNU Classpath can be found in the
740 @node Building and running with the X AWT peers, Misc. Notes, Installation, Top
741 @comment node-name, next, previous, up
742 @chapter Building and running with the X AWT peers
744 In order build the X peers you need the Escher library version 0.2.3
745 from @uref{http://escher.sourceforge.net,escher.sourceforge.net}.
746 Unpack (and optionally build) the
747 Escher library following the instructions in the downloaded
748 package. Enable the build of the X peers by passing
749 @option{--with-escher=/path/to/escher} to @command{configure} where @file{/path/to/escher}
750 either points to a directory structure or JAR file containing the
751 Escher classes. For Unix systems it is preferable to also build local
752 socket support by passing @option{--enable-local-sockets}, which accelerates
753 the network communication to the X server significantly.
755 In this release you have to enable the X peers at runtime by
756 setting the system property awt.toolkit=gnu.java.awt.peer.x.XToolkit
757 by passing @option{-Dawt.toolkit=gnu.java.awt.peer.x.XToolkit} to the @command{java}
758 command when running an application.
760 @node Misc. Notes, Programming Standards, Building and running with the X AWT peers, Top
761 @comment node-name, next, previous, up
764 Compilation is accomplished using a compiler's @@file syntax. For our
765 part, we avoid placing make style dependencies as rules upon the
766 compilation of a particular class file and leave this up to the Java
769 The @option{--enable-maintainer-mode} option to @command{configure} currently does very
770 little and shouldn't be used by ordinary developers or users anyway.
772 On Windows machines, the native libraries do not currently build, but
773 the Java bytecode library will. Gcj trunk is beginning to work under
776 @node Programming Standards, Hacking Code, Misc. Notes, Top
777 @comment node-name, next, previous, up
778 @chapter Programming Standards
780 For C source code, follow the
781 @uref{http://www.gnu.org/prep/standards/,GNU Coding Standards}.
782 The standards also specify various things like the install directory
783 structure. These should be followed if possible.
785 For Java source code, please follow the
786 @uref{http://www.gnu.org/prep/standards/,GNU Coding
787 Standards}, as much as possible. There are a number of exceptions to
788 the GNU Coding Standards that we make for GNU Classpath as documented
789 in this guide. We will hopefully be providing developers with a code
790 formatting tool that closely matches those rules soon.
792 For API documentation comments, please follow
793 @uref{http://java.sun.com/products/jdk/javadoc/writingdoccomments.html,How
794 to Write Doc Comments for Javadoc}. We would like to have a set of
795 guidelines more tailored to GNU Classpath as part of this document.
798 * Source Code Style Guide::
801 @node Source Code Style Guide, , Programming Standards, Programming Standards
802 @comment node-name, next, previous, up
803 @section Java source coding style
805 Here is a list of some specific rules used when hacking on GNU
806 Classpath java source code. We try to follow the standard
807 @uref{http://www.gnu.org/prep/standards/,GNU Coding Standards}
808 for that. There are lots of tools that can automatically generate it
809 (although most tools assume C source, not java source code) and it
810 seems as good a standard as any. There are a couple of exceptions and
811 specific rules when hacking on GNU Classpath java source code however.
812 The following lists how code is formatted (and some other code
819 Java source files in GNU Classpath are encoded using UTF-8. However,
820 ordinarily it is considered best practice to use the ASCII subset of
821 UTF-8 and write non-ASCII characters using \u escapes.
824 If possible, generate specific imports (expand) over java.io.* type
825 imports. Order by gnu, java, javax, org. There must be one blank line
826 between each group. The imports themselves are ordered alphabetically by
827 package name. Classes and interfaces occur before sub-packages. The
828 classes/interfaces are then also sorted alphabetical. Note that uppercase
829 characters occur before lowercase characters.
832 import gnu.java.awt.EmbeddedWindow;
834 import java.io.IOException;
835 import java.io.InputStream;
837 import javax.swing.JFrame;
841 Blank line after package statement, last import statement, classes,
845 Opening/closing brace for class and method is at the same level of
846 indent as the declaration. All other braces are indented and content
847 between braces indented again.
850 Since method definitions don't start in column zero anyway (since they
851 are always inside a class definition), the rational for easy grepping
852 for ``^method_def'' is mostly gone already. Since it is customary for
853 almost everybody who writes java source code to put modifiers, return
854 value and method name on the same line, we do too.
856 @c fixme Another rational for always indenting the method definition is that it makes it a bit easier to distinguish methods in inner and anonymous classes from code in their enclosing context. NEED EXAMPLE.
859 Implements and extends on separate lines, throws too. Indent extends,
860 implements, throws. Apply deep indentation for method arguments.
862 @c fixme Needs example.
865 Don't add a space between a method or constructor call/definition and
866 the open-bracket. This is because often the return value is an object on
867 which you want to apply another method or from which you want to access
873 getToolkit ().createWindow (this);
878 getToolkit().createWindow(this);
882 The GNU Coding Standard it gives examples for almost every construct
883 (if, switch, do, while, etc.). One missing is the try-catch construct
884 which should be formatted as:
898 Wrap lines at 80 characters after assignments and before operators.
899 Wrap always before extends, implements, throws, and labels.
902 Don't put multiple class definitions in the same file, except for
903 inner classes. File names (plus .java) and class names should be the
907 Don't catch a @code{NullPointerException} as an alternative to simply
908 checking for @code{null}. It is clearer and usually more efficient
909 to simply write an explicit check.
911 For instance, don't write:
918 catch (NullPointerException _)
924 If your intent above is to check whether @samp{foo} is @code{null},
935 Don't use redundant modifiers or other redundant constructs. Here is
936 some sample code that shows various redundant items in comments:
939 /*import java.lang.Integer;*/
940 /*abstract*/ interface I @{
941 /*public abstract*/ void m();
942 /*public static final*/ int i = 1;
943 /*public static*/ class Inner @{@}
945 final class C /*extends Object*/ @{
946 /*final*/ void m() @{@}
950 Note that Jikes will generate warnings for redundant modifiers if you
951 use @code{+Predundant-modifiers} on the command line.
954 Modifiers should be listed in the standard order recommended by the
955 JLS. Jikes will warn for this when given @code{+Pmodifier-order}.
958 Because the output of different compilers differs, we have
959 standardized on explicitly specifying @code{serialVersionUID} in
960 @code{Serializable} classes in Classpath. This field should be
961 declared as @code{private static final}. Note that a class may be
962 @code{Serializable} without being explicitly marked as such, due to
963 inheritance. For instance, all subclasses of @code{Throwable} need to
964 have @code{serialVersionUID} declared.
966 @c fixme link to the discussion
969 Don't declare unchecked exceptions in the @code{throws} clause of a
970 method. However, if throwing an unchecked exception is part of the
971 method's API, you should mention it in the Javadoc. There is one
972 important exception to this rule, which is that a stub method should
973 be marked as throwing @code{gnu.classpath.NotImplementedException}.
974 This will let our API comparison tools note that the method is not
978 When overriding @code{Object.equals}, remember that @code{instanceof}
979 filters out @code{null}, so an explicit check is not needed.
982 When catching an exception and rethrowing a new exception you should
983 ``chain'' the Throwables. Don't just add the String representation of
984 the caught exception.
989 // Some code that can throw
991 catch (IOException ioe)
993 throw (SQLException) new SQLException("Database corrupt").setCause(ioe);
998 Avoid the use of reserved words for identifiers. This is obvious with those
999 such as @code{if} and @code{while} which have always been part of the Java
1000 programming language, but you should be careful about accidentally using
1001 words which have been added in later versions. Notable examples are
1002 @code{assert} (added in 1.4) and @code{enum} (added in 1.5). Jikes will warn
1003 of the use of the word @code{enum}, but, as it doesn't yet support the 1.5
1004 version of the language, it will still allow this usage through. A
1005 compiler which supports 1.5 (e.g. the Eclipse compiler, ecj) will simply
1006 fail to compile the offending source code.
1008 @c fixme Describe Anonymous classes (example).
1009 @c fixme Descibe Naming conventions when different from GNU Coding Standards.
1010 @c fixme Describee API doc javadoc tags used.
1014 Some things are the same as in the normal GNU Coding Standards:
1019 Unnecessary braces can be removed, one line after an if, for, while as
1023 Space around operators (assignment, logical, relational, bitwise,
1024 mathematical, shift).
1027 Blank line before single-line comments, multi-line comments, javadoc
1031 If more than 2 blank lines, trim to 2.
1034 Don't keep commented out code. Just remove it or add a real comment
1035 describing what it used to do and why it is changed to the current
1040 @node Hacking Code, Programming Goals, Programming Standards, Top
1041 @comment node-name, next, previous, up
1042 @chapter Working on the code, Working with others
1044 There are a lot of people helping out with GNU Classpath. Here are a
1045 couple of practical guidelines to make working together on the code
1048 The main thing is to always discuss what you are up to on the
1049 mailinglist. Making sure that everybody knows who is working on what
1050 is the most important thing to make sure we cooperate most
1054 @uref{http://www.gnu.org/software/classpath/tasks.html,Task List}
1055 which contains items that you might want to work on.
1057 Before starting to work on something please make sure you read this
1058 complete guide. And discuss it on list to make sure your work does
1059 not duplicate or interferes with work someone else is already doing.
1060 Always make sure that you submit things that are your own work. And
1061 that you have paperwork on file (as stated in the requirements
1062 section) with the FSF authorizing the use of your additions.
1064 Technically the GNU Classpath project is hosted on
1065 @uref{http://savannah.gnu.org/,Savannah} a central point for
1066 development, distribution and maintenance of GNU Software. Here you
1068 @uref{https://savannah.gnu.org/projects/classpath/,project page}, bug
1069 reports, pending patches, links to mailing lists, news items and CVS.
1071 You can find instructions on getting a CVS checkout for classpath at
1072 @uref{https://savannah.gnu.org/cvs/?group=classpath}.
1074 You don't have to get CVS commit write access to contribute, but it is
1075 sometimes more convenient to be able to add your changes directly to
1076 the project CVS. Please contact the GNU Classpath savannah admins to
1077 arrange CVS access if you would like to have it.
1079 Make sure to be subscribed to the commit-classpath mailinglist while
1080 you are actively hacking on Classpath. You have to send patches (cvs
1081 diff -uN) to this list before committing.
1083 We really want to have a pretty open check-in policy. But this means
1084 that you should be extra careful if you check something in. If at all
1085 in doubt or if you think that something might need extra explaining
1086 since it is not completely obvious please make a little announcement
1087 about the change on the mailinglist. And if you do commit something
1088 without discussing it first and another GNU Classpath hackers asks for
1089 extra explanation or suggests to revert a certain commit then please
1090 reply to the request by explaining why something should be so or if
1091 you agree to revert it. (Just reverting immediately is OK without
1092 discussion, but then please don't mix it with other changes and please
1095 Patches that are already approved for libgcj or also OK for Classpath.
1096 (But you still have to send a patch/diff to the list.) All other
1097 patches require you to think whether or not they are really OK and
1098 non-controversial, or if you would like some feedback first on them
1099 before committing. We might get real commit rules in the future, for
1100 now use your own judgment, but be a bit conservative.
1102 Always contact the GNU Classpath maintainer before adding anything
1103 non-trivial that you didn't write yourself and that does not come from
1104 libgcj or from another known GNU Classpath or libgcj hacker. If you
1105 have been assigned to commit changes on behalf of another project or
1106 a company always make sure they come from people who have signed the
1107 papers for the FSF and/or fall under the arrangement your company made
1108 with the FSF for contributions. Mention in the ChangeLog who actually
1111 Commits for completely unrelated changes they should be committed
1112 separately (especially when doing a formatting change and a logical
1113 change, do them in two separate commits). But do try to do a commit of
1114 as much things/files that are done at the same time which can
1115 logically be seen as part of the same change/cleanup etc.
1117 When the change fixes an important bug or adds nice new functionality
1118 please write a short entry for inclusion in the @file{NEWS} file. If it
1119 changes the VM interface you must mention that in both the @file{NEWS} file
1120 and the VM Integration Guide.
1122 All the ``rules'' are really meant to make sure that GNU Classpath
1123 will be maintainable in the long run and to give all the projects that
1124 are now using GNU Classpath an accurate view of the changes we make to
1125 the code and to see what changed when. If you think the requirements
1126 are ``unworkable'' please try it first for a couple of weeks. If you
1127 still feel the same after having some more experience with the project
1128 please feel free to bring up suggestions for improvements on the list.
1129 But don't just ignore the rules! Other hackers depend on them being
1130 followed to be the most productive they can be (given the above
1135 * Writing ChangeLogs::
1138 @node Branches, Writing ChangeLogs, Hacking Code, Hacking Code
1139 @comment node-name, next, previous, up
1140 @section Working with branches
1142 Sometimes it is necessary to create branch of the source for doing new
1143 work that is disruptive to the other hackers, or that needs new
1144 language or libraries not yet (easily) available.
1146 After discussing the need for a branch on the main mailinglist with
1147 the other hackers explaining the need of a branch and suggestion of
1148 the particular branch rules (what will be done on the branch, who will
1149 work on it, will there be different commit guidelines then for the
1150 mainline trunk and when is the branch estimated to be finished and
1151 merged back into the trunk) every GNU Classpath hacker with commit
1152 access should feel free to create a branch. There are however a couple
1153 of rules that every branch should follow:
1157 @item All branches ought to be documented in the developer wiki at
1158 @uref{http://developer.classpath.org/mediation/ClasspathBranches}, so
1159 we can know which are live, who owns them, and when they die.
1161 @item Some rules can be changed on a branch. In particular the branch
1162 maintainer can change the review requirements, and the requirement of
1163 keeping things building, testing, etc, can also be lifted. (These
1164 should be documented along with the branch name and owner if they
1165 differ from the trunk.)
1167 @item Requirements for patch email to classpath-patches and for paperwork
1168 @strong{cannot} be lifted. See @ref{Requirements}.
1170 @item A branch should not be seen as ``private'' or
1171 ``may be completely broken''. It should be as much as possible
1172 something that you work on with a team (and if there is no team - yet
1173 - then there is nothing as bad as having a completely broken build to
1174 get others to help out). There can of course be occasional breakage, but
1175 it should be planned and explained. And you can certainly have a rule
1176 like ``please ask me before committing to this branch''.
1178 @item Merges from the trunk to a branch are at the discretion of the
1181 @item A merge from a branch to the trunk is treated like any other patch.
1182 In particular, it has to go through review, it must satisfy all the
1183 trunk requirements (build, regression test, documentation).
1185 @item There may be additional timing requirements on merging a branch to
1186 the trunk depending on the release schedule, etc. For instance we may
1187 not want to do a branch merge just before a release.
1191 If any of these rules are unclear please discuss on the list first.
1194 * Writing ChangeLogs::
1197 @node Writing ChangeLogs, , Branches, Hacking Code
1198 @comment node-name, next, previous, up
1199 @section Documenting what changed when with ChangeLog entries
1201 To keep track of who did what when we keep an explicit ChangeLog entry
1202 together with the code. This mirrors the CVS commit messages and in
1203 general the ChangeLog entry is the same as the CVS commit message.
1204 This provides an easy way for people getting a (snapshot) release or
1205 without access to the CVS server to see what happened when. We do not
1206 generate the ChangeLog file automatically from the CVS server since
1207 that is not reliable.
1209 A good ChangeLog entry guideline can be found in the Guile Manual at
1210 @uref{http://www.gnu.org/software/guile/changelogs/guile-changelogs_3.html}.
1212 Here are some example to explain what should or shouldn't be in a
1213 ChangeLog entry (and the corresponding commit message):
1218 The first line of a ChangeLog entry should be:
1221 [date] <two spaces> [full name] <two spaces> [email-contact]
1224 The second line should be blank. All other lines should be indented
1228 Just state what was changed. Why something is done as it is done in
1229 the current code should be either stated in the code itself or be
1230 added to one of the documentation files (like this Hacking Guide).
1235 * java/awt/font/OpenType.java: Remove 'public static final'
1236 from OpenType tags, reverting the change of 2003-08-11. See
1237 Classpath discussion list of 2003-08-11.
1243 * java/awt/font/OpenType.java: Remove 'public static final' from
1247 In this case the reason for the change was added to this guide.
1250 Just as with the normal code style guide, don't make lines longer then
1254 Just as with comments in the code. The ChangeLog entry should be a
1255 full sentence, starting with a capital and ending with a period.
1258 Be precise in what changed, not the effect of the change (which should
1259 be clear from the code/patch). So don't write:
1262 * java/io/ObjectOutputStream.java : Allow putFields be called more
1266 But explain what changed and in which methods it was changed:
1269 * java/io/ObjectOutputStream.java (putFields): Don't call
1270 markFieldsWritten(). Only create new PutField when
1271 currentPutField is null.
1272 (writeFields): Call markFieldsWritten().
1277 The above are all just guidelines. We all appreciate the fact that writing
1278 ChangeLog entries, using a coding style that is not ``your own'' and the
1279 CVS, patch and diff tools do take some time to getting used to. So don't
1280 feel like you have to do it perfect right away or that contributions
1281 aren't welcome if they aren't ``perfect''. We all learn by doing and
1282 interacting with each other.
1285 @node Programming Goals, API Compatibility, Hacking Code, Top
1286 @comment node-name, next, previous, up
1287 @chapter Programming Goals
1289 When you write code for Classpath, write with three things in mind, and
1290 in the following order: portability, robustness, and efficiency.
1292 If efficiency breaks portability or robustness, then don't do it the
1293 efficient way. If robustness breaks portability, then bye-bye robust
1294 code. Of course, as a programmer you would probably like to find sneaky
1295 ways to get around the issue so that your code can be all three ... the
1296 following chapters will give some hints on how to do this.
1299 * Portability:: Writing Portable Software
1300 * Utility Classes:: Reusing Software
1301 * Robustness:: Writing Robust Software
1302 * Java Efficiency:: Writing Efficient Java
1303 * Native Efficiency:: Writing Efficient JNI
1304 * Security:: Writing Secure Software
1307 @node Portability, Utility Classes, Programming Goals, Programming Goals
1308 @comment node-name, next, previous, up
1309 @section Portability
1311 The portability goal for Classpath is the following:
1315 native functions for each platform that work across all VMs on that
1318 a single classfile set that work across all VMs on all platforms that
1319 support the native functions.
1322 For almost all of Classpath, this is a very feasible goal, using a
1323 combination of JNI and native interfaces. This is what you should shoot
1324 for. For those few places that require knowledge of the Virtual Machine
1325 beyond that provided by the Java standards, the VM Interface was designed.
1326 Read the Virtual Machine Integration Guide for more information.
1328 Right now the only supported platform is Linux. This will change as that
1329 version stabilizes and we begin the effort to port to many other
1330 platforms. Jikes RVM runs Classpath on AIX, and generally the Jikes
1331 RVM team fixes Classpath to work on that platform.
1333 @node Utility Classes, Robustness, Portability, Programming Goals
1334 @comment node-name, next, previous, up
1335 @section Utility Classes
1337 At the moment, we are not very good at reuse of the JNI code. There
1338 have been some attempts, called @dfn{libclasspath}, to
1339 create generally useful utility classes. The utility classes are in
1340 the directory @file{native/jni/classpath} and they are mostly declared
1341 in @file{native/jni/classpath/jcl.h}. These utility classes are
1342 currently only discussed in @ref{Robustness} and in @ref{Native
1345 There are more utility classes available that could be factored out if
1346 a volunteer wants something nice to hack on. The error reporting and
1347 exception throwing functions and macros in
1348 @file{native/jni/gtk-peer/gthread-jni.c} might be good
1349 candidates for reuse. There are also some generally useful utility
1350 functions in @file{gnu_java_awt_peer_gtk_GtkMainThread.c} that could
1351 be split out and put into libclasspath.
1353 @node Robustness, Java Efficiency, Utility Classes, Programming Goals
1354 @comment node-name, next, previous, up
1357 Native code is very easy to make non-robust. (That's one reason Java is
1358 so much better!) Here are a few hints to make your native code more
1361 Always check return values for standard functions. It's sometimes easy
1362 to forget to check that malloc() return for an error. Don't make that
1363 mistake. (In fact, use JCL_malloc() in the jcl library instead--it will
1364 check the return value and throw an exception if necessary.)
1366 Always check the return values of JNI functions, or call
1367 @code{ExceptionOccurred} to check whether an error occurred. You must
1368 do this after @emph{every} JNI call. JNI does not work well when an
1369 exception has been raised, and can have unpredictable behavior.
1371 Throw exceptions using @code{JCL_ThrowException}. This guarantees that if
1372 something is seriously wrong, the exception text will at least get out
1373 somewhere (even if it is stderr).
1375 Check for null values of @code{jclass}es before you send them to JNI functions.
1376 JNI does not behave nicely when you pass a null class to it: it
1377 terminates Java with a "JNI Panic."
1379 In general, try to use functions in @file{native/jni/classpath/jcl.h}. They
1380 check exceptions and return values and throw appropriate exceptions.
1382 @node Java Efficiency, Native Efficiency, Robustness, Programming Goals
1383 @comment node-name, next, previous, up
1384 @section Java Efficiency
1386 For methods which explicitly throw a @code{NullPointerException} when an
1387 argument is passed which is null, per a Sun specification, do not write
1392 strlen (String foo) throws NullPointerException
1395 throw new NullPointerException ("foo is null");
1396 return foo.length ();
1400 Instead, the code should be written as:
1404 strlen (String foo) throws NullPointerException
1406 return foo.length ();
1410 Explicitly comparing foo to null is unnecessary, as the virtual machine
1411 will throw a NullPointerException when length() is invoked. Classpath
1412 is designed to be as fast as possible -- every optimization, no matter
1413 how small, is important.
1415 @node Native Efficiency, Security, Java Efficiency, Programming Goals
1416 @comment node-name, next, previous, up
1417 @section Native Efficiency
1419 You might think that using native methods all over the place would give
1420 our implementation of Java speed, speed, blinding speed. You'd be
1421 thinking wrong. Would you believe me if I told you that an empty
1422 @emph{interpreted} Java method is typically about three and a half times
1423 @emph{faster} than the equivalent native method?
1425 Bottom line: JNI is overhead incarnate. In Sun's implementation, even
1426 the JNI functions you use once you get into Java are slow.
1428 A final problem is efficiency of native code when it comes to things
1429 like method calls, fields, finding classes, etc. Generally you should
1430 cache things like that in static C variables if you're going to use them
1431 over and over again. GetMethodID(), GetFieldID(), and FindClass() are
1432 @emph{slow}. Classpath provides utility libraries for caching methodIDs
1433 and fieldIDs in @file{native/jni/classpath/jnilink.h}. Other native data can
1434 be cached between method calls using functions found in
1435 @file{native/jni/classpath/native_state.h}.
1437 Here are a few tips on writing native code efficiently:
1439 Make as few native method calls as possible. Note that this is not the
1440 same thing as doing less in native method calls; it just means that, if
1441 given the choice between calling two native methods and writing a single
1442 native method that does the job of both, it will usually be better to
1443 write the single native method. You can even call the other two native
1444 methods directly from your native code and not incur the overhead of a
1445 method call from Java to C.
1447 Cache @code{jmethodID}s and @code{jfieldID}s wherever you can. String
1449 expensive. The best way to do this is to use the
1450 @file{native/jni/classpath/jnilink.h}
1451 library. It will ensure that @code{jmethodID}s are always valid, even if the
1452 class is unloaded at some point. In 1.1, jnilink simply caches a
1453 @code{NewGlobalRef()} to the method's underlying class; however, when 1.2 comes
1454 along, it will use a weak reference to allow the class to be unloaded
1455 and then re-resolve the @code{jmethodID} the next time it is used.
1457 Cache classes that you need to access often. jnilink will help with
1458 this as well. The issue here is the same as the methodID and fieldID
1459 issue--how to make certain the class reference remains valid.
1461 If you need to associate native C data with your class, use Paul
1462 Fisher's native_state library (NSA). It will allow you to get and set
1463 state fairly efficiently. Japhar now supports this library, making
1464 native state get and set calls as fast as accessing a C variable
1467 If you are using native libraries defined outside of Classpath, then
1468 these should be wrapped by a Classpath function instead and defined
1469 within a library of their own. This makes porting Classpath's native
1470 libraries to new platforms easier in the long run. It would be nice
1471 to be able to use Mozilla's NSPR or Apache's APR, as these libraries
1472 are already ported to numerous systems and provide all the necessary
1473 system functions as well.
1475 @node Security, , Native Efficiency, Programming Goals
1476 @comment node-name, next, previous, up
1479 Security is such a huge topic it probably deserves its own chapter.
1480 Most of the current code needs to be audited for security to ensure
1481 all of the proper security checks are in place within the Java
1482 platform, but also to verify that native code is reasonably secure and
1483 avoids common pitfalls, buffer overflows, etc. A good source for
1484 information on secure programming is the excellent HOWTO by David
1486 @uref{http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/index.html,Secure
1487 Programming for Linux and Unix HOWTO}.
1489 @node API Compatibility, Specification Sources, Programming Goals, Top
1490 @comment node-name, next, previous, up
1491 @chapter API Compatibility
1494 * Serialization:: Serialization
1495 * Deprecated Methods:: Deprecated methods
1498 @node Serialization, Deprecated Methods, API Compatibility, API Compatibility
1499 @comment node-name, next, previous, up
1500 @section Serialization
1502 Sun has produced documentation concerning much of the information
1503 needed to make Classpath serializable compatible with Sun
1504 implementations. Part of doing this is to make sure that every class
1505 that is Serializable actually defines a field named serialVersionUID
1506 with a value that matches the output of serialver on Sun's
1507 implementation. The reason for doing this is below.
1509 If a class has a field (of any accessibility) named serialVersionUID
1510 of type long, that is what serialver uses. Otherwise it computes a
1511 value using some sort of hash function on the names of all method
1512 signatures in the .class file. The fact that different compilers
1513 create different synthetic method signatures, such as access$0() if an
1514 inner class needs access to a private member of an enclosing class,
1515 make it impossible for two distinct compilers to reliably generate the
1516 same serial #, because their .class files differ. However, once you
1517 have a .class file, its serial # is unique, and the computation will
1518 give the same result no matter what platform you execute on.
1520 Serialization compatibility can be tested using tools provided with
1521 @uref{http://www.kaffe.org/~stuart/japi/,Japitools}. These
1522 tools can test binary serialization compatibility and also provide
1523 information about unknown serialized formats by writing these in XML
1524 instead. Japitools is also the primary means of checking API
1525 compatibility for GNU Classpath with Sun's Java Platform.
1527 @node Deprecated Methods, , Serialization, API Compatibility
1528 @comment node-name, next, previous, up
1529 @section Deprecated Methods
1531 Sun has a practice of creating ``alias'' methods, where a public or
1532 protected method is deprecated in favor of a new one that has the same
1533 function but a different name. Sun's reasons for doing this vary; as
1534 an example, the original name may contain a spelling error or it may
1535 not follow Java naming conventions.
1537 Unfortunately, this practice complicates class library code that calls
1538 these aliased methods. Library code must still call the deprecated
1539 method so that old client code that overrides it continues to work.
1540 But library code must also call the new version, because new code is
1541 expected to override the new method.
1543 The correct way to handle this (and the way Sun does it) may seem
1544 counterintuitive because it means that new code is less efficient than
1545 old code: the new method must call the deprecated method, and throughout
1546 the library code calls to the old method must be replaced with calls to
1549 Take the example of a newly-written container laying out a component and
1550 wanting to know its preferred size. The Component class has a
1551 deprecated preferredSize method and a new method, getPreferredSize.
1552 Assume that the container is laying out an old component that overrides
1553 preferredSize and a new component that overrides getPreferredSize. If
1554 the container calls getPreferredSize and the default implementation of
1555 getPreferredSize calls preferredSize, then the old component will have
1556 its preferredSize method called and new code will have its
1557 getPreferredSize method called.
1559 Even using this calling scheme, an old component may still be laid out
1560 improperly if it implements a method, getPreferredSize, that has the
1561 same signature as the new Component.getPreferredSize. But that is a
1562 general problem -- adding new public or protected methods to a
1563 widely-used class that calls those methods internally is risky, because
1564 existing client code may have already declared methods with the same
1567 The solution may still seem counterintuitive -- why not have the
1568 deprecated method call the new method, then have the library always call
1569 the old method? One problem with that, using the preferred size example
1570 again, is that new containers, which will use the non-deprecated
1571 getPreferredSize, will not get the preferred size of old components.
1573 @node Specification Sources, Naming Conventions, API Compatibility, Top
1574 @comment node-name, next, previous, up
1575 @chapter Specification Sources
1577 There are a number of specification sources to use when working on
1578 Classpath. In general, the only place you'll find your classes
1579 specified is in the JavaDoc documentation or possibly in the
1580 corresponding white paper. In the case of java.lang, java.io and
1581 java.util, you should look at the Java Language Specification.
1583 Here, however, is a list of specs, in order of canonicality:
1587 @uref{http://java.sun.com/docs/books/jls/clarify.html,Clarifications and Amendments to the JLS - 1.1}
1589 @uref{http://java.sun.com/docs/books/jls/html/1.1Update.html,JLS Updates
1592 @uref{http://java.sun.com/docs/books/jls/html/index.html,The 1.0 JLS}
1594 @uref{http://java.sun.com/docs/books/vmspec/index.html,JVM spec - 1.1}
1596 @uref{http://java.sun.com/products/jdk/1.1/docs/guide/jni/spec/jniTOC.doc.html,JNI spec - 1.1}
1598 @uref{http://java.sun.com/products/jdk/1.1/docs/api/packages.html,Sun's javadoc - 1.1}
1599 (since Sun's is the reference implementation, the javadoc is
1600 documentation for the Java platform itself.)
1602 @uref{http://java.sun.com/products/jdk/1.2/docs/guide/jvmdi/jvmdi.html,JVMDI spec - 1.2},
1603 @uref{http://java.sun.com/products/jdk/1.2/docs/guide/jni/jni-12.html,JNI spec - 1.2}
1604 (sometimes gives clues about unspecified things in 1.1; if
1605 it was not specified accurately in 1.1, then use the spec
1606 for 1.2; also, we are using JVMDI in this project.)
1608 @uref{http://java.sun.com/products/jdk/1.2/docs/api/frame.html,Sun's javadoc - 1.2}
1609 (sometimes gives clues about unspecified things in 1.1; if
1610 it was not specified accurately in 1.1, then use the spec
1613 @uref{http://developer.java.sun.com/developer/bugParade/index.html,The
1614 Bug Parade}: I have obtained a ton of useful information about how
1615 things do work and how they *should* work from the Bug Parade just by
1616 searching for related bugs. The submitters are very careful about their
1617 use of the spec. And if something is unspecified, usually you can find
1618 a request for specification or a response indicating how Sun thinks it
1619 should be specified here.
1622 You'll notice that in this document, white papers and specification
1623 papers are more canonical than the JavaDoc documentation. This is true
1627 @node Naming Conventions, Character Conversions, Specification Sources, Top
1628 @comment node-name, next, previous, up
1629 @chapter Directory and File Naming Conventions
1631 The Classpath directory structure is laid out in the following manner:
1673 Here is a brief description of the toplevel directories and their contents.
1678 Contains the source code to the Java packages that make up the core
1679 class library. Because this is the public interface to Java, it is
1680 important that the public classes, interfaces, methods, and variables
1681 are exactly the same as specified in Sun's documentation. The directory
1682 structure is laid out just like the java package names. For example,
1683 the class java.util.zip would be in the directory java-util.
1686 Internal classes (roughly analogous to Sun's sun.* classes) should go
1687 under the @file{gnu/java} directory. Classes related to a particular public
1688 Java package should go in a directory named like that package. For
1689 example, classes related to java.util.zip should go under a directory
1690 @file{gnu/java/util/zip}. Sub-packages under the main package name are
1691 allowed. For classes spanning multiple public Java packages, pick an
1692 appropriate name and see what everybody else thinks.
1695 This directory holds native code needed by the public Java packages.
1696 Each package has its own subdirectory, which is the ``flattened'' name
1697 of the package. For example, native method implementations for
1698 java.util.zip should go in @file{native/classpath/java-util}. Classpath
1699 actually includes an all Java version of the zip classes, so no native
1704 Each person working on a package get's his or her own ``directory
1705 space'' underneath each of the toplevel directories. In addition to the
1706 general guidelines above, the following standards should be followed:
1711 Classes that need to load native code should load a library with the
1712 same name as the flattened package name, with all hyphens removed. For
1713 example, the native library name specified in LoadLibrary for
1714 java-util would be ``javautil''.
1717 Each package has its own shared library for native code (if any).
1720 The main native method implementation for a given method in class should
1721 go in a file with the same name as the class with a ``.c'' extension.
1722 For example, the JNI implementation of the native methods in
1723 java.net.InetAddress would go in @file{native/jni/java-net/InetAddress.c}.
1724 ``Internal'' native functions called from the main native method can
1725 reside in files of any name.
1728 @node Character Conversions, Localization, Naming Conventions, Top
1729 @comment node-name, next, previous, up
1730 @chapter Character Conversions
1732 Java uses the Unicode character encoding system internally. This is a
1733 sixteen bit (two byte) collection of characters encompassing most of the
1734 world's written languages. However, Java programs must often deal with
1735 outside interfaces that are byte (eight bit) oriented. For example, a
1736 Unix file, a stream of data from a network socket, etc. Beginning with
1737 Java 1.1, the @code{Reader} and @code{Writer} classes provide functionality
1738 for dealing with character oriented streams. The classes
1739 @code{InputStreamReader} and @code{OutputStreamWriter} bridge the gap
1740 between byte streams and character streams by converting bytes to
1741 Unicode characters and vice versa.
1743 In Classpath, @code{InputStreamReader} and @code{OutputStreamWriter}
1744 rely on an internal class called @code{gnu.java.io.EncodingManager} to load
1745 translators that perform the actual conversion. There are two types of
1746 converters, encoders and decoders. Encoders are subclasses of
1747 @code{gnu.java.io.encoder.Encoder}. This type of converter takes a Java
1748 (Unicode) character stream or buffer and converts it to bytes using
1749 a specified encoding scheme. Decoders are a subclass of
1750 @code{gnu.java.io.decoder.Decoder}. This type of converter takes a
1751 byte stream or buffer and converts it to Unicode characters. The
1752 @code{Encoder} and @code{Decoder} classes are subclasses of
1753 @code{Writer} and @code{Reader} respectively, and so can be used in
1754 contexts that require character streams, but the Classpath implementation
1755 currently does not make use of them in this fashion.
1757 The @code{EncodingManager} class searches for requested encoders and
1758 decoders by name. Since encoders and decoders are separate in Classpath,
1759 it is possible to have a decoder without an encoder for a particular
1760 encoding scheme, or vice versa. @code{EncodingManager} searches the
1761 package path specified by the @code{file.encoding.pkg} property. The
1762 name of the encoder or decoder is appended to the search path to
1763 produce the required class name. Note that @code{EncodingManager} knows
1764 about the default system encoding scheme, which it retrieves from the
1765 system property @code{file.encoding}, and it will return the proper
1766 translator for the default encoding if no scheme is specified. Also, the
1767 Classpath standard translator library, which is the @code{gnu.java.io} package,
1768 is automatically appended to the end of the path.
1770 For efficiency, @code{EncodingManager} maintains a cache of translators
1771 that it has loaded. This eliminates the need to search for a commonly
1772 used translator each time it is requested.
1774 Finally, @code{EncodingManager} supports aliasing of encoding scheme names.
1775 For example, the ISO Latin-1 encoding scheme can be referred to as
1776 ''8859_1'' or ''ISO-8859-1''. @code{EncodingManager} searches for
1777 aliases by looking for the existence of a system property called
1778 @code{gnu.java.io.encoding_scheme_alias.<encoding name>}. If such a
1779 property exists. The value of that property is assumed to be the
1780 canonical name of the encoding scheme, and a translator with that name is
1781 looked up instead of one with the original name.
1783 Here is an example of how @code{EncodingManager} works. A class requests
1784 a decoder for the ''UTF-8'' encoding scheme by calling
1785 @code{EncodingManager.getDecoder("UTF-8")}. First, an alias is searched
1786 for by looking for the system property
1787 @code{gnu.java.io.encoding_scheme_alias.UTF-8}. In our example, this
1788 property exists and has the value ''UTF8''. That is the actual
1789 decoder that will be searched for. Next, @code{EncodingManager} looks
1790 in its cache for this translator. Assuming it does not find it, it
1791 searches the translator path, which is this example consists only of
1792 the default @code{gnu.java.io}. The ''decoder'' package name is
1793 appended since we are looking for a decoder. (''encoder'' would be
1794 used if we were looking for an encoder). Then name name of the translator
1795 is appended. So @code{EncodingManager} attempts to load a translator
1796 class called @code{gnu.java.io.decoder.UTF8}. If that class is found,
1797 an instance of it is returned. If it is not found, a
1798 @code{UnsupportedEncodingException}.
1800 To write a new translator, it is only necessary to subclass
1801 @code{Encoder} and/or @code{Decoder}. Only a handful of abstract
1802 methods need to be implemented. In general, no methods need to be
1803 overridden. The needed methods calculate the number of bytes/chars
1804 that the translation will generate, convert buffers to/from bytes,
1805 and read/write a requested number of characters to/from a stream.
1807 Many common encoding schemes use only eight bits to encode characters.
1808 Writing a translator for these encodings is very easy. There are
1809 abstract translator classes @code{gnu.java.io.decode.DecoderEightBitLookup}
1810 and @code{gnu.java.io.encode.EncoderEightBitLookup}. These classes
1811 implement all of the necessary methods. All that is necessary to
1812 create a lookup table array that maps bytes to Unicode characters and
1813 set the class variable @code{lookup_table} equal to it in a static
1814 initializer. Also, a single constructor that takes an appropriate
1815 stream as an argument must be supplied. These translators are
1816 exceptionally easy to create and there are several of them supplied
1817 in the Classpath distribution.
1819 Writing multi-byte or variable-byte encodings is more difficult, but
1820 often not especially challenging. The Classpath distribution ships with
1821 translators for the UTF8 encoding scheme which uses from one to three
1822 bytes to encode Unicode characters. This can serve as an example of
1823 how to write such a translator.
1825 Many more translators are needed. All major character encodings should
1826 eventually be supported.
1828 @node Localization, , Character Conversions, Top
1829 @comment node-name, next, previous, up
1830 @chapter Localization
1832 There are many parts of the Java standard runtime library that must
1833 be customized to the particular locale the program is being run in.
1834 These include the parsing and display of dates, times, and numbers;
1835 sorting words alphabetically; breaking sentences into words, etc.
1836 In general, Classpath uses general classes for performing these tasks,
1837 and customizes their behavior with configuration data specific to a
1841 * String Collation:: Sorting strings in different locales
1842 * Break Iteration:: Breaking up text into words, sentences, and lines
1843 * Date Formatting and Parsing:: Locale specific date handling
1844 * Decimal/Currency Formatting and Parsing:: Local specific number handling
1847 In Classpath, all locale specific data is stored in a
1848 @code{ListResourceBundle} class in the package @code{gnu/java/locale}.
1849 The basename of the bundle is @code{LocaleInformation}. See the
1850 documentation for the @code{java.util.ResourceBundle} class for details
1851 on how the specific locale classes should be named.
1853 @code{ListResourceBundle}'s are used instead of
1854 @code{PropertyResourceBundle}'s because data more complex than simple
1855 strings need to be provided to configure certain Classpath components.
1856 Because @code{ListResourceBundle} allows an arbitrary Java object to
1857 be associated with a given configuration option, it provides the
1858 needed flexibility to accomodate Classpath's needs.
1860 Each Java library component that can be localized requires that certain
1861 configuration options be specified in the resource bundle for it. It is
1862 important that each and every option be supplied for a specific
1863 component or a critical runtime error will most likely result.
1865 As a standard, each option should be assigned a name that is a string.
1866 If the value is stored in a class or instance variable, then the option
1867 should name should have the name name as the variable. Also, the value
1868 associated with each option should be a Java object with the same name
1869 as the option name (unless a simple scalar value is used). Here is an
1872 A class loads a value for the @code{format_string} variable from the
1873 resource bundle in the specified locale. Here is the code in the
1877 ListResourceBundle lrb =
1878 ListResourceBundle.getBundle ("gnu/java/locale/LocaleInformation", locale);
1879 String format_string = lrb.getString ("format_string");
1882 In the actual resource bundle class, here is how the configuration option
1887 * This is the format string used for displaying values
1889 private static final String format_string = "%s %d %i";
1891 private static final Object[][] contents =
1893 @{ "format_string", format_string @}
1897 Note that each variable should be @code{private}, @code{final}, and
1898 @code{static}. Each variable should also have a description of what it
1899 does as a documentation comment. The @code{getContents()} method returns
1900 the @code{contents} array.
1902 There are many functional areas of the standard class library that are
1903 configured using this mechanism. A given locale does not need to support
1904 each functional area. But if a functional area is supported, then all
1905 of the specified entries for that area must be supplied. In order to
1906 determine which functional areas are supported, there is a special key
1907 that is queried by the affected class or classes. If this key exists,
1908 and has a value that is a @code{Boolean} object wrappering the
1909 @code{true} value, then full support is assumed. Otherwise it is
1910 assumed that no support exists for this functional area. Every class
1911 using resources for configuration must use this scheme and define a special
1912 scheme that indicates the functional area is supported. Simply checking
1913 for the resource bundle's existence is not sufficient to ensure that a
1914 given functional area is supported.
1916 The following sections define the functional areas that use resources
1917 for locale specific configuration in GNU Classpath. Please refer to the
1918 documentation for the classes mentioned for details on how these values
1919 are used. You may also wish to look at the source file for
1920 @file{gnu/java/locale/LocaleInformation_en} as an example.
1922 @node String Collation, Break Iteration, Localization, Localization
1923 @comment node-name, next, previous, up
1924 @section String Collation
1926 Collation involves the sorting of strings. The Java class library provides
1927 a public class called @code{java.text.RuleBasedCollator} that performs
1928 sorting based on a set of sorting rules.
1931 @item RuleBasedCollator - A @code{Boolean} wrappering @code{true} to indicate
1932 that this functional area is supported.
1933 @item collation_rules - The rules the specify how string collation is to
1937 Note that some languages might be too complex for @code{RuleBasedCollator}
1938 to handle. In this case an entirely new class might need to be written in
1939 lieu of defining this rule string.
1941 @node Break Iteration, Date Formatting and Parsing, String Collation, Localization
1942 @comment node-name, next, previous, up
1943 @section Break Iteration
1945 The class @code{java.text.BreakIterator} breaks text into words, sentences,
1946 and lines. It is configured with the following resource bundle entries:
1949 @item BreakIterator - A @code{Boolean} wrappering @code{true} to indicate
1950 that this functional area is supported.
1951 @item word_breaks - A @code{String} array of word break character sequences.
1952 @item sentence_breaks - A @code{String} array of sentence break character
1954 @item line_breaks - A @code{String} array of line break character sequences.
1957 @node Date Formatting and Parsing, Decimal/Currency Formatting and Parsing, Break Iteration, Localization
1958 @comment node-name, next, previous, up
1959 @section Date Formatting and Parsing
1961 Date formatting and parsing is handled by the
1962 @code{java.text.SimpleDateFormat} class in most locales. This class is
1963 configured by attaching an instance of the @code{java.text.DateFormatSymbols}
1964 class. That class simply reads properties from our locale specific
1965 resource bundle. The following items are required (refer to the
1966 documentation of the @code{java.text.DateFormatSymbols} class for details
1967 io what the actual values should be):
1970 @item DateFormatSymbols - A @code{Boolean} wrappering @code{true} to indicate
1971 that this functional area is supported.
1972 @item months - A @code{String} array of month names.
1973 @item shortMonths - A @code{String} array of abbreviated month names.
1974 @item weekdays - A @code{String} array of weekday names.
1975 @item shortWeekdays - A @code{String} array of abbreviated weekday names.
1976 @item ampms - A @code{String} array containing AM/PM names.
1977 @item eras - A @code{String} array containing era (i.e., BC/AD) names.
1978 @item zoneStrings - An array of information about valid timezones for this
1980 @item localPatternChars - A @code{String} defining date/time pattern symbols.
1981 @item shortDateFormat - The format string for dates used by
1982 @code{DateFormat.SHORT}
1983 @item mediumDateFormat - The format string for dates used by
1984 @code{DateFormat.MEDIUM}
1985 @item longDateFormat - The format string for dates used by
1986 @code{DateFormat.LONG}
1987 @item fullDateFormat - The format string for dates used by
1988 @code{DateFormat.FULL}
1989 @item shortTimeFormat - The format string for times used by
1990 @code{DateFormat.SHORT}
1991 @item mediumTimeFormat - The format string for times used by
1992 @code{DateFormat.MEDIUM}
1993 @item longTimeFormat - The format string for times used by
1994 @code{DateFormat.LONG}
1995 @item fullTimeFormat - The format string for times used by
1996 @code{DateFormat.FULL}
1999 Note that it may not be possible to use this mechanism for all locales.
2000 In those cases a special purpose class may need to be written to handle
2001 date/time processing.
2003 @node Decimal/Currency Formatting and Parsing, , Date Formatting and Parsing, Localization
2004 @comment node-name, next, previous, up
2005 @section Decimal/Currency Formatting and Parsing
2007 @code{NumberFormat} is an abstract class for formatting and parsing numbers.
2008 The class @code{DecimalFormat} provides a concrete subclass that handles
2009 this is in a locale independent manner. As with @code{SimpleDateFormat},
2010 this class gets information on how to format numbers from a class that
2011 wrappers a collection of locale specific formatting values. In this case,
2012 the class is @code{DecimalFormatSymbols}. That class reads its default
2013 values for a locale from the resource bundle. The required entries are:
2016 @item DecimalFormatSymbols - A @code{Boolean} wrappering @code{true} to
2017 indicate that this functional area is supported.
2018 @item currencySymbol - The string representing the local currency.
2019 @item intlCurrencySymbol - The string representing the local currency in an
2020 international context.
2021 @item decimalSeparator - The character to use as the decimal point as a
2023 @item digit - The character used to represent digits in a format string,
2025 @item exponential - The char used to represent the exponent separator of a
2026 number written in scientific notation, as a @code{String}.
2027 @item groupingSeparator - The character used to separate groups of numbers
2028 in a large number, such as the ``,'' separator for thousands in the US, as
2030 @item infinity - The string representing infinity.
2031 @item NaN - The string representing the Java not a number value.
2032 @item minusSign - The character representing the negative sign, as a
2034 @item monetarySeparator - The decimal point used in currency values, as a
2036 @item patternSeparator - The character used to separate positive and
2037 negative format patterns, as a @code{String}.
2038 @item percent - The percent sign, as a @code{String}.
2039 @item perMill - The per mille sign, as a @code{String}.
2040 @item zeroDigit - The character representing the digit zero, as a @code{String}.
2043 Note that several of these values are an individual character. These should
2044 be wrappered in a @code{String} at character position 0, not in a
2045 @code{Character} object.