110 |
The Electrical File VM continues to be listed as a Mozilla project |
The Electrical File VM continues to be listed as a Mozilla project |
111 |
though development has been somewhat quiet. A number of concepts from |
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 |
EF were expected at one point to be rolled into Japhar, but that |
113 |
development has not occured as of yet. |
development has not occurred as of yet. |
114 |
|
|
115 |
@item @uref{http://latte.snu.ac.kr/,LaTTe} |
@item @uref{http://latte.snu.ac.kr/,LaTTe} |
116 |
This VM project so far supports only Sun UltraSparc processors using the |
This VM project so far supports only Sun UltraSparc processors using the |
175 |
@comment node-name, next, previous, up |
@comment node-name, next, previous, up |
176 |
@chapter Classpath Hooks |
@chapter Classpath Hooks |
177 |
|
|
178 |
Several core classes must be implemented by the VM for Classpath to |
The primary method of interaction between Classpath and the VM is via |
179 |
work. These classes are: |
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 |
@itemize @bullet |
255 |
@item java.lang.Class |
@item 1.0 |
256 |
@item java.lang.Runtime |
@itemize @bullet |
257 |
@item java.lang.Thread |
@item @code{isInterface(Class)} -- This is simply a property test, and matches |
258 |
@item java.lang.reflect.Constructor |
the presence of an appropriate flag within the class file. |
259 |
@item java.lang.reflect.Method |
@item @code{getName(Class)} -- Returns the fully-qualified name of the class. |
260 |
@item java.lang.reflect.Field |
@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 |
@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 |
You also need to implement some helper classes in java.lang that classes |
@menu |
884 |
from Classpath call out to to get certain VM-specific dirty work done: |
* 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 |
@itemize @bullet |
897 |
@item @code{java.lang.VMObject} |
@item @code{pushContext(AccessControlContext)} -- Adds a new context to the |
898 |
is the bridge between the low level @code{Object} facilities such |
stack for the current thread. This is called before a privileged action |
899 |
as making a clone, getting the class of the object and the wait/notify |
takes place. |
900 |
semantics. |
@item @code{popContext()} -- Removes the top context from the stack. This |
901 |
@item @code{java.lang.VMClassLoader} |
is performed after the privileged action takes place. |
902 |
provides methods for defining and resolving core and primitive classes. |
@item @code{getContext()} -- Either derives a context based on the |
903 |
@item @code{java.lang.VMSystem} |
@code{ProtectionDomain}s of the call stack (see the next method) or returns |
904 |
is used to initialize the @code{System} properties, the @code{System.arraycopy} |
the top of the context stack. |
905 |
method and the @code{identityHashCode} of an @code{Object}. |
@item @code{getStack()} -- Provides access to the call stack as a pair of |
906 |
@item @code{java.lang.VMSecurityManager} |
arrays of classes and method names. The actual implementation returns |
907 |
provides the class context (stack trace) of the currently |
an empty array, indicating that there are no permissions. |
|
executing thread and a way to get the currently active @code{ClassLoader}. |
|
|
@item @code{java.lang.VMThrowable} |
|
|
used to hold the VM state of a throwable, created when a @code{Throwable} is |
|
|
created or the @code{fillInStacktrace()} method is called, when the actual stack |
|
|
trace is needed (a lot of exceptions are never actually used), the |
|
|
@code{getStackTrace()} method is used to create a real @code{StackTraceElement} array |
|
|
for the exception. |
|
908 |
@end itemize |
@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 |
Some of the classes you implement for the VM will need to call back to |
1054 |
package-private methods in Classpath: |
package-private methods in Classpath: |
1055 |
|
|
1060 |
|
|
1061 |
@item @code{java.lang.ThreadGroup.removeThread(Thread)} |
@item @code{java.lang.ThreadGroup.removeThread(Thread)} |
1062 |
Call this method from @code{Thread} when a @code{Thread} is stopped or destroyed. |
Call this method from @code{Thread} when a @code{Thread} is stopped or destroyed. |
|
|
|
1063 |
@end itemize |
@end itemize |
1064 |
|
|
|
|
|
1065 |
@node VM Hooks, JNI Implementation, Classpath Hooks, Top |
@node VM Hooks, JNI Implementation, Classpath Hooks, Top |
1066 |
@comment node-name, next, previous, up |
@comment node-name, next, previous, up |
1067 |
@chapter VM Hooks |
@chapter VM Hooks |
1071 |
classes. This is a guide to all of the things the VM itself needs to |
classes. This is a guide to all of the things the VM itself needs to |
1072 |
know about classes. |
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 |
@itemize @bullet |
1103 |
@item @code{java.lang.Class} @* |
@item @code{java.lang.Class} @* |
1104 |
You, the VM, get to create this @code{Class}, so you may define the internal |
The GNU Classpath implementation of @code{java.lang.Class} provides an |
1105 |
structure any way you wish. You probably have code somewhere to |
object for storing the internal state of the class maintained by the VM. |
1106 |
translate your internal class structure into a @code{Class} object. That is |
This is the only known place where this matters. The class is |
1107 |
the only known place where this matters. Some VMs do not create the |
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, they wait |
@code{Class} object at the point where the class is defined; instead, |
1109 |
until a @code{Class} object is actually used. |
they wait until a @code{Class} object is actually used. |
1110 |
|
|
1111 |
@item Array Classes @* |
@item Array Classes @* |
1112 |
When you are creating an array class, you should set the @code{ClassLoader} of |
When you are creating an array class, you should set the |
1113 |
the array class to the @code{ClassLoader} of its component type. Whenever you |
@code{ClassLoader} of the array class to the @code{ClassLoader} of its |
1114 |
add a class to a @code{ClassLoader}, you need to notify the @code{ClassLoader} and |
component type. Whenever you add a class to a @code{ClassLoader}, you |
1115 |
add the new @code{Class} to its internal cache of classes. To do this, call |
need to notify the @code{ClassLoader} and add the new @code{Class} to |
1116 |
@code{ClassLoader.addVMCreatedClass(Class)}. @emph{Note: this is written in |
its internal cache of classes. To do this, call |
1117 |
anticipation of 1.2 support and does not apply just yet.} |
@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 @* |
@item Primordial Class Loader @* |
1121 |
When the primordial class loader loads a class, it needs to tell |
When the primordial class loader loads a class, it needs to tell |
1288 |
@bye |
@bye |
1289 |
|
|
1290 |
|
|
1291 |
|
|