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