1 |
14 |
jlechner |
\input texinfo @c -*-texinfo-*-
|
2 |
|
|
|
3 |
|
|
@c %**start of header
|
4 |
|
|
@setfilename vmintegration.info
|
5 |
|
|
@settitle GNU Classpath VM Integration Guide
|
6 |
|
|
@c %**end of header
|
7 |
|
|
|
8 |
|
|
@setchapternewpage off
|
9 |
|
|
|
10 |
|
|
@ifinfo
|
11 |
|
|
This file contains important information you will need to know if you
|
12 |
|
|
are going to write an interface between GNU Classpath and a Virtual
|
13 |
|
|
Machine.
|
14 |
|
|
|
15 |
|
|
Copyright (C) 1998-2002, 2004, 2005 Free Software Foundation, Inc.
|
16 |
|
|
|
17 |
|
|
@ifnotplaintext
|
18 |
|
|
@dircategory GNU Libraries
|
19 |
|
|
@direntry
|
20 |
|
|
* VM Integration: (vmintegration). GNU Classpath VM Integration Guide
|
21 |
|
|
@end direntry
|
22 |
|
|
@end ifnotplaintext
|
23 |
|
|
@end ifinfo
|
24 |
|
|
|
25 |
|
|
@titlepage
|
26 |
|
|
@title GNU Classpath VM Integration Guide
|
27 |
|
|
@author John Keiser
|
28 |
|
|
@author C. Brian Jones
|
29 |
|
|
@author Mark Wielaard
|
30 |
|
|
|
31 |
|
|
@page
|
32 |
|
|
@vskip 0pt plus 1filll
|
33 |
|
|
Copyright @copyright{} 1998-2002 Free Software Foundation, Inc.
|
34 |
|
|
@sp 2
|
35 |
|
|
Permission is granted to make and distribute verbatim copies of
|
36 |
|
|
this document provided the copyright notice and this permission notice
|
37 |
|
|
are preserved on all copies.
|
38 |
|
|
|
39 |
|
|
Permission is granted to copy and distribute modified versions of this
|
40 |
|
|
document under the conditions for verbatim copying, provided that the
|
41 |
|
|
entire resulting derived work is distributed under the terms of a
|
42 |
|
|
permission notice identical to this one.
|
43 |
|
|
|
44 |
|
|
Permission is granted to copy and distribute translations of this manual
|
45 |
|
|
into another language, under the above conditions for modified versions,
|
46 |
|
|
except that this permission notice may be stated in a translation
|
47 |
|
|
approved by the Free Software Foundation.
|
48 |
|
|
|
49 |
|
|
@end titlepage
|
50 |
|
|
|
51 |
|
|
@ifinfo
|
52 |
|
|
@node Top, Introduction, (dir), (dir)
|
53 |
|
|
@top GNU Classpath Hacker's Guide
|
54 |
|
|
|
55 |
|
|
This file contains important information you will need to know if you
|
56 |
|
|
are going to write an interface between GNU Classpath and a Virtual
|
57 |
|
|
Machine.
|
58 |
|
|
|
59 |
|
|
This document is incomplete, as we are still in alpha with the interface.
|
60 |
|
|
|
61 |
|
|
@end ifinfo
|
62 |
|
|
|
63 |
|
|
@menu
|
64 |
|
|
* Introduction:: An introduction to the Classpath project
|
65 |
|
|
* Initialization:: Initializing the classes
|
66 |
|
|
* Classpath Hooks:: Hooks from Classpath to the VM
|
67 |
|
|
* VM Hooks:: Hooks from the underlying VM to Classpath
|
68 |
|
|
* JNI Implementation:: Hooking the VM to jni.h
|
69 |
|
|
* Miscellaneous VM Requirements::
|
70 |
|
|
@end menu
|
71 |
|
|
|
72 |
|
|
@node Introduction, Initialization, Top, Top
|
73 |
|
|
@comment node-name, next, previous, up
|
74 |
|
|
@chapter Introduction
|
75 |
|
|
|
76 |
|
|
The Classpath Project's ambition to be a 100% clean room implementation
|
77 |
|
|
of the standard Java class libraries cannot be fulfilled without some
|
78 |
|
|
level of integration with the Virtual Machine, the underlying machinery
|
79 |
|
|
that actually runs Java.
|
80 |
|
|
|
81 |
|
|
There are several VMs out there, here is a small list.
|
82 |
|
|
|
83 |
|
|
@itemize @bullet
|
84 |
|
|
@item @uref{http://www.hungry.com/old-hungry/products/japhar/,Japhar}
|
85 |
|
|
Japhar was the first VM to use GNU Classpath. Today you can see that
|
86 |
|
|
sort of relationship in the source tree which denotes several Japhar
|
87 |
|
|
specific files as a reference implementation of those pieces. This VM
|
88 |
|
|
has been primarily tested against Linux and lacks garbage collections, a
|
89 |
|
|
JIT, and suffers recently from slow development.
|
90 |
|
|
|
91 |
|
|
@item @uref{http://www.intel.com/research/mrl/orp/,Intel's Open Runtime Platform}
|
92 |
|
|
Intel surprised us not long ago with the release of this rather advanced
|
93 |
|
|
VM that uses GNU Classpath for a set of class libraries and works on
|
94 |
|
|
Linux and Windows 2000. As of June, 2004, it does not appear that ORP
|
95 |
|
|
is under active development.
|
96 |
|
|
|
97 |
|
|
@item @uref{http://www.sablevm.org/,SableVM}
|
98 |
|
|
SableVM is a robust, extremely portable, efficient, and
|
99 |
|
|
specifications-compliant Java Virtual Machine that aims to be easy to
|
100 |
|
|
maintain and to extend. It features a state-of-the-art, efficient
|
101 |
|
|
interpreter engine. Its source code is very accessible and easy to
|
102 |
|
|
understand, and has many robustness features that have been the object
|
103 |
|
|
of careful design.
|
104 |
|
|
|
105 |
|
|
@item @uref{http://www.kaffe.org,Kaffe}
|
106 |
|
|
Kaffe is an advanced VM and together with its own class libraries
|
107 |
|
|
provides a Java 1.1 compatible environment.
|
108 |
|
|
|
109 |
|
|
@item @uref{http://www.mozilla.org/projects/ef,Electrical Fire}
|
110 |
|
|
The Electrical File VM continues to be listed as a Mozilla project
|
111 |
|
|
though development has been somewhat quiet. A number of concepts from
|
112 |
|
|
EF were expected at one point to be rolled into Japhar, but that
|
113 |
|
|
development has not occurred as of yet.
|
114 |
|
|
|
115 |
|
|
@item @uref{http://latte.snu.ac.kr/,LaTTe}
|
116 |
|
|
This VM project so far supports only Sun UltraSparc processors using the
|
117 |
|
|
proprietary Solaris 2.5.1 or higher operating system. LaTTe was derived
|
118 |
|
|
from Kaffe but claims a number of improvements.
|
119 |
|
|
|
120 |
|
|
@item @uref{http://gcc.gnu.org/java/,GNU Compiler for Java (GCJ)}
|
121 |
|
|
This is a portable, optimizing, ahead-of-time compiler for the Java
|
122 |
|
|
Programming Language. It can compile Java source code directly to native
|
123 |
|
|
machine code, Java source code to Java bytecode (class files), and Java
|
124 |
|
|
bytecode to native machine code. Compiled applications are linked with the
|
125 |
|
|
GCJ runtime, libgcj which is based on the GNU Classpath code, which provides
|
126 |
|
|
the core class libraries, a garbage collector, and a bytecode interpreter.
|
127 |
|
|
libgcj can dynamically load and interpret class files, resulting in mixed
|
128 |
|
|
compiled/interpreted applications.
|
129 |
|
|
GCJ is part of the GNU Compiler Collection (@uref{http://gcc.gnu.org/,GCC}).
|
130 |
|
|
On March 6 2000 the libgcj and GNU Classpath projects were officially merged
|
131 |
|
|
and there is active work on merging all the classes between the projects.
|
132 |
|
|
Licensed under GPL+exception, just as GNU Classpath is.
|
133 |
|
|
|
134 |
|
|
@item @uref{http://kissme.sourceforge.net/,Kissme}
|
135 |
|
|
This is a free Java Virtual Machine that is being developed on GNU/Linux
|
136 |
|
|
and can run console Java applications. Kissme also provides support for
|
137 |
|
|
orthogonally persistent Java.
|
138 |
|
|
@c I don't know what ``orthogonally persistent Java'' is, and I bet
|
139 |
|
|
@c there are other people don't know either. -- Steve Augart, 4 June 2004
|
140 |
|
|
|
141 |
|
|
@item @uref{http://jamvm.sourceforge.net/,JamVM}
|
142 |
|
|
A simple, small bytecode interpreter that works out-of-the-box with
|
143 |
|
|
pure GNU Classpath; it is emerging as the preferred platform for
|
144 |
|
|
quickly testing a new build of GNU Classpath. Licensed under the GPL.
|
145 |
|
|
|
146 |
|
|
@item @uref{http://oss.software.ibm.com/jikesrvm,Jikes RVM}
|
147 |
|
|
A free runtime environment for Java, written in Java. Works
|
148 |
|
|
out-of-the-box with pure GNU Classpath. Features an optimizing JIT.
|
149 |
|
|
Runs on the x86 and PowerPC architectures, on the AIX, Linux, and Mac
|
150 |
|
|
OS/X operating systems. Licensed under the CPL (Common Public
|
151 |
|
|
License). Extensively documented. Actively developed as of June,
|
152 |
|
|
2004.
|
153 |
|
|
|
154 |
|
|
@end itemize
|
155 |
|
|
|
156 |
|
|
In the past integration efforts were focused mainly on Japhar with an eye
|
157 |
|
|
towards getting Electrical Fire to work. Most information contained in
|
158 |
|
|
this document is gleaned from these efforts. Recently more work has been
|
159 |
|
|
done on getting gcj, orp and kissme to work out of the box with GNU Classpath
|
160 |
|
|
but there is much to do before that becomes a reality.
|
161 |
|
|
|
162 |
|
|
|
163 |
|
|
@node Initialization, Classpath Hooks, Introduction, Top
|
164 |
|
|
@comment node-name, next, previous, up
|
165 |
|
|
@chapter Initialization
|
166 |
|
|
|
167 |
|
|
The order of initialization, as far as I can tell, doesn't matter just
|
168 |
|
|
yet. However, when we move to 1.2 support, it probably will matter, so
|
169 |
|
|
we'll have a note in here at that time.
|
170 |
|
|
|
171 |
|
|
The initialization order is currently documented in the
|
172 |
|
|
@file{Runtime.java} source file.
|
173 |
|
|
|
174 |
|
|
@node Classpath Hooks, VM Hooks, Initialization, Top
|
175 |
|
|
@comment node-name, next, previous, up
|
176 |
|
|
@chapter Classpath Hooks
|
177 |
|
|
|
178 |
|
|
The primary method of interaction between Classpath and the VM is via
|
179 |
|
|
the helper classes, which are named after the relevant core library
|
180 |
|
|
class, but include an additional `VM' prefix. The library classes from
|
181 |
|
|
Classpath call out to these to get certain VM-specific dirty work done.
|
182 |
|
|
A reference copy of each VM class exists. The majority consist of a
|
183 |
|
|
series of static methods, some of which are simply declared
|
184 |
|
|
@code{native}, and some which provide a default implementation. VMs may
|
185 |
|
|
either use these as is, or create their own local variations. When
|
186 |
|
|
using the default implementations, the VM is responsible for
|
187 |
|
|
implementing any of the code marked as @code{native} which corresponds
|
188 |
|
|
to functionality they wish their VM to provide. When using their own
|
189 |
|
|
versions of the classes, VM implementors may choose to change the mix of
|
190 |
|
|
native and non-native methods from that below, so as to best suit their
|
191 |
|
|
implementation.
|
192 |
|
|
|
193 |
|
|
@menu
|
194 |
|
|
* java.lang::
|
195 |
|
|
* gnu.classpath::
|
196 |
|
|
* java.util::
|
197 |
|
|
* java.io::
|
198 |
|
|
* java.security::
|
199 |
|
|
* java.net::
|
200 |
|
|
* java.nio::
|
201 |
|
|
* java.nio.channels::
|
202 |
|
|
* gnu.java.nio::
|
203 |
|
|
* Classpath Callbacks::
|
204 |
|
|
@end menu
|
205 |
|
|
|
206 |
|
|
@node java.lang, gnu.classpath, Classpath Hooks, Classpath Hooks
|
207 |
|
|
@comment node-name, next, previous, up
|
208 |
|
|
|
209 |
|
|
@section @code{java.lang}
|
210 |
|
|
|
211 |
|
|
@code{java.lang} is the core Java package, being imported automatically by all
|
212 |
|
|
classes. It includes basic classes as @code{Object} and @code{String}.
|
213 |
|
|
A VM must implement at least some parts of this package in order to
|
214 |
|
|
become operable.
|
215 |
|
|
|
216 |
|
|
@menu
|
217 |
|
|
* java.lang.VMClass::
|
218 |
|
|
* java.lang.VMObject::
|
219 |
|
|
* java.lang.VMClassLoader::
|
220 |
|
|
* java.lang.VMSystem::
|
221 |
|
|
* java.lang.VMThrowable::
|
222 |
|
|
* java.lang.VMCompiler::
|
223 |
|
|
* java.lang.VMDouble::
|
224 |
|
|
* java.lang.VMFloat::
|
225 |
|
|
* java.lang.VMProcess::
|
226 |
|
|
* java.lang.VMRuntime::
|
227 |
|
|
* java.lang.VMString::
|
228 |
|
|
* java.lang.VMThread::
|
229 |
|
|
@end menu
|
230 |
|
|
|
231 |
|
|
@node java.lang.VMClass, java.lang.VMObject ,java.lang,java.lang
|
232 |
|
|
@subsection @code{java.lang.VMClass}
|
233 |
|
|
|
234 |
|
|
The core class, @code{java.lang.Class}, and the corresponding VM class,
|
235 |
|
|
@code{java.lang.VMClass}, provide two main functions within GNU Classpath.
|
236 |
|
|
|
237 |
|
|
@enumerate
|
238 |
|
|
@item For basic VM operation, @code{java.lang.Class} provides the link between
|
239 |
|
|
the Java-based representation of a class it embodies and the VM's own
|
240 |
|
|
internal structure for a class. @xref{VM Hooks}.
|
241 |
|
|
|
242 |
|
|
@item As far as the user is concerned, the main function of
|
243 |
|
|
@code{java.lang.Class} is as an entry point to the reflection
|
244 |
|
|
facilities, and so it also provides this functionality, backed by the
|
245 |
|
|
VM class.
|
246 |
|
|
@end enumerate
|
247 |
|
|
|
248 |
|
|
This VM class lists the following methods, organized by the version of the
|
249 |
|
|
Java specification in which they occur. All are @code{native}, unless
|
250 |
|
|
otherwise specified, and pertain to reflection. As a result, the VM only
|
251 |
|
|
needs to implement these methods in order to provide reflection support,
|
252 |
|
|
and then only to the degree required.
|
253 |
|
|
|
254 |
|
|
@itemize @bullet
|
255 |
|
|
@item 1.0
|
256 |
|
|
@itemize @bullet
|
257 |
|
|
@item @code{isInterface(Class)} -- This is simply a property test, and matches
|
258 |
|
|
the presence of an appropriate flag within the class file.
|
259 |
|
|
@item @code{getName(Class)} -- Returns the fully-qualified name of the class.
|
260 |
|
|
@item @code{getSuperclass(Class)} -- Returns a @code{Class} instance which
|
261 |
|
|
represents the superclass. Again, the class file contains an element directly
|
262 |
|
|
relating to this. @code{null} is returned for primitives, interfaces and
|
263 |
|
|
@code{Object}.
|
264 |
|
|
@item @code{getInterfaces(Class)} -- Same as the above, but the implemented
|
265 |
|
|
or extended interfaces rather than the superclass. An empty array should
|
266 |
|
|
be returned, rather than @code{null}.
|
267 |
|
|
@item @code{getDeclaredClasses(Class,boolean)} -- Returns the internal classes
|
268 |
|
|
this instance declares directly. The flag determines whether or not the
|
269 |
|
|
VM should filter out non-public classes.
|
270 |
|
|
@item @code{getDeclaredFields(Class,boolean)} -- The same for fields.
|
271 |
|
|
@item @code{getDeclaredMethods(Class,boolean)} -- And for methods.
|
272 |
|
|
@item @code{getDeclaredConstructors(Class,boolean)} -- And constructors.
|
273 |
|
|
@item @code{getClassLoader(Class)} -- Returns the @code{ClassLoader} instance
|
274 |
|
|
which is responsible for the specified class.
|
275 |
|
|
@item @code{forName(String)} -- The VM should create a @code{Class} instance
|
276 |
|
|
corresponding to the named class. As noted in @ref{VM Hooks}, the internal
|
277 |
|
|
content of the instance is the responsibility of the VM.
|
278 |
|
|
@item @code{isArray(Class)} -- Another property test, corresponding to a
|
279 |
|
|
class file flag.
|
280 |
|
|
@item @code{initialize(Class)} -- The VM should initialize the class fully,
|
281 |
|
|
if it has not already done so.
|
282 |
|
|
@item @code{loadArrayClass(String,ClassLoader)} -- This is called if
|
283 |
|
|
@code{forName} returns @code{null} and the string specifies an array class.
|
284 |
|
|
The specified array class should be loaded with the supplied class loader.
|
285 |
|
|
@item @code{throwException(Throwable)} -- The VM should throw the supplied
|
286 |
|
|
checked exception, without declaring it.
|
287 |
|
|
@end itemize
|
288 |
|
|
@item 1.1
|
289 |
|
|
@itemize @bullet
|
290 |
|
|
@item @code{isInstance(Class,Object)} -- This is a reflection-based equivalent
|
291 |
|
|
of the @code{instanceof} operator.
|
292 |
|
|
@item @code{isAssignableFrom(Class,Class)} -- Mainly a shorthand for the above,
|
293 |
|
|
removing the need to create an instance to test assignability.
|
294 |
|
|
@item @code{isPrimitive(Class)} -- Returns true if this class is simply
|
295 |
|
|
a representation of one of the primitive types: @code{boolean}, @code{byte},
|
296 |
|
|
@code{char}, @code{short}, @code{int}, @code{long}, @code{float},
|
297 |
|
|
@code{double} and @code{void}.
|
298 |
|
|
@item @code{getComponentType(Class)} -- Produces a @code{Class} instance which
|
299 |
|
|
represents the type of the members of the array the class instance represents.
|
300 |
|
|
Classes which don't represent an array type return @code{null}.
|
301 |
|
|
@item @code{getModifiers(Class,boolean)} -- Returns an integer which encodes
|
302 |
|
|
the class' modifiers, such as @code{public}. Again, this relates to
|
303 |
|
|
information stored in the class file.
|
304 |
|
|
@item @code{getDeclaringClass(Class)} -- Returns the class that declared
|
305 |
|
|
an inner or member class, or @code{null} if the instance refers to a top-level
|
306 |
|
|
class.
|
307 |
|
|
@end itemize
|
308 |
|
|
@end itemize
|
309 |
|
|
|
310 |
|
|
@node java.lang.VMObject, java.lang.VMClassLoader, java.lang.VMClass, java.lang
|
311 |
|
|
@subsection @code{java.lang.VMObject}
|
312 |
|
|
|
313 |
|
|
@code{VMObject} is the bridge between the low level @code{Object} facilities
|
314 |
|
|
such as making a clone, getting the class of the object and the wait/notify
|
315 |
|
|
semantics. This is accomplished using the following @code{native}
|
316 |
|
|
methods.
|
317 |
|
|
|
318 |
|
|
@itemize @bullet
|
319 |
|
|
@item @code{getClass(Object)} -- Returns the @code{Class} instance for the
|
320 |
|
|
object. @code{Class} objects are produced by the VM, as described in
|
321 |
|
|
@ref{VM Hooks}.
|
322 |
|
|
@item @code{clone(Cloneable)} -- The VM should produce a low-level clone of the
|
323 |
|
|
specified object, creating a field-by-field shallow copy of the original.
|
324 |
|
|
The only difference between the two is that the new object should still be
|
325 |
|
|
@code{finalizable}, even if the original is not.
|
326 |
|
|
@item @code{notify(Object)} -- The VM should choose one of the threads waiting
|
327 |
|
|
for a lock on the specified object arbitrarily, and wake it. If the current
|
328 |
|
|
thread does not currently hold the lock on the object, then an
|
329 |
|
|
@code{IllegalMonitorStateException} should be thrown.
|
330 |
|
|
@item @code{notifyAll(Object)} -- Same as the above, but all threads are
|
331 |
|
|
awakened.
|
332 |
|
|
@item @code{wait(Object,long,int)} -- The VM should set the current thread
|
333 |
|
|
into a waiting state, which persists until it receives a notify signal or the
|
334 |
|
|
specified time (in milliseconds and nanoseconds) is exceeded. The nanoseconds
|
335 |
|
|
restriction may be ignored if such granularity is not available, and a
|
336 |
|
|
@code{IllegalMonitorStateException} should be thrown if the current thread
|
337 |
|
|
doesn't own the object.
|
338 |
|
|
@end itemize
|
339 |
|
|
|
340 |
|
|
@node java.lang.VMClassLoader, java.lang.VMSystem, java.lang.VMObject, java.lang
|
341 |
|
|
@subsection @code{java.lang.VMClassLoader}
|
342 |
|
|
@code{VMClassLoader} provides methods for defining and resolving core and
|
343 |
|
|
primitive classes, as well as handling resources, packages and assertions.
|
344 |
|
|
The class is a mixture of @code{native} methods and Java-based
|
345 |
|
|
implementations, with some of the latter being @emph{stubs}.
|
346 |
|
|
|
347 |
|
|
@itemize @bullet
|
348 |
|
|
@item Native Methods
|
349 |
|
|
@itemize @bullet
|
350 |
|
|
@item @code{defineClass(ClassLoader,String,byte[],int,int,ProtectionDomain)}
|
351 |
|
|
-- The VM should create a @code{Class} instance from the supplied byte array.
|
352 |
|
|
@item @code{resolveClass(Class)} -- Resolve references to other classes in the
|
353 |
|
|
supplied class.
|
354 |
|
|
@item @code{loadClass(name,boolean)} -- Load a class using the bootstrap
|
355 |
|
|
loader.
|
356 |
|
|
@item @code{getPrimitiveClass(char)} -- The VM should provide a @code{Class}
|
357 |
|
|
implementation for one of the primitive classes. The supplied character
|
358 |
|
|
matches the JNI code for the primitive class e.g. `B' for byte and
|
359 |
|
|
`Z' for boolean.
|
360 |
|
|
@end itemize
|
361 |
|
|
@item Java Methods
|
362 |
|
|
@itemize @bullet
|
363 |
|
|
@item @code{getResource(String)} -- The default implementation calls
|
364 |
|
|
@code{getResources} and returns the first element in the returned enumeration,
|
365 |
|
|
or @code{null} if there are no elements.
|
366 |
|
|
@item @code{getResources(String)} -- By default, this compiles a list of
|
367 |
|
|
URLs via the boot class path. Any matching files within a zip file are added,
|
368 |
|
|
and directories on the boot class path are automatically converted to file
|
369 |
|
|
URLs that refer to join the directory with the resource name (whether or not
|
370 |
|
|
it actually exists).
|
371 |
|
|
@item @code{getPackage(String)} -- Always returns null, which may be suitable
|
372 |
|
|
if the VM does not wish to return a @code{Package} implementation. Otherwise,
|
373 |
|
|
it may be necessary to make this a @code{native} method.
|
374 |
|
|
@item @code{getPackages()} -- As with the last, a default stub implementation
|
375 |
|
|
exists (returning an empty array) which may be replaced if support is
|
376 |
|
|
required.
|
377 |
|
|
@item @code{defaultAssertionStatus()} -- A stub which can be implemented
|
378 |
|
|
by VMs providing assertion support. At present, it always returns @code{true}.
|
379 |
|
|
@item @code{packageAssertionStatus()} -- Much the same status as the above.
|
380 |
|
|
The method should return a map converting package names to boolean status
|
381 |
|
|
values. The stub implementation provides an empty map.
|
382 |
|
|
@item @code{classAssertionStatus()} -- Same as the last, but for classes.
|
383 |
|
|
@item @code{getSystemClassLoader()} -- The default calls @code{ClassLoader}
|
384 |
|
|
to create a new auxillary class loader with a system and extension class
|
385 |
|
|
loader. The VM may wish to replace it if it wishes to supply its own custom
|
386 |
|
|
system class loader.
|
387 |
|
|
@end itemize
|
388 |
|
|
@end itemize
|
389 |
|
|
@node java.lang.VMSystem, java.lang.VMThrowable, java.lang.VMClassLoader, java.lang
|
390 |
|
|
@subsection @code{java.lang.VMSystem}
|
391 |
|
|
@code{VMSystem} handles the default I/O streams, provides access to the
|
392 |
|
|
system clock and environment variables and provides methods for
|
393 |
|
|
@code{System.arraycopy} and the @code{identityHashCode} of an
|
394 |
|
|
@code{Object}. It consists of @code{native} methods, but the default
|
395 |
|
|
implementation also provides some helper methods to simplify stream
|
396 |
|
|
creation.
|
397 |
|
|
|
398 |
|
|
@itemize @bullet
|
399 |
|
|
@item Native Methods
|
400 |
|
|
@itemize @bullet
|
401 |
|
|
@item @code{arraycopy(Object,int,Object,int,int)} -- The VM should copy
|
402 |
|
|
a specified number of array objects from one array to another, with
|
403 |
|
|
appropriate checks for compatible typing, available elements and space.
|
404 |
|
|
The VM should be able to perform this more efficiently using native code
|
405 |
|
|
and direct memory manipulation than would have been achieved by using Java.
|
406 |
|
|
@item @code{identityHashCode(Object)} -- This is the hashcode for
|
407 |
|
|
@code{Object}, which relates to the actual location of the object in memory.
|
408 |
|
|
@item @code{setIn(InputStream)} -- Set the system input stream.
|
409 |
|
|
@item @code{setOut(PrintStream)} -- Set the system output stream.
|
410 |
|
|
@item @code{setErr(PrintStream)} -- Set the system error stream.
|
411 |
|
|
@item @code{currentTimeMillis()} -- Gets the system time in milliseconds.
|
412 |
|
|
@item @code{getenv(String)} -- Returns the value of the specified environment
|
413 |
|
|
variable.
|
414 |
|
|
@end itemize
|
415 |
|
|
@item Java Methods
|
416 |
|
|
@itemize @bullet
|
417 |
|
|
@item @code{makeStandardInputStream()} -- Helps provide the functionality of
|
418 |
|
|
@code{System.in} by wrapping the appropriate file descriptor in a buffered
|
419 |
|
|
file input stream. VMs may choose to create the stream from the descriptor
|
420 |
|
|
differently rather than using this method.
|
421 |
|
|
@item @code{makeStandardOutputStream()} -- Helps provide the functionality of
|
422 |
|
|
@code{System.out} by wrapping the appropriate file descriptor in a buffered
|
423 |
|
|
file output stream. VMs may choose to create the stream from the descriptor
|
424 |
|
|
differently rather than using this method.
|
425 |
|
|
@item @code{makeStandardErrorStream()} -- Helps provide the functionality of
|
426 |
|
|
@code{System.err} by wrapping the appropriate file descriptor in a buffered
|
427 |
|
|
file output stream. VMs may choose to create the stream from the descriptor
|
428 |
|
|
differently rather than using this method.
|
429 |
|
|
@end itemize
|
430 |
|
|
@end itemize
|
431 |
|
|
|
432 |
|
|
Classpath also provides native implementations of
|
433 |
|
|
|
434 |
|
|
@itemize @bullet
|
435 |
|
|
@item @code{setIn(InputStream)}
|
436 |
|
|
@item @code{setOut(PrintStream)}
|
437 |
|
|
@item @code{setErr(PrintStream)}
|
438 |
|
|
@item @code{currentTimeMillis()}
|
439 |
|
|
@item @code{getenv(String)}
|
440 |
|
|
@end itemize
|
441 |
|
|
|
442 |
|
|
making a VM implementation optional.
|
443 |
|
|
|
444 |
|
|
@node java.lang.VMThrowable, java.lang.VMCompiler, java.lang.VMSystem, java.lang
|
445 |
|
|
@subsection @code{java.lang.VMThrowable}
|
446 |
|
|
@code{VMThrowable} is used to hold the VM state of a throwable, created either
|
447 |
|
|
when a @code{Throwable} is created or the @code{fillInStackTrace()} method is
|
448 |
|
|
called (i.e. when the actual stack trace is needed, as a lot of exceptions are
|
449 |
|
|
never actually used). The actual class has two @code{native} methods,
|
450 |
|
|
one (@code{fillInStackTrace()}) being a method of the class used to obtain
|
451 |
|
|
instances, and the other an instance method, @code{getStackTrace()}.
|
452 |
|
|
@itemize @bullet
|
453 |
|
|
@item @code{fillInStackTrace(Throwable)} -- The VM should return the current
|
454 |
|
|
execution state of the @code{Throwable} in the form of a @code{VMThrowable}
|
455 |
|
|
instance. The VM may also return @code{null} if it does not support this
|
456 |
|
|
functionality.
|
457 |
|
|
@item @code{getStackTrace()} -- This is used to create a real
|
458 |
|
|
@code{StackTraceElement} array for the exception, using the state data
|
459 |
|
|
stored during creation of the instance.
|
460 |
|
|
@end itemize
|
461 |
|
|
|
462 |
|
|
@node java.lang.VMCompiler, java.lang.VMDouble, java.lang.VMThrowable, java.lang
|
463 |
|
|
@subsection @code{java.lang.VMCompiler}
|
464 |
|
|
|
465 |
|
|
@code{VMCompiler} provides an interface for VMs which wish to provide
|
466 |
|
|
JIT compilation support. The default implementation is simply a series
|
467 |
|
|
of stubs. The property, @code{java.compiler}, should point to a library
|
468 |
|
|
containing the function @code{java_lang_Compiler_start()} if such support
|
469 |
|
|
is to be provided.
|
470 |
|
|
|
471 |
|
|
@itemize @bullet
|
472 |
|
|
@item @code{compileClass(Class)} -- Invoke the compiler to compile the specific
|
473 |
|
|
class, returning @code{true} if successful.
|
474 |
|
|
@item @code{compileClasses(String)} -- The compiler should compile the classes
|
475 |
|
|
matching the specified string, again returning @code{true} on success.
|
476 |
|
|
@item @code{command(Object)} -- The object represents a command given to the
|
477 |
|
|
compiler, and is specific to the compiler implementation.
|
478 |
|
|
@item @code{enable} -- Enable the operation of the compiler.
|
479 |
|
|
@item @code{disable} -- Disable compiler operation.
|
480 |
|
|
@end itemize
|
481 |
|
|
|
482 |
|
|
@node java.lang.VMDouble, java.lang.VMFloat, java.lang.VMCompiler, java.lang
|
483 |
|
|
@subsection @code{java.lang.VMDouble}
|
484 |
|
|
|
485 |
|
|
@code{VMDouble} provides native support for the conversion and parsing
|
486 |
|
|
of doubles.
|
487 |
|
|
|
488 |
|
|
@itemize @bullet
|
489 |
|
|
@item @code{doubleToLongBits(double)} -- Converts the double to the IEEE 754
|
490 |
|
|
bit layout, collapsing NaNs to @code{0x7ff8000000000000L}.
|
491 |
|
|
@item @code{doubleToRawLongBits(double)} -- Same as the above, but preserves
|
492 |
|
|
NaNs.
|
493 |
|
|
@item @code{longBitsToDouble(long)} -- This is the inverse of the last method,
|
494 |
|
|
preserving NaNs so that the output of one can be fed into the other without
|
495 |
|
|
data loss.
|
496 |
|
|
@item @code{toString(double,boolean)} -- Converts the double to a string,
|
497 |
|
|
giving a shorter value if the flag @code{isFloat} is @code{true}, indicating
|
498 |
|
|
that the conversion was requested by @code{java.lang.Float} rather than
|
499 |
|
|
@code{java.lang.Double}.
|
500 |
|
|
@item @code{initIDs} -- Used by JNI-based solutions to initialize the cache
|
501 |
|
|
of the static field IDs. The default @code{VMDouble} implementation has a
|
502 |
|
|
static initializer which loads the JNI library and calls this method.
|
503 |
|
|
@item @code{parseDouble} -- Turn the string into a usable double value.
|
504 |
|
|
@end itemize
|
505 |
|
|
|
506 |
|
|
Classpath provides native implementations of all these, making VM
|
507 |
|
|
implementation optional.
|
508 |
|
|
|
509 |
|
|
@node java.lang.VMFloat, java.lang.VMProcess, java.lang.VMDouble, java.lang
|
510 |
|
|
@subsection @code{java.lang.VMFloat}
|
511 |
|
|
|
512 |
|
|
@code{VMFloat} provides native support for the conversion of floats.
|
513 |
|
|
|
514 |
|
|
@itemize @bullet
|
515 |
|
|
@item @code{floatToIntBits(float)} -- Converts the float to the IEEE 754
|
516 |
|
|
bit layout, collapsing NaNs to @code{0x7fc00000}.
|
517 |
|
|
@item @code{floatToRawIntBits(float)} -- Same as the above, but preserves
|
518 |
|
|
NaNs.
|
519 |
|
|
@item @code{intBitsToFloat(int)} -- This is the inverse of the last method,
|
520 |
|
|
preserving NaNs so that the output of one can be fed into the other without
|
521 |
|
|
data loss.
|
522 |
|
|
@end itemize
|
523 |
|
|
|
524 |
|
|
Classpath provides native implementations of all these, making VM
|
525 |
|
|
implementation optional.
|
526 |
|
|
|
527 |
|
|
@node java.lang.VMProcess, java.lang.VMRuntime, java.lang.VMFloat, java.lang
|
528 |
|
|
@subsection @code{java.lang.VMProcess}
|
529 |
|
|
|
530 |
|
|
@code{VMProcess} handles the execution of external processes. In the
|
531 |
|
|
default implementation, threads are spawned and reaped by @code{ProcessThread}.
|
532 |
|
|
A constructor creates a new @code{VMProcess}, which extends rather than
|
533 |
|
|
complements @code{Process}, using an array of arguments, an array of
|
534 |
|
|
environment variables and a working directory. The instance maintains
|
535 |
|
|
system input, output and error streams linked to the external process.
|
536 |
|
|
Three @code{native} methods are used, and implementations are provided
|
537 |
|
|
for all three by Classpath, making VM implementation optional. These use
|
538 |
|
|
the POSIX functions, @code{fork()}, @code{waitpid()} and @code{kill()}.
|
539 |
|
|
|
540 |
|
|
@itemize @bullet
|
541 |
|
|
@item @code{nativeSpawn(String[],String[],File)} -- The VM should create a
|
542 |
|
|
new process which uses the specified command-line arguments, environment
|
543 |
|
|
variables and working directory. Unlike the other two methods, this
|
544 |
|
|
method is linked to an instance, and must call @code{setProcessInfo()} with
|
545 |
|
|
the results before returning.
|
546 |
|
|
@item @code{nativeReap()} -- This is called to perform a reap of any
|
547 |
|
|
zombie processes, and should not block, instead returning a boolean as to
|
548 |
|
|
whether reaping actually took place.
|
549 |
|
|
@item @code{nativeKill(long)} -- The VM should terminate the specified PID.
|
550 |
|
|
@end itemize
|
551 |
|
|
|
552 |
|
|
@node java.lang.VMRuntime, java.lang.VMString, java.lang.VMProcess, java.lang
|
553 |
|
|
@subsection @code{java.lang.VMRuntime}
|
554 |
|
|
|
555 |
|
|
The @code{VMRuntime} class provides a series of native methods
|
556 |
|
|
which divulge information about the runtime or invoke certain
|
557 |
|
|
operations. This includes retrieving the amount of available memory,
|
558 |
|
|
and scheduling the garbage collector. There are two exceptions: the
|
559 |
|
|
@code{enableShutdownHooks} method, which allows the VM to put in its own
|
560 |
|
|
shutdown hooks when @code{Runtime.addShutdownHook()} is first invoked,
|
561 |
|
|
and @code{exec(String[],String[],File)} which spawns an external process.
|
562 |
|
|
These are Java-based static methods instead. The first is simply a stub by
|
563 |
|
|
default, while the second simply links to the functionality of
|
564 |
|
|
@code{VMProcess} (and should be changed if a different @code{Process}
|
565 |
|
|
implementation is used).
|
566 |
|
|
|
567 |
|
|
@itemize @bullet
|
568 |
|
|
@item @code{availableProcessors()} -- Returns the number of processors
|
569 |
|
|
available to the VM.
|
570 |
|
|
@item @code{freeMemory()} -- Returns the amount of memory the VM has available
|
571 |
|
|
on the heap for allocating.
|
572 |
|
|
@item @code{totalMemory()} -- Returns the size of the heap.
|
573 |
|
|
@item @code{maxMemory()} -- Returns the maximum memory block the VM will
|
574 |
|
|
attempt to allocate. May be simply @code{Long.MAX_VALUE} (8 exabytes!)
|
575 |
|
|
@item @code{gc()} -- Allows users to explicitly invoke the garbage collector.
|
576 |
|
|
This is a suggestion to the VM, rather than a command, and the garbage
|
577 |
|
|
collector should run anyway @emph{without} it being invoked.
|
578 |
|
|
@item @code{runFinalization()} -- Like the above, but related to the
|
579 |
|
|
finalilzation of objects rather than the garbage collector.
|
580 |
|
|
@item @code{runFinalizationForExit()} -- Called immediately prior to VM
|
581 |
|
|
shutdown in order to finalize all objects (including `live' ones)
|
582 |
|
|
@item @code{traceInstructions(boolean)} -- This turns on and off the optional
|
583 |
|
|
VM functionality of printing a trace of executed bytecode instructions.
|
584 |
|
|
@item @code{traceMethodCalls(boolean)} -- This turns on and off the optional
|
585 |
|
|
VM functionality of printing a trace of methods called.
|
586 |
|
|
@item @code{runFinalizersOnExit(boolean)} -- A toggleable setting for
|
587 |
|
|
running the finalization process at exit.
|
588 |
|
|
@item @code{exit(int)} -- The VM should shutdown with the specified exit code.
|
589 |
|
|
@item @code{nativeLoad(String,ClassLoader)} -- Attempts to load a file,
|
590 |
|
|
returning an integer which is non-zero for success. Nothing happens if the
|
591 |
|
|
file has already been loaded.
|
592 |
|
|
@item @code{mapLibraryName(String)} -- The VM should map the system-independent
|
593 |
|
|
library name supplied to the platform-dependent equivalent (e.g. a @code{.so}
|
594 |
|
|
or @code{.dll} file)
|
595 |
|
|
@end itemize
|
596 |
|
|
|
597 |
|
|
@node java.lang.VMString, java.lang.VMThread, java.lang.VMRuntime, java.lang
|
598 |
|
|
@subsection @code{java.lang.VMString}
|
599 |
|
|
@code{VMString} is responsible for handling interned strings. If two strings
|
600 |
|
|
are equal (using the @code{equals()} method), then the results of calling
|
601 |
|
|
the @code{intern()} method on each of them makes them equal
|
602 |
|
|
(using @code{==}). Thus, the same string object is always returned by
|
603 |
|
|
@code{intern} if the two strings are equal. The default implementation
|
604 |
|
|
is Java-based and implements @code{intern(String)} by maintaining a
|
605 |
|
|
@code{WeakHashMap} which links the strings to their @code{WeakReference}.
|
606 |
|
|
A new mapping is created for each new string being @code{intern}ed.
|
607 |
|
|
A VM may implement this differently by implementing this method,
|
608 |
|
|
which is @code{static} and the only one in @code{VMString}.
|
609 |
|
|
|
610 |
|
|
@node java.lang.VMThread,, java.lang.VMString, java.lang
|
611 |
|
|
@subsection @code{java.lang.VMThread}
|
612 |
|
|
|
613 |
|
|
@code{VMThread} provides the link between Java's threads and the platform
|
614 |
|
|
threading support. A @code{VMThread} is created via a private constructor
|
615 |
|
|
and linked to a @code{Thread} instance. This occurs when the @code{Thread}
|
616 |
|
|
instance is started by the static @code{create(Thread,long)} method (the second
|
617 |
|
|
argument requests a certain stack size, usually zero). The thread itself is
|
618 |
|
|
executed via the @code{run()} method, which handles any problems with the
|
619 |
|
|
running of the thread and its eventual death.
|
620 |
|
|
|
621 |
|
|
@code{VMThread} provides the following accessors and mutators for accessing
|
622 |
|
|
the thread state via @code{VMThread},
|
623 |
|
|
|
624 |
|
|
@itemize @bullet
|
625 |
|
|
@item @code{getName()}
|
626 |
|
|
@item @code{setName(String)}
|
627 |
|
|
@item @code{getPriority()}
|
628 |
|
|
@item @code{setPriotity(int)}
|
629 |
|
|
@item @code{isDaemon()}
|
630 |
|
|
@end itemize
|
631 |
|
|
|
632 |
|
|
all of which refer to the @code{Thread} instance. @code{setPriority(int)} also
|
633 |
|
|
calls the appropriate native method. @code{stop(Throwable)} similarly wraps
|
634 |
|
|
a native method, merely adding in a check for the state of the thread.
|
635 |
|
|
|
636 |
|
|
The default implementation also provides Java-based implementations of
|
637 |
|
|
@code{join(long,int)}, @code{sleep(long,int)} and
|
638 |
|
|
@code{holdsLock(Object)}. @code{join} and @code{sleep} simply wait for
|
639 |
|
|
the appropriate amount of time, with @code{join} additionally waiting
|
640 |
|
|
for the thread instance to become @code{null}. @code{holdsLock} simply
|
641 |
|
|
checks if an object is locked by the current thread by trying to invoke
|
642 |
|
|
the @code{notify} method, and catching the failing exception if this is
|
643 |
|
|
not the case.
|
644 |
|
|
|
645 |
|
|
The remainder of the class is a series of @code{native} methods, some of
|
646 |
|
|
which are mandatory for VM implementation and others which provide optional
|
647 |
|
|
or deprecated functionality.
|
648 |
|
|
|
649 |
|
|
@itemize @bullet
|
650 |
|
|
@item Mandatory Instance Methods
|
651 |
|
|
@itemize @bullet
|
652 |
|
|
@item @code{start(long)} -- The VM should create the native thread and start
|
653 |
|
|
it running using the @code{run} method of the @code{VMThread} instance on
|
654 |
|
|
which this method is called.
|
655 |
|
|
@item @code{interrupt()} -- The VM should interrupt the running thread and
|
656 |
|
|
throw an appropriate exception.
|
657 |
|
|
@item @code{isInterrupted()} -- Checks the interrupted state of the thread.
|
658 |
|
|
@item @code{suspend()} -- The thread should be suspended until resumed.
|
659 |
|
|
@item @code{resume()} -- The thread should be resumed from its suspended state.
|
660 |
|
|
This pair of methods are deprecated, due to the possibility of a deadlock
|
661 |
|
|
occuring when a thread with locks is suspended.
|
662 |
|
|
@item @code{nativeSetPriority(int)} -- Called by @code{setPriority}
|
663 |
|
|
to allow the setting to flow down to the native thread.
|
664 |
|
|
@item @code{nativeStop(Throwable)} -- The VM should stop the thread abnormally
|
665 |
|
|
and throw the specified exception. This is clearly deprecated, due to the
|
666 |
|
|
ambiguous state an abruptly-stopped thread may leave.
|
667 |
|
|
@end itemize
|
668 |
|
|
@item Mandatory Class Methods
|
669 |
|
|
@itemize @bullet
|
670 |
|
|
@item @code{currentThread()} -- Return a reference to the thread currently
|
671 |
|
|
being executed.
|
672 |
|
|
@item @code{yield()} -- The VM should allow some other thread to run.
|
673 |
|
|
The current thread maintains its locks even though it stops executing for
|
674 |
|
|
the time being.
|
675 |
|
|
@item @code{interrupted()} -- A shortcut to obtaining the interrupted state
|
676 |
|
|
of the current thread.
|
677 |
|
|
@end itemize
|
678 |
|
|
@item Other Methods
|
679 |
|
|
@itemize @bullet
|
680 |
|
|
@item @code{countStackFrames()} -- Returns a count of the number of stack
|
681 |
|
|
frames in the thread. This depends on the deprecated method @code{suspend()}
|
682 |
|
|
having returned true, and is thus deprecated as a result.
|
683 |
|
|
@end itemize
|
684 |
|
|
@end itemize
|
685 |
|
|
|
686 |
|
|
@node gnu.classpath, java.util, java.lang, Classpath Hooks
|
687 |
|
|
@section @code{gnu.classpath}
|
688 |
|
|
|
689 |
|
|
The @code{gnu.classpath} package provides Classpath-specific functionality,
|
690 |
|
|
primarily relating to the features in @code{java.lang}. At present, this
|
691 |
|
|
includes the context of a class (the stack) and the system properties.
|
692 |
|
|
|
693 |
|
|
@menu
|
694 |
|
|
* gnu.classpath.VMStackWalker::
|
695 |
|
|
* gnu.classpath.VMSystemProperties::
|
696 |
|
|
@end menu
|
697 |
|
|
|
698 |
|
|
@node gnu.classpath.VMStackWalker,gnu.classpath.VMSystemProperties,gnu.classpath,gnu.classpath
|
699 |
|
|
@subsection @code{gnu.classpath.VMStackWalker}
|
700 |
|
|
|
701 |
|
|
@code{VMStackWalker} provides access to the class context or stack. The
|
702 |
|
|
default implementation consists of a @code{native} @code{static} method,
|
703 |
|
|
@code{getClassContext()}, which obtains the class context, and two helper
|
704 |
|
|
methods which obtain the calling class (the 3rd element in the context array)
|
705 |
|
|
and its class loader, respectively.
|
706 |
|
|
|
707 |
|
|
@itemize @bullet
|
708 |
|
|
@item @code{getClassContext()} -- The VM should return an array of
|
709 |
|
|
@code{Class} objects, each of which relates to the method currently being
|
710 |
|
|
executed at that point on the stack. Thus, the first item (index 0) is the
|
711 |
|
|
class that contains this method.
|
712 |
|
|
@item @code{getCallingClass()} -- A Java-based helper method which returns
|
713 |
|
|
the @code{Class} object which contains the method that called the method
|
714 |
|
|
accessing @code{getCallingClass()}.
|
715 |
|
|
@item @code{getCallingClassLoader()} -- Like the last, but returning the class
|
716 |
|
|
loader of the class.
|
717 |
|
|
@end itemize
|
718 |
|
|
|
719 |
|
|
@node gnu.classpath.VMSystemProperties,,gnu.classpath.VMStackWalker,gnu.classpath
|
720 |
|
|
@subsection @code{gnu.classpath.VMSystemProperties}
|
721 |
|
|
|
722 |
|
|
@code{VMSystemProperties} allows the VM to hook into the property creation
|
723 |
|
|
process, both before and after the system properties are added by GNU
|
724 |
|
|
Classpath. The default implementation assumes that the VM will add its
|
725 |
|
|
properties first, by making the pre-initialisation method @code{native},
|
726 |
|
|
and that the Classpath properties may then be altered by a Java-based
|
727 |
|
|
post-initialisation method.
|
728 |
|
|
|
729 |
|
|
As these methods are called as part of the bootstrap process, caution should
|
730 |
|
|
be used as to what classes are used, and properties should only be set
|
731 |
|
|
using @code{Properties.setProperty()}. Specifically, I/O classes should be
|
732 |
|
|
avoided at this early stage.
|
733 |
|
|
|
734 |
|
|
@itemize @bullet
|
735 |
|
|
@item @code{preInit(Properties)} -- Allows the VM to add properties
|
736 |
|
|
@emph{before} the Classpath properties are added. The default implementation
|
737 |
|
|
includes a full list of properties that @emph{must} be added by the VM, but
|
738 |
|
|
additional VM-specific ones may also be added.
|
739 |
|
|
@item @code{postInit(Properties)} -- Same as the last, but called after the
|
740 |
|
|
Classpath properties have been added. The main purpose of this is to allow
|
741 |
|
|
the VM to alter the properties added by GNU Classpath to suit it.
|
742 |
|
|
@end itemize
|
743 |
|
|
|
744 |
|
|
@node java.util, java.io, gnu.classpath, Classpath Hooks
|
745 |
|
|
@section java.util
|
746 |
|
|
|
747 |
|
|
The @code{java.util} VM hooks provide links between the mix of functionality
|
748 |
|
|
present in that package, which includes collections, date and time handling
|
749 |
|
|
and parsing. At present, there is only one hook, which connects GNU Classpath
|
750 |
|
|
to the timezone information provided by the underlying platform.
|
751 |
|
|
|
752 |
|
|
@menu
|
753 |
|
|
* java.util.VMTimeZone::
|
754 |
|
|
@end menu
|
755 |
|
|
|
756 |
|
|
@node java.util.VMTimeZone,,java.util,java.util
|
757 |
|
|
@subsection @code{java.util.VMTimeZone}
|
758 |
|
|
|
759 |
|
|
@code{VMTimeZone} joins @code{TimeZone} to the platform timezone information
|
760 |
|
|
via the static method, @code{getDefaultTimeZoneId()}. The VM hook is
|
761 |
|
|
expected to return a @code{TimeZone} instance that represents the current
|
762 |
|
|
timezone in use by the platform. The default implementation provides
|
763 |
|
|
this functionality for POSIX or GNU-like systems, and VMs that want this
|
764 |
|
|
functionality can keep this implementation and implement the native
|
765 |
|
|
method, @code{getSystemTimeZoneId()}. This method is only called when
|
766 |
|
|
obtaining the timezone name from the @code{TZ} environment variable,
|
767 |
|
|
@code{/etc/timezone} and @code{/etc/localtime} all fail. This fallback
|
768 |
|
|
mechanism also means that a system which doesn't provide the above three
|
769 |
|
|
methods, but does provide a timezone in string form, can still use this
|
770 |
|
|
implementation.
|
771 |
|
|
|
772 |
|
|
@node java.io, java.security, java.util, Classpath Hooks
|
773 |
|
|
@section java.io
|
774 |
|
|
|
775 |
|
|
The @code{java.io} package is heavily reliant on access to the I/O facilities
|
776 |
|
|
of the underlying platform. As far as its VM hooks go, they provide two
|
777 |
|
|
areas of functionality to GNU Classpath, these being
|
778 |
|
|
|
779 |
|
|
@itemize @bullet
|
780 |
|
|
@item File and directory queries and manipulation
|
781 |
|
|
@item Serialization of objects
|
782 |
|
|
@end itemize
|
783 |
|
|
|
784 |
|
|
The first corresponds directly to most of the @code{File} class, while
|
785 |
|
|
the latter underlies the functionality provided by the
|
786 |
|
|
@code{ObjectInputStream} and @code{ObjectOutputStream}. More low-level I/O
|
787 |
|
|
is provided by @ref{java.nio}.
|
788 |
|
|
|
789 |
|
|
@menu
|
790 |
|
|
* java.io.VMFile::
|
791 |
|
|
* java.io.VMObjectInputStream::
|
792 |
|
|
* java.io.VMObjectStreamClass::
|
793 |
|
|
@end menu
|
794 |
|
|
|
795 |
|
|
@node java.io.VMFile,java.io.VMObjectInputStream,java.io,java.io
|
796 |
|
|
@subsection @code{java.io.VMFile}
|
797 |
|
|
|
798 |
|
|
@code{VMFile} allows GNU Classpath's @code{File} representations to
|
799 |
|
|
probe and modify the file system using the native functions of the
|
800 |
|
|
platform. The default implementation (which consists of both a
|
801 |
|
|
@code{VMFile} class and the native methods) is primarily UNIX-centric,
|
802 |
|
|
working with POSIX functions and assuming case-sensitive filenames,
|
803 |
|
|
without the restriction of the 8.3 format. It consists mainly of
|
804 |
|
|
@code{static} @code{native} methods, with a few Java helper methods.
|
805 |
|
|
The native methods represent the file as a string containing its path,
|
806 |
|
|
rather than using the object itself.
|
807 |
|
|
|
808 |
|
|
@itemize @bullet
|
809 |
|
|
@item Native Methods
|
810 |
|
|
@itemize @bullet
|
811 |
|
|
@item @code{lastModified(String)} -- The native method should return a
|
812 |
|
|
@code{long} value that represents the last modified date of the file.
|
813 |
|
|
@item @code{setReadOnly(String)} -- Sets the file's permissions to read only,
|
814 |
|
|
in whichever way this is realised by the platform.
|
815 |
|
|
@item @code{create(String)} -- Create the named file.
|
816 |
|
|
@item @code{list(String)} -- The native method opens the named directory,
|
817 |
|
|
reads the contents and returns them as a Java @code{String} array.
|
818 |
|
|
@item @code{renameTo(String,String)} -- Renames the first file to the second.
|
819 |
|
|
@item @code{length(String)} -- Returns a @code{long} value representing
|
820 |
|
|
the file size.
|
821 |
|
|
@item @code{exists(String)} -- Tests for the existence of the named file
|
822 |
|
|
or directory.
|
823 |
|
|
@item @code{delete(String)} -- Deletes the file or directory.
|
824 |
|
|
@item @code{setLastModified(String,long)} -- Change the last modified time.
|
825 |
|
|
@item @code{mkdir(String)} -- Creates the named directory.
|
826 |
|
|
@item @code{isFile(String)} -- Tests that the named path references a file.
|
827 |
|
|
@item @code{canWrite(String)} -- Tests that the file can be written to.
|
828 |
|
|
This method is @code{synchronized}, so the object is locked during the check.
|
829 |
|
|
@item @code{canRead(String)} -- Complement of the last method.
|
830 |
|
|
@item @code{isDirectory(String)} -- Tests that the named path references
|
831 |
|
|
a directory.
|
832 |
|
|
@end itemize
|
833 |
|
|
@item Java Helper Methods
|
834 |
|
|
@itemize @bullet
|
835 |
|
|
@item @code{canWriteDirectory(File)} -- Checks that the directory can be
|
836 |
|
|
written to, by trying to create a temporary file in it.
|
837 |
|
|
@item @code{listRoots()} -- Returns the root of a GNU filesystem i.e. `/'
|
838 |
|
|
in an array.
|
839 |
|
|
@item @code{isHidden(String)} -- Checks whether the file starts with `.',
|
840 |
|
|
which is how files are hidden on UNIX-style systems.
|
841 |
|
|
@item @code{getName(String)} -- Pulls the actual filename from the end of
|
842 |
|
|
the path, by breaking off the characters after the last occurrence of the
|
843 |
|
|
platform's file separator.
|
844 |
|
|
@item @code{getCanonicalForm(String)} -- This converts a UNIX path to
|
845 |
|
|
its canonical form by removing the `.' and `..' sections that occur within.
|
846 |
|
|
@end itemize
|
847 |
|
|
@end itemize
|
848 |
|
|
|
849 |
|
|
@node java.io.VMObjectInputStream,java.io.VMObjectStreamClass,java.io.VMFile,java.io
|
850 |
|
|
@subsection @code{java.io.VMObjectInputStream}
|
851 |
|
|
|
852 |
|
|
This class consists of two methods which provide functionality used in
|
853 |
|
|
deserializing an object. @code{currentClassLoader()} provides the first
|
854 |
|
|
user-defined class loader from the class context
|
855 |
|
|
(@xref{gnu.classpath.VMStackWalker},) via a @code{PrivilegedAction}.
|
856 |
|
|
@code{allocateObject(Class,Class,Constructor)} is a @code{native} method
|
857 |
|
|
(a reference implementation is provided) which creates an object but
|
858 |
|
|
calls the constructor of another class, which is a superclass of the
|
859 |
|
|
object's class.
|
860 |
|
|
|
861 |
|
|
@node java.io.VMObjectStreamClass,,java.io.VMObjectInputStream,java.io
|
862 |
|
|
@subsection @code{java.io.VMObjectStreamClass}
|
863 |
|
|
|
864 |
|
|
@code{VMObjectStreamClass} is a series of @code{static} @code{native}
|
865 |
|
|
methods that provide some of the groundwork for @code{ObjectStreamClass}
|
866 |
|
|
and @code{ObjectStreamField}. @code{hasClassInitializer(Class)} works
|
867 |
|
|
with the former, and checks for the presence of a static initializer.
|
868 |
|
|
The remaining methods are of the form @code{setXXXNative(Field,Object,XXX)}
|
869 |
|
|
and support @code{ObjectStreamField}. One exists for each of the main types
|
870 |
|
|
(boolean, float, double, long, int, short, char, byte and object) and is used
|
871 |
|
|
to set the specified field in the supplied instance to the given value.
|
872 |
|
|
|
873 |
|
|
A default implementation is provided for all of them, so a VM implementation
|
874 |
|
|
is optional.
|
875 |
|
|
|
876 |
|
|
@node java.security, java.net, java.io, Classpath Hooks
|
877 |
|
|
@section java.security
|
878 |
|
|
|
879 |
|
|
The @code{java.security} package provides support for Java's security
|
880 |
|
|
architecture. At present, @code{VMAccessController} represents the sole
|
881 |
|
|
VM hook for this.
|
882 |
|
|
|
883 |
|
|
@menu
|
884 |
|
|
* java.security.VMAccessController::
|
885 |
|
|
@end menu
|
886 |
|
|
|
887 |
|
|
@node java.security.VMAccessController,,java.security,java.security
|
888 |
|
|
@subsection @code{java.security.VMAccessController}
|
889 |
|
|
|
890 |
|
|
The @code{AccessController} is used to perform privileged actions. Its
|
891 |
|
|
hook class, @code{VMAccessController}, maintains the
|
892 |
|
|
@code{AccessControlContext} and the default implementation is purely
|
893 |
|
|
Java-based. The VM may choose to replace this with their own.
|
894 |
|
|
The methods in the reference version are as follows:
|
895 |
|
|
|
896 |
|
|
@itemize @bullet
|
897 |
|
|
@item @code{pushContext(AccessControlContext)} -- Adds a new context to the
|
898 |
|
|
stack for the current thread. This is called before a privileged action
|
899 |
|
|
takes place.
|
900 |
|
|
@item @code{popContext()} -- Removes the top context from the stack. This
|
901 |
|
|
is performed after the privileged action takes place.
|
902 |
|
|
@item @code{getContext()} -- Either derives a context based on the
|
903 |
|
|
@code{ProtectionDomain}s of the call stack (see the next method) or returns
|
904 |
|
|
the top of the context stack.
|
905 |
|
|
@item @code{getStack()} -- Provides access to the call stack as a pair of
|
906 |
|
|
arrays of classes and method names. The actual implementation returns
|
907 |
|
|
an empty array, indicating that there are no permissions.
|
908 |
|
|
@end itemize
|
909 |
|
|
|
910 |
|
|
@node java.net, java.nio, java.security, Classpath Hooks
|
911 |
|
|
@section java.net
|
912 |
|
|
|
913 |
|
|
The @code{java.net} package is heavily reliant on access to the networking
|
914 |
|
|
facilities of the underlying platform. The VM hooks provide information
|
915 |
|
|
about the available network interfaces, and access to lookup facilities
|
916 |
|
|
for network addresses.
|
917 |
|
|
|
918 |
|
|
@menu
|
919 |
|
|
* java.net.VMInetAddress::
|
920 |
|
|
* java.net.VMNetworkInterface::
|
921 |
|
|
@end menu
|
922 |
|
|
|
923 |
|
|
@node java.net.VMInetAddress,java.net.VMNetworkInterface,java.net,java.net
|
924 |
|
|
@subsection @code{java.net.VMInetAddress}
|
925 |
|
|
|
926 |
|
|
@code{VMInetAddress} is a series of @code{static} @code{native} methods
|
927 |
|
|
which provide access to the platform's lookup facilities. All the methods
|
928 |
|
|
are implemented by GNU Classpath, making VM implementation optional, and
|
929 |
|
|
are as follows:
|
930 |
|
|
|
931 |
|
|
@itemize @bullet
|
932 |
|
|
@item @code{getLocalHostname()} -- Wraps the @code{gethostname} function, and
|
933 |
|
|
falls back on `localhost'.
|
934 |
|
|
@item @code{lookupInaddrAny()} -- Returns the value of @code{INADDR_ANY}.
|
935 |
|
|
@item @code{getHostByAddr(byte[])} -- Looks up the hostname based on an IP
|
936 |
|
|
address.
|
937 |
|
|
@item @code{getHostByName(String)} -- The reverse of the last method, it
|
938 |
|
|
returns the IP addresses which the given host name resolves to.
|
939 |
|
|
@end itemize
|
940 |
|
|
|
941 |
|
|
@node java.net.VMNetworkInterface,,java.net.VMInetAddress,java.net
|
942 |
|
|
@subsection @code{java.net.VMNetworkInterface}
|
943 |
|
|
|
944 |
|
|
@code{VMNetworkInterface} currently consists of a single @code{static}
|
945 |
|
|
@code{native} method, @code{getInterfaces()}, which retrieves the
|
946 |
|
|
network interfaces available on the underlying platform as a @code{Vector}.
|
947 |
|
|
The current GNU Classpath implementation is a native stub.
|
948 |
|
|
|
949 |
|
|
@node java.nio, java.nio.channels, java.net, Classpath Hooks
|
950 |
|
|
@section java.nio
|
951 |
|
|
|
952 |
|
|
The @code{java.nio} package is part of the New I/O framework added in
|
953 |
|
|
Java 1.4. This splits I/O into the concepts of @emph{buffers},
|
954 |
|
|
@emph{charsets}, @emph{channels} and @emph{selectors}, and
|
955 |
|
|
@code{java.nio} defines the buffer classes. As far as native and VM
|
956 |
|
|
code is concerned, the new package needs support for low-level efficient
|
957 |
|
|
buffer operations.
|
958 |
|
|
|
959 |
|
|
@menu
|
960 |
|
|
* java.nio.VMDirectByteBuffer::
|
961 |
|
|
@end menu
|
962 |
|
|
|
963 |
|
|
@node java.nio.VMDirectByteBuffer,,java.nio,java.nio
|
964 |
|
|
@subsection @code{java.nio.VMDirectByteBuffer}
|
965 |
|
|
|
966 |
|
|
A @code{ByteBuffer} maintains a buffer of bytes, and allows it to be
|
967 |
|
|
manipulated using primitive operations such as @code{get}, @code{put},
|
968 |
|
|
@code{allocate} and @code{free}. A direct buffer avoids intermediate
|
969 |
|
|
copying, and uses native data which shouldn't be manipulated by a
|
970 |
|
|
garbage collector. The VM class consists of @code{static} @code{native}
|
971 |
|
|
methods, all of which are given default implementations by GNU
|
972 |
|
|
Classpath.
|
973 |
|
|
|
974 |
|
|
@itemize @bullet
|
975 |
|
|
@item @code{init()} -- Creates an instance of an appropriate
|
976 |
|
|
@code{gnu.classpath.RawData} class. This class is not garbage
|
977 |
|
|
collected, is created natively and is used in the other methods to reference
|
978 |
|
|
the buffered data.
|
979 |
|
|
@item @code{allocate(int)} -- Allocates the memory for the buffer using
|
980 |
|
|
@code{malloc} and returns a reference to the @code{RawData} class.
|
981 |
|
|
@item @code{free(RawData)} -- Frees the memory used by the buffer.
|
982 |
|
|
@item @code{get(RawData,int)} -- Returns the data at the specified index.
|
983 |
|
|
@item @code{get(RawData,int,byte[],int,int)} -- Copies a section of the
|
984 |
|
|
data into a byte array using @code{memcpy}.
|
985 |
|
|
@item @code{put(RawData,int,byte)} -- Puts the given data in the buffer
|
986 |
|
|
at the specified index.
|
987 |
|
|
@item @code{adjustAddress(RawData,int)} -- Adjusts the pointer into the buffer.
|
988 |
|
|
@item @code{shiftDown(RawData,int,int,int)} -- Moves the content of the buffer
|
989 |
|
|
at an offset down to a new offset using @code{memmove}.
|
990 |
|
|
@end itemize
|
991 |
|
|
|
992 |
|
|
@node java.nio.channels, gnu.java.nio, java.nio, Classpath Hooks
|
993 |
|
|
@section java.nio.channels
|
994 |
|
|
|
995 |
|
|
Channels provide the data for the buffers with the New I/O packages.
|
996 |
|
|
For example, a channel may wrap a file or a socket. The VM hooks,
|
997 |
|
|
at the moment, simply allow the channels to be accessed by @code{java.io}
|
998 |
|
|
streams.
|
999 |
|
|
|
1000 |
|
|
@menu
|
1001 |
|
|
* java.nio.channels.VMChannels::
|
1002 |
|
|
@end menu
|
1003 |
|
|
|
1004 |
|
|
@node java.nio.channels.VMChannels,,java.nio.channels,java.nio.channels
|
1005 |
|
|
@subsection @code{java.nio.channels.VMChannels}
|
1006 |
|
|
|
1007 |
|
|
@code{VMChannels} provides the methods that create the channels or
|
1008 |
|
|
streams. The default implementation is in pure Java and simply wraps
|
1009 |
|
|
the channels in standard I/O classes from @code{java.io}.
|
1010 |
|
|
|
1011 |
|
|
@itemize @bullet
|
1012 |
|
|
@item @code{createStream(Class,Channel)} -- Creates a @code{FileChannel}
|
1013 |
|
|
which wraps an instance of the specified stream class, created by reflection.
|
1014 |
|
|
This method is private, and is used by the other two.
|
1015 |
|
|
@item @code{newInputStream(ReadableByteChannel)} -- Wraps the channel
|
1016 |
|
|
in a @code{FileInputStream}.
|
1017 |
|
|
@item @code{newOutputStream(WritableByteChannel)} -- Wraps the channel
|
1018 |
|
|
in a @code{FileOutputStream}.
|
1019 |
|
|
@end itemize
|
1020 |
|
|
|
1021 |
|
|
@node gnu.java.nio, Classpath Callbacks, java.nio.channels, Classpath Hooks
|
1022 |
|
|
@section gnu.java.nio
|
1023 |
|
|
|
1024 |
|
|
The @code{gnu.java.nio} class provides Classpath implementations of the
|
1025 |
|
|
interfaces provided by @code{java.nio}. The VM classes provide the native
|
1026 |
|
|
support necessary to implement @emph{pipes} and @emph{selectors}.
|
1027 |
|
|
|
1028 |
|
|
@menu
|
1029 |
|
|
* gnu.java.nio.VMPipe::
|
1030 |
|
|
* gnu.java.nio.VMSelector::
|
1031 |
|
|
@end menu
|
1032 |
|
|
|
1033 |
|
|
@node gnu.java.nio.VMPipe,gnu.java.nio.VMSelector,gnu.java.nio,gnu.java.nio
|
1034 |
|
|
@subsection @code{gnu.java.nio.VMPipe}
|
1035 |
|
|
|
1036 |
|
|
@code{VMPipe} provides the native functionality for a uni-directional pipe
|
1037 |
|
|
between a source and a destination (sink) channel. It consists of one
|
1038 |
|
|
@code{static} @code{native} method, @code{init(PipeImpl,SelectorProvider)},
|
1039 |
|
|
the reference implementation of which is currently a native stub. Ideally,
|
1040 |
|
|
this should initialise the pipe at the native level.
|
1041 |
|
|
|
1042 |
|
|
@node gnu.java.nio.VMSelector,,gnu.java.nio.VMPipe,gnu.java.nio
|
1043 |
|
|
@subsection @code{gnu.java.nio.VMSelector}
|
1044 |
|
|
|
1045 |
|
|
A @code{Selector} selects between multiple @code{SelectableChannel}s based
|
1046 |
|
|
on their readiness and a key set. The VM hook for the Classpath implementation
|
1047 |
|
|
of this is @code{VMSelector}, and this allows the actual @code{select()}
|
1048 |
|
|
operation to be performed. This is represented by the @code{static}
|
1049 |
|
|
@code{native} method, @code{select(int[],int[],int[],long)}, and a default
|
1050 |
|
|
implementation of this is provided.
|
1051 |
|
|
|
1052 |
|
|
@node Classpath Callbacks, , gnu.java.nio, Classpath Hooks
|
1053 |
|
|
Some of the classes you implement for the VM will need to call back to
|
1054 |
|
|
package-private methods in Classpath:
|
1055 |
|
|
|
1056 |
|
|
@itemize @bullet
|
1057 |
|
|
@item @code{java.lang.ThreadGroup.addThread(Thread)}
|
1058 |
|
|
Call this method from @code{Thread} when a new @code{Thread} is created, to add it to
|
1059 |
|
|
the group.
|
1060 |
|
|
|
1061 |
|
|
@item @code{java.lang.ThreadGroup.removeThread(Thread)}
|
1062 |
|
|
Call this method from @code{Thread} when a @code{Thread} is stopped or destroyed.
|
1063 |
|
|
@end itemize
|
1064 |
|
|
|
1065 |
|
|
@node VM Hooks, JNI Implementation, Classpath Hooks, Top
|
1066 |
|
|
@comment node-name, next, previous, up
|
1067 |
|
|
@chapter VM Hooks
|
1068 |
|
|
|
1069 |
|
|
VMs need to do some dirty work; there are some things in the VM that
|
1070 |
|
|
unfortunately are dependent on the internal structure of various
|
1071 |
|
|
classes. This is a guide to all of the things the VM itself needs to
|
1072 |
|
|
know about classes.
|
1073 |
|
|
|
1074 |
|
|
Some of the core classes, while being implemented by GNU Classpath,
|
1075 |
|
|
provide space for state (in the form of a @code{vmdata} object) to be
|
1076 |
|
|
stored by the VM, and can not be constructed normally.
|
1077 |
|
|
|
1078 |
|
|
@itemize @bullet
|
1079 |
|
|
@item java.lang.Class
|
1080 |
|
|
@item java.lang.ClassLoader
|
1081 |
|
|
@end itemize
|
1082 |
|
|
|
1083 |
|
|
The default implementations of some VM classes also follow this methodology,
|
1084 |
|
|
when it is intended that most VMs will keep the default.
|
1085 |
|
|
|
1086 |
|
|
@itemize @bullet
|
1087 |
|
|
@item java.lang.VMThread
|
1088 |
|
|
@item java.lang.VMThrowable
|
1089 |
|
|
@end itemize
|
1090 |
|
|
|
1091 |
|
|
Several core classes must be completely implemented by the VM for Classpath to
|
1092 |
|
|
work, although reference implementations are provided. These classes are:
|
1093 |
|
|
|
1094 |
|
|
@itemize @bullet
|
1095 |
|
|
@item java.lang.reflect.Constructor
|
1096 |
|
|
@item java.lang.reflect.Method
|
1097 |
|
|
@item java.lang.reflect.Field
|
1098 |
|
|
@end itemize
|
1099 |
|
|
|
1100 |
|
|
The following issues are of note;
|
1101 |
|
|
|
1102 |
|
|
@itemize @bullet
|
1103 |
|
|
@item @code{java.lang.Class} @*
|
1104 |
|
|
The GNU Classpath implementation of @code{java.lang.Class} provides an
|
1105 |
|
|
object for storing the internal state of the class maintained by the VM.
|
1106 |
|
|
This is the only known place where this matters. The class is
|
1107 |
|
|
constructed with this data by the VM. Some VMs do not create the
|
1108 |
|
|
@code{Class} object at the point where the class is defined; instead,
|
1109 |
|
|
they wait until a @code{Class} object is actually used.
|
1110 |
|
|
|
1111 |
|
|
@item Array Classes @*
|
1112 |
|
|
When you are creating an array class, you should set the
|
1113 |
|
|
@code{ClassLoader} of the array class to the @code{ClassLoader} of its
|
1114 |
|
|
component type. Whenever you add a class to a @code{ClassLoader}, you
|
1115 |
|
|
need to notify the @code{ClassLoader} and add the new @code{Class} to
|
1116 |
|
|
its internal cache of classes. To do this, call
|
1117 |
|
|
@code{ClassLoader.addVMCreatedClass(Class)}. @emph{Note: this is
|
1118 |
|
|
written in anticipation of 1.2 support and does not apply just yet.}
|
1119 |
|
|
|
1120 |
|
|
@item Primordial Class Loader @*
|
1121 |
|
|
When the primordial class loader loads a class, it needs to tell
|
1122 |
|
|
Classpath what it has done in order for security stuff to work right.
|
1123 |
|
|
To do this, call the static method
|
1124 |
|
|
@code{ClassLoader.newPrimordialClass(Class)}.
|
1125 |
|
|
|
1126 |
|
|
Even the first few core classes need to do this; in order to do it,
|
1127 |
|
|
simply call this method @emph{after} the initial class loading has been
|
1128 |
|
|
done. No harm will come, as long as you follow the guidelines in the
|
1129 |
|
|
@pxref{Initialization} section.
|
1130 |
|
|
|
1131 |
|
|
@emph{Note: this is written in anticipation of 1.2 support and does not
|
1132 |
|
|
apply just yet.}
|
1133 |
|
|
|
1134 |
|
|
@item Top-level Exception Handler @*
|
1135 |
|
|
Exceptions take care of themselves in Classpath; all you need to do in
|
1136 |
|
|
the top-level exception handler is call @code{Throwable.printStackTrace()}.
|
1137 |
|
|
|
1138 |
|
|
@item Security and Traces @*
|
1139 |
|
|
There will eventually be a feature in the 1.2 security that keeps the
|
1140 |
|
|
@code{AccessController} from having to evaluate @emph{all} of the
|
1141 |
|
|
@code{ProtectionDomain}s every time a security check is made. I think a common
|
1142 |
|
|
case is a single method doing a lot of things that require security
|
1143 |
|
|
checks. However, I don't want to bog down the method stack too much, so
|
1144 |
|
|
this feature of the VM will have the @code{AccessController} for a thread
|
1145 |
|
|
calling out to the VM to tell it how high it was on the stack when it
|
1146 |
|
|
made the last security request. Every time the stack goes lower than
|
1147 |
|
|
that number, the VM will decrement the number. The @code{AccessController}
|
1148 |
|
|
will remember what the accumulated protection status was at every stack
|
1149 |
|
|
level (an @code{AccessControlContext}) and use that aggregated information to
|
1150 |
|
|
do the check. I am not sure, however, whether the savings are
|
1151 |
|
|
substantial enough to outweigh the integer check and set after every
|
1152 |
|
|
method call. I will investigate.
|
1153 |
|
|
|
1154 |
|
|
@item Threading @*
|
1155 |
|
|
I figured I'd put this here because a VM guy might be wondering about it.
|
1156 |
|
|
We implement @code{ThreadGroup}, but that class is almost entirely
|
1157 |
|
|
VM-independent. The root @code{ThreadGroup}, a static field called
|
1158 |
|
|
@code{ThreadGroup.root}, should be initialized by Classpath, but if you wish to
|
1159 |
|
|
reinitialize it yourself, there should be no harm.
|
1160 |
|
|
|
1161 |
|
|
@end itemize
|
1162 |
|
|
|
1163 |
|
|
@node JNI Implementation, Miscellaneous VM Requirements, VM Hooks, Top
|
1164 |
|
|
@comment node-name, next, previous, up
|
1165 |
|
|
@chapter JNI Implementation
|
1166 |
|
|
|
1167 |
|
|
Classpath comes with its own implementation of @file{jni.h}. This
|
1168 |
|
|
file can be customized by the VM in a few ways, by defining macros
|
1169 |
|
|
that affect the interpretation of the file. These macros are all
|
1170 |
|
|
intended for use by a VM which uses GNU Classpath and which wants to
|
1171 |
|
|
use a single copy of @file{jni.h} for both internal and external use.
|
1172 |
|
|
|
1173 |
|
|
@itemize @bullet
|
1174 |
|
|
@item _CLASSPATH_VM_JNI_TYPES_DEFINED
|
1175 |
|
|
Some VMs like to define JNI ``object'' types in a special way. If
|
1176 |
|
|
this macro is defined, the Classpath @file{jni.h} will avoid defining
|
1177 |
|
|
these types. By default, these types are defined in @file{jni.h}.
|
1178 |
|
|
The full list of types and macros treated this way is: @samp{jobject},
|
1179 |
|
|
@samp{jclass}, @samp{jstring}, @samp{jthrowable}, @samp{jweak},
|
1180 |
|
|
@samp{jarray}, @samp{jobjectArray}, @samp{jbyteArray},
|
1181 |
|
|
@samp{jshortArray}, @samp{jintArray}, @samp{jlongArray},
|
1182 |
|
|
@samp{jbooleanArray}, @samp{jcharArray}, @samp{jfloatArray},
|
1183 |
|
|
@samp{jdoubleArray}, @samp{JNIEnv}, @samp{JavaVM}, @samp{JNI_TRUE}
|
1184 |
|
|
(macro), @samp{JNI_FALSE} (macro).
|
1185 |
|
|
|
1186 |
|
|
@item _CLASSPATH_VM_INTERNAL_TYPES_DEFINED
|
1187 |
|
|
If the VM has its own definitions for @samp{jfieldID} and
|
1188 |
|
|
@samp{jmethodID}, then it should define this macro. Otherwise,
|
1189 |
|
|
@file{jni.h} will provide definitions for these types.
|
1190 |
|
|
|
1191 |
|
|
@item _CLASSPATH_JNIIMPEXP
|
1192 |
|
|
Three functions -- @samp{JNI_GetDefaultJavaVMInitArgs},
|
1193 |
|
|
@samp{JNI_CreateJavaVM}, and @samp{JNI_GetCreatedJavaVMs} -- must be
|
1194 |
|
|
marked as @samp{JNIIMPORT} when seen by user code, but most likely
|
1195 |
|
|
should be marked as @samp{JNIEXPORT} when defined in the VM
|
1196 |
|
|
implementation. This macro can be defined to one or the other by the
|
1197 |
|
|
VM as appropriate. If this macro is not defined, it defaults to
|
1198 |
|
|
@samp{JNIIMPORT}.
|
1199 |
|
|
|
1200 |
|
|
@item _CLASSPATH_JNIENV_CONTENTS
|
1201 |
|
|
A VM can add fields to the @samp{JNIEnv} structure by defining this to
|
1202 |
|
|
be a sequence of field declarations.
|
1203 |
|
|
|
1204 |
|
|
@end itemize
|
1205 |
|
|
|
1206 |
|
|
|
1207 |
|
|
@node Miscellaneous VM Requirements, , JNI Implementation, Top
|
1208 |
|
|
@comment node-name, next, previous, up
|
1209 |
|
|
@chapter Miscellaneous VM Requirements
|
1210 |
|
|
|
1211 |
|
|
Classpath places a few requirements on the VM that uses it.
|
1212 |
|
|
|
1213 |
|
|
@menu
|
1214 |
|
|
* JNI Version::
|
1215 |
|
|
* VM Threading Model::
|
1216 |
|
|
* Boot Library Path Property::
|
1217 |
|
|
@end menu
|
1218 |
|
|
|
1219 |
|
|
@node JNI Version, VM Threading Model, Miscellaneous VM Requirements, Miscellaneous VM Requirements
|
1220 |
|
|
@comment node-name, next, previous, up
|
1221 |
|
|
@section JNI Version
|
1222 |
|
|
|
1223 |
|
|
Classpath currently uses only JNI 1.1, except for one JNI 1.2 function
|
1224 |
|
|
in the JNI Invocation API: GetEnv(). And GetEnv() is only used in the
|
1225 |
|
|
``portable native sync'' code, so it's only actually used by Jikes RVM
|
1226 |
|
|
and Kaffe.
|
1227 |
|
|
|
1228 |
|
|
A future direction will probably be to require that all VMs provide
|
1229 |
|
|
JNI 1.2. If this poses problems, please raise them on the classpath
|
1230 |
|
|
mailing list.
|
1231 |
|
|
|
1232 |
|
|
@node VM Threading Model, Boot Library Path Property, JNI Version, Miscellaneous VM Requirements
|
1233 |
|
|
@comment node-name, next, previous, up
|
1234 |
|
|
@section VM Threading Model
|
1235 |
|
|
|
1236 |
|
|
Classpath's AWT peers use GTK+. GTK+ uses GLIB. Normally, Classpath
|
1237 |
|
|
will initialize GLIB's @dfn{gthreads} to use
|
1238 |
|
|
the platform's native threading model@footnote{The native threading
|
1239 |
|
|
model is pthreads on Linux and AIX, the two platforms Classpath
|
1240 |
|
|
currently runs on.}
|
1241 |
|
|
|
1242 |
|
|
If the Java runtime doesn't use the native threading model, then you
|
1243 |
|
|
will want Classpath to tell GLIB to use the Java threading primitives
|
1244 |
|
|
instead. Otherwise, GLIB would use the native threading model to
|
1245 |
|
|
perform operations such as creating thread-local data, and that just
|
1246 |
|
|
doesn't work on systems (such as Kaffe in some configurations, and
|
1247 |
|
|
such as Jikes RVM) that use @i{m}:@i{n} threading.
|
1248 |
|
|
|
1249 |
|
|
Historically, enabling the Java threading primitives had been done at
|
1250 |
|
|
build time, by configuring classpath with the
|
1251 |
|
|
@option{--portable-native-sync} option. This had bad consequences,
|
1252 |
|
|
though -- it meant that the prebuild GNU Classpath package distributed
|
1253 |
|
|
with Debian GNU/Linux would not be usable with VMs that could
|
1254 |
|
|
otherwise have used it. Instead, we encourage
|
1255 |
|
|
the use of the Java system property
|
1256 |
|
|
@code{gnu.classpath.awt.gtk.portable.native.sync}. A VM that wants
|
1257 |
|
|
GLIB to use the Java threading primitives should modify
|
1258 |
|
|
@code{VMRuntime.insertSystemProperties()} to include code like the
|
1259 |
|
|
following:
|
1260 |
|
|
|
1261 |
|
|
@example
|
1262 |
|
|
static void insertSystemProperties(Properties @var{p})
|
1263 |
|
|
@end example
|
1264 |
|
|
...
|
1265 |
|
|
@example
|
1266 |
|
|
@var{p}.put("gnu.classpath.awt.gtk.portable.native.sync", "true");
|
1267 |
|
|
@end example
|
1268 |
|
|
|
1269 |
|
|
So, the configure option
|
1270 |
|
|
@option{--portable-native-sync} is deprecated, and should go away in a
|
1271 |
|
|
subsequent release of GNU Classpath.
|
1272 |
|
|
|
1273 |
|
|
@node Boot Library Path Property, , VM Threading Model, Miscellaneous VM Requirements
|
1274 |
|
|
@comment node-name, next, previous, up
|
1275 |
|
|
@section Boot Library Path Property
|
1276 |
|
|
|
1277 |
|
|
As of GNU Classpath 0.15 a system property named @code{gnu.classpath.boot.library.path}
|
1278 |
|
|
can be set by the VM to specify the directories which contain GNU Classpath's native
|
1279 |
|
|
libraries. Usually this value is given at configuration time and is then hardcoded
|
1280 |
|
|
in the VM. However for development purposes it is handy to switch to another installation
|
1281 |
|
|
by overriding the properties' value on the command line.
|
1282 |
|
|
|
1283 |
|
|
A VM that does not support this feature can simply ignore the property.
|
1284 |
|
|
|
1285 |
|
|
For compatibility reasons we suggest to set the default value of @code{java.library.path}
|
1286 |
|
|
to the value of the @code{LD_LIBRARY_PATH} environment if it exists on your platform.
|
1287 |
|
|
|
1288 |
|
|
@bye
|
1289 |
|
|
|
1290 |
|
|
|
1291 |
|
|
|