summaryrefslogtreecommitdiff
path: root/doc/hacking.texinfo
blob: efb7aa903c034b88f551bc368b35f6503f95f4a8 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
\input texinfo @c -*-texinfo-*-

@c %**start of header
@setfilename hacking.info
@settitle GNU Classpath Hacker's Guide
@c %**end of header

@setchapternewpage off

@ifinfo
This file contains important information you will need to know if you
are going to hack on the GNU Classpath project code.

Copyright (C) 1998,1999,2000,2001,2002,2003,2004, 2005 Free Software Foundation, Inc.

@ifnotplaintext
@dircategory GNU Libraries
@direntry
* Classpath Hacking: (hacking).   GNU Classpath Hacker's Guide
@end direntry
@end ifnotplaintext
@end ifinfo

@titlepage
@title GNU Classpath Hacker's Guide
@author Aaron M. Renn
@author Paul N. Fisher
@author John Keiser
@author C. Brian Jones
@author Mark J. Wielaard

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1998,1999,2000,2001,2002,2003,2004 Free Software Foundation, Inc.
@sp 2
Permission is granted to make and distribute verbatim copies of
this document provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
document under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved by the Free Software Foundation.

@end titlepage

@ifinfo
@node Top, Introduction, (dir), (dir)
@top GNU Classpath Hacker's Guide

This document contains important information you'll want to know if
you want to hack on GNU Classpath, Essential Libraries for Java, to
help create free core class libraries for use with virtual machines
and compilers for the java programming language.
@end ifinfo

@menu
* Introduction::                An introduction to the GNU Classpath project
* Requirements::                Very important rules that must be followed
* Volunteering::                So you want to help out
* Project Goals::               Goals of the GNU Classpath project
* Needed Tools and Libraries::  A list of programs and libraries you will need
* Programming Standards::       Standards to use when writing code
* Hacking Code::                Working on code, Working with others
* Programming Goals::           What to consider when writing code
* API Compatibility::           How to handle serialization and deprecated methods
* Specification Sources::       Where to find class library specs
* Naming Conventions::          How files and directories are named
* Character Conversions::       Working on Character conversions
* Localization::                How to handle localization/internationalization

@detailmenu
 --- The Detailed Node Listing ---

Programming Standards

* Source Code Style Guide::     

Working on the code, Working with others

* Branches::                    
* Writing ChangeLogs::          

Working with branches

* Writing ChangeLogs::          

Programming Goals

* Portability::                 Writing Portable Software                
* Utility Classes::             Reusing Software
* Robustness::                  Writing Robust Software               
* Java Efficiency::             Writing Efficient Java            
* Native Efficiency::           Writing Efficient JNI          
* Security::                    Writing Secure Software

API Compatibility

* Serialization::               Serialization
* Deprecated Methods::          Deprecated methods

Localization

* String Collation::            Sorting strings in different locales
* Break Iteration::             Breaking up text into words, sentences, and lines
* Date Formatting and Parsing::  Locale specific date handling
* Decimal/Currency Formatting and Parsing::  Local specific number handling

@end detailmenu
@end menu

@node Introduction, Requirements, Top, Top
@comment node-name, next, previous, up
@chapter Introduction

The GNU Classpath Project is a dedicated to providing a 100% free,
clean room implementation of the standard core class libraries for
compilers and runtime environments for the java programming language.
It offers free software developers an alternative core library
implementation upon which larger java-like programming environments
can be build.  The GNU Classpath Project was started in the Spring of
1998 as an official Free Software Foundation project.  Most of the
volunteers working on GNU Classpath do so in their spare time, but a
couple of projects based on GNU Classpath have paid programmers to
improve the core libraries.  We appreciate everyone's efforts in the
past to improve and help the project and look forward to future
contributions by old and new members alike.

@node Requirements, Volunteering, Introduction, Top
@comment node-name, next, previous, up
@chapter Requirements

Although GNU Classpath is following an open development model where input
from developers is welcome, there are certain base requirements that
need to be met by anyone who wants to contribute code to this project.
They are mostly dictated by legal requirements and are not arbitrary
restrictions chosen by the GNU Classpath team.

You will need to adhere to the following things if you want to donate
code to the GNU Classpath project:

@itemize @bullet
@item
@strong{Never under any circumstances refer to proprietary code while
working on GNU Classpath.}  It is best if you have never looked at
alternative proprietary core library code at all.  To reduce
temptation, it would be best if you deleted the @file{src.zip} file
from your proprietary JDK distribution (note that recent versions of
GNU Classpath and the compilers and environments build on it are
mature enough to not need any proprietary implementation at all when
working on GNU Classpath, except in exceptional cases where you need
to test compatibility issues pointed out by users).  If you have
signed Sun's non-disclosure statement, then you unfortunately cannot
work on Classpath code at all.  If you have any reason to believe that
your code might be ``tainted'', please say something on the mailing
list before writing anything.  If it turns out that your code was not
developed in a clean room environment, we could be very embarrassed
someday in court.  Please don't let that happen.

@item
@strong{Never decompile proprietary class library implementations.}  While
the wording of the license in Sun's Java 2 releases has changed, it is
not acceptable, under any circumstances, for a person working on
GNU Classpath to decompile Sun's class libraries.  Allowing the use of
decompilation in the GNU Classpath project would open up a giant can of
legal worms, which we wish to avoid.

@item
Classpath is licensed under the terms of the
@uref{http://www.fsf.org/copyleft/gpl.html,GNU General Public
License}, with a special exception included to allow linking with
non-GPL licensed works as long as no other license would restrict such
linking.  To preserve freedom for all users and to maintain uniform
licensing of Classpath, we will not accept code into the main
distribution that is not licensed under these terms.  The exact
wording of the license of the current version of GNU Classpath can be
found online from the
@uref{http://www.gnu.org/software/classpath/license.html, GNU
Classpath license page} and is of course distributed with current
snapshot release from @uref{ftp://ftp.gnu.org/gnu/classpath/} or by
obtaining a copy of the current CVS tree.

@item
GNU Classpath is GNU software and this project is being officially sponsored
by the @uref{http://www.fsf.org/,Free Software Foundation}.  Because of
this, the FSF will hold copyright to all code developed as part of
GNU Classpath.  This will allow them to pursue copyright violators in court,
something an individual developer may neither have the time nor
resources to do.  Everyone contributing code to GNU Classpath will need to
sign a copyright assignment statement.  Additionally, if you are
employed as a programmer, your employer may need to sign a copyright
waiver disclaiming all interest in the software.  This may sound harsh,
but unfortunately, it is the only way to ensure that the code you write
is legally yours to distribute.
@end itemize

@node Volunteering, Project Goals, Requirements, Top
@comment node-name, next, previous, up
@chapter Volunteering to Help

The GNU Classpath project needs volunteers to help us out.  People are
needed to write unimplemented core packages, to test GNU Classpath on
free software programs written in the java programming language, to
test it on various platforms, and to port it to platforms that are
currently unsupported.

While pretty much all contributions are welcome (but see 
@pxref{Requirements}) it is always preferable that volunteers do the
whole job when volunteering for a task.  So when you volunteer to write
a Java package, please be willing to do the following:

@itemize @bullet
@item
Implement a complete drop-in replacement for the particular package.
That means implementing any ``internal'' classes.  For example, in the
java.net package, there are non-public classes for implementing sockets.
Without those classes, the public socket interface is useless.  But do
not feel obligated to completely implement all of the functionality at
once.  For example, in the java.net package, there are different types
of protocol handlers for different types of URL's.  Not all of these
need to be written at once.

@item
Please write complete and thorough API documentation comments for
every public and protected method and variable.  These should be
superior to Sun's and cover everything about the item being
documented.

@item
Please write a regression test package that can be used to run tests
of your package's functionality.  GNU Classpath uses the
@uref{http://sources.redhat.com/mauve/,Mauve project} for testing the
functionality of the core class libraries.  The Classpath Project is
fast approaching the point in time where all modifications to the
source code repository will require appropriate test cases in Mauve to
ensure correctness and prevent regressions.  
@end itemize

Writing good documentation, tests and fixing bugs should be every
developer's top priority in order to reach the elusive release of
version 1.0.

@node Project Goals, Needed Tools and Libraries, Volunteering, Top
@comment node-name, next, previous, up
@chapter Project Goals

The goal of the Classpath project is to produce a
@uref{http://www.fsf.org/philosophy/free-sw.html,free} implementation of
the standard class library for Java.  However, there are other more
specific goals as to which platforms should be supported.

Classpath is targeted to support the following operating systems:

@enumerate
@item
Free operating systems.  This includes GNU/Linux, GNU/Hurd, and the free
BSDs.

@item
Other Unix-like operating systems.

@item
Platforms which currently have no Java support at all.

@item 
Other platforms such as MS-Windows.
@end enumerate

While free operating systems are the top priority, the other priorities
can shift depending on whether or not there is a volunteer to port
Classpath to those platforms and to test releases.

Eventually we hope the Classpath will support all JVM's that provide
JNI or CNI support.  However, the top priority is free JVM's.  A small
list of Compiler/VM environments that are currently actively
incorporating GNU Classpath is below.  A more complete overview of
projects based on GNU classpath can be found online at
@uref{http://www.gnu.org/software/classpath/stories.html,the GNU
Classpath stories page}.

@enumerate
@item
@uref{http://gcc.gnu.org/java/,GCJ}
@item 
@uref{http://jamvm.sourceforge.net/,jamvm}
@item 
@uref{http://kissme.sourceforge.net/,Kissme}
@item
@uref{http://www.ibm.com/developerworks/oss/jikesrvm/,Jikes RVM}
@item
@uref{http://www.sablevm.org/,SableVM}
@item
@uref{http://www.kaffe.org/,Kaffe}
@end enumerate

As with OS platform support, this priority list could change if a
volunteer comes forward to port, maintain, and test releases for a
particular JVM.  Since gcj is part of the GNU Compiler Collective it
is one of the most important targets.  But since it doesn't currently
work out of the box with GNU Classpath it is currently not the easiest
target.  When hacking on GNU Classpath the easiest is to use
compilers and runtime environments that that work out of the box with
it, such as the jikes compiler and the runtime environments jamvm and
kissme.  But you can also work directly with targets like gcj and
kaffe that have their own copy of GNU Classpath currently.  In that
case changes have to be merged back into GNU Classpath proper though,
which is sometimes more work.  SableVM is starting to migrate from an
integrated GNU Classpath version to being usable with GNU Classpath
out of the box.


The initial target version for Classpath is the 1.1 spec.  Higher
versions can be implemented (and have been implemented, including lots
of 1.4 functionality) if desired, but please do not create classes
that depend on features in those packages unless GNU Classpath already
contains those features.  GNU Classpath has been free of any
proprietary dependencies for a long time now and we like to keep it
that way.  But finishing, polishing up, documenting, testing and
debugging current functionality is of higher priority then adding new
functionality.

@node Needed Tools and Libraries, Programming Standards, Project Goals, Top
@comment node-name, next, previous, up
@chapter Needed Tools and Libraries

If you want to hack on Classpath, you should at least download and
install the following tools.  And try to familiarize yourself with
them.  Although in most cases having these tools installed will be all
you really need to know about them.  Also note that when working on
(snapshot) releases only GCC 3.3+ (plus a free VM from the list above
and the libraries listed below) is needed.  The other tools are only
needed when working directly on the CVS version.

@itemize @bullet
@item
GCC 3.3+
@item
CVS 1.11+
@item
automake 1.7+
@item
autoconf 2.59+
@item
libtool 1.4.2+
@item
GNU m4 1.4
@item
texinfo 4.2+
@end itemize

All of these tools are available from
@uref{ftp://gnudist.gnu.org/pub/gnu/,gnudist.gnu.org} via anonymous
ftp, except CVS which is available from
@uref{http://www.cvshome.org/,www.cvshome.org}.  They are fully
documented with texinfo manuals.  Texinfo can be browsed with the
Emacs editor, or with the text editor of your choice, or transformed
into nicely printable Postscript.

Here is a brief description of the purpose of those tools.

@table @b

@item GCC
The GNU Compiler Collection. This contains a C compiler (gcc) for
compiling the native C code and a compiler for the java programming
language (gcj).  You will need at least gcj version 3.3 or higher.  If
that version is not available for your platform you can try the
@uref{http://www.jikes.org/, jikes compiler}.  We try to keep all code
compilable with both gcj and jikes at all times.

@item CVS  
A version control system that maintains a centralized Internet
repository of all code in the Classpath system.

@item automake  
This tool automatically creates Makefile.in files from Makefile.am
files.  The Makefile.in is turned into a Makefile by autoconf.  Why
use this?  Because it automatically generates every makefile target
you would ever want (clean, install, dist, etc) in full compliance
with the GNU coding standards.  It also simplifies Makefile creation
in a number of ways that cannot be described here.  Read the docs for
more info.

@item autoconf  
Automatically configures a package for the platform on which it is
being built and generates the Makefile for that platform.

@item libtool  
Handles all of the zillions of hairy platform specific options needed
to build shared libraries.

@item m4
The free GNU replacement for the standard Unix macro processor.
Proprietary m4 programs are broken and so GNU m4 is required for
autoconf to work though knowing a lot about GNU m4 is not required to
work with autoconf.

@item perl
Larry Wall's scripting language.  It is used internally by automake.

@item texinfo
Manuals and documentation (like this guide) are written in texinfo.
Texinfo is the official documentation format of the GNU project.
Texinfo uses a single source file to produce output in a number of formats,
both online and printed (dvi, info, html, xml, etc.). This means that
instead of writing different documents for online information and another
for a printed manual, you need write only one document. And when the work
is revised, you need revise only that one document.

@end table


For compiling the native AWT libraries you need to have the following
libraries installed:

@table @b
@item GTK+ 2.2.x
@uref{http://www.gtk.org/,GTK+} is a multi-platform toolkit for
creating graphical user interfaces.  It is used as the basis of the
GNU desktop project GNOME.

@item gdk-pixbuf
@uref{http://www.gnome.org/start/,gdk-pixbuf} is a GNOME library for
representing images.
@end table


GNU Classpath comes with a couple of libraries included in the source
that are not part of GNU Classpath proper, but that have been included
to provide certain needed functionality.  All these external libraries
should be clearly marked as such.  In general we try to use as much as
possible the clean upstream versions of these sources.  That way
merging in new versions will be easiest.  You should always try to get
bug fixes to these files accepted upstream first.  Currently we
include the following 'external' libraries.  Most of these sources are
included in the @file{external} directory.  That directory also
contains a @file{README} file explaining how to import newer versions.

@table @b

@item GNU jaxp
Can be found in @file{external/jaxp}.  Provides javax.xml, org.w3c and
org.xml packages.  Upstream is
@uref{http://www.gnu.org/software/classpathx/,GNU ClasspathX}.

@item fdlibm
Can be found in @file{native/fdlibm}.  Provides native implementations
of some of the Float and Double operations.  Upstream is
@uref{http://gcc.gnu.org/java/,libgcj}, they sync again with the
'real' upstream @uref{http://www.netlib.org/fdlibm/readme}.  See also
java.lang.StrictMath.

@end table


@node Programming Standards, Hacking Code, Needed Tools and Libraries, Top
@comment node-name, next, previous, up
@chapter Programming Standards

For C source code, follow the
@uref{http://www.gnu.org/prep/standards/,GNU Coding Standards}.
The standards also specify various things like the install directory
structure.  These should be followed if possible.

For Java source code, please follow the
@uref{http://www.gnu.org/prep/standards/,GNU Coding
Standards}, as much as possible.  There are a number of exceptions to
the GNU Coding Standards that we make for GNU Classpath as documented
in this guide.  We will hopefully be providing developers with a code
formatting tool that closely matches those rules soon.

For API documentation comments, please follow
@uref{http://java.sun.com/products/jdk/javadoc/writingdoccomments.html,How
to Write Doc Comments for Javadoc}.  We would like to have a set of
guidelines more tailored to GNU Classpath as part of this document.

@menu
* Source Code Style Guide::     
@end menu

@node Source Code Style Guide,  , Programming Standards, Programming Standards
@comment node-name, next, previous, up
@section Java source coding style

Here is a list of some specific rules used when hacking on GNU
Classpath java source code. We try to follow the standard
@uref{http://www.gnu.org/prep/standards/,GNU Coding Standards}
for that. There are lots of tools that can automatically generate it
(although most tools assume C source, not java source code) and it
seems as good a standard as any. There are a couple of exceptions and
specific rules when hacking on GNU Classpath java source code however.
The following lists how code is formatted (and some other code
conventions):


@itemize @bullet

@item
Java source files in GNU Classpath are encoded using UTF-8.  However,
ordinarily it is considered best practice to use the ASCII subset of
UTF-8 and write non-ASCII characters using \u escapes.

@item
If possible, generate specific imports (expand) over java.io.* type
imports. Order by gnu, java, javax, org. There must be one blank line
between each group. The imports themselves are ordered alphabetically by
package name. Classes and interfaces occur before sub-packages. The
classes/interfaces are then also sorted alphabetical. Note that uppercase
characters occur before lowercase characters.

@example
import gnu.java.awt.EmbeddedWindow;

import java.io.IOException;
import java.io.InputStream;

import javax.swing.JFrame;
@end example

@item
Blank line after package statement, last import statement, classes,
interfaces, methods.

@item
Opening/closing brace for class and method is at the same level of
indent as the declaration.  All other braces are indented and content
between braces indented again.

@item
Since method definitions don't start in column zero anyway (since they
are always inside a class definition), the rational for easy grepping
for ``^method_def'' is mostly gone already. Since it is customary for
almost everybody who writes java source code to put modifiers, return
value and method name on the same line, we do too.

@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.

@item
Implements and extends on separate lines, throws too.  Indent extends,
implements, throws.  Apply deep indentation for method arguments.

@c fixme Needs example.

@item
Don't add a space between a method or constructor call/definition and
the open-bracket. This is because often the return value is an object on
which you want to apply another method or from which you want to access
a field.
        
Don't write:

@example
  getToolkit ().createWindow (this);
@end example

But write:
@example
  getToolkit().createWindow(this);
@end example

@item
The GNU Coding Standard it gives examples for almost every construct
(if, switch, do, while, etc.).  One missing is the try-catch construct
which should be formatted as:

@example
  try
    @{
      //
    @}
  catch (...)
    @{
      //
    @}
@end example

@item
Wrap lines at 80 characters after assignments and before operators.
Wrap always before extends, implements, throws, and labels.

@item
Don't put multiple class definitions in the same file, except for
inner classes. File names (plus .java) and class names should be the
same.

@item
Don't catch a @code{NullPointerException} as an alternative to simply
checking for @code{null}.  It is clearer and usually more efficient
to simply write an explicit check.

For instance, don't write:

@example
try
  @{
    return foo.doit();
  @}
catch (NullPointerException _)
  @{
    return 7;
  @}
@end example

If your intent above is to check whether @samp{foo} is @code{null},
instead write:

@example
if (foo == null)
  return 7;
else
  return foo.doit();
@end example

@item
Don't use redundant modifiers or other redundant constructs.  Here is
some sample code that shows various redundant items in comments:

@example
/*import java.lang.Integer;*/
/*abstract*/ interface I @{
   /*public abstract*/ void m();
   /*public static final*/ int i = 1;
   /*public static*/ class Inner @{@}
@}
final class C /*extends Object*/ @{
   /*final*/ void m() @{@}
@}
@end example

Note that Jikes will generate warnings for redundant modifiers if you
use @code{+Predundant-modifiers} on the command line.

@item
Modifiers should be listed in the standard order recommended by the
JLS.  Jikes will warn for this when given @code{+Pmodifier-order}.

@item
Because the output of different compilers differs, we have
standardized on explicitly specifying @code{serialVersionUID} in
@code{Serializable} classes in Classpath.  This field should be
declared as @code{private static final}.  Note that a class may be
@code{Serializable} without being explicitly marked as such, due to
inheritance.  For instance, all subclasses of @code{Throwable} need to
have @code{serialVersionUID} declared.
@c fixme index
@c fixme link to the discussion

@item
Don't declare unchecked exceptions in the @code{throws} clause of a
method.  However, if throwing an unchecked exception is part of the
method's API, you should mention it in the Javadoc.  There is one
important exception to this rule, which is that a stub method should
be marked as throwing @code{gnu.classpath.NotImplementedException}.
This will let our API comparison tools note that the method is not
fully implemented.

@item
When overriding @code{Object.equals}, remember that @code{instanceof}
filters out @code{null}, so an explicit check is not needed.

@item
When catching an exception and rethrowing a new exception you should
``chain'' the Throwables.  Don't just add the String representation of
the caught exception.

@example
  try
    @{
      // Some code that can throw
    @}
  catch (IOException ioe)
    @{
      throw (SQLException) new SQLException("Database corrupt").setCause(ioe);
    @}
@end example

@item
Avoid the use of reserved words for identifiers.  This is obvious with those
such as @code{if} and @code{while} which have always been part of the Java
programming language, but you should be careful about accidentally using
words which have been added in later versions.  Notable examples are
@code{assert} (added in 1.4) and @code{enum} (added in 1.5).  Jikes will warn
of the use of the word @code{enum}, but, as it doesn't yet support the 1.5
version of the language, it will still allow this usage through.  A
compiler which supports 1.5 (e.g. the Eclipse compiler, ecj) will simply
fail to compile the offending source code.

@c fixme Describe Anonymous classes (example).
@c fixme Descibe Naming conventions when different from GNU Coding Standards.
@c fixme Describee API doc javadoc tags used.

@end itemize

Some things are the same as in the normal GNU Coding Standards:

@itemize @bullet

@item
Unnecessary braces can be removed, one line after an if, for, while as
examples.

@item
Space around operators (assignment, logical, relational, bitwise,
mathematical, shift).

@item
Blank line before single-line comments, multi-line comments, javadoc
comments.

@item
If more than 2 blank lines, trim to 2.

@item
Don't keep commented out code.  Just remove it or add a real comment
describing what it used to do and why it is changed to the current
implementation.
@end itemize


@node Hacking Code, Programming Goals, Programming Standards, Top
@comment node-name, next, previous, up
@chapter Working on the code, Working with others

There are a lot of people helping out with GNU Classpath.  Here are a
couple of practical guidelines to make working together on the code
smoother.

The main thing is to always discuss what you are up to on the
mailinglist.  Making sure that everybody knows who is working on what
is the most important thing to make sure we cooperate most
effectively.

We maintain a
@uref{http://www.gnu.org/software/classpath/tasks.html,Task List}
which contains items that you might want to work on.

Before starting to work on something please make sure you read this
complete guide.  And discuss it on list to make sure your work does
not duplicate or interferes with work someone else is already doing.
Always make sure that you submit things that are your own work.  And
that you have paperwork on file (as stated in the requirements
section) with the FSF authorizing the use of your additions.

Technically the GNU Classpath project is hosted on
@uref{http://savannah.gnu.org/,Savannah} a central point for
development, distribution and maintenance of GNU Software.  Here you
will find the
@uref{https://savannah.gnu.org/projects/classpath/,project page}, bug
reports, pending patches, links to mailing lists, news items and CVS.

You can find instructions on getting a CVS checkout for classpath at
@uref{https://savannah.gnu.org/cvs/?group=classpath}.

You don't have to get CVS commit write access to contribute, but it is
sometimes more convenient to be able to add your changes directly to
the project CVS. Please contact the GNU Classpath savannah admins to
arrange CVS access if you would like to have it.

Make sure to be subscribed to the commit-classpath mailinglist while
you are actively hacking on Classpath.  You have to send patches (cvs
diff -uN) to this list before committing.

We really want to have a pretty open check-in policy.  But this means
that you should be extra careful if you check something in.  If at all
in doubt or if you think that something might need extra explaining
since it is not completely obvious please make a little announcement
about the change on the mailinglist.  And if you do commit something
without discussing it first and another GNU Classpath hackers asks for
extra explanation or suggests to revert a certain commit then please
reply to the request by explaining why something should be so or if
you agree to revert it.  (Just reverting immediately is OK without
discussion, but then please don't mix it with other changes and please
say so on list.)

Patches that are already approved for libgcj or also OK for Classpath.
(But you still have to send a patch/diff to the list.)  All other
patches require you to think whether or not they are really OK and
non-controversial, or if you would like some feedback first on them
before committing.  We might get real commit rules in the future, for
now use your own judgment, but be a bit conservative.

Always contact the GNU Classpath maintainer before adding anything
non-trivial that you didn't write yourself and that does not come from
libgcj or from another known GNU Classpath or libgcj hacker.  If you
have been assigned to commit changes on behalf of another project or
a company always make sure they come from people who have signed the
papers for the FSF and/or fall under the arrangement your company made
with the FSF for contributions.  Mention in the ChangeLog who actually
wrote the patch.

Commits for completely unrelated changes they should be committed
separately (especially when doing a formatting change and a logical
change, do them in two separate commits). But do try to do a commit of
as much things/files that are done at the same time which can
logically be seen as part of the same change/cleanup etc.

When the change fixes an important bug or adds nice new functionality
please write a short entry for inclusion in the @file{NEWS} file.  If it
changes the VM interface you must mention that in both the @file{NEWS} file
and the VM Integration Guide.

All the ``rules'' are really meant to make sure that GNU Classpath
will be maintainable in the long run and to give all the projects that
are now using GNU Classpath an accurate view of the changes we make to
the code and to see what changed when.  If you think the requirements
are ``unworkable'' please try it first for a couple of weeks.  If you
still feel the same after having some more experience with the project
please feel free to bring up suggestions for improvements on the list.
But don't just ignore the rules!  Other hackers depend on them being
followed to be the most productive they can be (given the above
constraints).

@menu
* Branches::                    
* Writing ChangeLogs::          
@end menu

@node Branches, Writing ChangeLogs, Hacking Code, Hacking Code
@comment node-name, next, previous, up
@section Working with branches

Sometimes it is necessary to create branch of the source for doing new
work that is disruptive to the other hackers, or that needs new
language or libraries not yet (easily) available.

After discussing the need for a branch on the main mailinglist with
the other hackers explaining the need of a branch and suggestion of
the particular branch rules (what will be done on the branch, who will
work on it, will there be different commit guidelines then for the
mainline trunk and when is the branch estimated to be finished and
merged back into the trunk) every GNU Classpath hacker with commit
access should feel free to create a branch. There are however a couple
of rules that every branch should follow:

@itemize @bullet

@item All branches ought to be documented in the developer wiki at
@uref{http://developer.classpath.org/mediation/ClasspathBranches}, so
we can know which are live, who owns them, and when they die.

@item Some rules can be changed on a branch.  In particular the branch
maintainer can change the review requirements, and the requirement of
keeping things building, testing, etc, can also be lifted.  (These
should be documented along with the branch name and owner if they
differ from the trunk.)

@item Requirements for patch email to classpath-patches and for paperwork
@strong{cannot} be lifted. See @ref{Requirements}.

@item A branch should not be seen as ``private'' or
``may be completely broken''. It should be as much as possible
something that you work on with a team (and if there is no team - yet
- then there is nothing as bad as having a completely broken build to
get others to help out). There can of course be occasional breakage, but
it should be planned and explained. And you can certainly have a rule
like ``please ask me before committing to this branch''.

@item Merges from the trunk to a branch are at the discretion of the
branch maintainer.

@item A merge from a branch to the trunk is treated like any other patch.
In particular, it has to go through review, it must satisfy all the
trunk requirements (build, regression test, documentation).

@item There may be additional timing requirements on merging a branch to
the trunk depending on the release schedule, etc.  For instance we may
not want to do a branch merge just before a release.

@end itemize

If any of these rules are unclear please discuss on the list first.

@menu
* Writing ChangeLogs::          
@end menu

@node Writing ChangeLogs,  , Branches, Hacking Code
@comment node-name, next, previous, up
@section Documenting what changed when with ChangeLog entries

To keep track of who did what when we keep an explicit ChangeLog entry
together with the code.  This mirrors the CVS commit messages and in
general the ChangeLog entry is the same as the CVS commit message.
This provides an easy way for people getting a (snapshot) release or
without access to the CVS server to see what happened when.  We do not
generate the ChangeLog file automatically from the CVS server since
that is not reliable.

A good ChangeLog entry guideline can be found in the Guile Manual at
@uref{http://www.gnu.org/software/guile/changelogs/guile-changelogs_3.html}.

Here are some example to explain what should or shouldn't be in a
ChangeLog entry (and the corresponding commit message):

@itemize @bullet

@item
The first line of a ChangeLog entry should be:

@example
[date] <two spaces> [full name] <two spaces> [email-contact]
@end example

The second line should be blank. All other lines should be indented
with one tab.

@item
Just state what was changed.  Why something is done as it is done in
the current code should be either stated in the code itself or be
added to one of the documentation files (like this Hacking Guide).

So don't write:

@example
        * java/awt/font/OpenType.java: Remove 'public static final'
        from OpenType tags, reverting the change of 2003-08-11.  See
        Classpath discussion list of 2003-08-11.
@end example

Just state:

@example
        * java/awt/font/OpenType.java: Remove 'public static final' from
        all member fields.
@end example

In this case the reason for the change was added to this guide.

@item
Just as with the normal code style guide, don't make lines longer then
80 characters.

@item
Just as with comments in the code. The ChangeLog entry should be a
full sentence, starting with a captital and ending with a period.

@item
Be precise in what changed, not the effect of the change (which should
be clear from the code/patch).  So don't write:

@example
 * java/io/ObjectOutputStream.java : Allow putFields be called more 
 than once.
@end example

But explain what changed and in which methods it was changed:

@example
 * java/io/ObjectOutputStream.java (putFields): Don't call
 markFieldsWritten(). Only create new PutField when
 currentPutField is null.
 (writeFields): Call markFieldsWritten().
@end example

@end itemize

The above are all just guidelines.  We all appreciate the fact that writing
ChangeLog entries, using a coding style that is not ``your own'' and the
CVS, patch and diff tools do take some time to getting used to.  So don't
feel like you have to do it perfect right away or that contributions
aren't welcome if they aren't ``perfect''.  We all learn by doing and
interacting with each other.


@node Programming Goals, API Compatibility, Hacking Code, Top
@comment node-name, next, previous, up
@chapter Programming Goals

When you write code for Classpath, write with three things in mind, and
in the following order: portability, robustness, and efficiency.

If efficiency breaks portability or robustness, then don't do it the
efficient way.  If robustness breaks portability, then bye-bye robust
code.  Of course, as a programmer you would probably like to find sneaky
ways to get around the issue so that your code can be all three ... the
following chapters will give some hints on how to do this.

@menu
* Portability::                 Writing Portable Software                
* Utility Classes::             Reusing Software
* Robustness::                  Writing Robust Software               
* Java Efficiency::             Writing Efficient Java            
* Native Efficiency::           Writing Efficient JNI          
* Security::                    Writing Secure Software
@end menu

@node Portability, Utility Classes, Programming Goals, Programming Goals
@comment node-name, next, previous, up
@section Portability

The portability goal for Classpath is the following:

@enumerate
@item
native functions for each platform that work across all VMs on that
platform
@item
a single classfile set that work across all VMs on all platforms that
support the native functions.
@end enumerate

For almost all of Classpath, this is a very feasible goal, using a
combination of JNI and native interfaces.  This is what you should shoot
for.  For those few places that require knowledge of the Virtual Machine
beyond that provided by the Java standards, the VM Interface was designed.
Read the Virtual Machine Integration Guide for more information.

Right now the only supported platform is Linux.  This will change as that
version stabilizes and we begin the effort to port to many other
platforms.  Jikes RVM runs Classpath on AIX, and generally the Jikes
RVM team fixes Classpath to work on that platform. 

@node Utility Classes, Robustness, Portability, Programming Goals
@comment  node-name,  next,  previous,  up
@section Utility Classes

At the moment, we are not very good at reuse of the JNI code.  There
have been some attempts, called @dfn{libclasspath}, to
create generally useful utility classes.  The utility classes are in
the directory @file{native/jni/classpath} and they are mostly declared
in @file{native/jni/classpath/jcl.h}.  These utility classes are
currently only discussed in @ref{Robustness} and in @ref{Native
Efficiency}.

There are more utility classes available that could be factored out if
a volunteer wants something nice to hack on.  The error reporting and
exception throwing functions and macros in
@file{native/jni/gtk-peer/gthread-jni.c} might be good
candidates for reuse.  There are also some generally useful utility
functions in @file{gnu_java_awt_peer_gtk_GtkMainThread.c} that could
be split out and put into libclasspath.

@node Robustness, Java Efficiency, Utility Classes, Programming Goals
@comment node-name, next, previous, up
@section Robustness

Native code is very easy to make non-robust.  (That's one reason Java is
so much better!)  Here are a few hints to make your native code more
robust.

Always check return values for standard functions.  It's sometimes easy
to forget to check that malloc() return for an error.  Don't make that
mistake.  (In fact, use JCL_malloc() in the jcl library instead--it will
check the return value and throw an exception if necessary.)

Always check the return values of JNI functions, or call
@code{ExceptionOccurred} to check whether an error occurred.  You must
do this after @emph{every} JNI call.  JNI does not work well when an
exception has been raised, and can have unpredictable behavior.

Throw exceptions using @code{JCL_ThrowException}.  This guarantees that if
something is seriously wrong, the exception text will at least get out
somewhere (even if it is stderr).

Check for null values of @code{jclass}es before you send them to JNI functions.
JNI does not behave nicely when you pass a null class to it: it
terminates Java with a "JNI Panic."

In general, try to use functions in @file{native/jni/classpath/jcl.h}.  They
check exceptions and return values and throw appropriate exceptions.

@node Java Efficiency, Native Efficiency, Robustness, Programming Goals
@comment node-name, next, previous, up
@section Java Efficiency

For methods which explicitly throw a @code{NullPointerException} when an
argument is passed which is null, per a Sun specification, do not write
code like:

@example
int 
strlen (String foo) throws NullPointerException
@{
  if (foo == null)
    throw new NullPointerException ("foo is null");
  return foo.length ();
@}
@end example

Instead, the code should be written as:

@example
int
strlen (String foo) throws NullPointerException
@{
  return foo.length ();
@}
@end example

Explicitly comparing foo to null is unnecessary, as the virtual machine
will throw a NullPointerException when length() is invoked.  Classpath
is designed to be as fast as possible -- every optimization, no matter
how small, is important.

@node Native Efficiency, Security, Java Efficiency, Programming Goals
@comment node-name, next, previous, up
@section Native Efficiency

You might think that using native methods all over the place would give
our implementation of Java speed, speed, blinding speed.  You'd be
thinking wrong.  Would you believe me if I told you that an empty
@emph{interpreted} Java method is typically about three and a half times
@emph{faster} than the equivalent native method?

Bottom line: JNI is overhead incarnate.  In Sun's implementation, even
the JNI functions you use once you get into Java are slow.

A final problem is efficiency of native code when it comes to things
like method calls, fields, finding classes, etc.  Generally you should
cache things like that in static C variables if you're going to use them
over and over again.  GetMethodID(), GetFieldID(), and FindClass() are
@emph{slow}.  Classpath provides utility libraries for caching methodIDs
and fieldIDs in @file{native/jni/classpath/jnilink.h}.  Other native data can
be cached between method calls using functions found in
@file{native/jni/classpath/native_state.h}.

Here are a few tips on writing native code efficiently:

Make as few native method calls as possible.  Note that this is not the
same thing as doing less in native method calls; it just means that, if
given the choice between calling two native methods and writing a single
native method that does the job of both, it will usually be better to
write the single native method.  You can even call the other two native
methods directly from your native code and not incur the overhead of a
method call from Java to C.

Cache @code{jmethodID}s and @code{jfieldID}s wherever you can.  String
lookups are 
expensive.  The best way to do this is to use the 
@file{native/jni/classpath/jnilink.h}
library.  It will ensure that @code{jmethodID}s are always valid, even if the
class is unloaded at some point.  In 1.1, jnilink simply caches a
@code{NewGlobalRef()} to the method's underlying class; however, when 1.2 comes
along, it will use a weak reference to allow the class to be unloaded
and then re-resolve the @code{jmethodID} the next time it is used.

Cache classes that you need to access often.  jnilink will help with
this as well.  The issue here is the same as the methodID and fieldID
issue--how to make certain the class reference remains valid.

If you need to associate native C data with your class, use Paul
Fisher's native_state library (NSA).  It will allow you to get and set
state fairly efficiently.  Japhar now supports this library, making
native state get and set calls as fast as accessing a C variable
directly.

If you are using native libraries defined outside of Classpath, then
these should be wrapped by a Classpath function instead and defined
within a library of their own.  This makes porting Classpath's native
libraries to new platforms easier in the long run.  It would be nice
to be able to use Mozilla's NSPR or Apache's APR, as these libraries
are already ported to numerous systems and provide all the necessary
system functions as well.

@node Security,  , Native Efficiency, Programming Goals
@comment  node-name,  next,  previous,  up
@section Security

Security is such a huge topic it probably deserves its own chapter.
Most of the current code needs to be audited for security to ensure
all of the proper security checks are in place within the Java
platform, but also to verify that native code is reasonably secure and
avoids common pitfalls, buffer overflows, etc.  A good source for
information on secure programming is the excellent HOWTO by David
Wheeler,
@uref{http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/index.html,Secure
Programming for Linux and Unix HOWTO}.

@node API Compatibility, Specification Sources, Programming Goals, Top
@comment  node-name,  next,  previous,  up
@chapter API Compatibility

@menu
* Serialization::               Serialization
* Deprecated Methods::          Deprecated methods
@end menu

@node Serialization, Deprecated Methods, API Compatibility, API Compatibility
@comment  node-name,  next,  previous,  up
@section Serialization

Sun has produced documentation concerning much of the information
needed to make Classpath serializable compatible with Sun
implementations.  Part of doing this is to make sure that every class
that is Serializable actually defines a field named serialVersionUID
with a value that matches the output of serialver on Sun's
implementation.  The reason for doing this is below.

If a class has a field (of any accessibility) named serialVersionUID
of type long, that is what serialver uses. Otherwise it computes a
value using some sort of hash function on the names of all method
signatures in the .class file.  The fact that different compilers
create different synthetic method signatures, such as access$0() if an
inner class needs access to a private member of an enclosing class,
make it impossible for two distinct compilers to reliably generate the
same serial #, because their .class files differ. However, once you
have a .class file, its serial # is unique, and the computation will
give the same result no matter what platform you execute on.

Serialization compatibility can be tested using tools provided with
@uref{http://www.kaffe.org/~stuart/japi/,Japitools}.  These
tools can test binary serialization compatibility and also provide
information about unknown serialized formats by writing these in XML
instead.  Japitools is also the primary means of checking API
compatibility for GNU Classpath with Sun's Java Platform.

@node Deprecated Methods,  , Serialization, API Compatibility
@comment  node-name,  next,  previous,  up
@section Deprecated Methods

Sun has a practice of creating ``alias'' methods, where a public or
protected method is deprecated in favor of a new one that has the same
function but a different name.  Sun's reasons for doing this vary; as
an example, the original name may contain a spelling error or it may
not follow Java naming conventions.

Unfortunately, this practice complicates class library code that calls
these aliased methods.  Library code must still call the deprecated
method so that old client code that overrides it continues to work.
But library code must also call the new version, because new code is
expected to override the new method.

The correct way to handle this (and the way Sun does it) may seem
counterintuitive because it means that new code is less efficient than
old code: the new method must call the deprecated method, and throughout
the library code calls to the old method must be replaced with calls to
the new one.

Take the example of a newly-written container laying out a component and
wanting to know its preferred size.  The Component class has a
deprecated preferredSize method and a new method, getPreferredSize. 
Assume that the container is laying out an old component that overrides
preferredSize and a new component that overrides getPreferredSize.  If
the container calls getPreferredSize and the default implementation of
getPreferredSize calls preferredSize, then the old component will have
its preferredSize method called and new code will have its
getPreferredSize method called.

Even using this calling scheme, an old component may still be laid out
improperly if it implements a method, getPreferredSize, that has the
same signature as the new Component.getPreferredSize.  But that is a
general problem -- adding new public or protected methods to a
widely-used class that calls those methods internally is risky, because
existing client code may have already declared methods with the same
signature.

The solution may still seem counterintuitive -- why not have the
deprecated method call the new method, then have the library always call
the old method?  One problem with that, using the preferred size example
again, is that new containers, which will use the non-deprecated
getPreferredSize, will not get the preferred size of old components.

@node Specification Sources, Naming Conventions, API Compatibility, Top
@comment node-name, next, previous, up
@chapter Specification Sources

There are a number of specification sources to use when working on
Classpath.  In general, the only place you'll find your classes
specified is in the JavaDoc documentation or possibly in the
corresponding white paper.  In the case of java.lang, java.io and
java.util, you should look at the Java Language Specification.

Here, however, is a list of specs, in order of canonicality:

@enumerate
@item
@uref{http://java.sun.com/docs/books/jls/clarify.html,Clarifications and Amendments to the JLS - 1.1}
@item
@uref{http://java.sun.com/docs/books/jls/html/1.1Update.html,JLS Updates
- 1.1}
@item
@uref{http://java.sun.com/docs/books/jls/html/index.html,The 1.0 JLS}
@item
@uref{http://java.sun.com/docs/books/vmspec/index.html,JVM spec - 1.1}
@item
@uref{http://java.sun.com/products/jdk/1.1/docs/guide/jni/spec/jniTOC.doc.html,JNI spec - 1.1}
@item
@uref{http://java.sun.com/products/jdk/1.1/docs/api/packages.html,Sun's javadoc - 1.1}
(since Sun's is the reference implementation, the javadoc is
documentation for the Java platform itself.)
@item
@uref{http://java.sun.com/products/jdk/1.2/docs/guide/jvmdi/jvmdi.html,JVMDI spec - 1.2},
@uref{http://java.sun.com/products/jdk/1.2/docs/guide/jni/jni-12.html,JNI spec - 1.2}
(sometimes gives clues about unspecified things in 1.1; if
it was not specified accurately in 1.1, then use the spec
for 1.2; also, we are using JVMDI in this project.)
@item
@uref{http://java.sun.com/products/jdk/1.2/docs/api/frame.html,Sun's javadoc - 1.2}
(sometimes gives clues about unspecified things in 1.1; if
it was not specified accurately in 1.1, then use the spec
for 1.2)
@item
@uref{http://developer.java.sun.com/developer/bugParade/index.html,The
Bug Parade}: I have obtained a ton of useful information about how
things do work and how they *should* work from the Bug Parade just by
searching for related bugs.  The submitters are very careful about their
use of the spec.  And if something is unspecified, usually you can find
a request for specification or a response indicating how Sun thinks it
should be specified here.
@end enumerate

You'll notice that in this document, white papers and specification
papers are more canonical than the JavaDoc documentation.  This is true
in general.


@node Naming Conventions, Character Conversions, Specification Sources, Top
@comment node-name, next, previous, up
@chapter Directory and File Naming Conventions

The Classpath directory structure is laid out in the following manner:

@example
classpath
 |
 |---->java
 |       |
 |       |-->awt
 |       |-->io
 |       |-->lang
 |       |-->util
 |       |     |
 |       |     |--->zip
 |       |     |--->jar
 |       |-->net
 |       |-->etc
 |
 |---->gnu
 |       |
 |       |-->java
 |             |
 |             |-->awt
 |             |-->lang
 |             |-->util
 |             |     |
 |             |     |-->zip
 |             |-->etc
 |
 |---->native
         |
         |-->jni
         |    |-->classpath
         |    |-->gtk-peer
         |    |-->java-io
         |    |-->java-lang
         |    |-->java-net
         |    |-->java-util
         |    |-->etc
         |-->cni
  
@end example

Here is a brief description of the toplevel directories and their contents.

@table @b

@item java
Contains the source code to the Java packages that make up the core
class library.  Because this is the public interface to Java, it is
important that the public classes, interfaces, methods, and variables
are exactly the same as specified in Sun's documentation.  The directory
structure is laid out just like the java package names.  For example,
the class java.util.zip would be in the directory java-util.

@item gnu/java
Internal classes (roughly analogous to Sun's sun.* classes) should go
under the @file{gnu/java} directory.  Classes related to a particular public
Java package should go in a directory named like that package.  For
example, classes related to java.util.zip should go under a directory
@file{gnu/java/util/zip}.  Sub-packages under the main package name are
allowed.  For classes spanning multiple public Java packages, pick an
appropriate name and see what everybody else thinks.

@item native
This directory holds native code needed by the public Java packages.
Each package has its own subdirectory, which is the ``flattened'' name
of the package.  For example, native method implementations for
java.util.zip should go in @file{native/classpath/java-util}.  Classpath
actually includes an all Java version of the zip classes, so no native
code is required.

@end table

Each person working on a package get's his or her own ``directory
space'' underneath each of the toplevel directories.  In addition to the
general guidelines above, the following standards should be followed:

@itemize @bullet

@item
Classes that need to load native code should load a library with the
same name as the flattened package name, with all hyphens removed.  For
example, the native library name specified in LoadLibrary for
java-util would be ``javautil''.

@item
Each package has its own shared library for native code (if any).

@item
The main native method implementation for a given method in class should
go in a file with the same name as the class with a ``.c'' extension.
For example, the JNI implementation of the native methods in
java.net.InetAddress would go in @file{native/jni/java-net/InetAddress.c}.
``Internal'' native functions called from the main native method can
reside in files of any name.
@end itemize

@node Character Conversions, Localization, Naming Conventions, Top
@comment node-name, next, previous, up
@chapter Character Conversions

Java uses the Unicode character encoding system internally.  This is a
sixteen bit (two byte) collection of characters encompassing most of the
world's written languages.  However, Java programs must often deal with
outside interfaces that are byte (eight bit) oriented.  For example, a
Unix file, a stream of data from a network socket, etc.  Beginning with
Java 1.1, the @code{Reader} and @code{Writer} classes provide functionality
for dealing with character oriented streams.  The classes 
@code{InputStreamReader} and @code{OutputStreamWriter} bridge the gap
between byte streams and character streams by converting bytes to 
Unicode characters and vice versa.

In Classpath, @code{InputStreamReader} and @code{OutputStreamWriter}
rely on an internal class called @code{gnu.java.io.EncodingManager} to load
translaters that perform the actual conversion.  There are two types of
converters, encoders and decoders.  Encoders are subclasses of
@code{gnu.java.io.encoder.Encoder}.  This type of converter takes a Java
(Unicode) character stream or buffer and converts it to bytes using
a specified encoding scheme.  Decoders are a subclass of 
@code{gnu.java.io.decoder.Decoder}.  This type of converter takes a 
byte stream or buffer and converts it to Unicode characters.  The
@code{Encoder} and @code{Decoder} classes are subclasses of
@code{Writer} and @code{Reader} respectively, and so can be used in
contexts that require character streams, but the Classpath implementation
currently does not make use of them in this fashion.

The @code{EncodingManager} class searches for requested encoders and
decoders by name.  Since encoders and decoders are separate in Classpath,
it is possible to have a decoder without an encoder for a particular 
encoding scheme, or vice versa.  @code{EncodingManager} searches the
package path specified by the @code{file.encoding.pkg} property.  The
name of the encoder or decoder is appended to the search path to
produce the required class name.  Note that @code{EncodingManager} knows
about the default system encoding scheme, which it retrieves from the
system property @code{file.encoding}, and it will return the proper
translator for the default encoding if no scheme is specified.  Also, the 
Classpath standard translator library, which is the @code{gnu.java.io} package, 
is automatically appended to the end of the path.

For efficiency, @code{EncodingManager} maintains a cache of translators
that it has loaded.  This eliminates the need to search for a commonly
used translator each time it is requested.

Finally, @code{EncodingManager} supports aliasing of encoding scheme names.
For example, the ISO Latin-1 encoding scheme can be referred to as
''8859_1'' or ''ISO-8859-1''.  @code{EncodingManager} searches for 
aliases by looking for the existence of a system property called
@code{gnu.java.io.encoding_scheme_alias.<encoding name>}.  If such a
property exists.  The value of that property is assumed to be the
canonical name of the encoding scheme, and a translator with that name is 
looked up instead of one with the original name.

Here is an example of how @code{EncodingManager} works.  A class requests
a decoder for the ''UTF-8'' encoding scheme by calling
@code{EncodingManager.getDecoder("UTF-8")}.  First, an alias is searched
for by looking for the system property 
@code{gnu.java.io.encoding_scheme_alias.UTF-8}.  In our example, this
property exists and has the value ''UTF8''.  That is the actual
decoder that will be searched for.  Next, @code{EncodingManager} looks
in its cache for this translator.  Assuming it does not find it, it
searches the translator path, which is this example consists only of
the default @code{gnu.java.io}.  The ''decoder'' package name is 
appended since we are looking for a decoder.  (''encoder'' would be 
used if we were looking for an encoder).  Then name name of the translator
is appended.  So @code{EncodingManager} attempts to load a translator
class called @code{gnu.java.io.decoder.UTF8}.  If that class is found,
an instance of it is returned.  If it is not found, a
@code{UnsupportedEncodingException}.

To write a new translator, it is only necessary to subclass 
@code{Encoder} and/or @code{Decoder}.  Only a handful of abstract
methods need to be implemented.  In general, no methods need to be
overridden.  The needed methods calculate the number of bytes/chars
that the translation will generate, convert buffers to/from bytes,
and read/write a requested number of characters to/from a stream.

Many common encoding schemes use only eight bits to encode characters.
Writing a translator for these encodings is very easy.  There are 
abstract translator classes @code{gnu.java.io.decode.DecoderEightBitLookup}
and @code{gnu.java.io.encode.EncoderEightBitLookup}.  These classes
implement all of the necessary methods.  All that is necessary to
create a lookup table array that maps bytes to Unicode characters and
set the class variable @code{lookup_table} equal to it in a static
initializer.  Also, a single constructor that takes an appropriate
stream as an argument must be supplied.  These translators are
exceptionally easy to create and there are several of them supplied
in the Classpath distribution.

Writing multi-byte or variable-byte encodings is more difficult, but
often not especially challenging.  The Classpath distribution ships with
translators for the UTF8 encoding scheme which uses from one to three
bytes to encode Unicode characters.  This can serve as an example of
how to write such a translator.

Many more translators are needed.  All major character encodings should
eventually be supported.

@node Localization,  , Character Conversions, Top
@comment node-name, next, previous, up
@chapter Localization

There are many parts of the Java standard runtime library that must
be customized to the particular locale the program is being run in.
These include the parsing and display of dates, times, and numbers;
sorting words alphabetically; breaking sentences into words, etc.
In general, Classpath uses general classes for performing these tasks,
and customizes their behavior with configuration data specific to a
given locale.

@menu
* String Collation::            Sorting strings in different locales
* Break Iteration::             Breaking up text into words, sentences, and lines
* Date Formatting and Parsing::  Locale specific date handling
* Decimal/Currency Formatting and Parsing::  Local specific number handling
@end menu

In Classpath, all locale specific data is stored in a 
@code{ListResourceBundle} class in the package @code{gnu/java/locale}.
The basename of the bundle is @code{LocaleInformation}.  See the
documentation for the @code{java.util.ResourceBundle} class for details
on how the specific locale classes should be named.

@code{ListResourceBundle}'s are used instead of 
@code{PropertyResourceBundle}'s because data more complex than simple
strings need to be provided to configure certain Classpath components.
Because @code{ListResourceBundle} allows an arbitrary Java object to
be associated with a given configuration option, it provides the
needed flexibility to accomodate Classpath's needs.

Each Java library component that can be localized requires that certain
configuration options be specified in the resource bundle for it.  It is
important that each and every option be supplied for a specific 
component or a critical runtime error will most likely result.

As a standard, each option should be assigned a name that is a string.
If the value is stored in a class or instance variable, then the option
should name should have the name name as the variable.  Also, the value
associated with each option should be a Java object with the same name
as the option name (unless a simple scalar value is used).  Here is an
example:

A class loads a value for the @code{format_string} variable from the
resource bundle in the specified locale.  Here is the code in the
library class:

@example
  ListResourceBundle lrb = 
    ListResourceBundle.getBundle ("gnu/java/locale/LocaleInformation", locale);
  String format_string = lrb.getString ("format_string");
@end example

In the actual resource bundle class, here is how the configuration option
gets defined:

@example
/**
  * This is the format string used for displaying values
  */
private static final String format_string = "%s %d %i";

private static final Object[][] contents =
@{
  @{ "format_string", format_string @}
@};
@end example

Note that each variable should be @code{private}, @code{final}, and
@code{static}.  Each variable should also have a description of what it
does as a documentation comment.  The @code{getContents()} method returns
the @code{contents} array.

There are many functional areas of the standard class library that are
configured using this mechanism.  A given locale does not need to support
each functional area.  But if a functional area is supported, then all
of the specified entries for that area must be supplied.  In order to
determine which functional areas are supported, there is a special key
that is queried by the affected class or classes.  If this key exists, 
and has a value that is a @code{Boolean} object wrappering the
@code{true} value, then full support is assumed.  Otherwise it is
assumed that no support exists for this functional area.  Every class
using resources for configuration must use this scheme and define a special
scheme that indicates the functional area is supported.  Simply checking
for the resource bundle's existence is not sufficient to ensure that a
given functional area is supported.

The following sections define the functional areas that use resources
for locale specific configuration in GNU Classpath.  Please refer to the 
documentation for the classes mentioned for details on how these values 
are used.  You may also wish to look at the source file for 
@file{gnu/java/locale/LocaleInformation_en} as an example.

@node String Collation, Break Iteration, Localization, Localization
@comment node-name, next, previous, up
@section String Collation

Collation involves the sorting of strings.  The Java class library provides
a public class called @code{java.text.RuleBasedCollator} that performs
sorting based on a set of sorting rules.

@itemize @bullet
@item RuleBasedCollator - A @code{Boolean} wrappering @code{true} to indicate
that this functional area is supported.
@item collation_rules - The rules the specify how string collation is to
be performed.
@end itemize

Note that some languages might be too complex for @code{RuleBasedCollator}
to handle.  In this case an entirely new class might need to be written in
lieu of defining this rule string.

@node Break Iteration, Date Formatting and Parsing, String Collation, Localization
@comment node-name, next, previous, up
@section Break Iteration

The class @code{java.text.BreakIterator} breaks text into words, sentences,
and lines.  It is configured with the following resource bundle entries:

@itemize @bullet
@item BreakIterator - A @code{Boolean} wrappering @code{true} to indicate
that this functional area is supported.
@item word_breaks - A @code{String} array of word break character sequences.
@item sentence_breaks - A @code{String} array of sentence break character
sequences.
@item line_breaks - A @code{String} array of line break character sequences.
@end itemize

@node Date Formatting and Parsing, Decimal/Currency Formatting and Parsing, Break Iteration, Localization
@comment node-name, next, previous, up
@section Date Formatting and Parsing

Date formatting and parsing is handled by the 
@code{java.text.SimpleDateFormat} class in most locales.  This class is
configured by attaching an instance of the @code{java.text.DateFormatSymbols}
class.  That class simply reads properties from our locale specific
resource bundle.  The following items are required (refer to the 
documentation of the @code{java.text.DateFormatSymbols} class for details
io what the actual values should be):

@itemize @bullet
@item DateFormatSymbols - A @code{Boolean} wrappering @code{true} to indicate
that this functional area is supported.
@item months - A @code{String} array of month names.
@item shortMonths - A @code{String} array of abbreviated month names.
@item weekdays - A @code{String} array of weekday names.
@item shortWeekdays - A @code{String} array of abbreviated weekday names.
@item ampms - A @code{String} array containing AM/PM names.
@item eras - A @code{String} array containing era (ie, BC/AD) names.
@item zoneStrings - An array of information about valid timezones for this 
locale.
@item localPatternChars - A @code{String} defining date/time pattern symbols.
@item shortDateFormat - The format string for dates used by 
@code{DateFormat.SHORT}
@item mediumDateFormat - The format string for dates used by 
@code{DateFormat.MEDIUM}
@item longDateFormat - The format string for dates used by 
@code{DateFormat.LONG}
@item fullDateFormat - The format string for dates used by 
@code{DateFormat.FULL}
@item shortTimeFormat - The format string for times used by 
@code{DateFormat.SHORT}
@item mediumTimeFormat - The format string for times used by 
@code{DateFormat.MEDIUM}
@item longTimeFormat - The format string for times used by 
@code{DateFormat.LONG}
@item fullTimeFormat - The format string for times used by 
@code{DateFormat.FULL}
@end itemize

Note that it may not be possible to use this mechanism for all locales.
In those cases a special purpose class may need to be written to handle 
date/time processing.

@node Decimal/Currency Formatting and Parsing,  , Date Formatting and Parsing, Localization
@comment node-name, next, previous, up
@section Decimal/Currency Formatting and Parsing

@code{NumberFormat} is an abstract class for formatting and parsing numbers.
The class @code{DecimalFormat} provides a concrete subclass that handles
this is in a locale independent manner.  As with @code{SimpleDateFormat},
this class gets information on how to format numbers from a class that
wrappers a collection of locale specific formatting values.  In this case,
the class is @code{DecimalFormatSymbols}.  That class reads its default
values for a locale from the resource bundle.  The required entries are:

@itemize @bullet
@item DecimalFormatSymbols - A @code{Boolean} wrappering @code{true} to 
indicate that this functional area is supported.
@item currencySymbol - The string representing the local currency.
@item intlCurrencySymbol - The string representing the local currency in an
international context.
@item decimalSeparator - The character to use as the decimal point as a
@code{String}.
@item digit - The character used to represent digits in a format string,
as a @code{String}.
@item exponential - The char used to represent the exponent separator of a 
number written in scientific notation, as a @code{String}.
@item groupingSeparator - The character used to separate groups of numbers
in a large number, such as the ``,'' separator for thousands in the US, as
a @code{String}.
@item infinity - The string representing infinity.
@item NaN - The string representing the Java not a number value.
@item minusSign - The character representing the negative sign, as a 
@code{String}.
@item monetarySeparator - The decimal point used in currency values, as a
@code{String}.
@item patternSeparator - The character used to separate positive and 
negative format patterns, as a @code{String}.
@item percent - The percent sign, as a @code{String}.
@item perMill - The per mille sign, as a @code{String}.
@item zeroDigit - The character representing the digit zero, as a @code{String}.
@end itemize

Note that several of these values are an individual character.  These should
be wrappered in a @code{String} at character position 0, not in a
@code{Character} object.

@bye