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

Save This Page
Home » openjdk-7 » java » lang » [javadoc | source]