summaryrefslogtreecommitdiff
path: root/doc/vmintegration.texinfo
blob: e7f85d088b5b19de26dc0347fa6a2f618093f000 (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
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
\input texinfo @c -*-texinfo-*-

@c %**start of header
@setfilename vmintegration.info
@settitle GNU Classpath VM Integration Guide
@c %**end of header

@setchapternewpage off

@ifinfo
This file contains important information you will need to know if you
are going to write an interface between GNU Classpath and a Virtual
Machine.

Copyright (C) 1998-2002, 2004, 2005, 2006 Free Software Foundation, Inc.

@ifnotplaintext
@dircategory GNU Libraries
@direntry
* VM Integration: (vmintegration).   GNU Classpath VM Integration Guide
@end direntry
@end ifnotplaintext
@end ifinfo

@titlepage
@title GNU Classpath VM Integration Guide
@author John Keiser
@author C. Brian Jones
@author Mark Wielaard

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1998-2002 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 file contains important information you will need to know if you
are going to write an interface between GNU Classpath and a Virtual
Machine.

This document is incomplete, as we are still in alpha with the interface.

@end ifinfo

@menu
* Introduction::                An introduction to the Classpath project
* Initialization::              Initializing the classes
* Classpath Hooks::             Hooks from Classpath to the VM
* VM Hooks::                    Hooks from the underlying VM to Classpath
* JNI Implementation::		Hooking the VM to jni.h
* JVMTI Implementation::        Hooking the VM to jvmti.h
* Miscellaneous VM Requirements::  
@end menu

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

The Classpath Project's ambition to be a 100% clean room implementation
of the standard Java class libraries cannot be fulfilled without some
level of integration with the Virtual Machine, the underlying machinery
that actually runs Java.

There are several VMs out there, here is a small list.

@itemize @bullet
@item @uref{http://www.hungry.com/old-hungry/products/japhar/,Japhar}
Japhar was the first VM to use GNU Classpath.  Today you can see that
sort of relationship in the source tree which denotes several Japhar
specific files as a reference implementation of those pieces.  This VM
has been primarily tested against Linux and lacks garbage collections, a
JIT, and suffers recently from slow development.

@item @uref{http://www.intel.com/research/mrl/orp/,Intel's Open Runtime Platform}
Intel surprised us not long ago with the release of this rather advanced
VM that uses GNU Classpath for a set of class libraries and works on
Linux and Windows 2000.  As of June, 2004, it does not appear that ORP
is under active development.

@item @uref{http://www.sablevm.org/,SableVM}
SableVM is a robust, extremely portable, efficient, and
specifications-compliant Java Virtual Machine that aims to be easy to
maintain and to extend. It features a state-of-the-art, efficient
interpreter engine. Its source code is very accessible and easy to
understand, and has many robustness features that have been the object
of careful design.

@item @uref{http://www.kaffe.org,Kaffe}
Kaffe is an advanced VM and together with its own class libraries
provides a Java 1.1 compatible environment.

@item @uref{http://www.mozilla.org/projects/ef,Electrical Fire}
The Electrical File VM continues to be listed as a Mozilla project
though development has been somewhat quiet.  A number of concepts from
EF were expected at one point to be rolled into Japhar, but that
development has not occurred as of yet.

@item @uref{http://latte.snu.ac.kr/,LaTTe}
This VM project so far supports only Sun UltraSparc processors using the
proprietary Solaris 2.5.1 or higher operating system.  LaTTe was derived
from Kaffe but claims a number of improvements.

@item @uref{http://gcc.gnu.org/java/,GNU Compiler for Java (GCJ)}
This is a portable, optimizing, ahead-of-time compiler for the Java
Programming Language. It can compile Java source code directly to native
machine code, Java source code to Java bytecode (class files), and Java
bytecode to native machine code. Compiled applications are linked with the
GCJ runtime, libgcj which is based on the GNU Classpath code, which provides
the core class libraries, a garbage collector, and a bytecode interpreter.
libgcj can dynamically load and interpret class files, resulting in mixed
compiled/interpreted applications.
GCJ is part of the GNU Compiler Collection (@uref{http://gcc.gnu.org/,GCC}).
On March 6 2000 the libgcj and GNU Classpath projects were officially merged
and there is active work on merging all the classes between the projects.
Licensed under GPL+exception, just as GNU Classpath is.

@item @uref{http://kissme.sourceforge.net/,Kissme}
This is a free Java Virtual Machine that is being developed on GNU/Linux
and can run console Java applications.  Kissme also provides support for
orthogonally persistent Java.
@c I don't know what ``orthogonally persistent Java'' is, and I bet
@c there are other people don't know either. -- Steve Augart, 4 June 2004

@item @uref{http://jamvm.sourceforge.net/,JamVM}
A simple, small bytecode interpreter that works out-of-the-box with
pure GNU Classpath; it is emerging as the preferred platform for
quickly testing a new build of GNU Classpath.  Licensed under the GPL.

@item @uref{http://oss.software.ibm.com/jikesrvm,Jikes RVM}
A free runtime environment for Java, written in Java.  Works
out-of-the-box with pure GNU Classpath.  Features an optimizing JIT.
Runs on the x86 and PowerPC architectures, on the AIX, Linux, and Mac
OS/X operating systems.  Licensed under the CPL (Common Public
License).  Extensively documented.  Actively developed as of June,
2004.

@end itemize

In the past integration efforts were focused mainly on Japhar with an eye
towards getting Electrical Fire to work.  Most information contained in
this document is gleaned from these efforts. Recently more work has been
done on getting gcj, orp and kissme to work out of the box with GNU Classpath
but there is much to do before that becomes a reality.


@node Initialization, Classpath Hooks, Introduction, Top
@comment node-name, next, previous, up
@chapter Initialization

The order of initialization, as far as I can tell, doesn't matter just
yet.  However, when we move to 1.2 support, it probably will matter, so
we'll have a note in here at that time.

The initialization order is currently documented in the
@file{Runtime.java} source file.

@node Classpath Hooks, VM Hooks, Initialization, Top
@comment node-name, next, previous, up
@chapter Classpath Hooks

The primary method of interaction between Classpath and the VM is via
the helper classes, which are named after the relevant core library
class, but include an additional `VM' prefix.  The library classes from
Classpath call out to these to get certain VM-specific dirty work done.
A reference copy of each VM class exists.  The majority consist of a
series of static methods, some of which are simply declared
@code{native}, and some which provide a default implementation.  VMs may
either use these as is, or create their own local variations.  When
using the default implementations, the VM is responsible for
implementing any of the code marked as @code{native} which corresponds
to functionality they wish their VM to provide.  When using their own
versions of the classes, VM implementors may choose to change the mix of
native and non-native methods from that below, so as to best suit their
implementation.

@menu
* java.lang::
* gnu.classpath::
* java.util::
* java.io::
* java.security::
* java.net::
* java.nio::
* java.nio.channels::
* gnu.java.nio::
* java.lang.reflect::
* gnu.java.lang::
* gnu.java.lang.management::
* java.lang.management::
* Classpath Callbacks::
@end menu

@node java.lang, gnu.classpath, Classpath Hooks, Classpath Hooks
@comment  node-name,  next,  previous,  up

@section @code{java.lang}

@code{java.lang} is the core Java package, being imported automatically by all
classes.  It includes basic classes as @code{Object} and @code{String}.
A VM must implement at least some parts of this package in order to
become operable.

@menu
* java.lang.VMClass::
* java.lang.VMObject::
* java.lang.VMClassLoader::
* java.lang.VMSystem::
* java.lang.VMThrowable::
* java.lang.VMCompiler::
* java.lang.VMDouble::
* java.lang.VMFloat::
* java.lang.VMProcess::
* java.lang.VMRuntime::
* java.lang.VMString::
* java.lang.VMThread::
* java.lang.VMMath::
@end menu

@node java.lang.VMClass, java.lang.VMObject ,java.lang,java.lang
@subsection @code{java.lang.VMClass}

The core class, @code{java.lang.Class}, and the corresponding VM class,
@code{java.lang.VMClass}, provide two main functions within GNU Classpath.

@enumerate
@item For basic VM operation, @code{java.lang.Class} provides the link between
the Java-based representation of a class it embodies and the VM's own
internal structure for a class.  @xref{VM Hooks}.

@item As far as the user is concerned, the main function of
@code{java.lang.Class} is as an entry point to the reflection
facilities, and so it also provides this functionality, backed by the
VM class.
@end enumerate

This VM class lists the following methods, organized by the version of the
Java specification in which they occur.  All are @code{native}, unless
otherwise specified, and pertain to reflection.  As a result, the VM only
needs to implement these methods in order to provide reflection support,
and then only to the degree required.

@itemize @bullet
@item 1.0
@itemize @bullet
@item @code{isInterface(Class)} -- This is simply a property test, and matches
the presence of an appropriate flag within the class file.
@item @code{getName(Class)} -- Returns the fully-qualified name of the class.
@item @code{getSuperclass(Class)} -- Returns a @code{Class} instance which
represents the superclass.  Again, the class file contains an element directly
relating to this.  @code{null} is returned for primitives, interfaces and
@code{Object}.
@item @code{getInterfaces(Class)} -- Same as the above, but the implemented
or extended interfaces rather than the superclass.  An empty array should
be returned, rather than @code{null}.
@item @code{getDeclaredClasses(Class,boolean)} -- Returns the internal classes
this instance declares directly.  The flag determines whether or not the
VM should filter out non-public classes.
@item @code{getDeclaredFields(Class,boolean)} -- The same for fields.
@item @code{getDeclaredMethods(Class,boolean)} -- And for methods.
@item @code{getDeclaredConstructors(Class,boolean)} -- And constructors.
@item @code{getClassLoader(Class)} -- Returns the @code{ClassLoader} instance
which is responsible for the specified class.
@item @code{forName(String, boolean, ClassLoader)} -- The VM should create a
@code{Class} instance corresponding to the named class.  As noted in
@ref{VM Hooks}, the internal content of the instance is the
responsibility of the VM.  The supplied class loader is recorded as that
which loaded the class, and the boolean specifies whether or not to
run the class initializer.
@item @code{isArray(Class)} -- Another property test, corresponding to a
class file flag.
@item @code{initialize(Class)} -- The VM should initialize the class fully,
if it has not already done so.
@item @code{loadArrayClass(String,ClassLoader)} -- This is called if
@code{forName} returns @code{null} and the string specifies an array class.
The specified array class should be loaded with the supplied class loader.
@item @code{throwException(Throwable)} -- The VM should throw the supplied
checked exception, without declaring it.
@end itemize
@item 1.1
@itemize @bullet
@item @code{isInstance(Class,Object)} -- This is a reflection-based equivalent
of the @code{instanceof} operator.
@item @code{isAssignableFrom(Class,Class)} -- Mainly a shorthand for the above,
removing the need to create an instance to test assignability.  
@item @code{isPrimitive(Class)} -- Returns true if this class is simply
a representation of one of the primitive types: @code{boolean}, @code{byte},
@code{char}, @code{short}, @code{int}, @code{long}, @code{float},
@code{double} and @code{void}.
@item @code{getComponentType(Class)} -- Produces a @code{Class} instance which
represents the type of the members of the array the class instance represents.
Classes which don't represent an array type return @code{null}.
@item @code{getModifiers(Class,boolean)} -- Returns an integer which encodes
the class' modifiers, such as @code{public}.  Again, this relates to
information stored in the class file.
@item @code{getDeclaringClass(Class)} -- Returns the class that declared
an inner or member class, or @code{null} if the instance refers to a top-level
class.
@end itemize
@item 1.5
@itemize @bullet
@item @code{isSynthetic(Class)} -- Returns true if the flags for this class
mark it as synthetic.
@item @code{isAnnotation(Class)} -- Returns true if the flags for this class
mark it as an annotation.
@item @code{isEnum(Class)} -- Returns true if the flags for this class
mark it as an enumeration.
@item @code{getSimpleName(Class)} -- Returns the simple name of the class.
A default implementation is provided, but a more efficient version may instead
be provided by the VM.
@item @code{getCanonicalName(Class)} -- Returns the canonical name of the
class.  A default implementation is provided, but a more efficient
version may instead be provided by the VM.
@item @code{getEnclosingClass(Class)} -- Returns the immediately enclosing
class (null for a top-level class).
@item @code{getEnclosingConstructor(Class)} -- Returns the constructor
which immediately encloses the supplied class.
@item @code{getEnclosingMethod(Class)} -- Returns the method
which immediately encloses the supplied class.
@item @code{getClassSignature(Class)} -- Returns the generic signature of
the class or null if there isn't one.
@item @code{isAnonymousClass(Class)} -- Returns true if the class is an
anonymous class.
@item @code{isLocalClass(Class)} -- Returns true if the class is an
local class.
@item @code{isMemberClass(Class)} -- Returns true if the class is an
member class.
@end itemize
@end itemize

@node java.lang.VMObject, java.lang.VMClassLoader, java.lang.VMClass, java.lang
@subsection @code{java.lang.VMObject}

@code{VMObject} is the bridge between the low level @code{Object}
facilities such as making a clone, getting the class of the object and
the wait/notify semantics.  This is accomplished using the following
@code{native} methods.

@itemize @bullet
@item @code{getClass(Object)} -- Returns the @code{Class} instance for the
object.  @code{Class} objects are produced by the VM, as described in
@ref{VM Hooks}.
@item @code{clone(Cloneable)} -- The VM should produce a low-level clone of the
specified object, creating a field-by-field shallow copy of the original.
The only difference between the two is that the new object should still be
@code{finalizable}, even if the original is not.
@item @code{notify(Object)} -- The VM should choose one of the threads waiting
for a lock on the specified object arbitrarily, and wake it.  If the current
thread does not currently hold the lock on the object, then an
@code{IllegalMonitorStateException} should be thrown.
@item @code{notifyAll(Object)} -- Same as the above, but all threads are
awakened.
@item @code{wait(Object,long,int)} -- The VM should set the current thread
into a waiting state, which persists until it receives a notify signal or the
specified time (in milliseconds and nanoseconds) is exceeded.  The nanoseconds
restriction may be ignored if such granularity is not available, and a
@code{IllegalMonitorStateException} should be thrown if the current thread
doesn't own the object.
@end itemize

@node java.lang.VMClassLoader, java.lang.VMSystem, java.lang.VMObject, java.lang
@subsection @code{java.lang.VMClassLoader}
@code{VMClassLoader} provides methods for defining and resolving core and
primitive classes, as well as handling resources, packages and assertions.
The class is a mixture of @code{native} methods and Java-based
implementations, with some of the latter being @emph{stubs}.

@itemize @bullet
@item Native Methods
@itemize @bullet
@item @code{defineClass(ClassLoader,String,byte[],int,int,ProtectionDomain)}
-- The VM should create a @code{Class} instance from the supplied byte array.
@item @code{resolveClass(Class)} -- Resolve references to other classes in the
supplied class.
@item @code{loadClass(name,boolean)} -- Load a class using the bootstrap
loader.
@item @code{getPrimitiveClass(char)} -- The VM should provide a @code{Class}
implementation for one of the primitive classes.  The supplied character
matches the JNI code for the primitive class e.g. `B' for byte and
`Z' for boolean.
@end itemize
@item Java Methods
@itemize @bullet
@item @code{getResource(String)} -- The default implementation calls
@code{getResources} and returns the first element in the returned enumeration,
or @code{null} if there are no elements.
@item @code{getResources(String)} -- By default, this compiles a list of
URLs via the boot class path.  Any matching files within a zip file are added,
and directories on the boot class path are automatically converted to file
URLs that refer to join the directory with the resource name (whether or not
it actually exists).
@item @code{getPackage(String)} -- Always returns null, which may be suitable
if the VM does not wish to return a @code{Package} implementation. Otherwise,
it may be necessary to make this a @code{native} method.
@item @code{getPackages()} -- As with the last, a default stub implementation
exists (returning an empty array) which may be replaced if support is
required. 
@item @code{defaultAssertionStatus()} -- A stub which can be implemented
by VMs providing assertion support.  At present, it always returns @code{true}.
@item @code{packageAssertionStatus()} -- Much the same status as the above.
The method should return a map converting package names to boolean status
values.  The stub implementation provides an empty map.
@item @code{classAssertionStatus()} -- Same as the last, but for classes.
@item @code{getSystemClassLoader()} -- The default calls @code{ClassLoader}
to create a new auxillary class loader with a system and extension class
loader.  The VM may wish to replace it if it wishes to supply its own custom
system class loader.
@end itemize
@end itemize
@node java.lang.VMSystem, java.lang.VMThrowable, java.lang.VMClassLoader, java.lang
@subsection @code{java.lang.VMSystem}
@code{VMSystem} handles the default I/O streams, provides access to the
system clock and environment variables and provides methods for
@code{System.arraycopy} and the @code{identityHashCode} of an
@code{Object}.  It consists of @code{native} methods, but the default
implementation also provides some helper methods to simplify stream
creation.  

@itemize @bullet
@item Native Methods
@itemize @bullet
@item @code{arraycopy(Object,int,Object,int,int)} -- The VM should copy
a specified number of array objects from one array to another, with 
appropriate checks for compatible typing, available elements and space.
The VM should be able to perform this more efficiently using native code
and direct memory manipulation than would have been achieved by using Java.
@item @code{identityHashCode(Object)} -- This is the hashcode for
@code{Object}, which relates to the actual location of the object in memory.
@item @code{setIn(InputStream)} -- Set the system input stream.
@item @code{setOut(PrintStream)} -- Set the system output stream.
@item @code{setErr(PrintStream)} -- Set the system error stream.
@item @code{currentTimeMillis()} -- Gets the system time in milliseconds.
@item @code{getenv(String)} -- Returns the value of the specified environment
variable.
@item @code{getenv()} -- Returns a list of `name=value' pairs which correspond
to the environment variables.
@end itemize
@item Java Methods
@itemize @bullet
@item @code{makeStandardInputStream()} -- Helps provide the functionality of
@code{System.in} by wrapping the appropriate file descriptor in a
buffered file input stream.  VMs may choose to create the stream from
the descriptor differently rather than using this method.
@item @code{makeStandardOutputStream()} -- Helps provide the functionality of
@code{System.out} by wrapping the appropriate file descriptor in a buffered
file output stream.  VMs may choose to create the stream from the descriptor
differently rather than using this method.
@item @code{makeStandardErrorStream()} -- Helps provide the functionality of
@code{System.err} by wrapping the appropriate file descriptor in a buffered
file output stream.  VMs may choose to create the stream from the descriptor
differently rather than using this method.
@end itemize
@end itemize

Classpath also provides native implementations of

@itemize @bullet
@item @code{setIn(InputStream)} 
@item @code{setOut(PrintStream)} 
@item @code{setErr(PrintStream)} 
@item @code{currentTimeMillis()} 
@item @code{getenv(String)}
@end itemize

making a VM implementation optional.

@node java.lang.VMThrowable, java.lang.VMCompiler, java.lang.VMSystem, java.lang
@subsection @code{java.lang.VMThrowable}
@code{VMThrowable} is used to hold the VM state of a throwable, created either
when a @code{Throwable} is created or the @code{fillInStackTrace()} method is
called (i.e. when the actual stack trace is needed, as a lot of exceptions are
never actually used).  The actual class has two @code{native} methods,
one (@code{fillInStackTrace()}) being a method of the class used to obtain
instances, and the other an instance method, @code{getStackTrace()}.
@itemize @bullet
@item @code{fillInStackTrace(Throwable)} -- The VM should return the current
execution state of the @code{Throwable} in the form of a @code{VMThrowable}
instance.  The VM may also return @code{null} if it does not support this
functionality.
@item @code{getStackTrace()} -- This is used to create a real
@code{StackTraceElement} array for the exception, using the state data
stored during creation of the instance.
@end itemize

@node java.lang.VMCompiler, java.lang.VMDouble, java.lang.VMThrowable, java.lang
@subsection @code{java.lang.VMCompiler}

@code{VMCompiler} provides an interface for VMs which wish to provide
JIT compilation support.  The default implementation is simply a series
of stubs. The property, @code{java.compiler}, should point to a library
containing the function @code{java_lang_Compiler_start()} if such support
is to be provided.

@itemize @bullet
@item @code{compileClass(Class)} -- Invoke the compiler to compile the specific
class, returning @code{true} if successful.
@item @code{compileClasses(String)} -- The compiler should compile the classes
matching the specified string, again returning @code{true} on success.
@item @code{command(Object)} -- The object represents a command given to the
compiler, and is specific to the compiler implementation.
@item @code{enable} -- Enable the operation of the compiler.
@item @code{disable} -- Disable compiler operation.
@end itemize

@node java.lang.VMDouble, java.lang.VMFloat, java.lang.VMCompiler, java.lang
@subsection @code{java.lang.VMDouble}

@code{VMDouble} provides native support for the conversion and parsing
of doubles.

@itemize @bullet
@item @code{doubleToLongBits(double)} -- Converts the double to the IEEE 754
bit layout, collapsing NaNs to @code{0x7ff8000000000000L}.
@item @code{doubleToRawLongBits(double)} -- Same as the above, but preserves
NaNs.
@item @code{longBitsToDouble(long)} -- This is the inverse of the last method,
preserving NaNs so that the output of one can be fed into the other without
data loss.
@item @code{toString(double,boolean)} -- Converts the double to a string,
giving a shorter value if the flag @code{isFloat} is @code{true}, indicating
that the conversion was requested by @code{java.lang.Float} rather than
@code{java.lang.Double}.
@item @code{initIDs} -- Used by JNI-based solutions to initialize the cache
of the static field IDs.  The default @code{VMDouble} implementation has a
static initializer which loads the JNI library and calls this method.
@item @code{parseDouble} -- Turn the string into a usable double value.
@end itemize

Classpath provides native implementations of all these, making VM
implementation optional.

@node java.lang.VMFloat, java.lang.VMProcess, java.lang.VMDouble, java.lang
@subsection @code{java.lang.VMFloat}

@code{VMFloat} provides native support for the conversion of floats.

@itemize @bullet
@item @code{floatToIntBits(float)} -- Converts the float to the IEEE 754
bit layout, collapsing NaNs to @code{0x7fc00000}.
@item @code{floatToRawIntBits(float)} -- Same as the above, but preserves
NaNs.
@item @code{intBitsToFloat(int)} -- This is the inverse of the last method,
preserving NaNs so that the output of one can be fed into the other without
data loss.
@end itemize

Classpath provides native implementations of all these, making VM
implementation optional.

@node java.lang.VMProcess, java.lang.VMRuntime, java.lang.VMFloat, java.lang
@subsection @code{java.lang.VMProcess}

@code{VMProcess} handles the execution of external processes.  In the
default implementation, threads are spawned and reaped by @code{ProcessThread}.
A constructor creates a new @code{VMProcess}, which extends rather than
complements @code{Process}, using an array of arguments, an array of
environment variables and a working directory.  The instance maintains
system input, output and error streams linked to the external process.
Three @code{native} methods are used, and implementations are provided
for all three by Classpath, making VM implementation optional.  These use
the POSIX functions, @code{fork()}, @code{waitpid()} and @code{kill()}.

@itemize @bullet
@item @code{nativeSpawn(String[],String[],File,boolean)} -- The VM should
create a new process which uses the specified command-line arguments,
environment variables and working directory.  Unlike the other two
methods, this method is linked to an instance, and must call
@code{setProcessInfo()} with the results before returning.  The
boolean argument maps to the @code{redirectErrorStream} property of
@code{java.lang.ProcessBuilder}.  When true, the output and error streams
are merged.
@item @code{nativeReap()} -- This is called to perform a reap of any
zombie processes, and should not block, instead returning a boolean as to
whether reaping actually took place.
@item @code{nativeKill(long)} -- The VM should terminate the specified PID.
@end itemize

@node java.lang.VMRuntime, java.lang.VMString, java.lang.VMProcess, java.lang
@subsection @code{java.lang.VMRuntime}

The @code{VMRuntime} class provides a series of native methods
which divulge information about the runtime or invoke certain
operations.  This includes retrieving the amount of available memory,
and scheduling the garbage collector.  There are two exceptions: the
@code{enableShutdownHooks} method, which allows the VM to put in its own
shutdown hooks when @code{Runtime.addShutdownHook()} is first invoked,
and @code{exec(String[],String[],File)} which spawns an external process.
These are Java-based static methods instead.  The first is simply a stub by
default, while the second simply links to the functionality of
@code{VMProcess} (and should be changed if a different @code{Process}
implementation is used).

@itemize @bullet
@item @code{availableProcessors()} -- Returns the number of processors 
available to the VM.
@item @code{freeMemory()} -- Returns the amount of memory the VM has available
on the heap for allocating.
@item @code{totalMemory()} -- Returns the size of the heap.
@item @code{maxMemory()} -- Returns the maximum memory block the VM will
attempt to allocate.  May be simply @code{Long.MAX_VALUE} (8 exabytes!)
@item @code{gc()} -- Allows users to explicitly invoke the garbage collector.
This is a suggestion to the VM, rather than a command, and the garbage
collector should run anyway @emph{without} it being invoked.
@item @code{runFinalization()} -- Like the above, but related to the
finalilzation of objects rather than the garbage collector.
@item @code{runFinalizationForExit()} -- Called immediately prior to VM
shutdown in order to finalize all objects (including `live' ones)
@item @code{traceInstructions(boolean)} -- This turns on and off the optional
VM functionality of printing a trace of executed bytecode instructions.
@item @code{traceMethodCalls(boolean)} -- This turns on and off the optional
VM functionality of printing a trace of methods called.
@item @code{runFinalizersOnExit(boolean)} -- A toggleable setting for
running the finalization process at exit.
@item @code{exit(int)} -- The VM should shutdown with the specified exit code.
@item @code{nativeLoad(String,ClassLoader)} -- Attempts to load a file,
returning an integer which is non-zero for success.  Nothing happens if the
file has already been loaded.
@item @code{mapLibraryName(String)} -- The VM should map the system-independent
library name supplied to the platform-dependent equivalent (e.g. a @code{.so}
or @code{.dll} file)
@end itemize

@node java.lang.VMString, java.lang.VMThread, java.lang.VMRuntime, java.lang
@subsection @code{java.lang.VMString}
@code{VMString} is responsible for handling interned strings.  If two strings
are equal (using the @code{equals()} method), then the results of calling
the @code{intern()} method on each of them makes them equal
(using @code{==}).  Thus, the same string object is always returned by
@code{intern} if the two strings are equal.  The default implementation
is Java-based and implements @code{intern(String)} by maintaining a
@code{WeakHashMap} which links the strings to their @code{WeakReference}.
A new mapping is created for each new string being @code{intern}ed.  
A VM may implement this differently by implementing this method,
which is @code{static} and the only one in @code{VMString}.

@node java.lang.VMThread, java.lang.VMMath, java.lang.VMString, java.lang
@subsection @code{java.lang.VMThread}

@code{VMThread} provides the link between Java's threads and the platform
threading support.  A @code{VMThread} is created via a private constructor
and linked to a @code{Thread} instance.  This occurs when the @code{Thread}
instance is started by the static @code{create(Thread,long)} method (the second
argument requests a certain stack size, usually zero).  The thread itself is
executed via the @code{run()} method, which handles any problems with the
running of the thread and its eventual death.

@code{VMThread} provides the following accessors and mutators for accessing
the thread state via @code{VMThread},

@itemize @bullet
@item @code{getName()}
@item @code{setName(String)}
@item @code{getPriority()}
@item @code{setPriotity(int)}
@item @code{isDaemon()}
@end itemize

all of which refer to the @code{Thread} instance. @code{setPriority(int)} also
calls the appropriate native method.  @code{stop(Throwable)} similarly wraps
a native method, merely adding in a check for the state of the thread.

The default implementation also provides Java-based implementations of
@code{join(long,int)}, @code{sleep(long,int)} and
@code{holdsLock(Object)}.  @code{join} and @code{sleep} simply wait for
the appropriate amount of time, with @code{join} additionally waiting
for the thread instance to become @code{null}.  @code{holdsLock} simply
checks if an object is locked by the current thread by trying to invoke
the @code{notify} method, and catching the failing exception if this is
not the case.

The remainder of the class is a series of @code{native} methods, some of
which are mandatory for VM implementation and others which provide optional
or deprecated functionality.

@itemize @bullet
@item Mandatory Instance Methods
@itemize @bullet
@item @code{start(long)} -- The VM should create the native thread and start
it running using the @code{run} method of the @code{VMThread} instance on
which this method is called.
@item @code{interrupt()} -- The VM should interrupt the running thread and
throw an appropriate exception.
@item @code{isInterrupted()} -- Checks the interrupted state of the thread.
@item @code{suspend()} -- The thread should be suspended until resumed.
@item @code{resume()} -- The thread should be resumed from its suspended state.
This pair of methods are deprecated, due to the possibility of a deadlock
occuring when a thread with locks is suspended.
@item @code{nativeSetPriority(int)} -- Called by @code{setPriority}
to allow the setting to flow down to the native thread.
@item @code{nativeStop(Throwable)} -- The VM should stop the thread abnormally
and throw the specified exception.  This is clearly deprecated, due to the
ambiguous state an abruptly-stopped thread may leave.
@item @code{getState()} -- Returns the VM's impression of the current state
of the thread.  The applicable states are supplied by the @code{State}
enumeration in @code{java.lang.Thread}.
@end itemize
@item Mandatory Class Methods
@itemize @bullet
@item @code{currentThread()} -- Return a reference to the thread currently
being executed.
@item @code{yield()} -- The VM should allow some other thread to run.
The current thread maintains its locks even though it stops executing for
the time being.
@item @code{interrupted()} -- A shortcut to obtaining the interrupted state
of the current thread.
@end itemize
@item Other Methods
@itemize @bullet
@item @code{countStackFrames()} -- Returns a count of the number of stack
frames in the thread.  This depends on the deprecated method @code{suspend()}
having returned true, and is thus deprecated as a result.
@end itemize
@end itemize

@node java.lang.VMMath,, java.lang.VMThread, java.lang
@subsection @code{java.lang.VMMath}

The @code{VMMath} class provides a series of native methods
for some of the mathematical functions present in @code{java.lang.Math}.
Classpath provides a default implementation of these which maps the
functions to those provided by @code{fdlibm}.  VM implementors are welcome
to replace this with more efficent implementations, as long as the accuracy
contract of these methods, specified in @code{java.lang.Math}, is maintained.

@itemize @bullet
@item 1.0
@itemize @bullet
@item @code{sin(double)} -- Returns the sine value for the given angle.
@item @code{cos(double)} -- Returns the cosine value for the given angle.
@item @code{tan(double)} -- Returns the tangent value for the given angle.
@item @code{asin(double)} -- Returns the arc sine value for the given angle.
@item @code{acos(double)} -- Returns the arc cosine value for the given angle.
@item @code{atan(double)} -- Returns the arc tangent value for the given angle.
@item @code{atan2(double,double)} -- Returns the arc tangent of the ratio of
the two arguments.
@item @code{exp(double)} -- Returns the exponent raised to the given power.
@item @code{log(double)} -- Returns the natural logarithm for the given value.
@item @code{sqrt(double)} -- Returns the square root of the value.
@item @code{pow(double,double)} -- Returns x to the power of y.
@item @code{IEEEremainder(double,double)} -- Returns the IEEE 754 remainder
for the two values.
@item @code{ceil(double)} -- Returns the nearest integer >= the value.
@item @code{floor(double)} -- Returns the nearest integer <= the value.
@item @code{rint(double)} -- Returns the nearest integer or the even one
if the distance between the two is equal.
@end itemize
@item 1.5
@itemize @bullet
@item @code{cbrt(double)} -- Returns the cube root of the value.
@item @code{cosh(double)} -- Returns the hyperbolic cosine value for the given
angle.
@item @code{expm1(double)} -- Returns the exponent of the value minus one.
@item @code{hypot(double,double)} -- Returns the hypotenuse corresponding to
x and y.
@item @code{log10(double)} -- Returns the base 10 logarithm of the given value.
@item @code{log1p(double)} -- Returns the natural logarithm of the value plus
one.
@item @code{sinh(double)} -- Returns the hyperbolic sine value for the given
angle.
@item @code{tanh(double)} -- Returns the hyperbolic tangent value for the given angle.
@end itemize
@end itemize

@node gnu.classpath, java.util, java.lang, Classpath Hooks
@section @code{gnu.classpath}

The @code{gnu.classpath} package provides Classpath-specific functionality,
primarily relating to the features in @code{java.lang}.  At present, this
includes the context of a class (the stack) and the system properties.

@menu
* gnu.classpath.VMStackWalker::
* gnu.classpath.VMSystemProperties::
* gnu.classpath.Unsafe::
@end menu

@node gnu.classpath.VMStackWalker,gnu.classpath.VMSystemProperties,gnu.classpath,gnu.classpath
@subsection @code{gnu.classpath.VMStackWalker}

@code{VMStackWalker} provides access to the class context or stack.  The
default implementation consists of a @code{native} @code{static} method,
@code{getClassContext()}, which obtains the class context, and two helper
methods which obtain the calling class (the 3rd element in the context array)
and its class loader, respectively.

@itemize @bullet
@item @code{getClassContext()} -- The VM should return an array of
@code{Class} objects, each of which relates to the method currently being
executed at that point on the stack.  Thus, the first item (index 0) is the
class that contains this method.
@item @code{getCallingClass()} -- A Java-based helper method which returns
the @code{Class} object which contains the method that called the method
accessing @code{getCallingClass()}. 
@item @code{getCallingClassLoader()} -- Like the last, but returning the class
loader of the class.
@end itemize

@node gnu.classpath.VMSystemProperties,gnu.classpath.Unsafe,gnu.classpath.VMStackWalker,gnu.classpath
@subsection @code{gnu.classpath.VMSystemProperties}

@code{VMSystemProperties} allows the VM to hook into the property creation
process, both before and after the system properties are added by GNU
Classpath.  The default implementation assumes that the VM will add its
properties first, by making the pre-initialisation method @code{native},
and that the Classpath properties may then be altered by a Java-based
post-initialisation method.

As these methods are called as part of the bootstrap process, caution should
be used as to what classes are used, and properties should only be set
using @code{Properties.setProperty()}.  Specifically, I/O classes should be
avoided at this early stage.

@itemize @bullet
@item @code{preInit(Properties)} -- Allows the VM to add properties
@emph{before} the Classpath properties are added. The default implementation
includes a full list of properties that @emph{must} be added by the VM, but
additional VM-specific ones may also be added.  
@item @code{postInit(Properties)} -- Same as the last, but called after the
Classpath properties have been added.  The main purpose of this is to allow
the VM to alter the properties added by GNU Classpath to suit it.
@end itemize

@node gnu.classpath.Unsafe,,gnu.classpath.VMSystemProperties,gnu.classpath
@subsection @code{gnu.classpath.Unsafe}

The @code{Unsafe} class provides access to some low-level unsafe operations
as required by the addition of the java.util.concurrent classes.  These
focus on direct memory access to the fields within the VM and providing
atomic update methods.

@itemize @bullet
@item @code{objectFieldOffset(Field)} -- Provides the caller with the memory
offset of a particular field.
@item @code{compareAndSwap*(Object,long,*,*)} -- One of these methods is
provided for each of int, long and Object (hence the *s).  The value of
a field pointed to by the given Object and offset is compared with the
first value and replaced with the second if they are the same.  The reason
for this method is to make this change operation atomic.
@item @code{put/get*(Object,long,*)} -- These are like the last set of
methods, handling integers, longs and Objects, but the field is always
changed on a put.  Different methods are provided for different semantics.
Ordered variants perform a lazy put, in that the change does not
immediately propogate to other threads, while the others provide
volatile or 'normal' semantics.
@item @code{arrayBaseOffset(Class)} and @code{arrayIndexScale(Class)} --
These two methods allow an array class to be traversed by pointer
arithmetic, by gaining the address of the first element and then
scaling appropriately for the later ones.
@item @code{park(boolean,long)} and @code{unpark(Thread)} -- These methods
block and unblock threads respectively, with an optional timeout being
provided for the blocking.  @code{unpark} is unsafe as the thread may have
been destroyed by native code. 
@end itemize

@node java.util, java.io, gnu.classpath, Classpath Hooks
@section java.util

The @code{java.util} VM hooks provide links between the mix of functionality
present in that package, which includes collections, date and time handling
and parsing.  At present, there is only one hook, which connects GNU Classpath
to the timezone information provided by the underlying platform.

@menu
* java.util.VMTimeZone::
@end menu

@node java.util.VMTimeZone,,java.util,java.util
@subsection @code{java.util.VMTimeZone}

@code{VMTimeZone} joins @code{TimeZone} to the platform timezone information
via the static method, @code{getDefaultTimeZoneId()}.  The VM hook is
expected to return a @code{TimeZone} instance that represents the current
timezone in use by the platform.  The default implementation provides
this functionality for POSIX or GNU-like systems, and VMs that want this
functionality can keep this implementation and implement the native
method, @code{getSystemTimeZoneId()}.  This method is only called when
obtaining the timezone name from the @code{TZ} environment variable,
@code{/etc/timezone} and @code{/etc/localtime} all fail.  This fallback
mechanism also means that a system which doesn't provide the above three
methods, but does provide a timezone in string form, can still use this
implementation.

@node java.io, java.security, java.util, Classpath Hooks
@section java.io

The @code{java.io} package is heavily reliant on access to the I/O facilities
of the underlying platform.  As far as its VM hooks go, they provide two
areas of functionality to GNU Classpath, these being

@itemize @bullet
@item File and directory queries and manipulation
@item Serialization of objects
@end itemize

The first corresponds directly to most of the @code{File} class, while
the latter underlies the functionality provided by the
@code{ObjectInputStream} and @code{ObjectOutputStream}.  More low-level I/O
is provided by @ref{java.nio}.

@menu
* java.io.VMFile::
* java.io.VMObjectInputStream::
* java.io.VMObjectStreamClass::
@end menu

@node java.io.VMFile,java.io.VMObjectInputStream,java.io,java.io
@subsection @code{java.io.VMFile}

@code{VMFile} allows GNU Classpath's @code{File} representations to
probe and modify the file system using the native functions of the
platform.  The default implementation (which consists of both a
@code{VMFile} class and the native methods) is primarily UNIX-centric,
working with POSIX functions and assuming case-sensitive filenames,
without the restriction of the 8.3 format.  It consists mainly of
@code{static} @code{native} methods, with a few Java helper methods.
The native methods represent the file as a string containing its path,
rather than using the object itself.

@itemize @bullet
@item Native Methods
@itemize @bullet
@item @code{lastModified(String)} -- The native method should return a
@code{long} value that represents the last modified date of the file.
@item @code{setReadOnly(String)} -- Sets the file's permissions to read only,
in whichever way this is realised by the platform.
@item @code{create(String)} -- Create the named file.
@item @code{list(String)} -- The native method opens the named directory,
reads the contents and returns them as a Java @code{String} array.
@item @code{renameTo(String,String)} -- Renames the first file to the second.
@item @code{length(String)} -- Returns a @code{long} value representing
the file size.
@item @code{exists(String)} -- Tests for the existence of the named file
or directory.
@item @code{delete(String)} -- Deletes the file or directory.
@item @code{setLastModified(String,long)} -- Change the last modified time.
@item @code{mkdir(String)} -- Creates the named directory.
@item @code{isFile(String)} -- Tests that the named path references a file.
@item @code{canWrite(String)} -- Tests that the file can be written to.
This method is @code{synchronized}, so the object is locked during the check.
@item @code{canRead(String)} -- Complement of the last method.
@item @code{isDirectory(String)} -- Tests that the named path references
a directory.
@end itemize
@item Java Helper Methods
@itemize @bullet
@item @code{canWriteDirectory(File)} -- Checks that the directory can be
written to, by trying to create a temporary file in it.
@item @code{listRoots()} -- Returns the root of a GNU filesystem i.e. `/'
in an array.
@item @code{isHidden(String)} -- Checks whether the file starts with `.',
which is how files are hidden on UNIX-style systems.
@item @code{getName(String)} -- Pulls the actual filename from the end of
the path, by breaking off the characters after the last occurrence of the
platform's file separator.
@item @code{getCanonicalForm(String)} -- This converts a UNIX path to
its canonical form by removing the `.' and `..' sections that occur within.
@end itemize
@end itemize

@node java.io.VMObjectInputStream,java.io.VMObjectStreamClass,java.io.VMFile,java.io
@subsection @code{java.io.VMObjectInputStream}

This class consists of two methods which provide functionality used in
deserializing an object.  @code{currentClassLoader()} provides the first
user-defined class loader from the class context
(@xref{gnu.classpath.VMStackWalker},) via a @code{PrivilegedAction}.
@code{allocateObject(Class,Class,Constructor)} is a @code{native} method
(a reference implementation is provided) which creates an object but
calls the constructor of another class, which is a superclass of the
object's class.

@node java.io.VMObjectStreamClass,,java.io.VMObjectInputStream,java.io
@subsection @code{java.io.VMObjectStreamClass}

@code{VMObjectStreamClass} is a series of @code{static} @code{native}
methods that provide some of the groundwork for @code{ObjectStreamClass}
and @code{ObjectStreamField}.  @code{hasClassInitializer(Class)} works
with the former, and checks for the presence of a static initializer.
The remaining methods are of the form @code{setXXXNative(Field,Object,XXX)}
and support @code{ObjectStreamField}.  One exists for each of the main types
(boolean, float, double, long, int, short, char, byte and object) and is used
to set the specified field in the supplied instance to the given value.

A default implementation is provided for all of them, so a VM implementation
is optional.

@node java.security, java.net, java.io, Classpath Hooks
@section java.security

The @code{java.security} package provides support for Java's security
architecture.  

@menu
* java.security.VMAccessController::
* java.security.VMSecureRandom::
@end menu

@node java.security.VMAccessController,java.security.VMSecureRandom,java.security,java.security
@subsection @code{java.security.VMAccessController}

The @code{AccessController} is used to perform privileged actions.  Its
hook class, @code{VMAccessController}, maintains the
@code{AccessControlContext} and the default implementation is purely
Java-based.  The VM may choose to replace this with their own.
The methods in the reference version are as follows:

@itemize @bullet
@item @code{pushContext(AccessControlContext)} -- Adds a new context to the
stack for the current thread.  This is called before a privileged action
takes place.
@item @code{popContext()} -- Removes the top context from the stack.  This
is performed after the privileged action takes place.
@item @code{getContext()} -- Either derives a context based on the 
@code{ProtectionDomain}s of the call stack (see the next method) or returns
the top of the context stack.
@item @code{getStack()} -- Provides access to the call stack as a pair of
arrays of classes and method names.  The actual implementation returns
an empty array, indicating that there are no permissions.
@end itemize

@node java.security.VMSecureRandom,,java.security.VMAccessController,java.security
@subsection @code{java.security.VMSecureRandom}

The @code{VMSecureRandom} class is used to provide access to
cryptographically secure random numbers.  The default implementation
of the class runs eight threads that increment counters in a tight
loop, and XORs each counter to produce one byte of seed data. This is
not very efficient, and is not guaranteed to be random (the thread
scheduler is probably deterministic, after all). VM implementors
should provide a version of this class, which implements the method
@code{generateSeed(byte[],int,int)}, so that it fills the buffer using
a random seed from a system facility, such as a system entropy
gathering device or hardware random number generator.  The parameters
are the usual set of buffer, offset and length and the method returns
the number of bytes actually generated, which may be less than that
requested.

@node java.net, java.nio, java.security, Classpath Hooks
@section java.net

The @code{java.net} package is heavily reliant on access to the networking
facilities of the underlying platform.  The VM hooks provide information
about the available network interfaces, and access to lookup facilities
for network addresses.

@menu
* java.net.VMInetAddress::
* java.net.VMNetworkInterface::
@end menu

@node java.net.VMInetAddress,java.net.VMNetworkInterface,java.net,java.net
@subsection @code{java.net.VMInetAddress}

@code{VMInetAddress} is a series of @code{static} @code{native} methods
which provide access to the platform's lookup facilities.  All the methods
are implemented by GNU Classpath, making VM implementation optional, and
are as follows:

@itemize @bullet
@item @code{getLocalHostname()} -- Wraps the @code{gethostname} function, and
falls back on `localhost'.
@item @code{lookupInaddrAny()} -- Returns the value of @code{INADDR_ANY}.
@item @code{getHostByAddr(byte[])} -- Looks up the hostname based on an IP
address.
@item @code{getHostByName(String)} -- The reverse of the last method, it
returns the IP addresses which the given host name resolves to.
@end itemize

@node java.net.VMNetworkInterface,,java.net.VMInetAddress,java.net
@subsection @code{java.net.VMNetworkInterface}

@code{VMNetworkInterface} currently consists of a single @code{static}
@code{native} method, @code{getInterfaces()}, which retrieves the
network interfaces available on the underlying platform as a @code{Vector}.
The current GNU Classpath implementation is a native stub.

@node java.nio, java.nio.channels, java.net, Classpath Hooks
@section java.nio

The @code{java.nio} package is part of the New I/O framework added in
Java 1.4.  This splits I/O into the concepts of @emph{buffers},
@emph{charsets}, @emph{channels} and @emph{selectors}, and
@code{java.nio} defines the buffer classes.  As far as native and VM
code is concerned, the new package needs support for low-level efficient
buffer operations.

@menu
* java.nio.VMDirectByteBuffer::
@end menu

@node java.nio.VMDirectByteBuffer,,java.nio,java.nio
@subsection @code{java.nio.VMDirectByteBuffer}

A @code{ByteBuffer} maintains a buffer of bytes, and allows it to be
manipulated using primitive operations such as @code{get}, @code{put},
@code{allocate} and @code{free}.  A direct buffer avoids intermediate
copying, and uses native data which shouldn't be manipulated by a
garbage collector.  The VM class consists of @code{static} @code{native}
methods, all of which are given default implementations by GNU
Classpath.

@itemize @bullet
@item @code{init()} -- Creates an instance of an appropriate
@code{gnu.classpath.RawData} class.  This class is not garbage
collected, is created natively and is used in the other methods to reference
the buffered data.
@item @code{allocate(int)} -- Allocates the memory for the buffer using
@code{malloc} and returns a reference to the @code{RawData} class.
@item @code{free(RawData)} -- Frees the memory used by the buffer.
@item @code{get(RawData,int)}  -- Returns the data at the specified index.
@item @code{get(RawData,int,byte[],int,int)} -- Copies a section of the
data into a byte array using @code{memcpy}.
@item @code{put(RawData,int,byte)} -- Puts the given data in the buffer
at the specified index.
@item @code{adjustAddress(RawData,int)} -- Adjusts the pointer into the buffer.
@item @code{shiftDown(RawData,int,int,int)} -- Moves the content of the buffer
at an offset down to a new offset using @code{memmove}.
@end itemize
 
@node java.nio.channels, gnu.java.nio, java.nio, Classpath Hooks
@section java.nio.channels

Channels provide the data for the buffers with the New I/O packages.
For example, a channel may wrap a file or a socket.  The VM hooks,
at the moment, simply allow the channels to be accessed by @code{java.io}
streams.

@menu
* java.nio.channels.VMChannels::
@end menu

@node java.nio.channels.VMChannels,,java.nio.channels,java.nio.channels
@subsection @code{java.nio.channels.VMChannels}

@code{VMChannels} provides the methods that create the channels or
streams.  The default implementation is in pure Java and simply wraps
the channels in standard I/O classes from @code{java.io}.

@itemize @bullet
@item @code{createStream(Class,Channel)} -- Creates a @code{FileChannel}
which wraps an instance of the specified stream class, created by reflection.
This method is private, and is used by the other two.
@item @code{newInputStream(ReadableByteChannel)} -- Wraps the channel
in a @code{FileInputStream}.
@item @code{newOutputStream(WritableByteChannel)} -- Wraps the channel
in a @code{FileOutputStream}.
@end itemize

@node gnu.java.nio, java.lang.reflect, java.nio.channels, Classpath Hooks
@section gnu.java.nio

The @code{gnu.java.nio} class provides Classpath implementations of the
interfaces provided by @code{java.nio}.  The VM classes provide the native
support necessary to implement @emph{pipes} and @emph{selectors}.

@menu
* gnu.java.nio.VMPipe::
* gnu.java.nio.VMSelector::
@end menu

@node gnu.java.nio.VMPipe,gnu.java.nio.VMSelector,gnu.java.nio,gnu.java.nio
@subsection @code{gnu.java.nio.VMPipe}

@code{VMPipe} provides the native functionality for a uni-directional pipe
between a source and a destination (sink) channel.  It consists of one 
@code{static} @code{native} method, @code{init(PipeImpl,SelectorProvider)},
the reference implementation of which is currently a native stub.  Ideally,
this should initialise the pipe at the native level.

@node gnu.java.nio.VMSelector,,gnu.java.nio.VMPipe,gnu.java.nio
@subsection @code{gnu.java.nio.VMSelector}

A @code{Selector} selects between multiple @code{SelectableChannel}s based
on their readiness and a key set.  The VM hook for the Classpath implementation
of this is @code{VMSelector}, and this allows the actual @code{select()}
operation to be performed.  This is represented by the @code{static}
@code{native} method, @code{select(int[],int[],int[],long)}, and a default
implementation of this is provided.

@node java.lang.reflect, gnu.java.lang, gnu.java.nio, Classpath Hooks
@section @code{java.lang.reflect}
@code{java.lang.reflect} provides the interface to Java's reflection
facilities.  Via reflection, programmers can obtain type information about
a particular instance at runtime or dynamically create new instances.

@menu
* java.lang.reflect.VMArray::
@end menu

@node java.lang.reflect.VMArray,,,java.lang.reflect
@subsection @code{java.lang.reflect.VMArray}

The @code{VMArray} class provides a hook, @code{createObjectArray},
which the VM uses to generate a new non-primitive array of a
particular class and size.  The default implementation simply passes
the job down to the standard JNI function, @code{NewObjectArray}.

@node gnu.java.lang, gnu.java.lang.management, java.lang.reflect, Classpath Hooks
@section @code{gnu.java.lang}

@code{gnu.java.lang} provides VM interfaces for the GNU
implementations of features in java.lang.  Currently, this includes the
implementation of instrumentation.

@menu
* gnu.java.lang.VMInstrumentationImpl::
@end menu

@node gnu.java.lang.VMInstrumentationImpl,,,gnu.java.lang
@subsection @code{gnu.java.lang.VMInstrumentationImpl}

The @code{gnu.java.lang.VMInstrumentationImpl} and
@code{gnu.java.lang.InstrumentationImpl} classes provide an implementation of the
@code{java.lang.instrument.Instrument} interface. 
A @code{InstrumentationImpl} object should be created by the VM when agents
are given in the command line (see the @code{java.lang.instrument} package
documentation). The VM has to set the static field
@code{VMClassLoader.instrumenter} to this object. The VM should implement the
static native methods of the @code{VMInstrumentationImpl} class.

@itemize @bullet
@item @code{isRedefineClassesSupported()} -- Returns true if the JVM supports
class redefinition.
@item @code{redefineClasses()} -- Gives a set of classes with new bytecodes.
The VM must redefine the classes by reading the new bytecodes.
@item @code{getAllLoadedClass()} -- Returns an array of all loaded classes.
@item @code{getInitiatedClass()} -- Returns an array of all classes loaded
by a specific class loader.
@item @code{getObjectSize()} -- Gives the size of an object.
@end itemize

Instrumentation allows to modify the bytecode of a class before it gets read
by the VM. In GNU Classpath, the @code{ClassLoader.defineClass} method calls
the @code{VMClassLoader.defineClassWithTransformers} method which first checks
if @code{VMClassLoader.instrumenter} is @code{null}. If it's the case, it
directly calls @code{VMClassLoader.defineClass}. If it's not the case, the
method calls at first the @code{InstrumentationImpl.callTransformers} method,
which calls each transformer registered to the @code{InstrumentationImpl}
object and returns a new bytecode array. Then, it calls the
@code{VMClassLoader.defineClass} method with this new bytecode array.

The second use of instrumentation is to redefine a class after it has been
loaded by the VM. This is done in the Java application by calling the
@code{Instrumentation.redefineClasses} method of the standard interface on
a @code{Instrumentation} object. The @code{InstrumentationImpl.redefineClasses}
method calls the @code{VMInstrumentationImpl.redefineClasses} native method
which must be implemented by the VM. The implementation should call the
@code{InstrumentationImpl.callTransformers} method.

@node gnu.java.lang.management, java.lang.management, gnu.java.lang, Classpath Hooks
@section @code{gnu.java.lang.management}

@code{gnu.java.lang.management} provides the VM interfaces for the GNU
implementations of the management beans.  

@menu
* gnu.java.lang.management.VMRuntimeMXBeanImpl::
* gnu.java.lang.management.VMClassLoadingMXBeanImpl::
* gnu.java.lang.management.VMThreadMXBeanImpl::
* gnu.java.lang.management.VMMemoryMXBeanImpl::
* gnu.java.lang.management.VMCompilationMXBeanImpl::
* gnu.java.lang.management.VMMemoryPoolMXBeanImpl::
* gnu.java.lang.management.VMMemoryManagerMXBeanImpl::
* gnu.java.lang.management.VMGarbageCollectorMXBeanImpl::
@end menu

@node gnu.java.lang.management.VMRuntimeMXBeanImpl,gnu.java.lang.management.VMClassLoadingMXBeanImpl,,gnu.java.lang.management
@subsection @code{gnu.java.lang.management.VMRuntimeMXBeanImpl}

The @code{gnu.java.lang.management.RuntimeMXBeanImpl} provides an
implementation of the @code{java.lang.management.RuntimeMXBean} interface,
and is supported by VM functionality in the form of
@code{gnu.java.lang.management.VMRuntimeMXBeanImpl}.  This provides a
series of methods, which should be implemented by the virtual machine
in order to provide the required information for the bean.  The VM
methods are generally representative of information that is only
available from the virtual machine, such as the command-line arguments
it was given at startup.

The methods are as follows:

@itemize @bullet
@item @code{(getInputArguments())} -- The VM should supply
a @code{String} array containing each of the command-line
arguments, excluding those that are directed at the
@code{main()} method.  The reference implementation expects
this to be a native method.
@item @code{(getName())} -- The VM developer should choose
an appropriate name for the virtual machine.  This name can
be instance-specific e.g. it can include things like the
process identifier or host name of the machine, which only
apply to the current running instance.  Thus, the intention is
that this name refers to the entity that the other information
refers to, rather than the VM in general.  The reference
implementation supplies a default concatenation of the VM
name and version.
@item @code{(getStartTime())} -- This should return the number
of milliseconds at which the virtual machine was started.
The uptime property of the bean is provided relative to this
value.  Again, the reference implementation also expects
this method to be native.
@end itemize

The virtual machine also needs to provide either the
@code{sun.boot.class.path} or @code{java.boot.class.path}
property in order to support the optional boot class path
retrieval functionality.

@node gnu.java.lang.management.VMClassLoadingMXBeanImpl,gnu.java.lang.management.VMThreadMXBeanImpl,gnu.java.lang.management.VMRuntimeMXBeanImpl,gnu.java.lang.management
@subsection @code{gnu.java.lang.management.VMClassLoadingMXBeanImpl}

The @code{gnu.java.lang.management.ClassLoadingMXBeanImpl} provides an
implementation of the @code{java.lang.management.ClassLoadingMXBean} interface,
and is supported by VM functionality in the form of
@code{gnu.java.lang.management.VMClassLoadingMXBeanImpl}.  This provides a
series of methods, which should be implemented by the virtual machine
in order to provide the required information for the bean.  Implementing
this bean requires the VM to monitor when classes are loaded and unloaded,
and provide the option of verbose class loading output.

The methods are as follows:

@itemize @bullet
@item @code{(getLoadedClassCount())} -- This should return
the number of classes that are currently loaded by the VM.
@item @code{(getUnloadedClassCount())} -- This should return
the number of classes that have been loaded by the VM, but
have since been unloaded.
@item @code{(isVerbose())} -- This should return @code{true}
or @code{false}, depending on whether verbose class loading
output is turned or not, respectively.
@item @code{(setVerbose(boolean))} -- This should allow the
verbose class loading output to be turned on and off.
@end itemize

@node gnu.java.lang.management.VMThreadMXBeanImpl,gnu.java.lang.management.VMMemoryMXBeanImpl,gnu.java.lang.management.VMClassLoadingMXBeanImpl,gnu.java.lang.management
@subsection @code{gnu.java.lang.management.VMThreadMXBeanImpl}

The @code{gnu.java.lang.management.ThreadMXBeanImpl} provides an
implementation of the @code{java.lang.management.ThreadMXBean} interface,
and is supported by VM functionality in the form of
@code{gnu.java.lang.management.VMThreadMXBeanImpl}.  This provides a
series of methods, which should be implemented by the virtual machine
in order to provide the required information for the bean.  Implementing
this bean requires the VM to monitor thread-related statistics such as
how often the blocked and waiting states have been entered, as well as
additional optional support for time and contention monitoring.

Optional support is determined by the following properties:

@itemize @bullet
@item @code{gnu.java.lang.management.CurrentThreadTimeSupport} --
This property should be present if the VM supports monitoring the
time used by the current thread.  If time monitoring for all threads
is supported, this need not be provided.
@item @code{gnu.java.lang.management.ThreadTimeSupport} --
This property should be present if the VM supports monitoring the
time used by all threads.
@item @code{gnu.java.lang.management.ThreadContentionSupport} --
This property should be present if the VM supports thread contention
monitoring.
@end itemize

In addition, the property
@code{gnu.java.lang.management.ThreadTimeInitallyEnabled} may be
set to the @code{String} value, @code{"true"}, if time monitoring
is enabled at startup.

The methods are as follows:

@itemize @bullet
@item @code{(findMonitorDeadlockedThreads())} -- This should return
an array of thread identifiers which match threads involved in
deadlock cycles (where each thread is waiting to obtain a lock
held by one of the others).  This is specified as a native method
in the reference implementation.
@item @code{(getAllThreads())} -- This should return an array of
all live threads and set the @code{filled} variable to the number
found.  A default implementation is provided.
@item @code{(getAllThreadIds())} -- This should return an array of
all live thread identifiers.  An implementation is provided against
@code{getAllThreads()} by default.
@item @code{(getCurrentThreadCpuTime())} -- This should return the
approximate number of nanoseconds of CPU time the current thread
has used.  This is an optional native method, which is used by VMs
supporting time monitoring.
@item @code{(getCurrentThreadUserTime())} -- This should return the
approximate number of nanoseconds of user time the current thread
has used.  This is an optional native method, which is used by VMs
supporting time monitoring.
@item @code{(getDaemonThreadCount())} -- This should return the number
of live daemon threads.  A default implementation is provided, based
on @code{getAllThreads()}.
@item @code{(getPeakThreadCount())} -- The VM should maintain a record
of the peak number of live threads, and return it when this method is
called.  This is specified as a native method in the reference
implementation.
@item @code{(resetPeakThreadCount())} -- This should reset the record
of the peak number of live threads to the current number of live
threads.  This is specified as a native method in the reference
implementation.
@item @code{(getThreadCount())} -- This should return the number of
live threads.  A default implementation is provided, based on
@code{getAllThreads()}.
@item @code{(getThreadCpuTime(long))} -- This should return the
approximate number of nanoseconds of CPU time the specified thread
has used.  This is an optional native method, which is used by VMs
supporting time monitoring.
@item @code{(getThreadUserTime(long))} -- This should return the
approximate number of nanoseconds of CPU time the specified thread
has used.  This is an optional native method, which is used by VMs
supporting time monitoring.
@item @code{(getThreadInfoForId(long, int))} -- This return an instance
of @code{java.lang.management.ThreadInfo} for the specified thread.
The class includes a private constructor which VMs should use to initialise
it with the appropriate values for the thread.  The second argument
given here specifies the depth of the stack trace supplied on construction
of the instance.  Special values are 0 (return an empty array) and
@code{Integer.MAX_VALUE} (return the maximum depth possible).  This
is specified as a native method in the reference implementation.
@item @code{(getTotalStartedThreadCount())} -- This should return the
total number of threads that have been started by the VM, including ones
that have died.  This is specified as a native method in the reference
implementation.
@end itemize

@node gnu.java.lang.management.VMMemoryMXBeanImpl,gnu.java.lang.management.VMCompilationMXBeanImpl,gnu.java.lang.management.VMThreadMXBeanImpl,gnu.java.lang.management
@subsection @code{gnu.java.lang.management.VMMemoryMXBeanImpl}

The @code{gnu.java.lang.management.MemoryMXBeanImpl} provides an
implementation of the @code{java.lang.management.MemoryMXBean} interface,
and is supported by VM functionality in the form of
@code{gnu.java.lang.management.VMMemoryMXBeanImpl}.  This provides a
series of methods, which should be implemented by the virtual machine
in order to provide the required information for the bean.  Implementing
this bean requires the VM to monitor the levels of heap and non-heap
memory, and provide the number of objects which are eligible for garbage
collection.

The methods are as follows:

@itemize @bullet
@item @code{(getHeapMemoryUsage())} -- This should return
an instance of @code{java.lang.management.MemoryUsage} with
values pertaining to the heap.  A default implementation is
provided, based on @code{java.lang.Runtime}'s methods.
@item @code{(getNonHeapMemoryUsage())} -- This should return
an instance of @code{java.lang.management.MemoryUsage} with
values pertaining to non-heap memory.
@item @code{(getObjectPendingFinalizationCount())} -- Returns
the number of objects which are no longer referenced, and which
will thus be garbage collected on the next run of the garbage
collector.
@item @code{(isVerbose())} -- This should return @code{true}
or @code{false}, depending on whether verbose memory management
output is turned or not, respectively.
@item @code{(setVerbose(boolean))} -- This should allow the
verbose memory management output to be turned on and off.
@end itemize

@node gnu.java.lang.management.VMCompilationMXBeanImpl,gnu.java.lang.management.VMMemoryPoolMXBeanImpl,gnu.java.lang.management.VMMemoryMXBeanImpl,gnu.java.lang.management
@subsection @code{gnu.java.lang.management.VMCompilationMXBeanImpl}

The @code{gnu.java.lang.management.CompilationMXBeanImpl} provides an
implementation of the optional @code{java.lang.management.CompilationMXBean}
interface, and is supported by VM functionality in the form of
@code{gnu.java.lang.management.VMCompilationMXBeanImpl}.  This provides a
single method for returning the number of milliseconds the virtual
machine's Just-In-Time (JIT) compiler has spent compiling.  Even if
a JIT compiler is available and an instance of the bean supplied, this
method is still optional.

Optional support is determined by the following properties:

@itemize @bullet
@item @code{gnu.java.lang.compiler.name} -- This property should
specify the name of the JIT compiler.  Classpath also uses this,
within @code{java.lang.management.ManagementFactory}, to determine
whether a bean should be created.  If this property is set to a
non-null value, a bean will be created and its @code{getName()}
method will return this value.
@item @code{gnu.java.lang.management.CompilationTimeSupport} --
This property should be present if the VM supports monitoring the
time spent compiling.
@end itemize

Time support is implemented by the following method:

@itemize @bullet
@item @code{(getTotalCompilationTime())} -- This should return the
number of milliseconds the JIT compiler has spent compiling.
@end itemize

@node gnu.java.lang.management.VMMemoryPoolMXBeanImpl,gnu.java.lang.management.VMMemoryManagerMXBeanImpl,gnu.java.lang.management.VMCompilationMXBeanImpl,gnu.java.lang.management
@subsection @code{gnu.java.lang.management.VMMemoryPoolMXBeanImpl}

The @code{gnu.java.lang.management.MemoryPoolMXBeanImpl} provides an
implementation of the optional @code{java.lang.management.MemoryPoolMXBean}
interface, and is supported by VM functionality in the form of
@code{gnu.java.lang.management.VMMemoryPoolMXBeanImpl}.  Providing
this interface requires implementing a number of methods for each supported
pool.  These return statistics on memory usage, and, optionally, allows
monitoring of when memory usage exceedes a preset threshold.

Optional support is determined by the following properties:

@itemize @bullet
@item @code{gnu.java.lang.management.CollectionUsageThresholdSupport} --
This property should be present if the VM supports setting a collection
usage threshold and monitoring when it is matched or exceeded.  Collection
usage thresholds are related to the remaining memory usage following a
garbage collection cycle.
@item @code{gnu.java.lang.management.UsageThresholdSupport} --
This property should be present if the VM supports setting a 
usage threshold and monitoring when it is matched or exceeded.  
@end itemize

The methods are as follows (all take a pool name as their
first parameter):

@itemize @bullet
@item @code{(getCollectionUsage(String))} -- Returns a
@code{java.lang.management.MemoryUsage} object, containing the
memory usage statistics following a garbage collection cycle
for the specified pool.  This may also return @code{null} if
the pool isn't an appropriate pool for this particular task.
@item @code{(getCollectionUsageThreshold(String))} -- Returns
the pool's collection usage threshold, if supported.
@item @code{(getCollectionUsageThresholdCount(String))} -- Returns
the number of times the specified pool has matched or exceeded
its collection usage threshold, if supported.
@item @code{(getMemoryManagerNames(String))} -- Returns a list
of names of memory managers which manage the specified pool.
@item @code{(getPeakUsage(String))} -- Returns a
@code{java.lang.management.MemoryUsage} object for the peak
usage level of the specified pool.
@item @code{(getType(String))} -- Returns a string containing
either @code{"HEAP"} or @code{"NON_HEAP"} which indicates the type of
memory used by the specified pool.
@item @code{(getUsage(String))} -- Returns a
@code{java.lang.management.MemoryUsage} object for the current
usage level of the specified pool.
@item @code{(getUsageThreshold(String))} -- Returns
the pool's usage threshold, if supported.
@item @code{(getUsageThresholdCount(String))} -- Returns
the number of times the specified pool has matched or exceeded
its usage threshold, if supported.
@item @code{(isValid(String))} -- Returns true if the pool
is still in use by the virtual machine.
@item @code{(resetPeakUsage(String))} -- Resets the peak usage
levels to the current usage levels for the specified pool.
@item @code{(setCollectionUsageThreshold(String, long))} -- Sets
the pool's collection usage threshold, if supported.
@item @code{(setUsageThreshold(String, long))} -- Sets
the pool's usage threshold, if supported.
@end itemize

@node gnu.java.lang.management.VMMemoryManagerMXBeanImpl,gnu.java.lang.management.VMGarbageCollectorMXBeanImpl,gnu.java.lang.management.VMMemoryPoolMXBeanImpl,gnu.java.lang.management
@subsection @code{gnu.java.lang.management.VMMemoryManagerMXBeanImpl}

The @code{gnu.java.lang.management.MemoryManagerMXBeanImpl} provides an
implementation of the optional @code{java.lang.management.MemoryManagerMXBean}
interface, and is supported by VM functionality in the form of
@code{gnu.java.lang.management.VMMemoryManagerMXBeanImpl}.  Providing
this interface requires implementing two methods (each takes the name
of the manager as the first argument):

@itemize @bullet
@item @code{(getMemoryPoolNames(String))} -- Returns a list of the
memory pools that the manager maintains.  A default implementation
which scans the results of @code{getMemoryManagerNames()} for each
pool is provided.
@item @code{(isValid(String))} -- Returns true if the specified
manager is still valid i.e. it is still in use by the virtual machine.
@end itemize

@node gnu.java.lang.management.VMGarbageCollectorMXBeanImpl,,gnu.java.lang.management.VMMemoryManagerMXBeanImpl,gnu.java.lang.management
@subsection @code{gnu.java.lang.management.VMGarbageCollectorMXBeanImpl}

The @code{gnu.java.lang.management.GarbageCollectorMXBeanImpl} provides an
implementation of the optional @code{java.lang.management.GarbageCollectorMXBean}
interface, and is supported by VM functionality in the form of
@code{gnu.java.lang.management.VMGarbageCollectorMXBeanImpl}.  Providing
this interface requires implementing two methods (each takes the name
of the garbage collector as the first argument):

@itemize @bullet
@item @code{(getCollectionCount(String))} -- Returns the number of
times the specified garbage collector has run.
@item @code{(getCollectionTime(String))} -- Returns the accumulated
number of milliseconds for which the garbage collector has run.
@end itemize

Note that each garbage collector is also a memory manager, and so an
implementation of the @code{gnu.java.lang.management.VMMemoryManagerMXBeanImpl}
methods for its name should also be provided.

@node java.lang.management, Classpath Callbacks, gnu.java.lang.management, Classpath Hooks
@section @code{java.lang.management}

@code{gnu.java.lang.management} provides the VM interfaces for the GNU
implementations of the management beans.  

@menu
* java.lang.management.VMManagementFactory::
@end menu

@node java.lang.management.VMManagementFactory,,,java.lang.management
@subsection @code{java.lang.management.VMManagementFactory}

This VM interface provides the names of the memory pools, memory managers
and garbage collectors for use by the @code{java.lang.management.ManagementFactory}
in creating lists of appropriate beans for these types of managed object.

The methods are as follows:

@itemize @bullet
@item @code{(getMemoryPoolNames())} -- Returns a list of the names
of the current memory pools in use by the virtual machine.
@item @code{(getMemoryManagerNames())} -- Returns a list of the names
of the current memory managers in use by the virtual machine.  This
should not include those that are also garbage collectors.
@item @code{(getGarbageCollectorNames())} -- Returns a list of the names
of the current garbage collectors in use by the virtual machine.
@end itemize

@node Classpath Callbacks, , java.lang.management, Classpath Hooks
Some of the classes you implement for the VM will need to call back to
package-private methods in Classpath:

@itemize @bullet
@item @code{java.lang.ThreadGroup.addThread(Thread)}
Call this method from @code{Thread} when a new @code{Thread} is created, to add it to
the group.

@item @code{java.lang.ThreadGroup.removeThread(Thread)}
Call this method from @code{Thread} when a @code{Thread} is stopped or destroyed.

@item @code{gnu.java.lang.management.MemoryMXBeanImpl.fireThresholdExceededNotification(String, long, long, long, long)}
If the monitoring of memory usage thresholds is supported, this method
should be called when the normal usage of a memory pool crosses the
threshold, in order to emit a notification.  Another notification
should not be emitted until there is an intermittent period where the
usage is again below the threshold.  The parameters are the memory
pool name, the usage levels (init, used, committed and max) and the
number of times the threshold has been crossed.

@item @code{gnu.java.lang.management.MemoryMXBeanImpl.fireCollectionThresholdExceededNotification(String, long, long, long, long)}
If the monitoring of memory usage thresholds is supported, this method
should be called when the usage of a memory pool after a garbage
collection cycle crosses the threshold, in order to emit a
notification.  Another notification should not be emitted until there
is an intermittent period where the usage is again below the
threshold.  The parameters are the memory pool name, the usage levels
(init, used, committed and max) and the number of times the threshold
has been crossed.

@end itemize

@node VM Hooks, JNI Implementation, Classpath Hooks, Top
@comment node-name, next, previous, up
@chapter VM Hooks

VMs need to do some dirty work; there are some things in the VM that
unfortunately are dependent on the internal structure of various
classes.  This is a guide to all of the things the VM itself needs to
know about classes.

Some of the core classes, while being implemented by GNU Classpath,
provide space for state (in the form of a @code{vmdata} object) to be
stored by the VM, and can not be constructed normally.

@itemize @bullet
@item java.lang.Class
@item java.lang.ClassLoader
@end itemize

The default implementations of some VM classes also follow this methodology,
when it is intended that most VMs will keep the default.

@itemize @bullet
@item java.lang.VMThread
@item java.lang.VMThrowable
@end itemize

Several core classes must be completely implemented by the VM for Classpath to
work, although reference implementations are provided.  These classes are:

@itemize @bullet
@item java.lang.reflect.Constructor
@item java.lang.reflect.Method
@item java.lang.reflect.Field
@end itemize

The following issues are of note;

@itemize @bullet
@item @code{java.lang.Class} @*
The GNU Classpath implementation of @code{java.lang.Class} provides an
object for storing the internal state of the class maintained by the VM.
This is the only known place where this matters.  The class is
constructed with this data by the VM.  Some VMs do not create the
@code{Class} object at the point where the class is defined; instead,
they wait until a @code{Class} object is actually used.

@item Array Classes @*
When you are creating an array class, you should set the
@code{ClassLoader} of the array class to the @code{ClassLoader} of its
component type.  Whenever you add a class to a @code{ClassLoader}, you
need to notify the @code{ClassLoader} and add the new @code{Class} to
its internal cache of classes.  To do this, call
@code{ClassLoader.addVMCreatedClass(Class)}.  @emph{Note: this is
written in anticipation of 1.2 support and does not apply just yet.}

@item Primordial Class Loader @*
When the primordial class loader loads a class, it needs to tell
Classpath what it has done in order for security stuff to work right.
To do this, call the static method
@code{ClassLoader.newPrimordialClass(Class)}.

Even the first few core classes need to do this; in order to do it,
simply call this method @emph{after} the initial class loading has been
done.  No harm will come, as long as you follow the guidelines in the
@pxref{Initialization} section.

@emph{Note: this is written in anticipation of 1.2 support and does not
apply just yet.}

@item Top-level Exception Handler @*
Exceptions take care of themselves in Classpath; all you need to do in
the top-level exception handler is call @code{Throwable.printStackTrace()}.

@item Security and Traces @*
There will eventually be a feature in the 1.2 security that keeps the
@code{AccessController} from having to evaluate @emph{all} of the
@code{ProtectionDomain}s every time a security check is made.  I think a common
case is a single method doing a lot of things that require security
checks.  However, I don't want to bog down the method stack too much, so
this feature of the VM will have the @code{AccessController} for a thread
calling out to the VM to tell it how high it was on the stack when it
made the last security request.  Every time the stack goes lower than
that number, the VM will decrement the number.  The @code{AccessController}
will remember what the accumulated protection status was at every stack
level (an @code{AccessControlContext}) and use that aggregated information to
do the check.  I am not sure, however, whether the savings are
substantial enough to outweigh the integer check and set after every
method call.  I will investigate.

@item Threading @*
I figured I'd put this here because a VM guy might be wondering about it.
We implement @code{ThreadGroup}, but that class is almost entirely
VM-independent.  The root @code{ThreadGroup}, a static field called
@code{ThreadGroup.root}, should be initialized by Classpath, but if you wish to
reinitialize it yourself, there should be no harm.

@end itemize

@node JNI Implementation, JVMTI Implementation, VM Hooks, Top
@comment  node-name,  next,  previous,  up
@chapter JNI Implementation

Classpath comes with its own implementation of @file{jni.h}.  This
file can be customized by the VM in a few ways, by defining macros
that affect the interpretation of the file.  These macros are all
intended for use by a VM which uses GNU Classpath and which wants to
use a single copy of @file{jni.h} for both internal and external use.

@itemize @bullet
@item _CLASSPATH_VM_JNI_TYPES_DEFINED
Some VMs like to define JNI ``object'' types in a special way.  If
this macro is defined, the Classpath @file{jni.h} will avoid defining
these types.  By default, these types are defined in @file{jni.h}.
The full list of types and macros treated this way is: @samp{jobject},
@samp{jclass}, @samp{jstring}, @samp{jthrowable}, @samp{jweak},
@samp{jarray}, @samp{jobjectArray}, @samp{jbyteArray},
@samp{jshortArray}, @samp{jintArray}, @samp{jlongArray},
@samp{jbooleanArray}, @samp{jcharArray}, @samp{jfloatArray},
@samp{jdoubleArray}, @samp{JNIEnv}, @samp{JavaVM}, @samp{JNI_TRUE}
(macro), @samp{JNI_FALSE} (macro).

@item _CLASSPATH_VM_INTERNAL_TYPES_DEFINED
If the VM has its own definitions for @samp{jfieldID} and
@samp{jmethodID}, then it should define this macro.  Otherwise,
@file{jni.h} will provide definitions for these types.

@item _CLASSPATH_JNIIMPEXP
Three functions -- @samp{JNI_GetDefaultJavaVMInitArgs},
@samp{JNI_CreateJavaVM}, and @samp{JNI_GetCreatedJavaVMs} -- must be
marked as @samp{JNIIMPORT} when seen by user code, but most likely
should be marked as @samp{JNIEXPORT} when defined in the VM
implementation.  This macro can be defined to one or the other by the
VM as appropriate.  If this macro is not defined, it defaults to
@samp{JNIIMPORT}.

@item _CLASSPATH_JNIENV_CONTENTS
A VM can add fields to the @samp{JNIEnv} structure by defining this to
be a sequence of field declarations.

@end itemize

@node JVMTI Implementation, Miscellaneous VM Requirements, JNI Implementation, Top
@comment node-name, next, previous, up
@chapter JVMTI Implementation

Classpath comes with its own implementation of @file{jvmti.h}.  This
file can be customized by the VM in a few ways by defining macros that
affect the interpretation of the file.  These macros are all intended
for use for use by a VM which uses GNU Classpath and which wants to
use a single copy of @file{jvmti.h} for both internal and external use.

@itemize @bullet
@item _CLASSPATH_VM_JVMTI_TYPES_DEFINED
Some VMs like to define JVMTI ``object'' types in a special way.  If
this macro is defined, the Classpath @file{jvmti.h} will avoid defining
these types.  By default these types are defined in @file{jvmti.h}.  
The full list of types and macros treated this way is: @samp{jthread},
@samp{jthreadGroup}, @samp{jlocation}, and @samp{jrawMonitorID}.  By
default @samp{jrawMonitorID} is defined as an opaque pointer which
must be defined by the VM.

@item _CLASSPATH_JVMTIENV_CONTENTS
A VM can add fields to the @samp{jvmtiEnv} structure by defining this
to be a sequence of field declarations.

@end itemize

@node Miscellaneous VM Requirements,  , JVMTI Implementation, Top
@comment  node-name,  next,  previous,  up
@chapter Miscellaneous VM Requirements

Classpath places a few requirements on the VM that uses it.

@menu
* JNI Version::                 
* VM Threading Model::          
* Boot Library Path Property::
@end menu

@node JNI Version, VM Threading Model, Miscellaneous VM Requirements, Miscellaneous VM Requirements
@comment  node-name,  next,  previous,  up
@section JNI Version

Classpath currently uses only JNI 1.1, except for one JNI 1.2 function
in the JNI Invocation API: GetEnv().  And GetEnv() is only used in the
``portable native sync'' code, so it's only actually used by Jikes RVM
and Kaffe.  

A future direction will probably be to require that all VMs provide
JNI 1.2.  If this poses problems, please raise them on the classpath
mailing list. 

@node VM Threading Model, Boot Library Path Property, JNI Version, Miscellaneous VM Requirements
@comment  node-name,  next,  previous,  up
@section VM Threading Model

Classpath's AWT peers use GTK+.  GTK+ uses GLIB.  Normally, Classpath
will initialize GLIB's @dfn{gthreads} to use
the platform's native threading model@footnote{The native threading
model is pthreads on Linux and AIX, the two platforms Classpath
currently runs on.}

If the Java runtime doesn't use the native threading model, then you
will want Classpath to tell GLIB to use the Java threading primitives
instead.  Otherwise, GLIB would use the native threading model to
perform operations such as creating thread-local data, and that just
doesn't work on systems (such as Kaffe in some configurations, and
such as Jikes RVM) that use @i{m}:@i{n} threading.

Historically, enabling the Java threading primitives had been done at
build time, by configuring classpath with the
@option{--portable-native-sync} option.  This had bad consequences,
though -- it meant that the prebuild GNU Classpath package distributed
with Debian GNU/Linux would not be usable with VMs that could
otherwise have used it.  Instead, we encourage
the use of the Java system property
@code{gnu.classpath.awt.gtk.portable.native.sync}.  A VM that wants
GLIB to use the Java threading primitives should modify
@code{VMRuntime.insertSystemProperties()} to include code like the
following:

@example
static void insertSystemProperties(Properties @var{p}) 
@end example
...
@example
@var{p}.put("gnu.classpath.awt.gtk.portable.native.sync", "true");
@end example

So, the configure option
@option{--portable-native-sync} is deprecated, and should go away in a
subsequent release of GNU Classpath.

@node Boot Library Path Property,  , VM Threading Model, Miscellaneous VM Requirements
@comment  node-name,  next,  previous,  up
@section Boot Library Path Property

As of GNU Classpath 0.15 a system property named @code{gnu.classpath.boot.library.path}
can be set by the VM to specify the directories which contain GNU Classpath's native
libraries. Usually this value is given at configuration time and is then hardcoded
in the VM. However for development purposes it is handy to switch to another installation
by overriding the properties' value on the command line.

A VM that does not support this feature can simply ignore the property.

For compatibility reasons we suggest to set the default value of @code{java.library.path}
to the value of the @code{LD_LIBRARY_PATH} environment if it exists on your platform.

@bye