Runtime


1   /*
2    * @(#)Runtime.java 1.74 04/05/18
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package java.lang;
9   
10  import java.io.*;
11  import java.util.StringTokenizer  ;
12  
13  /**
14   * Every Java application has a single instance of class 
15   * <code>Runtime</code> that allows the application to interface with 
16   * the environment in which the application is running. The current 
17   * runtime can be obtained from the <code>getRuntime</code> method. 
18   * <p>
19   * An application cannot create its own instance of this class. 
20   *
21   * @author  unascribed
22   * @version 1.74, 05/18/04
23   * @see     java.lang.Runtime#getRuntime()
24   * @since   JDK1.0
25   */
26  
27  public class Runtime {
28      private static Runtime   currentRuntime = new Runtime  ();
29  
30      /**
31       * Returns the runtime object associated with the current Java application.
32       * Most of the methods of class <code>Runtime</code> are instance 
33       * methods and must be invoked with respect to the current runtime object. 
34       * 
35       * @return  the <code>Runtime</code> object associated with the current
36       *          Java application.
37       */
38      public static Runtime   getRuntime() { 
39      return currentRuntime;
40      }
41  
42      /** Don't let anyone else instantiate this class */
43      private Runtime() {}
44  
45      /**
46       * Terminates the currently running Java virtual machine by initiating its
47       * shutdown sequence.  This method never returns normally.  The argument
48       * serves as a status code; by convention, a nonzero status code indicates
49       * abnormal termination.
50       *
51       * <p> The virtual machine's shutdown sequence consists of two phases.  In
52       * the first phase all registered {@link #addShutdownHook shutdown hooks},
53       * if any, are started in some unspecified order and allowed to run
54       * concurrently until they finish.  In the second phase all uninvoked
55       * finalizers are run if {@link #runFinalizersOnExit finalization-on-exit}
56       * has been enabled.  Once this is done the virtual machine {@link #halt
57       * halts}.
58       *
59       * <p> If this method is invoked after the virtual machine has begun its
60       * shutdown sequence then if shutdown hooks are being run this method will
61       * block indefinitely.  If shutdown hooks have already been run and on-exit
62       * finalization has been enabled then this method halts the virtual machine
63       * with the given status code if the status is nonzero; otherwise, it
64       * blocks indefinitely.
65       *
66       * <p> The <tt>{@link System#exit(int) System.exit}</tt> method is the
67       * conventional and convenient means of invoking this method. <p>
68       *
69       * @param  status
70       *         Termination status.  By convention, a nonzero status code
71       *         indicates abnormal termination.
72       *
73       * @throws SecurityException
74       *         If a security manager is present and its <tt>{@link
75       *         SecurityManager#checkExit checkExit}</tt> method does not permit
76       *         exiting with the specified status
77       *
78       * @see java.lang.SecurityException
79       * @see java.lang.SecurityManager#checkExit(int)
80       * @see #addShutdownHook
81       * @see #removeShutdownHook
82       * @see #runFinalizersOnExit
83       * @see #halt(int)
84       */
85      public void exit(int status) {
86      SecurityManager   security = System.getSecurityManager();
87      if (security != null) {
88          security.checkExit(status);
89      }
90      Shutdown.exit(status);
91      }
92  
93      /**
94       * Registers a new virtual-machine shutdown hook.
95       *
96       * <p> The Java virtual machine <i>shuts down</i> in response to two kinds
97       * of events:
98       *
99       *   <ul>
100      *
101      *   <p> <li> The program <i>exits</i> normally, when the last non-daemon
102      *   thread exits or when the <tt>{@link #exit exit}</tt> (equivalently,
103      *   <tt>{@link System#exit(int) System.exit}</tt>) method is invoked, or
104      *
105      *   <p> <li> The virtual machine is <i>terminated</i> in response to a
106      *   user interrupt, such as typing <tt>^C</tt>, or a system-wide event,
107      *   such as user logoff or system shutdown.
108      *
109      *   </ul>
110      *
111      * <p> A <i>shutdown hook</i> is simply an initialized but unstarted
112      * thread.  When the virtual machine begins its shutdown sequence it will
113      * start all registered shutdown hooks in some unspecified order and let
114      * them run concurrently.  When all the hooks have finished it will then
115      * run all uninvoked finalizers if finalization-on-exit has been enabled.
116      * Finally, the virtual machine will halt.  Note that daemon threads will
117      * continue to run during the shutdown sequence, as will non-daemon threads
118      * if shutdown was initiated by invoking the <tt>{@link #exit exit}</tt>
119      * method.
120      *
121      * <p> Once the shutdown sequence has begun it can be stopped only by
122      * invoking the <tt>{@link #halt halt}</tt> method, which forcibly
123      * terminates the virtual machine.
124      *
125      * <p> Once the shutdown sequence has begun it is impossible to register a
126      * new shutdown hook or de-register a previously-registered hook.
127      * Attempting either of these operations will cause an
128      * <tt>{@link IllegalStateException}</tt> to be thrown.
129      *
130      * <p> Shutdown hooks run at a delicate time in the life cycle of a virtual
131      * machine and should therefore be coded defensively.  They should, in
132      * particular, be written to be thread-safe and to avoid deadlocks insofar
133      * as possible.  They should also not rely blindly upon services that may
134      * have registered their own shutdown hooks and therefore may themselves in
135      * the process of shutting down.
136      *
137      * <p> Shutdown hooks should also finish their work quickly.  When a
138      * program invokes <tt>{@link #exit exit}</tt> the expectation is
139      * that the virtual machine will promptly shut down and exit.  When the
140      * virtual machine is terminated due to user logoff or system shutdown the
141      * underlying operating system may only allow a fixed amount of time in
142      * which to shut down and exit.  It is therefore inadvisable to attempt any
143      * user interaction or to perform a long-running computation in a shutdown
144      * hook.
145      *
146      * <p> Uncaught exceptions are handled in shutdown hooks just as in any
147      * other thread, by invoking the <tt>{@link ThreadGroup#uncaughtException
148      * uncaughtException}</tt> method of the thread's <tt>{@link
149      * ThreadGroup}</tt> object.  The default implementation of this method
150      * prints the exception's stack trace to <tt>{@link System#err}</tt> and
151      * terminates the thread; it does not cause the virtual machine to exit or
152      * halt.
153      *
154      * <p> In rare circumstances the virtual machine may <i>abort</i>, that is,
155      * stop running without shutting down cleanly.  This occurs when the
156      * virtual machine is terminated externally, for example with the
157      * <tt>SIGKILL</tt> signal on Unix or the <tt>TerminateProcess</tt> call on
158      * Microsoft Windows.  The virtual machine may also abort if a native method goes awry
159      * by, for example, corrupting internal data structures or attempting to
160      * access nonexistent memory.  If the virtual machine aborts then no
161      * guarantee can be made about whether or not any shutdown hooks will be
162      * run. <p>
163      *
164      * @param   hook
165      *          An initialized but unstarted <tt>{@link Thread}</tt> object
166      *
167      * @throws  IllegalArgumentException
168      *          If the specified hook has already been registered,
169      *          or if it can be determined that the hook is already running or
170      *          has already been run
171      *
172      * @throws  IllegalStateException
173      *          If the virtual machine is already in the process
174      *          of shutting down
175      *
176      * @throws  SecurityException
177      *          If a security manager is present and it denies
178      *          <tt>{@link RuntimePermission}("shutdownHooks")</tt>
179      *
180      * @see #removeShutdownHook
181      * @see #halt(int)
182      * @see #exit(int)
183      * @since 1.3
184      */
185     public void addShutdownHook(Thread   hook) {
186     SecurityManager   sm = System.getSecurityManager();
187     if (sm != null) {
188         sm.checkPermission(new RuntimePermission  ("shutdownHooks"));
189     }
190     Shutdown.add(hook);
191     }
192 
193     /**
194      * De-registers a previously-registered virtual-machine shutdown hook. <p>
195      *
196      * @param hook the hook to remove
197      * @return <tt>true</tt> if the specified hook had previously been
198      * registered and was successfully de-registered, <tt>false</tt>
199      * otherwise.
200      *
201      * @throws  IllegalStateException
202      *          If the virtual machine is already in the process of shutting
203      *          down
204      *
205      * @throws  SecurityException
206      *          If a security manager is present and it denies
207      *          <tt>{@link RuntimePermission}("shutdownHooks")</tt>
208      *
209      * @see #addShutdownHook
210      * @see #exit(int)
211      * @since 1.3
212      */
213     public boolean removeShutdownHook(Thread   hook) {
214     SecurityManager   sm = System.getSecurityManager();
215     if (sm != null) {
216         sm.checkPermission(new RuntimePermission  ("shutdownHooks"));
217     }
218     return Shutdown.remove(hook);
219     }
220 
221     /**
222      * Forcibly terminates the currently running Java virtual machine.  This
223      * method never returns normally.
224      *
225      * <p> This method should be used with extreme caution.  Unlike the
226      * <tt>{@link #exit exit}</tt> method, this method does not cause shutdown
227      * hooks to be started and does not run uninvoked finalizers if
228      * finalization-on-exit has been enabled.  If the shutdown sequence has
229      * already been initiated then this method does not wait for any running
230      * shutdown hooks or finalizers to finish their work. <p>
231      *
232      * @param  status
233      *         Termination status.  By convention, a nonzero status code
234      *         indicates abnormal termination.  If the <tt>{@link Runtime#exit
235      *         exit}</tt> (equivalently, <tt>{@link System#exit(int)
236      *         System.exit}</tt>) method has already been invoked then this
237      *         status code will override the status code passed to that method.
238      *
239      * @throws SecurityException
240      *         If a security manager is present and its <tt>{@link
241      *         SecurityManager#checkExit checkExit}</tt> method does not permit
242      *         an exit with the specified status
243      *
244      * @see #exit
245      * @see #addShutdownHook
246      * @see #removeShutdownHook
247      * @since 1.3
248      */
249     public void halt(int status) {
250     SecurityManager   sm = System.getSecurityManager();
251     if (sm != null) {
252         sm.checkExit(status);
253     }
254     Shutdown.halt(status);
255     }
256 
257     /**
258      * Enable or disable finalization on exit; doing so specifies that the
259      * finalizers of all objects that have finalizers that have not yet been
260      * automatically invoked are to be run before the Java runtime exits.
261      * By default, finalization on exit is disabled.
262      * 
263      * <p>If there is a security manager, 
264      * its <code>checkExit</code> method is first called
265      * with 0 as its argument to ensure the exit is allowed. 
266      * This could result in a SecurityException.
267      *
268      * @param value true to enable finalization on exit, false to disable
269      * @deprecated  This method is inherently unsafe.  It may result in
270      *      finalizers being called on live objects while other threads are
271      *      concurrently manipulating those objects, resulting in erratic
272      *      behavior or deadlock.
273      * 
274      * @throws  SecurityException
275      *        if a security manager exists and its <code>checkExit</code> 
276      *        method doesn't allow the exit.
277      *
278      * @see     java.lang.Runtime#exit(int)
279      * @see     java.lang.Runtime#gc()
280      * @see     java.lang.SecurityManager#checkExit(int)
281      * @since   JDK1.1
282      */
283     @Deprecated  
284     public static void runFinalizersOnExit(boolean value) {
285     SecurityManager   security = System.getSecurityManager();
286     if (security != null) {
287         try {
288         security.checkExit(0); 
289         } catch (SecurityException   e) {
290         throw new SecurityException  ("runFinalizersOnExit");
291         }
292     }
293     Shutdown.setRunFinalizersOnExit(value);
294     }
295 
296     /**
297      * Executes the specified string command in a separate process.
298      *
299      * <p>This is a convenience method.  An invocation of the form
300      * <tt>exec(command)</tt>
301      * behaves in exactly the same way as the invocation
302      * <tt>{@link #exec(String, String[], File) exec}(command, null, null)</tt>.
303      *
304      * @param   command   a specified system command.
305      *
306      * @return  A new {@link Process} object for managing the subprocess
307      *
308      * @throws  SecurityException
309      *          If a security manager exists and its
310      *          {@link SecurityManager#checkExec checkExec}
311      *          method doesn't allow creation of the subprocess
312      *
313      * @throws  IOException
314      *          If an I/O error occurs
315      *
316      * @throws  NullPointerException
317      *          If <code>command</code> is <code>null</code>
318      *
319      * @throws  IllegalArgumentException
320      *          If <code>command</code> is empty
321      *
322      * @see     #exec(String[], String[], File)
323      * @see     ProcessBuilder
324      */
325     public Process   exec(String   command) throws IOException {
326     return exec(command, null, null);
327     }
328 
329     /**
330      * Executes the specified string command in a separate process with the
331      * specified environment.
332      *
333      * <p>This is a convenience method.  An invocation of the form
334      * <tt>exec(command, envp)</tt>
335      * behaves in exactly the same way as the invocation
336      * <tt>{@link #exec(String, String[], File) exec}(command, envp, null)</tt>.
337      *
338      * @param   command   a specified system command.
339      *
340      * @param   envp      array of strings, each element of which
341      *                    has environment variable settings in the format
342      *                    <i>name</i>=<i>value</i>, or
343      *                    <tt>null</tt> if the subprocess should inherit
344      *                    the environment of the current process.
345      *
346      * @return  A new {@link Process} object for managing the subprocess
347      *
348      * @throws  SecurityException
349      *          If a security manager exists and its
350      *          {@link SecurityManager#checkExec checkExec}
351      *          method doesn't allow creation of the subprocess
352      *
353      * @throws  IOException
354      *          If an I/O error occurs
355      *
356      * @throws  NullPointerException
357      *          If <code>command</code> is <code>null</code>,
358      *          or one of the elements of <code>envp</code> is <code>null</code>
359      *
360      * @throws  IllegalArgumentException
361      *          If <code>command</code> is empty
362      *
363      * @see     #exec(String[], String[], File)
364      * @see     ProcessBuilder
365      */
366     public Process   exec(String   command, String  [] envp) throws IOException {
367         return exec(command, envp, null);
368     }
369 
370     /**
371      * Executes the specified string command in a separate process with the
372      * specified environment and working directory.
373      *
374      * <p>This is a convenience method.  An invocation of the form
375      * <tt>exec(command, envp, dir)</tt>
376      * behaves in exactly the same way as the invocation
377      * <tt>{@link #exec(String[], String[], File) exec}(cmdarray, envp, dir)</tt>,
378      * where <code>cmdarray</code> is an array of all the tokens in
379      * <code>command</code>.
380      *
381      * <p>More precisely, the <code>command</code> string is broken
382      * into tokens using a {@link StringTokenizer} created by the call
383      * <code>new {@link StringTokenizer}(command)</code> with no
384      * further modification of the character categories.  The tokens
385      * produced by the tokenizer are then placed in the new string
386      * array <code>cmdarray</code>, in the same order.
387      *
388      * @param   command   a specified system command.
389      *
390      * @param   envp      array of strings, each element of which
391      *                    has environment variable settings in the format
392      *                    <i>name</i>=<i>value</i>, or
393      *                    <tt>null</tt> if the subprocess should inherit
394      *                    the environment of the current process.
395      *
396      * @param   dir       the working directory of the subprocess, or
397      *                    <tt>null</tt> if the subprocess should inherit
398      *                    the working directory of the current process.
399      *
400      * @return  A new {@link Process} object for managing the subprocess
401      *
402      * @throws  SecurityException
403      *          If a security manager exists and its
404      *          {@link SecurityManager#checkExec checkExec}
405      *          method doesn't allow creation of the subprocess
406      *
407      * @throws  IOException
408      *          If an I/O error occurs
409      *
410      * @throws  NullPointerException
411      *          If <code>command</code> is <code>null</code>,
412      *          or one of the elements of <code>envp</code> is <code>null</code>
413      *
414      * @throws  IllegalArgumentException
415      *          If <code>command</code> is empty
416      *
417      * @see     ProcessBuilder
418      * @since 1.3
419      */
420     public Process   exec(String   command, String  [] envp, File dir)
421         throws IOException {
422         if (command.length() == 0)
423             throw new IllegalArgumentException  ("Empty command");
424 
425     StringTokenizer   st = new StringTokenizer  (command);
426     String  [] cmdarray = new String  [st.countTokens()];
427     for (int i = 0; st.hasMoreTokens(); i++)
428         cmdarray[i] = st.nextToken();
429     return exec(cmdarray, envp, dir);
430     }
431 
432     /**
433      * Executes the specified command and arguments in a separate process.
434      *
435      * <p>This is a convenience method.  An invocation of the form
436      * <tt>exec(cmdarray)</tt>
437      * behaves in exactly the same way as the invocation
438      * <tt>{@link #exec(String[], String[], File) exec}(cmdarray, null, null)</tt>.
439      *
440      * @param   cmdarray  array containing the command to call and
441      *                    its arguments.
442      *
443      * @return  A new {@link Process} object for managing the subprocess
444      *
445      * @throws  SecurityException
446      *          If a security manager exists and its
447      *          {@link SecurityManager#checkExec checkExec}
448      *          method doesn't allow creation of the subprocess
449      *
450      * @throws  IOException
451      *          If an I/O error occurs
452      *
453      * @throws  NullPointerException
454      *          If <code>cmdarray</code> is <code>null</code>,
455      *          or one of the elements of <code>cmdarray</code> is <code>null</code>
456      *
457      * @throws  IndexOutOfBoundsException
458      *          If <code>cmdarray</code> is an empty array
459      *          (has length <code>0</code>)
460      *
461      * @see     ProcessBuilder
462      */
463     public Process   exec(String   cmdarray[]) throws IOException {
464     return exec(cmdarray, null, null);
465     }
466 
467     /**
468      * Executes the specified command and arguments in a separate process
469      * with the specified environment.
470      *
471      * <p>This is a convenience method.  An invocation of the form
472      * <tt>exec(cmdarray, envp)</tt>
473      * behaves in exactly the same way as the invocation
474      * <tt>{@link #exec(String[], String[], File) exec}(cmdarray, envp, null)</tt>.
475      *
476      * @param   cmdarray  array containing the command to call and
477      *                    its arguments.
478      *
479      * @param   envp      array of strings, each element of which
480      *                    has environment variable settings in the format
481      *                    <i>name</i>=<i>value</i>, or
482      *                    <tt>null</tt> if the subprocess should inherit
483      *                    the environment of the current process.
484      *
485      * @return  A new {@link Process} object for managing the subprocess
486      *
487      * @throws  SecurityException
488      *          If a security manager exists and its
489      *          {@link SecurityManager#checkExec checkExec}
490      *          method doesn't allow creation of the subprocess
491      *
492      * @throws  IOException
493      *          If an I/O error occurs
494      *
495      * @throws  NullPointerException
496      *          If <code>cmdarray</code> is <code>null</code>,
497      *          or one of the elements of <code>cmdarray</code> is <code>null</code>,
498      *          or one of the elements of <code>envp</code> is <code>null</code>
499      *
500      * @throws  IndexOutOfBoundsException
501      *          If <code>cmdarray</code> is an empty array
502      *          (has length <code>0</code>)
503      *
504      * @see     ProcessBuilder
505      */
506     public Process   exec(String  [] cmdarray, String  [] envp) throws IOException {
507     return exec(cmdarray, envp, null);
508     }
509 
510 
511     /**
512      * Executes the specified command and arguments in a separate process with
513      * the specified environment and working directory.
514      *
515      * <p>Given an array of strings <code>cmdarray</code>, representing the
516      * tokens of a command line, and an array of strings <code>envp</code>,
517      * representing "environment" variable settings, this method creates
518      * a new process in which to execute the specified command.
519      *
520      * <p>This method checks that <code>cmdarray</code> is a valid operating
521      * system command.  Which commands are valid is system-dependent,
522      * but at the very least the command must be a non-empty list of
523      * non-null strings.
524      *
525      * <p>If <tt>envp</tt> is <tt>null</tt>, the subprocess inherits the
526      * environment settings of the current process.
527      *
528      * <p>{@link ProcessBuilder#start()} is now the preferred way to
529      * start a process with a modified environment.
530      *
531      * <p>The working directory of the new subprocess is specified by <tt>dir</tt>.
532      * If <tt>dir</tt> is <tt>null</tt>, the subprocess inherits the
533      * current working directory of the current process.
534      *
535      * <p>If a security manager exists, its
536      * {@link SecurityManager#checkExec checkExec}
537      * method is invoked with the first component of the array
538      * <code>cmdarray</code> as its argument. This may result in a
539      * {@link SecurityException} being thrown.
540      *
541      * <p>Starting an operating system process is highly system-dependent.
542      * Among the many things that can go wrong are:
543      * <ul>
544      * <li>The operating system program file was not found.
545      * <li>Access to the program file was denied.
546      * <li>The working directory does not exist.
547      * </ul>
548      *
549      * <p>In such cases an exception will be thrown.  The exact nature
550      * of the exception is system-dependent, but it will always be a
551      * subclass of {@link IOException}.
552      *
553      *
554      * @param   cmdarray  array containing the command to call and
555      *                    its arguments.
556      *
557      * @param   envp      array of strings, each element of which
558      *                    has environment variable settings in the format
559      *                    <i>name</i>=<i>value</i>, or
560      *                    <tt>null</tt> if the subprocess should inherit
561      *                    the environment of the current process.
562      *
563      * @param   dir       the working directory of the subprocess, or
564      *                    <tt>null</tt> if the subprocess should inherit
565      *                    the working directory of the current process.
566      *
567      * @return  A new {@link Process} object for managing the subprocess
568      *
569      * @throws  SecurityException
570      *          If a security manager exists and its
571      *          {@link SecurityManager#checkExec checkExec}
572      *          method doesn't allow creation of the subprocess
573      *
574      * @throws  IOException
575      *          If an I/O error occurs
576      *
577      * @throws  NullPointerException
578      *          If <code>cmdarray</code> is <code>null</code>,
579      *          or one of the elements of <code>cmdarray</code> is <code>null</code>,
580      *          or one of the elements of <code>envp</code> is <code>null</code>
581      *
582      * @throws  IndexOutOfBoundsException
583      *          If <code>cmdarray</code> is an empty array
584      *          (has length <code>0</code>)
585      *
586      * @see     ProcessBuilder
587      * @since 1.3
588      */
589     public Process   exec(String  [] cmdarray, String  [] envp, File dir)
590     throws IOException {
591     return new ProcessBuilder  (cmdarray)
592         .environment(envp)
593         .directory(dir)
594         .start();
595     }
596 
597     /**
598      * Returns the number of processors available to the Java virtual machine.
599      *
600      * <p> This value may change during a particular invocation of the virtual
601      * machine.  Applications that are sensitive to the number of available
602      * processors should therefore occasionally poll this property and adjust
603      * their resource usage appropriately. </p>
604      *
605      * @return  the maximum number of processors available to the virtual
606      *          machine; never smaller than one
607      * @since 1.4
608      */
609     public native int availableProcessors();
610 
611     /**
612      * Returns the amount of free memory in the Java Virtual Machine.
613      * Calling the 
614      * <code>gc</code> method may result in increasing the value returned 
615      * by <code>freeMemory.</code>
616      *
617      * @return  an approximation to the total amount of memory currently
618      *          available for future allocated objects, measured in bytes.
619      */
620     public native long freeMemory();
621 
622     /**
623      * Returns the total amount of memory in the Java virtual machine.
624      * The value returned by this method may vary over time, depending on 
625      * the host environment.
626      * <p>
627      * Note that the amount of memory required to hold an object of any 
628      * given type may be implementation-dependent.
629      * 
630      * @return  the total amount of memory currently available for current 
631      *          and future objects, measured in bytes.
632      */
633     public native long totalMemory();
634 
635     /**
636      * Returns the maximum amount of memory that the Java virtual machine will
637      * attempt to use.  If there is no inherent limit then the value {@link
638      * java.lang.Long#MAX_VALUE} will be returned. </p>
639      *
640      * @return  the maximum amount of memory that the virtual machine will
641      *          attempt to use, measured in bytes
642      * @since 1.4
643      */
644     public native long maxMemory();
645 
646     /**
647      * Runs the garbage collector.
648      * Calling this method suggests that the Java virtual machine expend 
649      * effort toward recycling unused objects in order to make the memory 
650      * they currently occupy available for quick reuse. When control 
651      * returns from the method call, the virtual machine has made 
652      * its best effort to recycle all discarded objects. 
653      * <p>
654      * The name <code>gc</code> stands for "garbage 
655      * collector". The virtual machine performs this recycling 
656      * process automatically as needed, in a separate thread, even if the 
657      * <code>gc</code> method is not invoked explicitly.
658      * <p>
659      * The method {@link System#gc()} is the conventional and convenient 
660      * means of invoking this method. 
661      */
662     public native void gc();
663 
664     /* Wormhole for calling java.lang.ref.Finalizer.runFinalization */
665     private static native void runFinalization0();
666 
667     /**
668      * Runs the finalization methods of any objects pending finalization.
669      * Calling this method suggests that the Java virtual machine expend 
670      * effort toward running the <code>finalize</code> methods of objects 
671      * that have been found to be discarded but whose <code>finalize</code> 
672      * methods have not yet been run. When control returns from the 
673      * method call, the virtual machine has made a best effort to 
674      * complete all outstanding finalizations. 
675      * <p>
676      * The virtual machine performs the finalization process 
677      * automatically as needed, in a separate thread, if the 
678      * <code>runFinalization</code> method is not invoked explicitly. 
679      * <p>
680      * The method {@link System#runFinalization()} is the conventional 
681      * and convenient means of invoking this method.
682      *
683      * @see     java.lang.Object#finalize()
684      */
685     public void runFinalization() {
686     runFinalization0();
687     }
688 
689     /**
690      * Enables/Disables tracing of instructions.
691      * If the <code>boolean</code> argument is <code>true</code>, this 
692      * method suggests that the Java virtual machine emit debugging 
693      * information for each instruction in the virtual machine as it 
694      * is executed. The format of this information, and the file or other 
695      * output stream to which it is emitted, depends on the host environment. 
696      * The virtual machine may ignore this request if it does not support 
697      * this feature. The destination of the trace output is system 
698      * dependent. 
699      * <p>
700      * If the <code>boolean</code> argument is <code>false</code>, this 
701      * method causes the virtual machine to stop performing the 
702      * detailed instruction trace it is performing.
703      *
704      * @param   on   <code>true</code> to enable instruction tracing;
705      *               <code>false</code> to disable this feature.
706      */
707     public native void traceInstructions(boolean on);
708 
709     /**
710      * Enables/Disables tracing of method calls.
711      * If the <code>boolean</code> argument is <code>true</code>, this 
712      * method suggests that the Java virtual machine emit debugging 
713      * information for each method in the virtual machine as it is 
714      * called. The format of this information, and the file or other output 
715      * stream to which it is emitted, depends on the host environment. The 
716      * virtual machine may ignore this request if it does not support 
717      * this feature.  
718      * <p>
719      * Calling this method with argument false suggests that the
720      * virtual machine cease emitting per-call debugging information.
721      *
722      * @param   on   <code>true</code> to enable instruction tracing;
723      *               <code>false</code> to disable this feature.
724      */
725     public native void traceMethodCalls(boolean on);
726 
727     /**
728      * Loads the specified filename as a dynamic library. The filename 
729      * argument must be a complete path name. 
730      * From <code>java_g</code> it will automagically insert "_g" before the
731      * ".so" (for example
732      * <code>Runtime.getRuntime().load("/home/avh/lib/libX11.so");</code>).
733      * <p>
734      * First, if there is a security manager, its <code>checkLink</code> 
735      * method is called with the <code>filename</code> as its argument. 
736      * This may result in a security exception. 
737      * <p>
738      * This is similar to the method {@link #loadLibrary(String)}, but it 
739      * accepts a general file name as an argument rather than just a library 
740      * name, allowing any file of native code to be loaded.
741      * <p>
742      * The method {@link System#load(String)} is the conventional and 
743      * convenient means of invoking this method.
744      *
745      * @param      filename   the file to load.
746      * @exception  SecurityException  if a security manager exists and its  
747      *             <code>checkLink</code> method doesn't allow 
748      *             loading of the specified dynamic library
749      * @exception  UnsatisfiedLinkError  if the file does not exist.
750      * @exception  NullPointerException if <code>filename</code> is
751      *             <code>null</code>
752      * @see        java.lang.Runtime#getRuntime()
753      * @see        java.lang.SecurityException
754      * @see        java.lang.SecurityManager#checkLink(java.lang.String)
755      */
756     public void load(String   filename) {
757         load0(System.getCallerClass(), filename);
758     }
759 
760     synchronized void load0(Class   fromClass, String   filename) {
761     SecurityManager   security = System.getSecurityManager();
762     if (security != null) {
763         security.checkLink(filename);
764     }
765     if (!(new File(filename).isAbsolute())) {
766         throw new UnsatisfiedLinkError  (
767             "Expecting an absolute path of the library: " + filename);
768     }
769     ClassLoader.loadLibrary(fromClass, filename, true);
770     }
771 
772     /**
773      * Loads the dynamic library with the specified library name. 
774      * A file containing native code is loaded from the local file system 
775      * from a place where library files are conventionally obtained. The 
776      * details of this process are implementation-dependent. The 
777      * mapping from a library name to a specific filename is done in a 
778      * system-specific manner. 
779      * <p>
780      * First, if there is a security manager, its <code>checkLink</code> 
781      * method is called with the <code>libname</code> as its argument. 
782      * This may result in a security exception. 
783      * <p>
784      * The method {@link System#loadLibrary(String)} is the conventional 
785      * and convenient means of invoking this method. If native
786      * methods are to be used in the implementation of a class, a standard 
787      * strategy is to put the native code in a library file (call it 
788      * <code>LibFile</code>) and then to put a static initializer:
789      * <blockquote><pre>
790      * static { System.loadLibrary("LibFile"); }
791      * </pre></blockquote>
792      * within the class declaration. When the class is loaded and 
793      * initialized, the necessary native code implementation for the native 
794      * methods will then be loaded as well. 
795      * <p>
796      * If this method is called more than once with the same library 
797      * name, the second and subsequent calls are ignored. 
798      *
799      * @param      libname   the name of the library.
800      * @exception  SecurityException  if a security manager exists and its  
801      *             <code>checkLink</code> method doesn't allow 
802      *             loading of the specified dynamic library
803      * @exception  UnsatisfiedLinkError  if the library does not exist.
804      * @exception  NullPointerException if <code>libname</code> is
805      *             <code>null</code>
806      * @see        java.lang.SecurityException
807      * @see        java.lang.SecurityManager#checkLink(java.lang.String)
808      */
809     public void loadLibrary(String   libname) {
810         loadLibrary0(System.getCallerClass(), libname); 
811     }
812 
813     synchronized void loadLibrary0(Class   fromClass, String   libname) {
814     SecurityManager   security = System.getSecurityManager();
815     if (security != null) {
816         security.checkLink(libname);
817     }
818     if (libname.indexOf((int)File.separatorChar) != -1) {
819         throw new UnsatisfiedLinkError  (
820     "Directory separator should not appear in library name: " + libname);
821     }
822     ClassLoader.loadLibrary(fromClass, libname, false);
823     }
824 
825     /**
826      * Creates a localized version of an input stream. This method takes 
827      * an <code>InputStream</code> and returns an <code>InputStream</code> 
828      * equivalent to the argument in all respects except that it is 
829      * localized: as characters in the local character set are read from 
830      * the stream, they are automatically converted from the local 
831      * character set to Unicode. 
832      * <p>
833      * If the argument is already a localized stream, it may be returned 
834      * as the result. 
835      *
836      * @param      in InputStream to localize
837      * @return     a localized input stream
838      * @see        java.io.InputStream
839      * @see        java.io.BufferedReader#BufferedReader(java.io.Reader)
840      * @see        java.io.InputStreamReader#InputStreamReader(java.io.InputStream)
841      * @deprecated As of JDK&nbsp;1.1, the preferred way to translate a byte
842      * stream in the local encoding into a character stream in Unicode is via
843      * the <code>InputStreamReader</code> and <code>BufferedReader</code>
844      * classes.
845      */
846     @Deprecated  
847     public InputStream getLocalizedInputStream(InputStream in) {
848     return in;
849     }
850 
851     /**
852      * Creates a localized version of an output stream. This method 
853      * takes an <code>OutputStream</code> and returns an 
854      * <code>OutputStream</code> equivalent to the argument in all respects 
855      * except that it is localized: as Unicode characters are written to 
856      * the stream, they are automatically converted to the local 
857      * character set. 
858      * <p>
859      * If the argument is already a localized stream, it may be returned 
860      * as the result. 
861      *
862      * @deprecated As of JDK&nbsp;1.1, the preferred way to translate a
863      * Unicode character stream into a byte stream in the local encoding is via
864      * the <code>OutputStreamWriter</code>, <code>BufferedWriter</code>, and
865      * <code>PrintWriter</code> classes.
866      *
867      * @param      out OutputStream to localize
868      * @return     a localized output stream
869      * @see        java.io.OutputStream
870      * @see        java.io.BufferedWriter#BufferedWriter(java.io.Writer)
871      * @see        java.io.OutputStreamWriter#OutputStreamWriter(java.io.OutputStream)
872      * @see        java.io.PrintWriter#PrintWriter(java.io.OutputStream)
873      */
874     @Deprecated  
875     public OutputStream getLocalizedOutputStream(OutputStream out) {
876     return out;
877     }
878 
879 }
880
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags