lib/classpath/doc/cp-hacking.info

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