OSDN Git Service

1f9b5c1287b47434d82d5236ae7a6218405d770b
[pf3gnuchains/gcc-fork.git] / libjava / classpath / doc / cp-hacking.texinfo
1 \input texinfo @c -*-texinfo-*-
2
3 @c %**start of header
4 @setfilename cp-hacking.info
5 @settitle GNU Classpath Hacker's Guide
6 @c %**end of header
7
8 @setchapternewpage off
9
10 @ifinfo
11 This file contains important information you will need to know if you
12 are going to hack on the GNU Classpath project code.
13
14 Copyright (C) 1998,1999,2000,2001,2002,2003,2004,2005,2007 Free Software Foundation, Inc.
15
16 @ifnotplaintext
17 @dircategory GNU Libraries
18 @direntry
19 * Classpath Hacking: (cp-hacking).  GNU Classpath Hacker's Guide
20 @end direntry
21 @end ifnotplaintext
22 @end ifinfo
23
24 @titlepage
25 @title GNU Classpath Hacker's Guide
26 @author Aaron M. Renn
27 @author Paul N. Fisher
28 @author John Keiser
29 @author C. Brian Jones
30 @author Mark J. Wielaard
31
32 @page
33 @vskip 0pt plus 1filll
34 Copyright @copyright{} 1998,1999,2000,2001,2002,2003,2004 Free Software Foundation, Inc.
35 @sp 2
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.
39
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.
44
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.
49
50 @end titlepage
51
52 @ifinfo
53 @node Top, Introduction, (dir), (dir)
54 @top GNU Classpath Hacker's Guide
55
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.
60 @end ifinfo
61
62 @menu
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
79
80 @detailmenu
81  --- The Detailed Node Listing ---
82
83 Programming Standards
84
85 * Source Code Style Guide::     
86
87 Working on the code, Working with others
88
89 * Branches::                    
90 * Writing ChangeLogs::          
91
92 Working with branches
93
94 * Writing ChangeLogs::          
95
96 Programming Goals
97
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
104
105 API Compatibility
106
107 * Serialization::               Serialization
108 * Deprecated Methods::          Deprecated methods
109
110 Localization
111
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
116
117 @end detailmenu
118 @end menu
119
120 @node Introduction, Requirements, Top, Top
121 @comment node-name, next, previous, up
122 @chapter Introduction
123
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.
136
137 @node Requirements, Volunteering, Introduction, Top
138 @comment node-name, next, previous, up
139 @chapter Requirements
140
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.
146
147 You will need to adhere to the following things if you want to donate
148 code to the GNU Classpath project:
149
150 @itemize @bullet
151 @item
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.
167
168 @item
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.
175
176 @item
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.
190
191 @item
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.
203 @end itemize
204
205 @node Volunteering, Project Goals, Requirements, Top
206 @comment node-name, next, previous, up
207 @chapter Volunteering to Help
208
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.
214
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:
219
220 @itemize @bullet
221 @item
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.
230
231 @item
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
235 documented.
236
237 @item
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.  
245 @end itemize
246
247 Writing good documentation, tests and fixing bugs should be every
248 developer's top priority in order to reach the elusive release of
249 version 1.0.
250
251 @node Project Goals, Needed Tools and Libraries, Volunteering, Top
252 @comment node-name, next, previous, up
253 @chapter Project Goals
254
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.
259
260 Classpath is targeted to support the following operating systems:
261
262 @enumerate
263 @item
264 Free operating systems.  This includes GNU/Linux, GNU/Hurd, and the free
265 BSDs.
266
267 @item
268 Other Unix-like operating systems.
269
270 @item
271 Platforms which currently have no Java support at all.
272
273 @item 
274 Other platforms such as MS-Windows.
275 @end enumerate
276
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.
280
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}.
288
289 @enumerate
290 @item
291 @uref{http://gcc.gnu.org/java/,GCJ}
292 @item 
293 @uref{http://jamvm.sourceforge.net/,jamvm}
294 @item 
295 @uref{http://kissme.sourceforge.net/,Kissme}
296 @item
297 @uref{http://www.ibm.com/developerworks/oss/jikesrvm/,Jikes RVM}
298 @item
299 @uref{http://www.sablevm.org/,SableVM}
300 @item
301 @uref{http://www.kaffe.org/,Kaffe}
302 @end enumerate
303
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
317 out of the box.
318
319
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
328 functionality.
329
330 @node Needed Tools and Libraries, Installation, Project Goals, Top
331 @comment node-name, next, previous, up
332 @chapter Needed Tools and Libraries
333
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.
341
342 @itemize @bullet
343 @item
344 GNU make 3.80+
345 @item
346 GCC 2.95+
347 @item
348 Eclipse Compiler for Java 3.1+
349 @item
350 CVS 1.11+
351 @item
352 automake 1.9+
353 @item
354 autoconf 2.59+
355 @item
356 libtool 1.5+
357 @item
358 GNU m4 1.4
359 @item
360 texinfo 4.2+
361 @end itemize
362
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}.
369
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.
374
375 Here is a brief description of the purpose of those tools.
376
377 @table @b
378
379 @item make
380 GNU make ("gmake") is required for building Classpath.
381
382 @item GCC
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.
389
390 @item ecj
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
394 Compiler download.
395
396 @item CVS  
397 A version control system that maintains a centralized Internet
398 repository of all code in the Classpath system.
399
400 @item automake  
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}.  
404
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.
410
411 @item autoconf  
412 Automatically configures a package for the platform on which it is
413 being built and generates the Makefile for that platform.
414
415 @item libtool  
416 Handles all of the zillions of hairy platform specific options needed
417 to build shared libraries.
418
419 @item m4
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
423 work with autoconf.
424
425 @item perl
426 Larry Wall's scripting language.  It is used internally by automake.
427
428 @item texinfo
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.
436
437 @end table
438
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}.
443
444 When working from CVS you can run those tools by executing
445 @command{autogen.sh} in the source directory.
446
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}.
451
452 Instead of @command{ecj}, you can also use @command{javac}, which is 
453 available at 
454 @uref{https://openjdk.dev.java.net/compiler, openjdk.dev.java.net/compiler}.
455
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}):
459
460 @table @b
461 @item GTK+ 2.8.x
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.
465
466 @item gdk-pixbuf
467 @uref{http://www.gnome.org/start/,gdk-pixbuf} is a GNOME library for
468 representing images.
469
470 @item XTest 
471 @uref{http://www.x.org,www.x.org} hosts the XTest Extension (libXtst).
472 It is necessary for GdkRobot support in java.awt.
473
474 @end table
475
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).
480
481 For building the Qt AWT peer JNI native libraries you have to
482 specify @option{--enable-qt-peer} and need the following library:
483
484 @table @b
485 @item Qt
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.
488
489 @end table
490
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.
496
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:
500
501 @table @b
502 @item Escher
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.
506
507 @end table
508
509 For building the ALSA midi provider code you will need
510 the following library:
511
512
513 @table @b
514 @item ALSA
515 @uref{http://www.alsa-project.org,ALSA} libraries.
516
517 The ALSA project provides sound device drivers and associated 
518 libraries for the Linux kernel.
519
520 @end table
521
522 Building the ALSA midi provider code can be disabled by passing
523 @option{--disable-alsa} to @command{configure}.
524
525 For building the DSSI midi synthesizer provider code you will
526 need the following libraries:
527
528 @table @b
529 @item DSSI
530 @uref{http://dssi.sourceforge.net,DSSI} library for audio
531 processing plugins.
532
533 @item liblo
534 @uref{http://plugin.org.uk/liblo/,liblo}, the Lightweight OSC 
535 implementation.
536
537 @item LADSPA
538 @uref{http://www.ladspa.org,LADSPA}, the Linux Audio Developer's 
539 Simple Plugin API.
540     
541 @item JACK
542 @uref{http://jackit.sourceforge.net,JACK}, a low latency audio 
543 server.
544     
545 @item libsndfile
546 @uref{http://www.mega-nerd.com/libsndfile/,libsndfile}, an audio 
547 file I/O library.
548     
549 @item fluidsynth
550 @uref{http://www.fluidsynth.org/,fluidsynth}, a real-time SoundFont 
551 2 based soft-synth.
552
553 @end table    
554
555 The GConf-based backend for java.util.prefs needs the following
556 library headers:
557
558 @table @b
559 @item GConf
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.
563
564 @end table
565
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}.
569
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}.
573
574 For building the xmlj JAXP implementation (disabled by default, 
575 use @command{configure --enable-xmlj}) you need the following libraries:
576
577 @table @b
578 @item libxml2
579 @uref{http://www.xmlsoft.org/,libxml2} version 2.6.8 or higher.
580
581 The libxml2 library is the XML C library for the Gnome desktop.
582
583 @item libxslt
584 @uref{http://www.xmlsoft.org/XSLT/,libxslt} version 1.1.11 or higher.
585
586 The libxslt library if the XSLT C library for the Gnome desktop.
587 @end table
588
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.
599
600 @table @b
601
602 @item GNU jaxp
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}.
606
607 @item fdlibm
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.
613
614 @end table
615
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
619
620 This package was designed to use the GNU standard for configuration
621 and makefiles.  To build and install do the following:
622
623 @enumerate
624 @item Configuration
625
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.  
630
631 @table @option
632 @item --enable-java       
633
634 compile Java source (default=@option{yes}).
635
636 @item --enable-jni
637
638 compile JNI source (default=@option{yes}).
639
640 @item --enable-gtk-peer
641
642 compile GTK native peers (default=@option{yes}).
643
644 @item --enable-qt-peer
645
646 compile Qt4 native peers (default=@option{no}).
647
648 @item --enable-default-toolkit
649
650 fully qualified class name of default AWT toolkit (default=@option{no}).
651
652 @item --enable-xmlj
653
654 compile native libxml/xslt library (default=@option{no}).
655
656 @item --enable-load-library
657
658 enable to use JNI native methods (default=@option{yes}).
659
660 @item --enable-local-sockets
661
662 enable build of local Unix sockets.
663
664 @item --with-glibj
665 define what to install @option{(zip|flat|both|none)} (default=@option{zip}).
666
667 @item --with-escher=/path/to/escher
668
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.
673
674 @item --enable-Werror
675
676 whether to compile C code with @option{-Werror} which turns
677 any compiler warning into a compilation failure
678 (default=@option{no}).
679
680 @item --with-gjdoc
681
682 generate documentation using @command{gjdoc} (default=@option{no}).
683
684 @item --with-jay
685
686 Regenerate the parsers with @command{jay}, must be given the
687 path to the @command{jay} executable
688
689 @item --with-glibj-zip=ABS.PATH
690
691 use prebuilt glibj.zip class library
692
693 @item --with-ecj-jar=ABS.PATH 
694
695 specify jar file containing the Eclipse Java Compiler
696
697 @end table
698
699 For more flags run @command{configure --help}.
700
701 @item Building
702
703 Type @command{gmake} to build the package.  There is no longer a
704 dependency problem and we aim to keep it that way.
705
706 @item Installation
707
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.
712
713 @end enumerate
714
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}.
718
719 Happy Hacking!
720
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}.
727
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.
730
731 @example
732 LD_LIBRARY_PATH=/usr/local/classpath/lib/classpath
733 CLASSPATH=/usr/local/classpath/share/classpath/glibj.zip:.
734 export LD_LIBRARY_PATH CLASSPATH
735 @end example
736
737 More information about the VMs that use GNU Classpath can be found in the
738 @file{README} file.
739
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
743
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.
754
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.
759
760 @node Misc. Notes, Programming Standards, Building and running with the X AWT peers, Top
761 @comment node-name, next, previous, up
762 @chapter Misc. Notes
763
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
767 compiler instead.
768
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.
771
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
774 Cygwin.
775
776 @node Programming Standards, Hacking Code, Misc. Notes, Top
777 @comment node-name, next, previous, up
778 @chapter Programming Standards
779
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.
784
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.
791
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.
796
797 @menu
798 * Source Code Style Guide::     
799 @end menu
800
801 @node Source Code Style Guide,  , Programming Standards, Programming Standards
802 @comment node-name, next, previous, up
803 @section Java source coding style
804
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
813 conventions):
814
815
816 @itemize @bullet
817
818 @item
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.
822
823 @item
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.
830
831 @example
832 import gnu.java.awt.EmbeddedWindow;
833
834 import java.io.IOException;
835 import java.io.InputStream;
836
837 import javax.swing.JFrame;
838 @end example
839
840 @item
841 Blank line after package statement, last import statement, classes,
842 interfaces, methods.
843
844 @item
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.
848
849 @item
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.
855
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.
857
858 @item
859 Implements and extends on separate lines, throws too.  Indent extends,
860 implements, throws.  Apply deep indentation for method arguments.
861
862 @c fixme Needs example.
863
864 @item
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
868 a field.
869         
870 Don't write:
871
872 @example
873   getToolkit ().createWindow (this);
874 @end example
875
876 But write:
877 @example
878   getToolkit().createWindow(this);
879 @end example
880
881 @item
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:
885
886 @example
887   try
888     @{
889       //
890     @}
891   catch (...)
892     @{
893       //
894     @}
895 @end example
896
897 @item
898 Wrap lines at 80 characters after assignments and before operators.
899 Wrap always before extends, implements, throws, and labels.
900
901 @item
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
904 same.
905
906 @item
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.
910
911 For instance, don't write:
912
913 @example
914 try
915   @{
916     return foo.doit();
917   @}
918 catch (NullPointerException _)
919   @{
920     return 7;
921   @}
922 @end example
923
924 If your intent above is to check whether @samp{foo} is @code{null},
925 instead write:
926
927 @example
928 if (foo == null)
929   return 7;
930 else
931   return foo.doit();
932 @end example
933
934 @item
935 Don't use redundant modifiers or other redundant constructs.  Here is
936 some sample code that shows various redundant items in comments:
937
938 @example
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 @{@}
944 @}
945 final class C /*extends Object*/ @{
946    /*final*/ void m() @{@}
947 @}
948 @end example
949
950 Note that Jikes will generate warnings for redundant modifiers if you
951 use @code{+Predundant-modifiers} on the command line.
952
953 @item
954 Modifiers should be listed in the standard order recommended by the
955 JLS.  Jikes will warn for this when given @code{+Pmodifier-order}.
956
957 @item
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.
965 @c fixme index
966 @c fixme link to the discussion
967
968 @item
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
975 fully implemented.
976
977 @item
978 When overriding @code{Object.equals}, remember that @code{instanceof}
979 filters out @code{null}, so an explicit check is not needed.
980
981 @item
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.
985
986 @example
987   try
988     @{
989       // Some code that can throw
990     @}
991   catch (IOException ioe)
992     @{
993       throw (SQLException) new SQLException("Database corrupt").setCause(ioe);
994     @}
995 @end example
996
997 @item
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.
1007
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.
1011
1012 @end itemize
1013
1014 Some things are the same as in the normal GNU Coding Standards:
1015
1016 @itemize @bullet
1017
1018 @item
1019 Unnecessary braces can be removed, one line after an if, for, while as
1020 examples.
1021
1022 @item
1023 Space around operators (assignment, logical, relational, bitwise,
1024 mathematical, shift).
1025
1026 @item
1027 Blank line before single-line comments, multi-line comments, javadoc
1028 comments.
1029
1030 @item
1031 If more than 2 blank lines, trim to 2.
1032
1033 @item
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
1036 implementation.
1037 @end itemize
1038
1039
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
1043
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
1046 smoother.
1047
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
1051 effectively.
1052
1053 We maintain a
1054 @uref{http://www.gnu.org/software/classpath/tasks.html,Task List}
1055 which contains items that you might want to work on.
1056
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.
1063
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
1067 will find the
1068 @uref{https://savannah.gnu.org/projects/classpath/,project page}, bug
1069 reports, pending patches, links to mailing lists, news items and CVS.
1070
1071 You can find instructions on getting a CVS checkout for classpath at
1072 @uref{https://savannah.gnu.org/cvs/?group=classpath}.
1073
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.
1078
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.
1082
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
1093 say so on list.)
1094
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.
1101
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
1109 wrote the patch.
1110
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.
1116
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.
1121
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
1131 constraints).
1132
1133 @menu
1134 * Branches::                    
1135 * Writing ChangeLogs::          
1136 @end menu
1137
1138 @node Branches, Writing ChangeLogs, Hacking Code, Hacking Code
1139 @comment node-name, next, previous, up
1140 @section Working with branches
1141
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.
1145
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:
1154
1155 @itemize @bullet
1156
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.
1160
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.)
1166
1167 @item Requirements for patch email to classpath-patches and for paperwork
1168 @strong{cannot} be lifted. See @ref{Requirements}.
1169
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''.
1177
1178 @item Merges from the trunk to a branch are at the discretion of the
1179 branch maintainer.
1180
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).
1184
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.
1188
1189 @end itemize
1190
1191 If any of these rules are unclear please discuss on the list first.
1192
1193 @menu
1194 * Writing ChangeLogs::          
1195 @end menu
1196
1197 @node Writing ChangeLogs,  , Branches, Hacking Code
1198 @comment node-name, next, previous, up
1199 @section Documenting what changed when with ChangeLog entries
1200
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.
1208
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}.
1211
1212 Here are some example to explain what should or shouldn't be in a
1213 ChangeLog entry (and the corresponding commit message):
1214
1215 @itemize @bullet
1216
1217 @item
1218 The first line of a ChangeLog entry should be:
1219
1220 @example
1221 [date] <two spaces> [full name] <two spaces> [email-contact]
1222 @end example
1223
1224 The second line should be blank. All other lines should be indented
1225 with one tab.
1226
1227 @item
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).
1231
1232 So don't write:
1233
1234 @example
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.
1238 @end example
1239
1240 Just state:
1241
1242 @example
1243         * java/awt/font/OpenType.java: Remove 'public static final' from
1244         all member fields.
1245 @end example
1246
1247 In this case the reason for the change was added to this guide.
1248
1249 @item
1250 Just as with the normal code style guide, don't make lines longer then
1251 80 characters.
1252
1253 @item
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.
1256
1257 @item
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:
1260
1261 @example
1262  * java/io/ObjectOutputStream.java : Allow putFields be called more 
1263  than once.
1264 @end example
1265
1266 But explain what changed and in which methods it was changed:
1267
1268 @example
1269  * java/io/ObjectOutputStream.java (putFields): Don't call
1270  markFieldsWritten(). Only create new PutField when
1271  currentPutField is null.
1272  (writeFields): Call markFieldsWritten().
1273 @end example
1274
1275 @end itemize
1276
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.
1283
1284
1285 @node Programming Goals, API Compatibility, Hacking Code, Top
1286 @comment node-name, next, previous, up
1287 @chapter Programming Goals
1288
1289 When you write code for Classpath, write with three things in mind, and
1290 in the following order: portability, robustness, and efficiency.
1291
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.
1297
1298 @menu
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
1305 @end menu
1306
1307 @node Portability, Utility Classes, Programming Goals, Programming Goals
1308 @comment node-name, next, previous, up
1309 @section Portability
1310
1311 The portability goal for Classpath is the following:
1312
1313 @enumerate
1314 @item
1315 native functions for each platform that work across all VMs on that
1316 platform
1317 @item
1318 a single classfile set that work across all VMs on all platforms that
1319 support the native functions.
1320 @end enumerate
1321
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.
1327
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. 
1332
1333 @node Utility Classes, Robustness, Portability, Programming Goals
1334 @comment  node-name,  next,  previous,  up
1335 @section Utility Classes
1336
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
1343 Efficiency}.
1344
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.
1352
1353 @node Robustness, Java Efficiency, Utility Classes, Programming Goals
1354 @comment node-name, next, previous, up
1355 @section Robustness
1356
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
1359 robust.
1360
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.)
1365
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.
1370
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).
1374
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."
1378
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.
1381
1382 @node Java Efficiency, Native Efficiency, Robustness, Programming Goals
1383 @comment node-name, next, previous, up
1384 @section Java Efficiency
1385
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
1388 code like:
1389
1390 @example
1391 int 
1392 strlen (String foo) throws NullPointerException
1393 @{
1394   if (foo == null)
1395     throw new NullPointerException ("foo is null");
1396   return foo.length ();
1397 @}
1398 @end example
1399
1400 Instead, the code should be written as:
1401
1402 @example
1403 int
1404 strlen (String foo) throws NullPointerException
1405 @{
1406   return foo.length ();
1407 @}
1408 @end example
1409
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.
1414
1415 @node Native Efficiency, Security, Java Efficiency, Programming Goals
1416 @comment node-name, next, previous, up
1417 @section Native Efficiency
1418
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?
1424
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.
1427
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}.
1436
1437 Here are a few tips on writing native code efficiently:
1438
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.
1446
1447 Cache @code{jmethodID}s and @code{jfieldID}s wherever you can.  String
1448 lookups are 
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.
1456
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.
1460
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
1465 directly.
1466
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.
1474
1475 @node Security,  , Native Efficiency, Programming Goals
1476 @comment  node-name,  next,  previous,  up
1477 @section Security
1478
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
1485 Wheeler,
1486 @uref{http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/index.html,Secure
1487 Programming for Linux and Unix HOWTO}.
1488
1489 @node API Compatibility, Specification Sources, Programming Goals, Top
1490 @comment  node-name,  next,  previous,  up
1491 @chapter API Compatibility
1492
1493 @menu
1494 * Serialization::               Serialization
1495 * Deprecated Methods::          Deprecated methods
1496 @end menu
1497
1498 @node Serialization, Deprecated Methods, API Compatibility, API Compatibility
1499 @comment  node-name,  next,  previous,  up
1500 @section Serialization
1501
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.
1508
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.
1519
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.
1526
1527 @node Deprecated Methods,  , Serialization, API Compatibility
1528 @comment  node-name,  next,  previous,  up
1529 @section Deprecated Methods
1530
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.
1536
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.
1542
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
1547 the new one.
1548
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.
1558
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
1565 signature.
1566
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.
1572
1573 @node Specification Sources, Naming Conventions, API Compatibility, Top
1574 @comment node-name, next, previous, up
1575 @chapter Specification Sources
1576
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.
1582
1583 Here, however, is a list of specs, in order of canonicality:
1584
1585 @enumerate
1586 @item
1587 @uref{http://java.sun.com/docs/books/jls/clarify.html,Clarifications and Amendments to the JLS - 1.1}
1588 @item
1589 @uref{http://java.sun.com/docs/books/jls/html/1.1Update.html,JLS Updates
1590 - 1.1}
1591 @item
1592 @uref{http://java.sun.com/docs/books/jls/html/index.html,The 1.0 JLS}
1593 @item
1594 @uref{http://java.sun.com/docs/books/vmspec/index.html,JVM spec - 1.1}
1595 @item
1596 @uref{http://java.sun.com/products/jdk/1.1/docs/guide/jni/spec/jniTOC.doc.html,JNI spec - 1.1}
1597 @item
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.)
1601 @item
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.)
1607 @item
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
1611 for 1.2)
1612 @item
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.
1620 @end enumerate
1621
1622 You'll notice that in this document, white papers and specification
1623 papers are more canonical than the JavaDoc documentation.  This is true
1624 in general.
1625
1626
1627 @node Naming Conventions, Character Conversions, Specification Sources, Top
1628 @comment node-name, next, previous, up
1629 @chapter Directory and File Naming Conventions
1630
1631 The Classpath directory structure is laid out in the following manner:
1632
1633 @example
1634 classpath
1635  |
1636  |---->java
1637  |       |
1638  |       |-->awt
1639  |       |-->io
1640  |       |-->lang
1641  |       |-->util
1642  |       |     |
1643  |       |     |--->zip
1644  |       |     |--->jar
1645  |       |-->net
1646  |       |-->etc
1647  |
1648  |---->gnu
1649  |       |
1650  |       |-->java
1651  |             |
1652  |             |-->awt
1653  |             |-->lang
1654  |             |-->util
1655  |             |     |
1656  |             |     |-->zip
1657  |             |-->etc
1658  |
1659  |---->native
1660          |
1661          |-->jni
1662          |    |-->classpath
1663          |    |-->gtk-peer
1664          |    |-->java-io
1665          |    |-->java-lang
1666          |    |-->java-net
1667          |    |-->java-util
1668          |    |-->etc
1669          |-->cni
1670   
1671 @end example
1672
1673 Here is a brief description of the toplevel directories and their contents.
1674
1675 @table @b
1676
1677 @item java
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.
1684
1685 @item gnu/java
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.
1693
1694 @item native
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
1700 code is required.
1701
1702 @end table
1703
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:
1707
1708 @itemize @bullet
1709
1710 @item
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''.
1715
1716 @item
1717 Each package has its own shared library for native code (if any).
1718
1719 @item
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.
1726 @end itemize
1727
1728 @node Character Conversions, Localization, Naming Conventions, Top
1729 @comment node-name, next, previous, up
1730 @chapter Character Conversions
1731
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.
1742
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.
1756
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.
1769
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.
1773
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.
1782
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}.
1799
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.
1806
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.
1818
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.
1824
1825 Many more translators are needed.  All major character encodings should
1826 eventually be supported.
1827
1828 @node Localization,  , Character Conversions, Top
1829 @comment node-name, next, previous, up
1830 @chapter Localization
1831
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
1838 given locale.
1839
1840 @menu
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
1845 @end menu
1846
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.
1852
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.
1859
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.
1864
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
1870 example:
1871
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
1874 library class:
1875
1876 @example
1877   ListResourceBundle lrb = 
1878     ListResourceBundle.getBundle ("gnu/java/locale/LocaleInformation", locale);
1879   String format_string = lrb.getString ("format_string");
1880 @end example
1881
1882 In the actual resource bundle class, here is how the configuration option
1883 gets defined:
1884
1885 @example
1886 /**
1887   * This is the format string used for displaying values
1888   */
1889 private static final String format_string = "%s %d %i";
1890
1891 private static final Object[][] contents =
1892 @{
1893   @{ "format_string", format_string @}
1894 @};
1895 @end example
1896
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.
1901
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.
1915
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.
1921
1922 @node String Collation, Break Iteration, Localization, Localization
1923 @comment node-name, next, previous, up
1924 @section String Collation
1925
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.
1929
1930 @itemize @bullet
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
1934 be performed.
1935 @end itemize
1936
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.
1940
1941 @node Break Iteration, Date Formatting and Parsing, String Collation, Localization
1942 @comment node-name, next, previous, up
1943 @section Break Iteration
1944
1945 The class @code{java.text.BreakIterator} breaks text into words, sentences,
1946 and lines.  It is configured with the following resource bundle entries:
1947
1948 @itemize @bullet
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
1953 sequences.
1954 @item line_breaks - A @code{String} array of line break character sequences.
1955 @end itemize
1956
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
1960
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):
1968
1969 @itemize @bullet
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 
1979 locale.
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}
1997 @end itemize
1998
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.
2002
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
2006
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:
2014
2015 @itemize @bullet
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
2022 @code{String}.
2023 @item digit - The character used to represent digits in a format string,
2024 as a @code{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
2029 a @code{String}.
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 
2033 @code{String}.
2034 @item monetarySeparator - The decimal point used in currency values, as a
2035 @code{String}.
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}.
2041 @end itemize
2042
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.
2046
2047 @bye
2048