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 11This file contains important information you will need to know if you 12are going to hack on the GNU Classpath project code. 13 14Copyright (C) 1998,1999,2000,2001,2002,2003,2004,2005,2007,2009 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 34Copyright @copyright{} 1998,1999,2000,2001,2002,2003,2004 Free Software Foundation, Inc. 35@sp 2 36Permission is granted to make and distribute verbatim copies of 37this document provided the copyright notice and this permission notice 38are preserved on all copies. 39 40Permission is granted to copy and distribute modified versions of this 41document under the conditions for verbatim copying, provided that the 42entire resulting derived work is distributed under the terms of a 43permission notice identical to this one. 44 45Permission is granted to copy and distribute translations of this manual 46into another language, under the above conditions for modified versions, 47except that this permission notice may be stated in a translation 48approved 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 56This document contains important information you'll want to know if 57you want to hack on GNU Classpath, Essential Libraries for Java, to 58help create free core class libraries for use with virtual machines 59and 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 83Programming Standards 84 85* Source Code Style Guide:: 86 87Working on the code, Working with others 88 89* Branches:: 90* Writing ChangeLogs:: 91 92Working with branches 93 94* Writing ChangeLogs:: 95 96Programming 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 105API Compatibility 106 107* Serialization:: Serialization 108* Deprecated Methods:: Deprecated methods 109 110Localization 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 124The GNU Classpath Project is dedicated to providing a 100% free, 125clean room implementation of the standard core class libraries for 126compilers and runtime environments for the java programming language. 127It offers free software developers an alternative core library 128implementation upon which larger java-like programming environments 129can be built. The GNU Classpath Project was started in the Spring of 1301998 as an official Free Software Foundation project. Most of the 131volunteers working on GNU Classpath do so in their spare time, but a 132couple of projects based on GNU Classpath have paid programmers to 133improve the core libraries. We appreciate everyone's efforts in the 134past to improve and help the project and look forward to future 135contributions by old and new members alike. 136 137@node Requirements, Volunteering, Introduction, Top 138@comment node-name, next, previous, up 139@chapter Requirements 140 141Although GNU Classpath is following an open development model where input 142from developers is welcome, there are certain base requirements that 143need to be met by anyone who wants to contribute code to this project. 144They are mostly dictated by legal requirements and are not arbitrary 145restrictions chosen by the GNU Classpath team. 146 147You will need to adhere to the following things if you want to donate 148code to the GNU Classpath project: 149 150@itemize @bullet 151@item 152@strong{Never under any circumstances refer to proprietary code while 153working on GNU Classpath.} It is best if you have never looked at 154alternative proprietary core library code at all. To reduce 155temptation, it would be best if you deleted the @file{src.zip} file 156from your proprietary JDK distribution (note that recent versions of 157GNU Classpath and the compilers and environments build on it are 158mature enough to not need any proprietary implementation at all when 159working on GNU Classpath, except in exceptional cases where you need 160to test compatibility issues pointed out by users). If you have 161signed Sun's non-disclosure statement, then you unfortunately cannot 162work on Classpath code at all. If you have any reason to believe that 163your code might be ``tainted'', please say something on the mailing 164list before writing anything. If it turns out that your code was not 165developed in a clean room environment, we could be very embarrassed 166someday in court. Please don't let that happen. 167 168@item 169@strong{Never decompile proprietary class library implementations.} While 170the wording of the license in Sun's Java 2 releases has changed, it is 171not acceptable, under any circumstances, for a person working on 172GNU Classpath to decompile Sun's class libraries. Allowing the use of 173decompilation in the GNU Classpath project would open up a giant can of 174legal worms, which we wish to avoid. 175 176@item 177Classpath is licensed under the terms of the 178@uref{http://www.fsf.org/copyleft/gpl.html,GNU General Public 179License}, with a special exception included to allow linking with 180non-GPL licensed works as long as no other license would restrict such 181linking. To preserve freedom for all users and to maintain uniform 182licensing of Classpath, we will not accept code into the main 183distribution that is not licensed under these terms. The exact 184wording of the license of the current version of GNU Classpath can be 185found online from the 186@uref{http://www.gnu.org/software/classpath/license.html, GNU 187Classpath license page} and is of course distributed with current 188snapshot release from @uref{ftp://ftp.gnu.org/gnu/classpath/} or by 189obtaining a copy of the current CVS tree. 190 191@item 192GNU Classpath is GNU software and this project is being officially sponsored 193by the @uref{http://www.fsf.org/,Free Software Foundation}. Because of 194this, the FSF will hold copyright to all code developed as part of 195GNU Classpath. This will allow them to pursue copyright violators in court, 196something an individual developer may neither have the time nor 197resources to do. Everyone contributing code to GNU Classpath will need to 198sign a copyright assignment statement. Additionally, if you are 199employed as a programmer, your employer may need to sign a copyright 200waiver disclaiming all interest in the software. This may sound harsh, 201but unfortunately, it is the only way to ensure that the code you write 202is 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 209The GNU Classpath project needs volunteers to help us out. People are 210needed to write unimplemented core packages, to test GNU Classpath on 211free software programs written in the java programming language, to 212test it on various platforms, and to port it to platforms that are 213currently unsupported. 214 215While pretty much all contributions are welcome (but see 216@pxref{Requirements}) it is always preferable that volunteers do the 217whole job when volunteering for a task. So when you volunteer to write 218a Java package, please be willing to do the following: 219 220@itemize @bullet 221@item 222Implement a complete drop-in replacement for the particular package. 223That means implementing any ``internal'' classes. For example, in the 224java.net package, there are non-public classes for implementing sockets. 225Without those classes, the public socket interface is useless. But do 226not feel obligated to completely implement all of the functionality at 227once. For example, in the java.net package, there are different types 228of protocol handlers for different types of URLs. Not all of these 229need to be written at once. 230 231@item 232Please write complete and thorough API documentation comments for 233every public and protected method and variable. These should be 234superior to Sun's and cover everything about the item being 235documented. 236 237@item 238Please write a regression test package that can be used to run tests 239of your package's functionality. GNU Classpath uses the 240@uref{http://sources.redhat.com/mauve/,Mauve project} for testing the 241functionality of the core class libraries. The Classpath Project is 242fast approaching the point in time where all modifications to the 243source code repository will require appropriate test cases in Mauve to 244ensure correctness and prevent regressions. 245@end itemize 246 247Writing good documentation, tests and fixing bugs should be every 248developer's top priority in order to reach the elusive release of 249version 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 255The goal of the Classpath project is to produce a 256@uref{http://www.fsf.org/philosophy/free-sw.html,free} implementation of 257the standard class library for Java. However, there are other more 258specific goals as to which platforms should be supported. 259 260Classpath is targeted to support the following operating systems: 261 262@enumerate 263@item 264Free operating systems. This includes GNU/Linux, GNU/Hurd, and the free 265BSDs. 266 267@item 268Other Unix-like operating systems. 269 270@item 271Platforms which currently have no Java support at all. 272 273@item 274Other platforms such as MS-Windows. 275@end enumerate 276 277While free operating systems are the top priority, the other priorities 278can shift depending on whether or not there is a volunteer to port 279Classpath to those platforms and to test releases. 280 281Eventually we hope the Classpath will support all JVMs that provide 282JNI or CNI support. However, the top priority is free JVMs. A small 283list of Compiler/VM environments that are currently actively 284incorporating GNU Classpath is below. A more complete overview of 285projects based on GNU classpath can be found online at 286@uref{http://www.gnu.org/software/classpath/stories.html,the GNU 287Classpath 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://www.cacaojvm.org/,cacao} 296@item 297@uref{http://jikesrvm.org,Jikes RVM} 298@item 299@uref{http://www.kaffe.org/,Kaffe} 300@item 301@uref{http://www.ikvm.net/,IKVM} 302@end enumerate 303 304As with OS platform support, this priority list could change if a 305volunteer comes forward to port, maintain, and test releases for a 306particular JVM@. Since gcj is part of the GNU Compiler Collective it 307is one of the most important targets. But since it doesn't currently 308work out of the box with GNU Classpath it is not the easiest 309target. When hacking on GNU Classpath the easiest solution is to use 310compilers and runtime environments that work out of the box with 311it, such as the Eclipse compiler, ecj, and the runtime environments jamvm and 312cacao. Both Jikes RVM and Kaffe use an included version of GNU Classpath by 313default, but Kaffe can now use a pre-installed version and Jikes RVM supports 314using a CVS snapshot as well as the latest release. Working directly with 315targets such as Jikes RVM, gcj and IKVM is possible but can be a little more 316difficult as changes have to be merged back into GNU Classpath proper, 317which requires additional work. Due to a recent switch to the use of 1.5 language 318features within GNU Classpath, a compiler compatible with these features is required. 319At present, this includes the Eclipse compiler, ecj, and the OpenJDK compiler. 320 321GNU Classpath currently implements the majority of the 1.4 and 1.5 APIs 322(binary compatibility is above 95% for both, but does not take into account 323internal implementations of features such as graphic and sound support). There 324is support for some 1.6 APIs but this is still nascent. Please do not create classes 325that depend on features in other packages unless GNU Classpath already 326contains those features. GNU Classpath has been free of any 327proprietary dependencies for a long time now and we like to keep it 328that way. Finishing, polishing up, documenting, testing and 329debugging current functionality is of higher priority then adding new 330functionality. 331 332@node Needed Tools and Libraries, Installation, Project Goals, Top 333@comment node-name, next, previous, up 334@chapter Needed Tools and Libraries 335 336If you want to hack on Classpath, you should at least download and 337install the following tools and try to familiarize yourself with 338them. In most cases having these tools installed will be all 339you really need to know about them. Also note that when working on 340(snapshot) releases only a 1.5 compiler (plus a free VM from the list above 341and the libraries listed below) is required. The other tools are only 342needed when working directly on the CVS version. 343 344@itemize @bullet 345@item 346GNU make 3.80+ 347@item 348GCC 2.95+ 349@item 350Eclipse Compiler for Java 3.1+ 351@item 352CVS 1.11+ 353@item 354automake 1.11+ 355@item 356autoconf 2.64+ 357@item 358libtool 1.5+ 359@item 360GNU m4 1.4.6 361@item 362texinfo 4.2+ 363@end itemize 364 365All of these tools are available from 366@uref{ftp://gnudist.gnu.org/pub/gnu/,gnudist.gnu.org} via anonymous 367ftp, except CVS which is available from 368@uref{http://www.cvshome.org/,www.cvshome.org} and the Eclipse 369Compiler for Java, which is available from 370@uref{http://www.eclipse.org/jdt/core,www.eclipse.org/jdt/core}. 371 372Except for the Eclipse Compiler for Java, they are fully documented 373with texinfo manuals. Texinfo can be browsed with the Emacs editor, 374or with the text editor of your choice, or transformed into nicely 375printable Postscript. 376 377Here is a brief description of the purpose of those tools. 378 379@table @b 380 381@item make 382GNU make ("gmake") is required for building Classpath. 383 384@item GCC 385The GNU Compiler Collection. This contains a C compiler (gcc) for 386compiling the native C code and a compiler for the java programming 387language (gcj). You will need at least gcc version 2.95 or higher 388in order to compile the native code. There is currently no 389released version of gcj that can compile the Java 1.5 programming 390language used by GNU Classpath. 391 392@item ecj 393The Eclipse Compiler for Java. This is a compiler for the Java 1.5 394programming language. It translates source code to bytecode. The 395Eclipse Foundation makes ``ecj.jar'' available as the JDT Core Batch 396Compiler download. 397 398@item CVS 399A version control system that maintains a centralized Internet 400repository of all code in the Classpath system. 401 402@item automake 403This tool automatically creates @file{Makefile.in} files from 404@file{Makefile.am} files. The @file{Makefile.in} is turned into a 405@file{Makefile} by @command{autoconf}. 406 407Why use this? Because it automatically generates every makefile 408target you would ever want (@option{clean}, @option{install}, 409@option{dist}, etc) in full compliance with the GNU coding standards. 410It also simplifies Makefile creation in a number of ways that cannot 411be described here. Read the docs for more info. 412 413@item autoconf 414Automatically configures a package for the platform on which it is 415being built and generates the Makefile for that platform. 416 417@item libtool 418Handles all of the zillions of hairy platform specific options needed 419to build shared libraries. 420 421@item m4 422The free GNU replacement for the standard Unix macro processor. 423Proprietary m4 programs are broken and so GNU m4 is required for 424autoconf to work though knowing a lot about GNU m4 is not required to 425work with autoconf. 426 427@item perl 428Larry Wall's scripting language. It is used internally by automake. 429 430@item texinfo 431Manuals and documentation (like this guide) are written in texinfo. 432Texinfo is the official documentation format of the GNU project. 433Texinfo uses a single source file to produce output in a number of formats, 434both online and printed (dvi, info, html, xml, etc.). This means that 435instead of writing different documents for online information and another 436for a printed manual, you need write only one document. And when the work 437is revised, you need revise only that one document. 438 439@end table 440 441For any build environment involving native libraries, recent 442versions of @command{autoconf}, @command{automake}, and @command{libtool} 443are required if changes are made that require rebuilding @file{configure}, 444@file{Makefile.in}, @file{aclocal.m4}, or @file{config.h.in}. 445 446When working from CVS you can run those tools by executing 447@command{autogen.sh} in the source directory. 448 449For building the Java bytecode (.class files), you can select 450which compiler should be employed using @option{--with-javac} or 451@option{--with-ecj} as an argument to @command{configure}; 452the present default is @command{ecj} if found. 453 454Instead of @command{ecj}, you can also use @command{javac}, which is 455available at 456@uref{https://openjdk.dev.java.net/compiler, openjdk.dev.java.net/compiler}. 457 458For compiling the native AWT libraries you need to have the following 459libraries installed (unless @option{--disable-gtk-peer} is used as an argument 460to @command{configure}): 461 462@table @b 463@item GTK+ 2.8.x 464@uref{http://www.gtk.org/,GTK+} is a multi-platform toolkit for 465creating graphical user interfaces. It is used as the basis of the 466GNU desktop project GNOME. 467 468@item gdk-pixbuf 469@uref{http://www.gnome.org/start/,gdk-pixbuf} is a GNOME library for 470representing images. 471 472@item XTest 473@uref{http://www.x.org,www.x.org} hosts the XTest Extension (libXtst). 474It is necessary for GdkRobot support in java.awt. 475 476@end table 477 478There is a bug in earlier versions of at-spi, atk, and gail, which are 479used for GNOME accessibility. Prior to version 1.18.0 of these packages, 480gtk graphical applications should be run without accessibility (clear the 481GTK_MODULES environment variable). 482 483For building the Qt AWT peer JNI native libraries you have to 484specify @option{--enable-qt-peer} and need the following library: 485 486@table @b 487@item Qt 488@uref{http://www.trolltech.com/products/qt,Qt} version 4.0.1 or higher. 489The Qt library is a cross-platform graphics toolkit. 490 491@end table 492 493Please note that at the moment most operating systems do not 494ship Qt version 4.0.1 by default. We recommend using GNU Classpath' Qt 495support only for its developers and bug reporters. See 496@uref{http://developer.classpath.org/mediation/ClasspathShowcase, the wiki} 497for details on how to get it to work. 498 499For building the X AWT peers you have to specify where to find the 500Escher library on your system using the @option{--with-escher=ABS.PATH} option. 501You will need the following library: 502 503@table @b 504@item Escher 505@uref{http://escher.sourceforge.net,Escher} version 0.2.3 or higher. 506The Escher library is an implementation of X protocol and associated 507libraries written in the Java programming language. 508 509@end table 510 511For building the ALSA midi provider code you will need 512the following library: 513 514 515@table @b 516@item ALSA 517@uref{http://www.alsa-project.org,ALSA} libraries. 518 519The ALSA project provides sound device drivers and associated 520libraries for the Linux kernel. 521 522@end table 523 524Building the ALSA midi provider code can be disabled by passing 525@option{--disable-alsa} to @command{configure}. 526 527For building the DSSI midi synthesizer provider code you will 528need the following libraries: 529 530@table @b 531@item DSSI 532@uref{http://dssi.sourceforge.net,DSSI} library for audio 533processing plugins. 534 535@item liblo 536@uref{http://plugin.org.uk/liblo/,liblo}, the Lightweight OSC 537implementation. 538 539@item LADSPA 540@uref{http://www.ladspa.org,LADSPA}, the Linux Audio Developer's 541Simple Plugin API. 542 543@item JACK 544@uref{http://jackit.sourceforge.net,JACK}, a low latency audio 545server. 546 547@item libsndfile 548@uref{http://www.mega-nerd.com/libsndfile/,libsndfile}, an audio 549file I/O library. 550 551@item fluidsynth 552@uref{http://www.fluidsynth.org/,fluidsynth}, a real-time SoundFont 5532 based soft-synth. 554 555@end table 556 557The GConf-based backend for java.util.prefs needs the following 558library headers: 559 560@table @b 561@item GConf 562@uref{http://www.gnome.org/projects/gconf/,GConf} version 2.11.2 563(or higher). GConf is used for storing desktop and application 564configuration settings in GNOME. 565 566@end table 567 568The GStreamer backend for javax.sound.sampled (The Java Sound API, not 569including the MIDI portion) needs the following library headers: 570 571@table @b 572@item GStreamer 573@uref{http://gstreamer.freedesktop.org/,GStreamer} version 0.10.10 574(or higher). You will also need at least gstreamer-base and 575gstreamer-plugins-base. More plugins can be used to allow streaming of 576different sound types but are not a compile time requirement. See 577README.gstreamer in the source distribution for more informations. 578 579@end table 580 581For building @command{gcjwebplugin} you'll need the Mozilla plugin 582support headers and libraries, which are available at 583@uref{http://www.mozilla.org,www.mozilla.org}. 584 585For enabling the com.sun.tools.javac support in tools.zip you 586will need a jar file containing the Eclipse Java Compiler. 587Otherwise com.sun.tools.javac will not be included in @file{tools.zip}. 588 589For building the xmlj JAXP implementation (disabled by default, 590use @command{configure --enable-xmlj}) you need the following libraries: 591 592@table @b 593@item libxml2 594@uref{http://www.xmlsoft.org/,libxml2} version 2.6.8 or higher. 595 596The libxml2 library is the XML C library for the Gnome desktop. 597 598@item libxslt 599@uref{http://www.xmlsoft.org/XSLT/,libxslt} version 1.1.11 or higher. 600 601The libxslt library if the XSLT C library for the Gnome desktop. 602@end table 603 604GNU Classpath comes with a couple of libraries included in the source 605that are not part of GNU Classpath proper, but that have been included 606to provide certain needed functionality. All these external libraries 607should be clearly marked as such. In general we try to use as much as 608possible the clean upstream versions of these sources. That way 609merging in new versions will be easier. You should always try to get 610bug fixes to these files accepted upstream first. Currently we 611include the following 'external' libraries. Most of these sources are 612included in the @file{external} directory. That directory also 613contains a @file{README} file explaining how to import newer versions. 614 615@table @b 616 617@item JSR166 concurrency support 618Can be found in @file{external/jsr166}. Provides java.util.concurrent 619and its subpackages. Upstream is 620@uref{http://g.oswego.edu/dl/concurrency-interest/,Doug Lea's Concurrency Interest Site}. 621 622@item RelaxNG Datatype Interfaces 623Can be found in @file{external/relaxngDatatype}. Provides org.relaxng.datatype 624and its subpackages. Upstream is 625@uref{http://www.oasis-open.org/committees/relax-ng/}. 626 627@item Simple API for XML (SAX) 628Can be found in @file{external/sax}. Provides org.xml.sax and its subpackages. 629Upstream is 630@uref{http://www.saxproject.org}. 631 632@item Document Object Model (DOM) bindings 633Can be found in @file{external/w3c_dom}. Provides org.w3c.dom and its subpackages. 634Upstream locations are listed in @file{external/w3c_dom/README}. 635 636@item fdlibm 637Can be found in @file{native/fdlibm}. Provides native implementations 638of some of the Float and Double operations. Upstream is 639@uref{http://gcc.gnu.org/java/,libgcj}, they sync again with the 640'real' upstream @uref{http://www.netlib.org/fdlibm/readme}. See also 641java.lang.StrictMath. 642 643@end table 644 645@node Installation, Building and running with the X AWT peers, Needed Tools and Libraries, Top 646@comment node-name, next, previous, up 647@chapter Installation instructions 648 649This package was designed to use the GNU standard for configuration 650and makefiles. To build and install do the following: 651 652@enumerate 653@item Configuration 654 655Run the @command{configure} script to configure the package. There are 656various options you might want to pass to @command{configure} to control how the 657package is built. Consider the following options, @command{configure --help} 658gives a complete list. 659 660@table @option 661@item --enable-java 662 663compile Java source (default=@option{yes}). 664 665@item --enable-jni 666 667compile JNI source (default=@option{yes}). 668 669@item --enable-gtk-peer 670 671compile GTK native peers (default=@option{yes}). 672 673@item --enable-qt-peer 674 675compile Qt4 native peers (default=@option{no}). 676 677@item --enable-default-toolkit 678 679fully qualified class name of default AWT toolkit (default=@option{no}). 680 681@item --enable-xmlj 682 683compile native libxml/xslt library (default=@option{no}). 684 685@item --enable-load-library 686 687enable to use JNI native methods (default=@option{yes}). 688 689@item --enable-local-sockets 690 691enable build of local Unix sockets. 692 693@item --with-glibj 694define what to install @option{(zip|flat|both|none)} (default=@option{zip}). 695 696@item --with-escher=/path/to/escher 697 698enable build of the X/Escher peers, with 699the escher library at @file{/path/to/escher}, either 700in the form of a JAR file, or a directory 701containing the .class files of Escher. 702 703@item --enable-Werror 704 705whether to compile C code with @option{-Werror} which turns 706any compiler warning into a compilation failure 707(default=@option{no}). 708 709@item --with-gjdoc 710 711generate documentation using @command{gjdoc} (default=@option{no}). 712 713@item --with-jay 714 715Regenerate the parsers with @command{jay}, must be given the 716path to the @command{jay} executable 717 718@item --with-glibj-zip=ABS.PATH 719 720use prebuilt glibj.zip class library 721 722@item --with-ecj-jar=ABS.PATH 723 724specify jar file containing the Eclipse Java Compiler 725 726@item --with-gstreamer-peer 727 728build the experimental GStreamer peer (see @file{README.gstreamer}) 729 730@end table 731 732For more flags run @command{configure --help}. 733 734@item Building 735 736Type @command{gmake} to build the package. There is no longer a 737dependency problem and we aim to keep it that way. 738 739@item Installation 740 741Type @command{gmake install} to install everything. This may require 742being the superuser. The default install path is /usr/local/classpath 743you may change it by giving @command{configure} the 744@option{--prefix=<path>} option. 745 746@end enumerate 747 748Report bugs to @email{classpath@@gnu.org} or much better to the 749GNU Classpath bug tracker at 750@uref{http://savannah.gnu.org/support/?func=addsupport&group=classpath,Savannah}. 751 752Happy Hacking! 753 754Once installed, GNU Classpath is ready to be used by any VM that supports 755using the official version of GNU Classpath. Simply ensure that 756@file{/usr/local/classpath/share/classpath} is in your @env{CLASSPATH} environment 757variable. You'll also have to set your @env{LD_LIBRARY_PATH} 758variable (or similar system configuration) to include the Classpath 759native libraries in @file{/usr/local/classpath/lib/classpath}. 760 761*NOTE* All example paths assume the default prefix is used with @command{configure}. 762If you don't know what this means then the examples are correct. 763 764@example 765LD_LIBRARY_PATH=/usr/local/classpath/lib/classpath 766CLASSPATH=/usr/local/classpath/share/classpath/glibj.zip:. 767export LD_LIBRARY_PATH CLASSPATH 768@end example 769 770More information about the VMs that use GNU Classpath can be found in the 771@file{README} file. 772 773@node Building and running with the X AWT peers, Misc. Notes, Installation, Top 774@comment node-name, next, previous, up 775@chapter Building and running with the X AWT peers 776 777In order build the X peers you need the Escher library version 0.2.3 778from @uref{http://escher.sourceforge.net,escher.sourceforge.net}. 779Unpack (and optionally build) the 780Escher library following the instructions in the downloaded 781package. Enable the build of the X peers by passing 782@option{--with-escher=/path/to/escher} to @command{configure} where @file{/path/to/escher} 783either points to a directory structure or JAR file containing the 784Escher classes. For Unix systems it is preferable to also build local 785socket support by passing @option{--enable-local-sockets}, which accelerates 786the network communication to the X server significantly. 787 788In this release you have to enable the X peers at runtime by 789setting the system property awt.toolkit=gnu.java.awt.peer.x.XToolkit 790by passing @option{-Dawt.toolkit=gnu.java.awt.peer.x.XToolkit} to the @command{java} 791command when running an application. 792 793@node Misc. Notes, Programming Standards, Building and running with the X AWT peers, Top 794@comment node-name, next, previous, up 795@chapter Misc. Notes 796 797Compilation is accomplished using a compiler's @@file syntax. For our 798part, we avoid placing make style dependencies as rules upon the 799compilation of a particular class file and leave this up to the Java 800compiler instead. 801 802The @option{--enable-maintainer-mode} option to @command{configure} currently does very 803little and shouldn't be used by ordinary developers or users anyway. 804 805On Windows machines, the native libraries do not currently build, but 806the Java bytecode library will. GCJ trunk is beginning to work under 807Cygwin. 808 809@node Programming Standards, Hacking Code, Misc. Notes, Top 810@comment node-name, next, previous, up 811@chapter Programming Standards 812 813For C source code, follow the 814@uref{http://www.gnu.org/prep/standards/,GNU Coding Standards}. 815The standards also specify various things like the install directory 816structure. These should be followed if possible. 817 818For Java source code, please follow the 819@uref{http://www.gnu.org/prep/standards/,GNU Coding 820Standards}, as much as possible. There are a number of exceptions to 821the GNU Coding Standards that we make for GNU Classpath as documented 822in this guide. We will hopefully be providing developers with a code 823formatting tool that closely matches those rules soon. 824 825For API documentation comments, please follow 826@uref{http://java.sun.com/products/jdk/javadoc/writingdoccomments.html,How 827to Write Doc Comments for Javadoc}. We would like to have a set of 828guidelines more tailored to GNU Classpath as part of this document. 829 830@menu 831* Source Code Style Guide:: 832@end menu 833 834@node Source Code Style Guide, , Programming Standards, Programming Standards 835@comment node-name, next, previous, up 836@section Java source coding style 837 838Here is a list of some specific rules used when hacking on GNU 839Classpath java source code. We try to follow the standard 840@uref{http://www.gnu.org/prep/standards/,GNU Coding Standards} 841for that. There are lots of tools that can automatically generate it 842(although most tools assume C source, not java source code) and it 843seems as good a standard as any. There are a couple of exceptions and 844specific rules when hacking on GNU Classpath java source code however. 845The following lists how code is formatted (and some other code 846conventions): 847 848 849@itemize @bullet 850 851@item 852Java source files in GNU Classpath are encoded using UTF-8. However, 853ordinarily it is considered best practice to use the ASCII subset of 854UTF-8 and write non-ASCII characters using \u escapes. 855 856@item 857If possible, generate specific imports (expand) over java.io.* type 858imports. Order by gnu, java, javax, org. There must be one blank line 859between each group. The imports themselves are ordered alphabetically by 860package name. Classes and interfaces occur before sub-packages. The 861classes/interfaces are then also sorted alphabetical. Note that uppercase 862characters occur before lowercase characters. 863 864@example 865import gnu.java.awt.EmbeddedWindow; 866 867import java.io.IOException; 868import java.io.InputStream; 869 870import javax.swing.JFrame; 871@end example 872 873@item 874Blank line after package statement, last import statement, classes, 875interfaces, methods. 876 877@item 878Opening/closing brace for class and method is at the same level of 879indent as the declaration. All other braces are indented and content 880between braces indented again. 881 882@item 883Since method definitions don't start in column zero anyway (since they 884are always inside a class definition), the rational for easy grepping 885for ``^method_def'' is mostly gone already. Since it is customary for 886almost everybody who writes java source code to put modifiers, return 887value and method name on the same line, we do too. 888 889@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. 890 891@item 892Implements and extends on separate lines, throws too. Indent extends, 893implements, throws. Apply deep indentation for method arguments. 894 895@c fixme Needs example. 896 897@item 898Don't add a space between a method or constructor call/definition and 899the open-bracket. This is because often the return value is an object on 900which you want to apply another method or from which you want to access 901a field. 902 903Don't write: 904 905@example 906 getToolkit ().createWindow (this); 907@end example 908 909But write: 910@example 911 getToolkit().createWindow(this); 912@end example 913 914@item 915The GNU Coding Standard it gives examples for almost every construct 916(if, switch, do, while, etc.). One missing is the try-catch construct 917which should be formatted as: 918 919@example 920 try 921 @{ 922 // 923 @} 924 catch (...) 925 @{ 926 // 927 @} 928@end example 929 930@item 931Wrap lines at 80 characters after assignments and before operators. 932Wrap always before extends, implements, throws, and labels. 933 934@item 935Don't put multiple class definitions in the same file, except for 936inner classes. File names (plus .java) and class names should be the 937same. 938 939@item 940Don't catch a @code{NullPointerException} as an alternative to simply 941checking for @code{null}. It is clearer and usually more efficient 942to simply write an explicit check. 943 944For instance, don't write: 945 946@example 947try 948 @{ 949 return foo.doit(); 950 @} 951catch (NullPointerException _) 952 @{ 953 return 7; 954 @} 955@end example 956 957If your intent above is to check whether @samp{foo} is @code{null}, 958instead write: 959 960@example 961if (foo == null) 962 return 7; 963else 964 return foo.doit(); 965@end example 966 967@item 968Don't use redundant modifiers or other redundant constructs. Here is 969some sample code that shows various redundant items in comments: 970 971@example 972/*import java.lang.Integer;*/ 973/*abstract*/ interface I @{ 974 /*public abstract*/ void m(); 975 /*public static final*/ int i = 1; 976 /*public static*/ class Inner @{@} 977@} 978final class C /*extends Object*/ @{ 979 /*final*/ void m() @{@} 980@} 981@end example 982 983Note that Jikes will generate warnings for redundant modifiers if you 984use @code{+Predundant-modifiers} on the command line. 985 986@item 987Modifiers should be listed in the standard order recommended by the 988JLS@. Jikes will warn for this when given @code{+Pmodifier-order}. 989 990@item 991Because the output of different compilers differs, we have 992standardized on explicitly specifying @code{serialVersionUID} in 993@code{Serializable} classes in Classpath. This field should be 994declared as @code{private static final}. Note that a class may be 995@code{Serializable} without being explicitly marked as such, due to 996inheritance. For instance, all subclasses of @code{Throwable} need to 997have @code{serialVersionUID} declared. 998@c fixme index 999@c fixme link to the discussion 1000 1001@item 1002Don't declare unchecked exceptions in the @code{throws} clause of a 1003method. However, if throwing an unchecked exception is part of the 1004method's API, you should mention it in the Javadoc. There is one 1005important exception to this rule, which is that a stub method should 1006be marked as throwing @code{gnu.classpath.NotImplementedException}. 1007This will let our API comparison tools note that the method is not 1008fully implemented. 1009 1010@item 1011When overriding @code{Object.equals}, remember that @code{instanceof} 1012filters out @code{null}, so an explicit check is not needed. 1013 1014@item 1015When catching an exception and rethrowing a new exception you should 1016``chain'' the Throwables. Don't just add the String representation of 1017the caught exception. 1018 1019@example 1020 try 1021 @{ 1022 // Some code that can throw 1023 @} 1024 catch (IOException ioe) 1025 @{ 1026 throw (SQLException) new SQLException("Database corrupt").setCause(ioe); 1027 @} 1028@end example 1029 1030@item 1031Avoid the use of reserved words for identifiers. This is obvious with those 1032such as @code{if} and @code{while} which have always been part of the Java 1033programming language, but you should be careful about accidentally using 1034words which have been added in later versions. Notable examples are 1035@code{assert} (added in 1.4) and @code{enum} (added in 1.5). Jikes will warn 1036of the use of the word @code{enum}, but, as it doesn't yet support the 1.5 1037version of the language, it will still allow this usage through. A 1038compiler which supports 1.5 (e.g.@: the Eclipse compiler, ecj) will simply 1039fail to compile the offending source code. 1040 1041@c fixme Describe Anonymous classes (example). 1042@c fixme Descibe Naming conventions when different from GNU Coding Standards. 1043@c fixme Describee API doc javadoc tags used. 1044 1045@end itemize 1046 1047Some things are the same as in the normal GNU Coding Standards: 1048 1049@itemize @bullet 1050 1051@item 1052Unnecessary braces can be removed, one line after an if, for, while as 1053examples. 1054 1055@item 1056Space around operators (assignment, logical, relational, bitwise, 1057mathematical, shift). 1058 1059@item 1060Blank line before single-line comments, multi-line comments, javadoc 1061comments. 1062 1063@item 1064If more than 2 blank lines, trim to 2. 1065 1066@item 1067Don't keep commented out code. Just remove it or add a real comment 1068describing what it used to do and why it is changed to the current 1069implementation. 1070@end itemize 1071 1072 1073@node Hacking Code, Programming Goals, Programming Standards, Top 1074@comment node-name, next, previous, up 1075@chapter Working on the code, Working with others 1076 1077There are a lot of people helping out with GNU Classpath. Here are a 1078couple of practical guidelines to make working together on the code 1079smoother. 1080 1081The main thing is to always discuss what you are up to on the 1082mailinglist. Making sure that everybody knows who is working on what 1083is the most important thing to make sure we cooperate most 1084effectively. 1085 1086We maintain a 1087@uref{http://www.gnu.org/software/classpath/tasks.html,Task List} 1088which contains items that you might want to work on. 1089 1090Before starting to work on something please make sure you read this 1091complete guide. And discuss it on list to make sure your work does 1092not duplicate or interferes with work someone else is already doing. 1093Always make sure that you submit things that are your own work. And 1094that you have paperwork on file (as stated in the requirements 1095section) with the FSF authorizing the use of your additions. 1096 1097Technically the GNU Classpath project is hosted on 1098@uref{http://savannah.gnu.org/,Savannah} a central point for 1099development, distribution and maintenance of GNU Software. Here you 1100will find the 1101@uref{https://savannah.gnu.org/projects/classpath/,project page}, bug 1102reports, pending patches, links to mailing lists, news items and CVS. 1103 1104You can find instructions on getting a CVS checkout for classpath at 1105@uref{https://savannah.gnu.org/cvs/?group=classpath}. 1106 1107You don't have to get CVS commit write access to contribute, but it is 1108sometimes more convenient to be able to add your changes directly to 1109the project CVS@. Please contact the GNU Classpath savannah admins to 1110arrange CVS access if you would like to have it. 1111 1112Make sure to be subscribed to the commit-classpath mailinglist while 1113you are actively hacking on Classpath. You have to send patches (cvs 1114diff -uN) to this list before committing. 1115 1116We really want to have a pretty open check-in policy. But this means 1117that you should be extra careful if you check something in. If at all 1118in doubt or if you think that something might need extra explaining 1119since it is not completely obvious please make a little announcement 1120about the change on the mailinglist. And if you do commit something 1121without discussing it first and another GNU Classpath hackers asks for 1122extra explanation or suggests to revert a certain commit then please 1123reply to the request by explaining why something should be so or if 1124you agree to revert it. (Just reverting immediately is OK without 1125discussion, but then please don't mix it with other changes and please 1126say so on list.) 1127 1128Patches that are already approved for libgcj or also OK for Classpath. 1129(But you still have to send a patch/diff to the list.) All other 1130patches require you to think whether or not they are really OK and 1131non-controversial, or if you would like some feedback first on them 1132before committing. We might get real commit rules in the future, for 1133now use your own judgement, but be a bit conservative. 1134 1135Always contact the GNU Classpath maintainer before adding anything 1136non-trivial that you didn't write yourself and that does not come from 1137libgcj or from another known GNU Classpath or libgcj hacker. If you 1138have been assigned to commit changes on behalf of another project or 1139a company always make sure they come from people who have signed the 1140papers for the FSF and/or fall under the arrangement your company made 1141with the FSF for contributions. Mention in the ChangeLog who actually 1142wrote the patch. 1143 1144Commits for completely unrelated changes they should be committed 1145separately (especially when doing a formatting change and a logical 1146change, do them in two separate commits). But do try to do a commit of 1147as much things/files that are done at the same time which can 1148logically be seen as part of the same change/cleanup etc. 1149 1150When the change fixes an important bug or adds nice new functionality 1151please write a short entry for inclusion in the @file{NEWS} file. If it 1152changes the VM interface you must mention that in both the @file{NEWS} file 1153and the VM Integration Guide. 1154 1155All the ``rules'' are really meant to make sure that GNU Classpath 1156will be maintainable in the long run and to give all the projects that 1157are now using GNU Classpath an accurate view of the changes we make to 1158the code and to see what changed when. If you think the requirements 1159are ``unworkable'' please try it first for a couple of weeks. If you 1160still feel the same after having some more experience with the project 1161please feel free to bring up suggestions for improvements on the list. 1162But don't just ignore the rules! Other hackers depend on them being 1163followed to be the most productive they can be (given the above 1164constraints). 1165 1166@menu 1167* Branches:: 1168* Writing ChangeLogs:: 1169@end menu 1170 1171@node Branches, Writing ChangeLogs, Hacking Code, Hacking Code 1172@comment node-name, next, previous, up 1173@section Working with branches 1174 1175Sometimes it is necessary to create branch of the source for doing new 1176work that is disruptive to the other hackers, or that needs new 1177language or libraries not yet (easily) available. 1178 1179After discussing the need for a branch on the main mailinglist with 1180the other hackers explaining the need of a branch and suggestion of 1181the particular branch rules (what will be done on the branch, who will 1182work on it, will there be different commit guidelines then for the 1183mainline trunk and when is the branch estimated to be finished and 1184merged back into the trunk) every GNU Classpath hacker with commit 1185access should feel free to create a branch. There are however a couple 1186of rules that every branch should follow: 1187 1188@itemize @bullet 1189 1190@item All branches ought to be documented in the developer wiki at 1191@uref{http://developer.classpath.org/mediation/ClasspathBranches}, so 1192we can know which are live, who owns them, and when they die. 1193 1194@item Some rules can be changed on a branch. In particular the branch 1195maintainer can change the review requirements, and the requirement of 1196keeping things building, testing, etc, can also be lifted. (These 1197should be documented along with the branch name and owner if they 1198differ from the trunk.) 1199 1200@item Requirements for patch email to classpath-patches and for paperwork 1201@strong{cannot} be lifted. See @ref{Requirements}. 1202 1203@item A branch should not be seen as ``private'' or 1204``may be completely broken''. It should be as much as possible 1205something that you work on with a team (and if there is no team - yet 1206- then there is nothing as bad as having a completely broken build to 1207get others to help out). There can of course be occasional breakage, but 1208it should be planned and explained. And you can certainly have a rule 1209like ``please ask me before committing to this branch''. 1210 1211@item Merges from the trunk to a branch are at the discretion of the 1212branch maintainer. 1213 1214@item A merge from a branch to the trunk is treated like any other patch. 1215In particular, it has to go through review, it must satisfy all the 1216trunk requirements (build, regression test, documentation). 1217 1218@item There may be additional timing requirements on merging a branch to 1219the trunk depending on the release schedule, etc. For instance we may 1220not want to do a branch merge just before a release. 1221 1222@end itemize 1223 1224If any of these rules are unclear please discuss on the list first. 1225 1226@menu 1227* Writing ChangeLogs:: 1228@end menu 1229 1230@node Writing ChangeLogs, , Branches, Hacking Code 1231@comment node-name, next, previous, up 1232@section Documenting what changed when with ChangeLog entries 1233 1234To keep track of who did what when we keep an explicit ChangeLog entry 1235together with the code. This mirrors the CVS commit messages and in 1236general the ChangeLog entry is the same as the CVS commit message. 1237This provides an easy way for people getting a (snapshot) release or 1238without access to the CVS server to see what happened when. We do not 1239generate the ChangeLog file automatically from the CVS server since 1240that is not reliable. 1241 1242A good ChangeLog entry guideline can be found in the Guile Manual at 1243@uref{http://www.gnu.org/software/guile/changelogs/guile-changelogs_3.html}. 1244 1245Here are some example to explain what should or shouldn't be in a 1246ChangeLog entry (and the corresponding commit message): 1247 1248@itemize @bullet 1249 1250@item 1251The first line of a ChangeLog entry should be: 1252 1253@example 1254[date] <two spaces> [full name] <two spaces> [email-contact] 1255@end example 1256 1257The second line should be blank. All other lines should be indented 1258with one tab. 1259 1260@item 1261Just state what was changed. Why something is done as it is done in 1262the current code should be either stated in the code itself or be 1263added to one of the documentation files (like this Hacking Guide). 1264 1265So don't write: 1266 1267@example 1268 * java/awt/font/OpenType.java: Remove 'public static final' 1269 from OpenType tags, reverting the change of 2003-08-11. See 1270 Classpath discussion list of 2003-08-11. 1271@end example 1272 1273Just state: 1274 1275@example 1276 * java/awt/font/OpenType.java: Remove 'public static final' from 1277 all member fields. 1278@end example 1279 1280In this case the reason for the change was added to this guide. 1281 1282@item 1283Just as with the normal code style guide, don't make lines longer then 128480 characters. 1285 1286@item 1287Just as with comments in the code. The ChangeLog entry should be a 1288full sentence, starting with a capital and ending with a period. 1289 1290@item 1291Be precise in what changed, not the effect of the change (which should 1292be clear from the code/patch). So don't write: 1293 1294@example 1295 * java/io/ObjectOutputStream.java : Allow putFields be called more 1296 than once. 1297@end example 1298 1299But explain what changed and in which methods it was changed: 1300 1301@example 1302 * java/io/ObjectOutputStream.java (putFields): Don't call 1303 markFieldsWritten(). Only create new PutField when 1304 currentPutField is null. 1305 (writeFields): Call markFieldsWritten(). 1306@end example 1307 1308@end itemize 1309 1310The above are all just guidelines. We all appreciate the fact that writing 1311ChangeLog entries, using a coding style that is not ``your own'' and the 1312CVS, patch and diff tools do take some time to getting used to. So don't 1313feel like you have to do it perfect right away or that contributions 1314aren't welcome if they aren't ``perfect''. We all learn by doing and 1315interacting with each other. 1316 1317 1318@node Programming Goals, API Compatibility, Hacking Code, Top 1319@comment node-name, next, previous, up 1320@chapter Programming Goals 1321 1322When you write code for Classpath, write with three things in mind, and 1323in the following order: portability, robustness, and efficiency. 1324 1325If efficiency breaks portability or robustness, then don't do it the 1326efficient way. If robustness breaks portability, then bye-bye robust 1327code. Of course, as a programmer you would probably like to find sneaky 1328ways to get around the issue so that your code can be all three ... the 1329following chapters will give some hints on how to do this. 1330 1331@menu 1332* Portability:: Writing Portable Software 1333* Utility Classes:: Reusing Software 1334* Robustness:: Writing Robust Software 1335* Java Efficiency:: Writing Efficient Java 1336* Native Efficiency:: Writing Efficient JNI 1337* Security:: Writing Secure Software 1338@end menu 1339 1340@node Portability, Utility Classes, Programming Goals, Programming Goals 1341@comment node-name, next, previous, up 1342@section Portability 1343 1344The portability goal for Classpath is the following: 1345 1346@enumerate 1347@item 1348native functions for each platform that work across all VMs on that 1349platform 1350@item 1351a single classfile set that work across all VMs on all platforms that 1352support the native functions. 1353@end enumerate 1354 1355For almost all of Classpath, this is a very feasible goal, using a 1356combination of JNI and native interfaces. This is what you should shoot 1357for. For those few places that require knowledge of the Virtual Machine 1358beyond that provided by the Java standards, the VM Interface was designed. 1359Read the Virtual Machine Integration Guide for more information. 1360 1361Right now the only supported platform is Linux. This will change as that 1362version stabilizes and we begin the effort to port to many other 1363platforms. Jikes RVM runs Classpath on AIX, and generally the Jikes 1364RVM team fixes Classpath to work on that platform. 1365 1366@node Utility Classes, Robustness, Portability, Programming Goals 1367@comment node-name, next, previous, up 1368@section Utility Classes 1369 1370At the moment, we are not very good at reuse of the JNI code. There 1371have been some attempts, called @dfn{libclasspath}, to 1372create generally useful utility classes. The utility classes are in 1373the directory @file{native/jni/classpath} and they are mostly declared 1374in @file{native/jni/classpath/jcl.h}. These utility classes are 1375currently only discussed in @ref{Robustness} and in @ref{Native 1376Efficiency}. 1377 1378There are more utility classes available that could be factored out if 1379a volunteer wants something nice to hack on. The error reporting and 1380exception throwing functions and macros in 1381@file{native/jni/gtk-peer/gthread-jni.c} might be good 1382candidates for reuse. There are also some generally useful utility 1383functions in @file{gnu_java_awt_peer_gtk_GtkMainThread.c} that could 1384be split out and put into libclasspath. 1385 1386@node Robustness, Java Efficiency, Utility Classes, Programming Goals 1387@comment node-name, next, previous, up 1388@section Robustness 1389 1390Native code is very easy to make non-robust. (That's one reason Java is 1391so much better!) Here are a few hints to make your native code more 1392robust. 1393 1394Always check return values for standard functions. It's sometimes easy 1395to forget to check that malloc() return for an error. Don't make that 1396mistake. (In fact, use JCL_malloc() in the jcl library instead--it will 1397check the return value and throw an exception if necessary.) 1398 1399Always check the return values of JNI functions, or call 1400@code{ExceptionOccurred} to check whether an error occurred. You must 1401do this after @emph{every} JNI call. JNI does not work well when an 1402exception has been raised, and can have unpredictable behavior. 1403 1404Throw exceptions using @code{JCL_ThrowException}. This guarantees that if 1405something is seriously wrong, the exception text will at least get out 1406somewhere (even if it is stderr). 1407 1408Check for null values of @code{jclass}es before you send them to JNI functions. 1409JNI does not behave nicely when you pass a null class to it: it 1410terminates Java with a "JNI Panic." 1411 1412In general, try to use functions in @file{native/jni/classpath/jcl.h}. They 1413check exceptions and return values and throw appropriate exceptions. 1414 1415@node Java Efficiency, Native Efficiency, Robustness, Programming Goals 1416@comment node-name, next, previous, up 1417@section Java Efficiency 1418 1419For methods which explicitly throw a @code{NullPointerException} when an 1420argument is passed which is null, per a Sun specification, do not write 1421code like: 1422 1423@example 1424int 1425strlen (String foo) throws NullPointerException 1426@{ 1427 if (foo == null) 1428 throw new NullPointerException ("foo is null"); 1429 return foo.length (); 1430@} 1431@end example 1432 1433Instead, the code should be written as: 1434 1435@example 1436int 1437strlen (String foo) throws NullPointerException 1438@{ 1439 return foo.length (); 1440@} 1441@end example 1442 1443Explicitly comparing foo to null is unnecessary, as the virtual machine 1444will throw a NullPointerException when length() is invoked. Classpath 1445is designed to be as fast as possible -- every optimization, no matter 1446how small, is important. 1447 1448@node Native Efficiency, Security, Java Efficiency, Programming Goals 1449@comment node-name, next, previous, up 1450@section Native Efficiency 1451 1452You might think that using native methods all over the place would give 1453our implementation of Java speed, speed, blinding speed. You'd be 1454thinking wrong. Would you believe me if I told you that an empty 1455@emph{interpreted} Java method is typically about three and a half times 1456@emph{faster} than the equivalent native method? 1457 1458Bottom line: JNI is overhead incarnate. In Sun's implementation, even 1459the JNI functions you use once you get into Java are slow. 1460 1461A final problem is efficiency of native code when it comes to things 1462like method calls, fields, finding classes, etc. Generally you should 1463cache things like that in static C variables if you're going to use them 1464over and over again. GetMethodID(), GetFieldID(), and FindClass() are 1465@emph{slow}. Classpath provides utility libraries for caching methodIDs 1466and fieldIDs in @file{native/jni/classpath/jnilink.h}. Other native data can 1467be cached between method calls using functions found in 1468@file{native/jni/classpath/native_state.h}. 1469 1470Here are a few tips on writing native code efficiently: 1471 1472Make as few native method calls as possible. Note that this is not the 1473same thing as doing less in native method calls; it just means that, if 1474given the choice between calling two native methods and writing a single 1475native method that does the job of both, it will usually be better to 1476write the single native method. You can even call the other two native 1477methods directly from your native code and not incur the overhead of a 1478method call from Java to C. 1479 1480Cache @code{jmethodID}s and @code{jfieldID}s wherever you can. String 1481lookups are 1482expensive. The best way to do this is to use the 1483@file{native/jni/classpath/jnilink.h} 1484library. It will ensure that @code{jmethodID}s are always valid, even if the 1485class is unloaded at some point. In 1.1, jnilink simply caches a 1486@code{NewGlobalRef()} to the method's underlying class; however, when 1.2 comes 1487along, it will use a weak reference to allow the class to be unloaded 1488and then re-resolve the @code{jmethodID} the next time it is used. 1489 1490Cache classes that you need to access often. jnilink will help with 1491this as well. The issue here is the same as the methodID and fieldID 1492issue--how to make certain the class reference remains valid. 1493 1494If you need to associate native C data with your class, use Paul 1495Fisher's native_state library (NSA). It will allow you to get and set 1496state fairly efficiently. Japhar now supports this library, making 1497native state get and set calls as fast as accessing a C variable 1498directly. 1499 1500If you are using native libraries defined outside of Classpath, then 1501these should be wrapped by a Classpath function instead and defined 1502within a library of their own. This makes porting Classpath's native 1503libraries to new platforms easier in the long run. It would be nice 1504to be able to use Mozilla's NSPR or Apache's APR, as these libraries 1505are already ported to numerous systems and provide all the necessary 1506system functions as well. 1507 1508@node Security, , Native Efficiency, Programming Goals 1509@comment node-name, next, previous, up 1510@section Security 1511 1512Security is such a huge topic it probably deserves its own chapter. 1513Most of the current code needs to be audited for security to ensure 1514all of the proper security checks are in place within the Java 1515platform, but also to verify that native code is reasonably secure and 1516avoids common pitfalls, buffer overflows, etc. A good source for 1517information on secure programming is the excellent HOWTO by David 1518Wheeler, 1519@uref{http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/index.html,Secure 1520Programming for Linux and Unix HOWTO}. 1521 1522@node API Compatibility, Specification Sources, Programming Goals, Top 1523@comment node-name, next, previous, up 1524@chapter API Compatibility 1525 1526@menu 1527* Serialization:: Serialization 1528* Deprecated Methods:: Deprecated methods 1529@end menu 1530 1531@node Serialization, Deprecated Methods, API Compatibility, API Compatibility 1532@comment node-name, next, previous, up 1533@section Serialization 1534 1535Sun has produced documentation concerning much of the information 1536needed to make Classpath serializable compatible with Sun 1537implementations. Part of doing this is to make sure that every class 1538that is Serializable actually defines a field named serialVersionUID 1539with a value that matches the output of serialver on Sun's 1540implementation. The reason for doing this is below. 1541 1542If a class has a field (of any accessibility) named serialVersionUID 1543of type long, that is what serialver uses. Otherwise it computes a 1544value using some sort of hash function on the names of all method 1545signatures in the .class file. The fact that different compilers 1546create different synthetic method signatures, such as access$0() if an 1547inner class needs access to a private member of an enclosing class, 1548make it impossible for two distinct compilers to reliably generate the 1549same serial #, because their .class files differ. However, once you 1550have a .class file, its serial # is unique, and the computation will 1551give the same result no matter what platform you execute on. 1552 1553Serialization compatibility can be tested using tools provided with 1554@uref{http://www.kaffe.org/~stuart/japi/,Japitools}. These 1555tools can test binary serialization compatibility and also provide 1556information about unknown serialized formats by writing these in XML 1557instead. Japitools is also the primary means of checking API 1558compatibility for GNU Classpath with Sun's Java Platform. 1559 1560@node Deprecated Methods, , Serialization, API Compatibility 1561@comment node-name, next, previous, up 1562@section Deprecated Methods 1563 1564Sun has a practice of creating ``alias'' methods, where a public or 1565protected method is deprecated in favor of a new one that has the same 1566function but a different name. Sun's reasons for doing this vary; as 1567an example, the original name may contain a spelling error or it may 1568not follow Java naming conventions. 1569 1570Unfortunately, this practice complicates class library code that calls 1571these aliased methods. Library code must still call the deprecated 1572method so that old client code that overrides it continues to work. 1573But library code must also call the new version, because new code is 1574expected to override the new method. 1575 1576The correct way to handle this (and the way Sun does it) may seem 1577counterintuitive because it means that new code is less efficient than 1578old code: the new method must call the deprecated method, and throughout 1579the library code calls to the old method must be replaced with calls to 1580the new one. 1581 1582Take the example of a newly-written container laying out a component and 1583wanting to know its preferred size. The Component class has a 1584deprecated preferredSize method and a new method, getPreferredSize. 1585Assume that the container is laying out an old component that overrides 1586preferredSize and a new component that overrides getPreferredSize. If 1587the container calls getPreferredSize and the default implementation of 1588getPreferredSize calls preferredSize, then the old component will have 1589its preferredSize method called and new code will have its 1590getPreferredSize method called. 1591 1592Even using this calling scheme, an old component may still be laid out 1593improperly if it implements a method, getPreferredSize, that has the 1594same signature as the new Component.getPreferredSize. But that is a 1595general problem -- adding new public or protected methods to a 1596widely-used class that calls those methods internally is risky, because 1597existing client code may have already declared methods with the same 1598signature. 1599 1600The solution may still seem counterintuitive -- why not have the 1601deprecated method call the new method, then have the library always call 1602the old method? One problem with that, using the preferred size example 1603again, is that new containers, which will use the non-deprecated 1604getPreferredSize, will not get the preferred size of old components. 1605 1606@node Specification Sources, Naming Conventions, API Compatibility, Top 1607@comment node-name, next, previous, up 1608@chapter Specification Sources 1609 1610There are a number of specification sources to use when working on 1611Classpath. In general, the only place you'll find your classes 1612specified is in the JavaDoc documentation or possibly in the 1613corresponding white paper. In the case of java.lang, java.io and 1614java.util, you should look at the Java Language Specification. 1615 1616Here, however, is a list of specs, in order of canonicality: 1617 1618@enumerate 1619@item 1620@uref{http://java.sun.com/docs/books/jls/clarify.html,Clarifications and Amendments to the JLS - 1.1} 1621@item 1622@uref{http://java.sun.com/docs/books/jls/html/1.1Update.html,JLS Updates 1623- 1.1} 1624@item 1625@uref{http://java.sun.com/docs/books/jls/html/index.html,The 1.0 JLS} 1626@item 1627@uref{http://java.sun.com/docs/books/vmspec/index.html,JVM spec - 1.1} 1628@item 1629@uref{http://java.sun.com/products/jdk/1.1/docs/guide/jni/spec/jniTOC.doc.html,JNI spec - 1.1} 1630@item 1631@uref{http://java.sun.com/products/jdk/1.1/docs/api/packages.html,Sun's javadoc - 1.1} 1632(since Sun's is the reference implementation, the javadoc is 1633documentation for the Java platform itself.) 1634@item 1635@uref{http://java.sun.com/products/jdk/1.2/docs/guide/jvmdi/jvmdi.html,JVMDI spec - 1.2}, 1636@uref{http://java.sun.com/products/jdk/1.2/docs/guide/jni/jni-12.html,JNI spec - 1.2} 1637(sometimes gives clues about unspecified things in 1.1; if 1638it was not specified accurately in 1.1, then use the spec 1639for 1.2; also, we are using JVMDI in this project.) 1640@item 1641@uref{http://java.sun.com/products/jdk/1.2/docs/api/frame.html,Sun's javadoc - 1.2} 1642(sometimes gives clues about unspecified things in 1.1; if 1643it was not specified accurately in 1.1, then use the spec 1644for 1.2) 1645@item 1646@uref{http://developer.java.sun.com/developer/bugParade/index.html,The 1647Bug Parade}: I have obtained a ton of useful information about how 1648things do work and how they *should* work from the Bug Parade just by 1649searching for related bugs. The submitters are very careful about their 1650use of the spec. And if something is unspecified, usually you can find 1651a request for specification or a response indicating how Sun thinks it 1652should be specified here. 1653@end enumerate 1654 1655You'll notice that in this document, white papers and specification 1656papers are more canonical than the JavaDoc documentation. This is true 1657in general. 1658 1659 1660@node Naming Conventions, Character Conversions, Specification Sources, Top 1661@comment node-name, next, previous, up 1662@chapter Directory and File Naming Conventions 1663 1664The Classpath directory structure is laid out in the following manner: 1665 1666@example 1667classpath 1668 | 1669 |---->java 1670 | | 1671 | |-->awt 1672 | |-->io 1673 | |-->lang 1674 | |-->util 1675 | | | 1676 | | |--->zip 1677 | | |--->jar 1678 | |-->net 1679 | |-->etc 1680 | 1681 |---->gnu 1682 | | 1683 | |-->java 1684 | | 1685 | |-->awt 1686 | |-->lang 1687 | |-->util 1688 | | | 1689 | | |-->zip 1690 | |-->etc 1691 | 1692 |---->native 1693 | 1694 |-->jni 1695 | |-->classpath 1696 | |-->gtk-peer 1697 | |-->java-io 1698 | |-->java-lang 1699 | |-->java-net 1700 | |-->java-util 1701 | |-->etc 1702 |-->cni 1703 1704@end example 1705 1706Here is a brief description of the toplevel directories and their contents. 1707 1708@table @b 1709 1710@item java 1711Contains the source code to the Java packages that make up the core 1712class library. Because this is the public interface to Java, it is 1713important that the public classes, interfaces, methods, and variables 1714are exactly the same as specified in Sun's documentation. The directory 1715structure is laid out just like the java package names. For example, 1716the class java.util.zip would be in the directory java-util. 1717 1718@item gnu/java 1719Internal classes (roughly analogous to Sun's sun.* classes) should go 1720under the @file{gnu/java} directory. Classes related to a particular public 1721Java package should go in a directory named like that package. For 1722example, classes related to java.util.zip should go under a directory 1723@file{gnu/java/util/zip}. Sub-packages under the main package name are 1724allowed. For classes spanning multiple public Java packages, pick an 1725appropriate name and see what everybody else thinks. 1726 1727@item native 1728This directory holds native code needed by the public Java packages. 1729Each package has its own subdirectory, which is the ``flattened'' name 1730of the package. For example, native method implementations for 1731java.util.zip should go in @file{native/classpath/java-util}. Classpath 1732actually includes an all Java version of the zip classes, so no native 1733code is required. 1734 1735@end table 1736 1737Each person working on a package get's his or her own ``directory 1738space'' underneath each of the toplevel directories. In addition to the 1739general guidelines above, the following standards should be followed: 1740 1741@itemize @bullet 1742 1743@item 1744Classes that need to load native code should load a library with the 1745same name as the flattened package name, with all hyphens removed. For 1746example, the native library name specified in LoadLibrary for 1747java-util would be ``javautil''. 1748 1749@item 1750Each package has its own shared library for native code (if any). 1751 1752@item 1753The main native method implementation for a given method in class should 1754go in a file with the same name as the class with a ``.c'' extension. 1755For example, the JNI implementation of the native methods in 1756java.net.InetAddress would go in @file{native/jni/java-net/InetAddress.c}. 1757``Internal'' native functions called from the main native method can 1758reside in files of any name. 1759@end itemize 1760 1761@node Character Conversions, Localization, Naming Conventions, Top 1762@comment node-name, next, previous, up 1763@chapter Character Conversions 1764 1765Java uses the Unicode character encoding system internally. This is a 1766sixteen bit (two byte) collection of characters encompassing most of the 1767world's written languages. However, Java programs must often deal with 1768outside interfaces that are byte (eight bit) oriented. For example, a 1769Unix file, a stream of data from a network socket, etc. Beginning with 1770Java 1.1, the @code{Reader} and @code{Writer} classes provide functionality 1771for dealing with character oriented streams. The classes 1772@code{InputStreamReader} and @code{OutputStreamWriter} bridge the gap 1773between byte streams and character streams by converting bytes to 1774Unicode characters and vice versa. 1775 1776In Classpath, @code{InputStreamReader} and @code{OutputStreamWriter} 1777rely on an internal class called @code{gnu.java.io.EncodingManager} to load 1778translators that perform the actual conversion. There are two types of 1779converters, encoders and decoders. Encoders are subclasses of 1780@code{gnu.java.io.encoder.Encoder}. This type of converter takes a Java 1781(Unicode) character stream or buffer and converts it to bytes using 1782a specified encoding scheme. Decoders are a subclass of 1783@code{gnu.java.io.decoder.Decoder}. This type of converter takes a 1784byte stream or buffer and converts it to Unicode characters. The 1785@code{Encoder} and @code{Decoder} classes are subclasses of 1786@code{Writer} and @code{Reader} respectively, and so can be used in 1787contexts that require character streams, but the Classpath implementation 1788currently does not make use of them in this fashion. 1789 1790The @code{EncodingManager} class searches for requested encoders and 1791decoders by name. Since encoders and decoders are separate in Classpath, 1792it is possible to have a decoder without an encoder for a particular 1793encoding scheme, or vice versa. @code{EncodingManager} searches the 1794package path specified by the @code{file.encoding.pkg} property. The 1795name of the encoder or decoder is appended to the search path to 1796produce the required class name. Note that @code{EncodingManager} knows 1797about the default system encoding scheme, which it retrieves from the 1798system property @code{file.encoding}, and it will return the proper 1799translator for the default encoding if no scheme is specified. Also, the 1800Classpath standard translator library, which is the @code{gnu.java.io} package, 1801is automatically appended to the end of the path. 1802 1803For efficiency, @code{EncodingManager} maintains a cache of translators 1804that it has loaded. This eliminates the need to search for a commonly 1805used translator each time it is requested. 1806 1807Finally, @code{EncodingManager} supports aliasing of encoding scheme names. 1808For example, the ISO Latin-1 encoding scheme can be referred to as 1809''8859_1'' or ''ISO-8859-1''. @code{EncodingManager} searches for 1810aliases by looking for the existence of a system property called 1811@code{gnu.java.io.encoding_scheme_alias.<encoding name>}. If such a 1812property exists. The value of that property is assumed to be the 1813canonical name of the encoding scheme, and a translator with that name is 1814looked up instead of one with the original name. 1815 1816Here is an example of how @code{EncodingManager} works. A class requests 1817a decoder for the ''UTF-8'' encoding scheme by calling 1818@code{EncodingManager.getDecoder("UTF-8")}. First, an alias is searched 1819for by looking for the system property 1820@code{gnu.java.io.encoding_scheme_alias.UTF-8}. In our example, this 1821property exists and has the value ''UTF8''. That is the actual 1822decoder that will be searched for. Next, @code{EncodingManager} looks 1823in its cache for this translator. Assuming it does not find it, it 1824searches the translator path, which is this example consists only of 1825the default @code{gnu.java.io}. The ''decoder'' package name is 1826appended since we are looking for a decoder. (''encoder'' would be 1827used if we were looking for an encoder). Then name name of the translator 1828is appended. So @code{EncodingManager} attempts to load a translator 1829class called @code{gnu.java.io.decoder.UTF8}. If that class is found, 1830an instance of it is returned. If it is not found, a 1831@code{UnsupportedEncodingException}. 1832 1833To write a new translator, it is only necessary to subclass 1834@code{Encoder} and/or @code{Decoder}. Only a handful of abstract 1835methods need to be implemented. In general, no methods need to be 1836overridden. The needed methods calculate the number of bytes/chars 1837that the translation will generate, convert buffers to/from bytes, 1838and read/write a requested number of characters to/from a stream. 1839 1840Many common encoding schemes use only eight bits to encode characters. 1841Writing a translator for these encodings is very easy. There are 1842abstract translator classes @code{gnu.java.io.decode.DecoderEightBitLookup} 1843and @code{gnu.java.io.encode.EncoderEightBitLookup}. These classes 1844implement all of the necessary methods. All that is necessary to 1845create a lookup table array that maps bytes to Unicode characters and 1846set the class variable @code{lookup_table} equal to it in a static 1847initializer. Also, a single constructor that takes an appropriate 1848stream as an argument must be supplied. These translators are 1849exceptionally easy to create and there are several of them supplied 1850in the Classpath distribution. 1851 1852Writing multi-byte or variable-byte encodings is more difficult, but 1853often not especially challenging. The Classpath distribution ships with 1854translators for the UTF8 encoding scheme which uses from one to three 1855bytes to encode Unicode characters. This can serve as an example of 1856how to write such a translator. 1857 1858Many more translators are needed. All major character encodings should 1859eventually be supported. 1860 1861@node Localization, , Character Conversions, Top 1862@comment node-name, next, previous, up 1863@chapter Localization 1864 1865There are many parts of the Java standard runtime library that must 1866be customized to the particular locale the program is being run in. 1867These include the parsing and display of dates, times, and numbers; 1868sorting words alphabetically; breaking sentences into words, etc. 1869In general, Classpath uses general classes for performing these tasks, 1870and customizes their behavior with configuration data specific to a 1871given locale. 1872 1873@menu 1874* String Collation:: Sorting strings in different locales 1875* Break Iteration:: Breaking up text into words, sentences, and lines 1876* Date Formatting and Parsing:: Locale specific date handling 1877* Decimal/Currency Formatting and Parsing:: Local specific number handling 1878@end menu 1879 1880In Classpath, all locale specific data is stored in a 1881@code{ListResourceBundle} class in the package @code{gnu/java/locale}. 1882The basename of the bundle is @code{LocaleInformation}. See the 1883documentation for the @code{java.util.ResourceBundle} class for details 1884on how the specific locale classes should be named. 1885 1886@code{ListResourceBundle}'s are used instead of 1887@code{PropertyResourceBundle}'s because data more complex than simple 1888strings need to be provided to configure certain Classpath components. 1889Because @code{ListResourceBundle} allows an arbitrary Java object to 1890be associated with a given configuration option, it provides the 1891needed flexibility to accomodate Classpath's needs. 1892 1893Each Java library component that can be localized requires that certain 1894configuration options be specified in the resource bundle for it. It is 1895important that each and every option be supplied for a specific 1896component or a critical runtime error will most likely result. 1897 1898As a standard, each option should be assigned a name that is a string. 1899If the value is stored in a class or instance variable, then the option 1900should name should have the name name as the variable. Also, the value 1901associated with each option should be a Java object with the same name 1902as the option name (unless a simple scalar value is used). Here is an 1903example: 1904 1905A class loads a value for the @code{format_string} variable from the 1906resource bundle in the specified locale. Here is the code in the 1907library class: 1908 1909@example 1910 ListResourceBundle lrb = 1911 ListResourceBundle.getBundle ("gnu/java/locale/LocaleInformation", locale); 1912 String format_string = lrb.getString ("format_string"); 1913@end example 1914 1915In the actual resource bundle class, here is how the configuration option 1916gets defined: 1917 1918@example 1919/** 1920 * This is the format string used for displaying values 1921 */ 1922private static final String format_string = "%s %d %i"; 1923 1924private static final Object[][] contents = 1925@{ 1926 @{ "format_string", format_string @} 1927@}; 1928@end example 1929 1930Note that each variable should be @code{private}, @code{final}, and 1931@code{static}. Each variable should also have a description of what it 1932does as a documentation comment. The @code{getContents()} method returns 1933the @code{contents} array. 1934 1935There are many functional areas of the standard class library that are 1936configured using this mechanism. A given locale does not need to support 1937each functional area. But if a functional area is supported, then all 1938of the specified entries for that area must be supplied. In order to 1939determine which functional areas are supported, there is a special key 1940that is queried by the affected class or classes. If this key exists, 1941and has a value that is a @code{Boolean} object wrappering the 1942@code{true} value, then full support is assumed. Otherwise it is 1943assumed that no support exists for this functional area. Every class 1944using resources for configuration must use this scheme and define a special 1945scheme that indicates the functional area is supported. Simply checking 1946for the resource bundle's existence is not sufficient to ensure that a 1947given functional area is supported. 1948 1949The following sections define the functional areas that use resources 1950for locale specific configuration in GNU Classpath. Please refer to the 1951documentation for the classes mentioned for details on how these values 1952are used. You may also wish to look at the source file for 1953@file{gnu/java/locale/LocaleInformation_en} as an example. 1954 1955@node String Collation, Break Iteration, Localization, Localization 1956@comment node-name, next, previous, up 1957@section String Collation 1958 1959Collation involves the sorting of strings. The Java class library provides 1960a public class called @code{java.text.RuleBasedCollator} that performs 1961sorting based on a set of sorting rules. 1962 1963@itemize @bullet 1964@item RuleBasedCollator - A @code{Boolean} wrappering @code{true} to indicate 1965that this functional area is supported. 1966@item collation_rules - The rules the specify how string collation is to 1967be performed. 1968@end itemize 1969 1970Note that some languages might be too complex for @code{RuleBasedCollator} 1971to handle. In this case an entirely new class might need to be written in 1972lieu of defining this rule string. 1973 1974@node Break Iteration, Date Formatting and Parsing, String Collation, Localization 1975@comment node-name, next, previous, up 1976@section Break Iteration 1977 1978The class @code{java.text.BreakIterator} breaks text into words, sentences, 1979and lines. It is configured with the following resource bundle entries: 1980 1981@itemize @bullet 1982@item BreakIterator - A @code{Boolean} wrappering @code{true} to indicate 1983that this functional area is supported. 1984@item word_breaks - A @code{String} array of word break character sequences. 1985@item sentence_breaks - A @code{String} array of sentence break character 1986sequences. 1987@item line_breaks - A @code{String} array of line break character sequences. 1988@end itemize 1989 1990@node Date Formatting and Parsing, Decimal/Currency Formatting and Parsing, Break Iteration, Localization 1991@comment node-name, next, previous, up 1992@section Date Formatting and Parsing 1993 1994Date formatting and parsing is handled by the 1995@code{java.text.SimpleDateFormat} class in most locales. This class is 1996configured by attaching an instance of the @code{java.text.DateFormatSymbols} 1997class. That class simply reads properties from our locale specific 1998resource bundle. The following items are required (refer to the 1999documentation of the @code{java.text.DateFormatSymbols} class for details 2000io what the actual values should be): 2001 2002@itemize @bullet 2003@item DateFormatSymbols - A @code{Boolean} wrappering @code{true} to indicate 2004that this functional area is supported. 2005@item months - A @code{String} array of month names. 2006@item shortMonths - A @code{String} array of abbreviated month names. 2007@item weekdays - A @code{String} array of weekday names. 2008@item shortWeekdays - A @code{String} array of abbreviated weekday names. 2009@item ampms - A @code{String} array containing AM/PM names. 2010@item eras - A @code{String} array containing era (i.e., BC/AD) names. 2011@item zoneStrings - An array of information about valid timezones for this 2012locale. 2013@item localPatternChars - A @code{String} defining date/time pattern symbols. 2014@item shortDateFormat - The format string for dates used by 2015@code{DateFormat.SHORT} 2016@item mediumDateFormat - The format string for dates used by 2017@code{DateFormat.MEDIUM} 2018@item longDateFormat - The format string for dates used by 2019@code{DateFormat.LONG} 2020@item fullDateFormat - The format string for dates used by 2021@code{DateFormat.FULL} 2022@item shortTimeFormat - The format string for times used by 2023@code{DateFormat.SHORT} 2024@item mediumTimeFormat - The format string for times used by 2025@code{DateFormat.MEDIUM} 2026@item longTimeFormat - The format string for times used by 2027@code{DateFormat.LONG} 2028@item fullTimeFormat - The format string for times used by 2029@code{DateFormat.FULL} 2030@end itemize 2031 2032Note that it may not be possible to use this mechanism for all locales. 2033In those cases a special purpose class may need to be written to handle 2034date/time processing. 2035 2036@node Decimal/Currency Formatting and Parsing, , Date Formatting and Parsing, Localization 2037@comment node-name, next, previous, up 2038@section Decimal/Currency Formatting and Parsing 2039 2040@code{NumberFormat} is an abstract class for formatting and parsing numbers. 2041The class @code{DecimalFormat} provides a concrete subclass that handles 2042this is in a locale independent manner. As with @code{SimpleDateFormat}, 2043this class gets information on how to format numbers from a class that 2044wrappers a collection of locale specific formatting values. In this case, 2045the class is @code{DecimalFormatSymbols}. That class reads its default 2046values for a locale from the resource bundle. The required entries are: 2047 2048@itemize @bullet 2049@item DecimalFormatSymbols - A @code{Boolean} wrappering @code{true} to 2050indicate that this functional area is supported. 2051@item currencySymbol - The string representing the local currency. 2052@item intlCurrencySymbol - The string representing the local currency in an 2053international context. 2054@item decimalSeparator - The character to use as the decimal point as a 2055@code{String}. 2056@item digit - The character used to represent digits in a format string, 2057as a @code{String}. 2058@item exponential - The char used to represent the exponent separator of a 2059number written in scientific notation, as a @code{String}. 2060@item groupingSeparator - The character used to separate groups of numbers 2061in a large number, such as the ``,'' separator for thousands in the US, as 2062a @code{String}. 2063@item infinity - The string representing infinity. 2064@item NaN - The string representing the Java not a number value. 2065@item minusSign - The character representing the negative sign, as a 2066@code{String}. 2067@item monetarySeparator - The decimal point used in currency values, as a 2068@code{String}. 2069@item patternSeparator - The character used to separate positive and 2070negative format patterns, as a @code{String}. 2071@item percent - The percent sign, as a @code{String}. 2072@item perMill - The per mille sign, as a @code{String}. 2073@item zeroDigit - The character representing the digit zero, as a @code{String}. 2074@end itemize 2075 2076Note that several of these values are an individual character. These should 2077be wrappered in a @code{String} at character position 0, not in a 2078@code{Character} object. 2079 2080@bye 2081 2082