sample/java.lang.Runtime.txt

   1 *java.lang.Runtime* *Runtime* Every Java application has a single instance of cl
   2
   3 public class Runtime
   4   extends    |java.lang.Object|
   5
   6 |java.lang.Runtime_Description|
   7 |java.lang.Runtime_Fields|
   8 |java.lang.Runtime_Constructors|
   9 |java.lang.Runtime_Methods|
  10
  11 ================================================================================
  12
  13 *java.lang.Runtime_Methods*
  14 |java.lang.Runtime.addShutdownHook(Thread)|Registers a new virtual-machine shut
  15 |java.lang.Runtime.availableProcessors()|Returns the number of processors avail
  16 |java.lang.Runtime.exec(String)|Executes the specified string command in a sepa
  17 |java.lang.Runtime.exec(String[])|Executes the specified command and arguments
  18 |java.lang.Runtime.exec(String[],String[])|Executes the specified command and a
  19 |java.lang.Runtime.exec(String[],String[],File)|Executes the specified command
  20 |java.lang.Runtime.exec(String,String[])|Executes the specified string command
  21 |java.lang.Runtime.exec(String,String[],File)|Executes the specified string com
  22 |java.lang.Runtime.exit(int)|Terminates the currently running Java virtual mach
  23 |java.lang.Runtime.freeMemory()|Returns the amount of free memory in the Java V
  24 |java.lang.Runtime.gc()|Runs the garbage collector.
  25 |java.lang.Runtime.getLocalizedInputStream(InputStream)|Creates a localized ver
  26 |java.lang.Runtime.getLocalizedOutputStream(OutputStream)|Creates a localized v
  27 |java.lang.Runtime.getRuntime()|Returns the runtime object associated with the
  28 |java.lang.Runtime.halt(int)|Forcibly terminates the currently running Java vir
  29 |java.lang.Runtime.load(String)|Loads the specified filename as a dynamic libra
  30 |java.lang.Runtime.loadLibrary(String)|Loads the dynamic library with the speci
  31 |java.lang.Runtime.maxMemory()|Returns the maximum amount of memory that the Ja
  32 |java.lang.Runtime.removeShutdownHook(Thread)|De-registers a previously-registe
  33 |java.lang.Runtime.runFinalization()|Runs the finalization methods of any objec
  34 |java.lang.Runtime.runFinalizersOnExit(boolean)|Enable or disable finalization
  35 |java.lang.Runtime.totalMemory()|Returns the total amount of memory in the Java
  36 |java.lang.Runtime.traceInstructions(boolean)|Enables/Disables tracing of instr
  37 |java.lang.Runtime.traceMethodCalls(boolean)|Enables/Disables tracing of method
  38
  39 *java.lang.Runtime_Description*
  40
  41 Every Java application has a single instance of class Runtime that allows the
  42 application to interface with the environment in which the application is
  43 running. The current runtime can be obtained from the getRuntime method.
  44
  45 An application cannot create its own instance of this class.
  46
  47
  48 *java.lang.Runtime.addShutdownHook(Thread)*
  49
  50 public void addShutdownHook(java.lang.Thread hook)
  51
  52 Registers a new virtual-machine shutdown hook.
  53
  54 The Java virtual machine shuts down in response to two kinds of events:
  55
  56
  57
  58 The program exits normally, when the last non-daemon thread exits or when the
  59 exit(|java.lang.Runtime|) (equivalently, System.exit(|java.lang.System|) )
  60 method is invoked, or
  61
  62 The virtual machine is terminated in response to a user interrupt, such as
  63 typing ^C, or a system-wide event, such as user logoff or system shutdown.
  64
  65
  66
  67 A shutdown hook is simply an initialized but unstarted thread. When the virtual
  68 machine begins its shutdown sequence it will start all registered shutdown
  69 hooks in some unspecified order and let them run concurrently. When all the
  70 hooks have finished it will then run all uninvoked finalizers if
  71 finalization-on-exit has been enabled. Finally, the virtual machine will halt.
  72 Note that daemon threads will continue to run during the shutdown sequence, as
  73 will non-daemon threads if shutdown was initiated by invoking the
  74 exit(|java.lang.Runtime|) method.
  75
  76 Once the shutdown sequence has begun it can be stopped only by invoking the
  77 halt(|java.lang.Runtime|) method, which forcibly terminates the virtual
  78 machine.
  79
  80 Once the shutdown sequence has begun it is impossible to register a new
  81 shutdown hook or de-register a previously-registered hook. Attempting either of
  82 these operations will cause an (|java.lang.IllegalStateException|) to be
  83 thrown.
  84
  85 Shutdown hooks run at a delicate time in the life cycle of a virtual machine
  86 and should therefore be coded defensively. They should, in particular, be
  87 written to be thread-safe and to avoid deadlocks insofar as possible. They
  88 should also not rely blindly upon services that may have registered their own
  89 shutdown hooks and therefore may themselves in the process of shutting down.
  90
  91 Shutdown hooks should also finish their work quickly. When a program invokes
  92 exit(|java.lang.Runtime|) the expectation is that the virtual machine will
  93 promptly shut down and exit. When the virtual machine is terminated due to user
  94 logoff or system shutdown the underlying operating system may only allow a
  95 fixed amount of time in which to shut down and exit. It is therefore
  96 inadvisable to attempt any user interaction or to perform a long-running
  97 computation in a shutdown hook.
  98
  99 Uncaught exceptions are handled in shutdown hooks just as in any other thread,
 100 by invoking the uncaughtException(|java.lang.ThreadGroup|) method of the
 101 thread's (|java.lang.ThreadGroup|) object. The default implementation of this
 102 method prints the exception's stack trace to (|java.lang.System|) and
 103 terminates the thread; it does not cause the virtual machine to exit or halt.
 104
 105 In rare circumstances the virtual machine may abort, that is, stop running
 106 without shutting down cleanly. This occurs when the virtual machine is
 107 terminated externally, for example with the SIGKILL signal on Unix or the
 108 TerminateProcess call on Microsoft Windows. The virtual machine may also abort
 109 if a native method goes awry by, for example, corrupting internal data
 110 structures or attempting to access nonexistent memory. If the virtual machine
 111 aborts then no guarantee can be made about whether or not any shutdown hooks
 112 will be run.
 113
 114     hook - An initialized but unstarted {@link Thread} object
 115
 116 *java.lang.Runtime.availableProcessors()*
 117
 118 public native int availableProcessors()
 119
 120 Returns the number of processors available to the Java virtual machine.
 121
 122 This value may change during a particular invocation of the virtual machine.
 123 Applications that are sensitive to the number of available processors should
 124 therefore occasionally poll this property and adjust their resource usage
 125 appropriately.
 126
 127
 128     Returns: the maximum number of processors available to the virtual machine; never
 129              smaller than one
 130 *java.lang.Runtime.exec(String)*
 131
 132 public |java.lang.Process| exec(java.lang.String command)
 133   throws |java.io.IOException|
 134
 135 Executes the specified string command in a separate process.
 136
 137 This is a convenience method. An invocation of the form exec(command) behaves
 138 in exactly the same way as the invocation exec(|java.lang.Runtime|) (command,
 139 null, null).
 140
 141     command - a specified system command.
 142
 143     Returns: A new {@link Process} object for managing the subprocess
 144 *java.lang.Runtime.exec(String[])*
 145
 146 public |java.lang.Process| exec(java.lang.String[] cmdarray)
 147   throws |java.io.IOException|
 148
 149 Executes the specified command and arguments in a separate process.
 150
 151 This is a convenience method. An invocation of the form exec(cmdarray) behaves
 152 in exactly the same way as the invocation exec(|java.lang.Runtime|) (cmdarray,
 153 null, null).
 154
 155     cmdarray - array containing the command to call and its arguments.
 156
 157     Returns: A new {@link Process} object for managing the subprocess
 158 *java.lang.Runtime.exec(String[],String[])*
 159
 160 public |java.lang.Process| exec(
 161   java.lang.String[] cmdarray,
 162   java.lang.String[] envp)
 163   throws |java.io.IOException|
 164
 165 Executes the specified command and arguments in a separate process with the
 166 specified environment.
 167
 168 This is a convenience method. An invocation of the form exec(cmdarray, envp)
 169 behaves in exactly the same way as the invocation exec(|java.lang.Runtime|)
 170 (cmdarray, envp, null).
 171
 172     cmdarray - array containing the command to call and its arguments.
 173     envp - array of strings, each element of which has environment variable settings in
 174        the format name=value, or null if the subprocess should inherit the
 175        environment of the current process.
 176
 177     Returns: A new {@link Process} object for managing the subprocess
 178 *java.lang.Runtime.exec(String[],String[],File)*
 179
 180 public |java.lang.Process| exec(
 181   java.lang.String[] cmdarray,
 182   java.lang.String[] envp,
 183   java.io.File dir)
 184   throws |java.io.IOException|
 185
 186 Executes the specified command and arguments in a separate process with the
 187 specified environment and working directory.
 188
 189 Given an array of strings cmdarray, representing the tokens of a command line,
 190 and an array of strings envp, representing "environment" variable settings,
 191 this method creates a new process in which to execute the specified command.
 192
 193 This method checks that cmdarray is a valid operating system command. Which
 194 commands are valid is system-dependent, but at the very least the command must
 195 be a non-empty list of non-null strings.
 196
 197 If envp is null, the subprocess inherits the environment settings of the
 198 current process.
 199
 200 (|java.lang.ProcessBuilder|) is now the preferred way to start a process with a
 201 modified environment.
 202
 203 The working directory of the new subprocess is specified by dir. If dir is
 204 null, the subprocess inherits the current working directory of the current
 205 process.
 206
 207 If a security manager exists, its checkExec(|java.lang.SecurityManager|) method
 208 is invoked with the first component of the array cmdarray as its argument. This
 209 may result in a (|java.lang.SecurityException|) being thrown.
 210
 211 Starting an operating system process is highly system-dependent. Among the many
 212 things that can go wrong are:
 213
 214 The operating system program file was not found. Access to the program file was
 215 denied. The working directory does not exist.
 216
 217 In such cases an exception will be thrown. The exact nature of the exception is
 218 system-dependent, but it will always be a subclass of (|java.io.IOException|) .
 219
 220     cmdarray - array containing the command to call and its arguments.
 221     envp - array of strings, each element of which has environment variable settings in
 222        the format name=value, or null if the subprocess should inherit the
 223        environment of the current process.
 224     dir - the working directory of the subprocess, or null if the subprocess should
 225        inherit the working directory of the current process.
 226
 227     Returns: A new {@link Process} object for managing the subprocess
 228 *java.lang.Runtime.exec(String,String[])*
 229
 230 public |java.lang.Process| exec(
 231   java.lang.String command,
 232   java.lang.String[] envp)
 233   throws |java.io.IOException|
 234
 235 Executes the specified string command in a separate process with the specified
 236 environment.
 237
 238 This is a convenience method. An invocation of the form exec(command, envp)
 239 behaves in exactly the same way as the invocation exec(|java.lang.Runtime|)
 240 (command, envp, null).
 241
 242     command - a specified system command.
 243     envp - array of strings, each element of which has environment variable settings in
 244        the format name=value, or null if the subprocess should inherit the
 245        environment of the current process.
 246
 247     Returns: A new {@link Process} object for managing the subprocess
 248 *java.lang.Runtime.exec(String,String[],File)*
 249
 250 public |java.lang.Process| exec(
 251   java.lang.String command,
 252   java.lang.String[] envp,
 253   java.io.File dir)
 254   throws |java.io.IOException|
 255
 256 Executes the specified string command in a separate process with the specified
 257 environment and working directory.
 258
 259 This is a convenience method. An invocation of the form exec(command, envp,
 260 dir) behaves in exactly the same way as the invocation
 261 exec(|java.lang.Runtime|) (cmdarray, envp, dir), where cmdarray is an array of
 262 all the tokens in command.
 263
 264 More precisely, the command string is broken into tokens using a
 265 (|java.util.StringTokenizer|) created by the call new
 266 (|java.util.StringTokenizer|) (command) with no further modification of the
 267 character categories. The tokens produced by the tokenizer are then placed in
 268 the new string array cmdarray, in the same order.
 269
 270     command - a specified system command.
 271     envp - array of strings, each element of which has environment variable settings in
 272        the format name=value, or null if the subprocess should inherit the
 273        environment of the current process.
 274     dir - the working directory of the subprocess, or null if the subprocess should
 275        inherit the working directory of the current process.
 276
 277     Returns: A new {@link Process} object for managing the subprocess
 278 *java.lang.Runtime.exit(int)*
 279
 280 public void exit(int status)
 281
 282 Terminates the currently running Java virtual machine by initiating its
 283 shutdown sequence. This method never returns normally. The argument serves as a
 284 status code; by convention, a nonzero status code indicates abnormal
 285 termination.
 286
 287 The virtual machine's shutdown sequence consists of two phases. In the first
 288 phase all registered shutdown hooks(|java.lang.Runtime|) , if any, are started
 289 in some unspecified order and allowed to run concurrently until they finish. In
 290 the second phase all uninvoked finalizers are run if
 291 finalization-on-exit(|java.lang.Runtime|) has been enabled. Once this is done
 292 the virtual machine halts(|java.lang.Runtime|) .
 293
 294 If this method is invoked after the virtual machine has begun its shutdown
 295 sequence then if shutdown hooks are being run this method will block
 296 indefinitely. If shutdown hooks have already been run and on-exit finalization
 297 has been enabled then this method halts the virtual machine with the given
 298 status code if the status is nonzero; otherwise, it blocks indefinitely.
 299
 300 The System.exit(|java.lang.System|) method is the conventional and convenient
 301 means of invoking this method.
 302
 303     status - Termination status. By convention, a nonzero status code indicates abnormal
 304        termination.
 305
 306 *java.lang.Runtime.freeMemory()*
 307
 308 public native long freeMemory()
 309
 310 Returns the amount of free memory in the Java Virtual Machine. Calling the gc
 311 method may result in increasing the value returned by freeMemory.
 312
 313
 314     Returns: an approximation to the total amount of memory currently available for future
 315              allocated objects, measured in bytes.
 316 *java.lang.Runtime.gc()*
 317
 318 public native void gc()
 319
 320 Runs the garbage collector. Calling this method suggests that the Java virtual
 321 machine expend effort toward recycling unused objects in order to make the
 322 memory they currently occupy available for quick reuse. When control returns
 323 from the method call, the virtual machine has made its best effort to recycle
 324 all discarded objects.
 325
 326 The name gc stands for "garbage collector". The virtual machine performs this
 327 recycling process automatically as needed, in a separate thread, even if the gc
 328 method is not invoked explicitly.
 329
 330 The method (|java.lang.System|) is the conventional and convenient means of
 331 invoking this method.
 332
 333
 334 *java.lang.Runtime.getLocalizedInputStream(InputStream)*
 335
 336 public |java.io.InputStream| getLocalizedInputStream(java.io.InputStream in)
 337
 338 Creates a localized version of an input stream. This method takes an
 339 InputStream and returns an InputStream equivalent to the argument in all
 340 respects except that it is localized: as characters in the local character set
 341 are read from the stream, they are automatically converted from the local
 342 character set to Unicode.
 343
 344 If the argument is already a localized stream, it may be returned as the
 345 result.
 346
 347     in - InputStream to localize
 348
 349     Returns: a localized input stream
 350 *java.lang.Runtime.getLocalizedOutputStream(OutputStream)*
 351
 352 public |java.io.OutputStream| getLocalizedOutputStream(java.io.OutputStream out)
 353
 354 Creates a localized version of an output stream. This method takes an
 355 OutputStream and returns an OutputStream equivalent to the argument in all
 356 respects except that it is localized: as Unicode characters are written to the
 357 stream, they are automatically converted to the local character set.
 358
 359 If the argument is already a localized stream, it may be returned as the
 360 result.
 361
 362     out - OutputStream to localize
 363
 364     Returns: a localized output stream
 365 *java.lang.Runtime.getRuntime()*
 366
 367 public static |java.lang.Runtime| getRuntime()
 368
 369 Returns the runtime object associated with the current Java application. Most
 370 of the methods of class Runtime are instance methods and must be invoked with
 371 respect to the current runtime object.
 372
 373
 374     Returns: the Runtime object associated with the current Java application.
 375 *java.lang.Runtime.halt(int)*
 376
 377 public void halt(int status)
 378
 379 Forcibly terminates the currently running Java virtual machine. This method
 380 never returns normally.
 381
 382 This method should be used with extreme caution. Unlike the
 383 exit(|java.lang.Runtime|) method, this method does not cause shutdown hooks to
 384 be started and does not run uninvoked finalizers if finalization-on-exit has
 385 been enabled. If the shutdown sequence has already been initiated then this
 386 method does not wait for any running shutdown hooks or finalizers to finish
 387 their work.
 388
 389     status - Termination status. By convention, a nonzero status code indicates abnormal
 390        termination. If the {@link Runtime#exit exit} (equivalently, {@link
 391        System#exit(int) System.exit}) method has already been invoked then this
 392        status code will override the status code passed to that method.
 393
 394 *java.lang.Runtime.load(String)*
 395
 396 public void load(java.lang.String filename)
 397
 398 Loads the specified filename as a dynamic library. The filename argument must
 399 be a complete path name. From java_g it will automagically insert "_g" before
 400 the ".so" (for example Runtime.getRuntime().load("/home/avh/lib/libX11.so");).
 401
 402 First, if there is a security manager, its checkLink method is called with the
 403 filename as its argument. This may result in a security exception.
 404
 405 This is similar to the method (|java.lang.Runtime|) , but it accepts a general
 406 file name as an argument rather than just a library name, allowing any file of
 407 native code to be loaded.
 408
 409 The method (|java.lang.System|) is the conventional and convenient means of
 410 invoking this method.
 411
 412     filename - the file to load.
 413
 414 *java.lang.Runtime.loadLibrary(String)*
 415
 416 public void loadLibrary(java.lang.String libname)
 417
 418 Loads the dynamic library with the specified library name. A file containing
 419 native code is loaded from the local file system from a place where library
 420 files are conventionally obtained. The details of this process are
 421 implementation-dependent. The mapping from a library name to a specific
 422 filename is done in a system-specific manner.
 423
 424 First, if there is a security manager, its checkLink method is called with the
 425 libname as its argument. This may result in a security exception.
 426
 427 The method (|java.lang.System|) is the conventional and convenient means of
 428 invoking this method. If native methods are to be used in the implementation of
 429 a class, a standard strategy is to put the native code in a library file (call
 430 it LibFile) and then to put a static initializer:
 431
 432 static { System.loadLibrary("LibFile"); }
 433
 434 within the class declaration. When the class is loaded and initialized, the
 435 necessary native code implementation for the native methods will then be loaded
 436 as well.
 437
 438 If this method is called more than once with the same library name, the second
 439 and subsequent calls are ignored.
 440
 441     libname - the name of the library.
 442
 443 *java.lang.Runtime.maxMemory()*
 444
 445 public native long maxMemory()
 446
 447 Returns the maximum amount of memory that the Java virtual machine will attempt
 448 to use. If there is no inherent limit then the value (|java.lang.Long|) will be
 449 returned.
 450
 451
 452     Returns: the maximum amount of memory that the virtual machine will attempt to use,
 453              measured in bytes
 454 *java.lang.Runtime.removeShutdownHook(Thread)*
 455
 456 public boolean removeShutdownHook(java.lang.Thread hook)
 457
 458 De-registers a previously-registered virtual-machine shutdown hook.
 459
 460     hook - the hook to remove
 461
 462     Returns: true if the specified hook had previously been registered and was successfully
 463              de-registered, false otherwise.
 464 *java.lang.Runtime.runFinalization()*
 465
 466 public void runFinalization()
 467
 468 Runs the finalization methods of any objects pending finalization. Calling this
 469 method suggests that the Java virtual machine expend effort toward running the
 470 finalize methods of objects that have been found to be discarded but whose
 471 finalize methods have not yet been run. When control returns from the method
 472 call, the virtual machine has made a best effort to complete all outstanding
 473 finalizations.
 474
 475 The virtual machine performs the finalization process automatically as needed,
 476 in a separate thread, if the runFinalization method is not invoked explicitly.
 477
 478 The method (|java.lang.System|) is the conventional and convenient means of
 479 invoking this method.
 480
 481
 482 *java.lang.Runtime.runFinalizersOnExit(boolean)*
 483
 484 public static void runFinalizersOnExit(boolean value)
 485
 486 Enable or disable finalization on exit; doing so specifies that the finalizers
 487 of all objects that have finalizers that have not yet been automatically
 488 invoked are to be run before the Java runtime exits. By default, finalization
 489 on exit is disabled.
 490
 491 If there is a security manager, its checkExit method is first called with 0 as
 492 its argument to ensure the exit is allowed. This could result in a
 493 SecurityException.
 494
 495     value - true to enable finalization on exit, false to disable
 496
 497 *java.lang.Runtime.totalMemory()*
 498
 499 public native long totalMemory()
 500
 501 Returns the total amount of memory in the Java virtual machine. The value
 502 returned by this method may vary over time, depending on the host environment.
 503
 504 Note that the amount of memory required to hold an object of any given type may
 505 be implementation-dependent.
 506
 507
 508     Returns: the total amount of memory currently available for current and future objects,
 509              measured in bytes.
 510 *java.lang.Runtime.traceInstructions(boolean)*
 511
 512 public native void traceInstructions(boolean on)
 513
 514 Enables/Disables tracing of instructions. If the boolean argument is true, this
 515 method suggests that the Java virtual machine emit debugging information for
 516 each instruction in the virtual machine as it is executed. The format of this
 517 information, and the file or other output stream to which it is emitted,
 518 depends on the host environment. The virtual machine may ignore this request if
 519 it does not support this feature. The destination of the trace output is system
 520 dependent.
 521
 522 If the boolean argument is false, this method causes the virtual machine to
 523 stop performing the detailed instruction trace it is performing.
 524
 525     on - true to enable instruction tracing; false to disable this feature.
 526
 527 *java.lang.Runtime.traceMethodCalls(boolean)*
 528
 529 public native void traceMethodCalls(boolean on)
 530
 531 Enables/Disables tracing of method calls. If the boolean argument is true, this
 532 method suggests that the Java virtual machine emit debugging information for
 533 each method in the virtual machine as it is called. The format of this
 534 information, and the file or other output stream to which it is emitted,
 535 depends on the host environment. The virtual machine may ignore this request if
 536 it does not support this feature.
 537
 538 Calling this method with argument false suggests that the virtual machine cease
 539 emitting per-call debugging information.
 540
 541     on - true to enable instruction tracing; false to disable this feature.
 542
 543