sample/java.lang.System.txt

   1 *java.lang.System* *System* The System class contains several useful class field
   2
   3 public final class System
   4   extends    |java.lang.Object|
   5
   6 |java.lang.System_Description|
   7 |java.lang.System_Fields|
   8 |java.lang.System_Constructors|
   9 |java.lang.System_Methods|
  10
  11 ================================================================================
  12
  13 *java.lang.System_Fields*
  14 |java.io.PrintStream_java.lang.System.err|
  15 |java.io.InputStream_java.lang.System.in|
  16 |java.io.PrintStream_java.lang.System.out|
  17
  18 *java.lang.System_Methods*
  19 |java.lang.System.arraycopy(Object,int,Object,int,int)|Copies an array from the
  20 |java.lang.System.clearProperty(String)|Removes the system property indicated b
  21 |java.lang.System.console()|Returns the uniquejava.io.Console Consoleobject ass
  22 |java.lang.System.currentTimeMillis()|Returns the current time in milliseconds.
  23 |java.lang.System.exit(int)|Terminates the currently running Java Virtual Machi
  24 |java.lang.System.gc()|Runs the garbage collector.
  25 |java.lang.System.getenv()|Returns an unmodifiable string map view of the curre
  26 |java.lang.System.getenv(String)|Gets the value of the specified environment va
  27 |java.lang.System.getProperties()|Determines the current system properties.
  28 |java.lang.System.getProperty(String)|Gets the system property indicated by the
  29 |java.lang.System.getProperty(String,String)|Gets the system property indicated
  30 |java.lang.System.getSecurityManager()|Gets the system security interface.
  31 |java.lang.System.identityHashCode(Object)|Returns the same hash code for the g
  32 |java.lang.System.inheritedChannel()|Returns the channel inherited from the ent
  33 |java.lang.System.load(String)|Loads a code file with the specified filename fr
  34 |java.lang.System.loadLibrary(String)|Loads the system library specified by the
  35 |java.lang.System.mapLibraryName(String)|Maps a library name into a platform-sp
  36 |java.lang.System.nanoTime()|Returns the current value of the most precise avai
  37 |java.lang.System.runFinalization()|Runs the finalization methods of any object
  38 |java.lang.System.runFinalizersOnExit(boolean)|Enable or disable finalization o
  39 |java.lang.System.setErr(PrintStream)|Reassigns the "standard" error output str
  40 |java.lang.System.setIn(InputStream)|Reassigns the "standard" input stream.
  41 |java.lang.System.setOut(PrintStream)|Reassigns the "standard" output stream.
  42 |java.lang.System.setProperties(Properties)|Sets the system properties to the P
  43 |java.lang.System.setProperty(String,String)|Sets the system property indicated
  44 |java.lang.System.setSecurityManager(SecurityManager)|Sets the System security.
  45
  46 *java.lang.System_Description*
  47
  48 The System class contains several useful class fields and methods. It cannot be
  49 instantiated.
  50
  51 Among the facilities provided by the System class are standard input, standard
  52 output, and error output streams; access to externally defined properties and
  53 environment variables; a means of loading files and libraries; and a utility
  54 method for quickly copying a portion of an array.
  55
  56
  57
  58 *java.io.PrintStream_java.lang.System.err*
  59
  60 The "standard" error output stream. This stream is already open and ready to
  61 accept output data.
  62
  63 Typically this stream corresponds to display output or another output
  64 destination specified by the host environment or user. By convention, this
  65 output stream is used to display error messages or other information that
  66 should come to the immediate attention of a user even if the principal output
  67 stream, the value of the variable out, has been redirected to a file or other
  68 destination that is typically not continuously monitored.
  69
  70
  71 *java.io.InputStream_java.lang.System.in*
  72
  73 The "standard" input stream. This stream is already open and ready to supply
  74 input data. Typically this stream corresponds to keyboard input or another
  75 input source specified by the host environment or user.
  76
  77
  78 *java.io.PrintStream_java.lang.System.out*
  79
  80 The "standard" output stream. This stream is already open and ready to accept
  81 output data. Typically this stream corresponds to display output or another
  82 output destination specified by the host environment or user.
  83
  84 For simple stand-alone Java applications, a typical way to write a line of
  85 output data is:
  86
  87 System.out.println(data)
  88
  89 See the println methods in class PrintStream.
  90
  91
  92
  93 *java.lang.System.arraycopy(Object,int,Object,int,int)*
  94
  95 public static native void arraycopy(
  96   java.lang.Object src,
  97   int srcPos,
  98   java.lang.Object dest,
  99   int destPos,
 100   int length)
 101
 102 Copies an array from the specified source array, beginning at the specified
 103 position, to the specified position of the destination array. A subsequence of
 104 array components are copied from the source array referenced by src to the
 105 destination array referenced by dest. The number of components copied is equal
 106 to the length argument. The components at positions srcPos through
 107 srcPos+length-1 in the source array are copied into positions destPos through
 108 destPos+length-1, respectively, of the destination array.
 109
 110 If the src and dest arguments refer to the same array object, then the copying
 111 is performed as if the components at positions srcPos through srcPos+length-1
 112 were first copied to a temporary array with length components and then the
 113 contents of the temporary array were copied into positions destPos through
 114 destPos+length-1 of the destination array.
 115
 116 If dest is null, then a NullPointerException is thrown.
 117
 118 If src is null, then a NullPointerException is thrown and the destination array
 119 is not modified.
 120
 121 Otherwise, if any of the following is true, an ArrayStoreException is thrown
 122 and the destination is not modified:
 123
 124 The src argument refers to an object that is not an array. The dest argument
 125 refers to an object that is not an array. The src argument and dest argument
 126 refer to arrays whose component types are different primitive types. The src
 127 argument refers to an array with a primitive component type and the dest
 128 argument refers to an array with a reference component type. The src argument
 129 refers to an array with a reference component type and the dest argument refers
 130 to an array with a primitive component type.
 131
 132 Otherwise, if any of the following is true, an IndexOutOfBoundsException is
 133 thrown and the destination is not modified:
 134
 135 The srcPos argument is negative. The destPos argument is negative. The length
 136 argument is negative. srcPos+length is greater than src.length, the length of
 137 the source array. destPos+length is greater than dest.length, the length of the
 138 destination array.
 139
 140 Otherwise, if any actual component of the source array from position srcPos
 141 through srcPos+length-1 cannot be converted to the component type of the
 142 destination array by assignment conversion, an ArrayStoreException is thrown.
 143 In this case, let k be the smallest nonnegative integer less than length such
 144 that src[srcPos+k] cannot be converted to the component type of the destination
 145 array; when the exception is thrown, source array components from positions
 146 srcPos through srcPos+k-1 will already have been copied to destination array
 147 positions destPos through destPos+k-1 and no other positions of the destination
 148 array will have been modified. (Because of the restrictions already itemized,
 149 this paragraph effectively applies only to the situation where both arrays have
 150 component types that are reference types.)
 151
 152
 153     src - the source array.
 154     srcPos - starting position in the source array.
 155     dest - the destination array.
 156     destPos - starting position in the destination data.
 157     length - the number of array elements to be copied.
 158
 159 *java.lang.System.clearProperty(String)*
 160
 161 public static |java.lang.String| clearProperty(java.lang.String key)
 162
 163 Removes the system property indicated by the specified key.
 164
 165 First, if a security manager exists, its SecurityManager.checkPermission method
 166 is called with a PropertyPermission(key, "write") permission. This may result
 167 in a SecurityException being thrown. If no exception is thrown, the specified
 168 property is removed.
 169
 170
 171     key - the name of the system property to be removed.
 172
 173     Returns: the previous string value of the system property, or null if there was no
 174              property with that key.
 175
 176 *java.lang.System.console()*
 177
 178 public static |java.io.Console| console()
 179
 180 Returns the unique Console(|java.io.Console|) object associated with the
 181 current Java virtual machine, if any.
 182
 183
 184
 185     Returns: The system console, if any, otherwise null.
 186
 187 *java.lang.System.currentTimeMillis()*
 188
 189 public static native long currentTimeMillis()
 190
 191 Returns the current time in milliseconds. Note that while the unit of time of
 192 the return value is a millisecond, the granularity of the value depends on the
 193 underlying operating system and may be larger. For example, many operating
 194 systems measure time in units of tens of milliseconds.
 195
 196 See the description of the class Date for a discussion of slight discrepancies
 197 that may arise between "computer time" and coordinated universal time (UTC).
 198
 199
 200
 201     Returns: the difference, measured in milliseconds, between the current time and
 202              midnight, January 1, 1970 UTC.
 203
 204 *java.lang.System.exit(int)*
 205
 206 public static void exit(int status)
 207
 208 Terminates the currently running Java Virtual Machine. The argument serves as a
 209 status code; by convention, a nonzero status code indicates abnormal
 210 termination.
 211
 212 This method calls the exit method in class Runtime. This method never returns
 213 normally.
 214
 215 The call System.exit(n) is effectively equivalent to the call:
 216
 217 Runtime.getRuntime().exit(n)
 218
 219
 220     status - exit status.
 221
 222 *java.lang.System.gc()*
 223
 224 public static void gc()
 225
 226 Runs the garbage collector.
 227
 228 Calling the gc method suggests that the Java Virtual Machine expend effort
 229 toward recycling unused objects in order to make the memory they currently
 230 occupy available for quick reuse. When control returns from the method call,
 231 the Java Virtual Machine has made a best effort to reclaim space from all
 232 discarded objects.
 233
 234 The call System.gc() is effectively equivalent to the call:
 235
 236 Runtime.getRuntime().gc()
 237
 238
 239
 240 *java.lang.System.getenv()*
 241
 242 public static |java.util.Map|<String,String> getenv()
 243
 244 Returns an unmodifiable string map view of the current system environment. The
 245 environment is a system-dependent mapping from names to values which is passed
 246 from parent to child processes.
 247
 248 If the system does not support environment variables, an empty map is returned.
 249
 250 The returned map will never contain null keys or values. Attempting to query
 251 the presence of a null key or value will throw a
 252 (|java.lang.NullPointerException|) . Attempting to query the presence of a key
 253 or value which is not of type (|java.lang.String|) will throw a
 254 (|java.lang.ClassCastException|) .
 255
 256 The returned map and its collection views may not obey the general contract of
 257 the (|java.lang.Object|) and (|java.lang.Object|) methods.
 258
 259 The returned map is typically case-sensitive on all platforms.
 260
 261 If a security manager exists, its checkPermission(|java.lang.SecurityManager|)
 262 method is called with a (|java.lang.RuntimePermission|) ("getenv.*")
 263 permission. This may result in a (|java.lang.SecurityException|) being thrown.
 264
 265 When passing information to a Java subprocess, system properties are generally
 266 preferred over environment variables.
 267
 268
 269
 270     Returns: the environment as a map of variable names to values
 271
 272 *java.lang.System.getenv(String)*
 273
 274 public static |java.lang.String| getenv(java.lang.String name)
 275
 276 Gets the value of the specified environment variable. An environment variable
 277 is a system-dependent external named value.
 278
 279 If a security manager exists, its checkPermission(|java.lang.SecurityManager|)
 280 method is called with a (|java.lang.RuntimePermission|) ("getenv."+name)
 281 permission. This may result in a (|java.lang.SecurityException|) being thrown.
 282 If no exception is thrown the value of the variable name is returned.
 283
 284 System properties and environment variables are both conceptually mappings
 285 between names and values. Both mechanisms can be used to pass user-defined
 286 information to a Java process. Environment variables have a more global effect,
 287 because they are visible to all descendants of the process which defines them,
 288 not just the immediate Java subprocess. They can have subtly different
 289 semantics, such as case insensitivity, on different operating systems. For
 290 these reasons, environment variables are more likely to have unintended side
 291 effects. It is best to use system properties where possible. Environment
 292 variables should be used when a global effect is desired, or when an external
 293 system interface requires an environment variable (such as PATH).
 294
 295 On UNIX systems the alphabetic case of name is typically significant, while on
 296 Microsoft Windows systems it is typically not. For example, the expression
 297 System.getenv("FOO").equals(System.getenv("foo")) is likely to be true on
 298 Microsoft Windows.
 299
 300
 301     name - the name of the environment variable
 302
 303     Returns: the string value of the variable, or null if the variable is not defined in the
 304              system environment
 305
 306 *java.lang.System.getProperties()*
 307
 308 public static |java.util.Properties| getProperties()
 309
 310 Determines the current system properties.
 311
 312 First, if there is a security manager, its checkPropertiesAccess method is
 313 called with no arguments. This may result in a security exception.
 314
 315 The current set of system properties for use by the (|java.lang.System|) method
 316 is returned as a Properties object. If there is no current set of system
 317 properties, a set of system properties is first created and initialized. This
 318 set of system properties always includes values for the following keys:
 319
 320 Key Description of Associated Value java.version Java Runtime Environment
 321 version java.vendor Java Runtime Environment vendorjava.vendor.url Java vendor
 322 URL java.home Java installation directory java.vm.specification.version Java
 323 Virtual Machine specification version java.vm.specification.vendor Java Virtual
 324 Machine specification vendor java.vm.specification.name Java Virtual Machine
 325 specification name java.vm.version Java Virtual Machine implementation version
 326 java.vm.vendor Java Virtual Machine implementation vendor java.vm.name Java
 327 Virtual Machine implementation name java.specification.version Java Runtime
 328 Environment specification version java.specification.vendor Java Runtime
 329 Environment specification vendor java.specification.name Java Runtime
 330 Environment specification name java.class.version Java class format version
 331 number java.class.path Java class path java.library.path List of paths to
 332 search when loading libraries java.io.tmpdir Default temp file path
 333 java.compiler Name of JIT compiler to use java.ext.dirs Path of extension
 334 directory or directories os.name Operating system name os.arch Operating system
 335 architecture os.version Operating system version file.separator File separator
 336 ("/" on UNIX) path.separator Path separator (":" on UNIX) line.separator Line
 337 separator ("\n" on UNIX) user.name User's account name user.home User's home
 338 directory user.dir User's current working directory
 339
 340 Multiple paths in a system property value are separated by the path separator
 341 character of the platform.
 342
 343 Note that even if the security manager does not permit the getProperties
 344 operation, it may choose to permit the (|java.lang.System|) operation.
 345
 346
 347
 348     Returns: the system properties
 349
 350 *java.lang.System.getProperty(String)*
 351
 352 public static |java.lang.String| getProperty(java.lang.String key)
 353
 354 Gets the system property indicated by the specified key.
 355
 356 First, if there is a security manager, its checkPropertyAccess method is called
 357 with the key as its argument. This may result in a SecurityException.
 358
 359 If there is no current set of system properties, a set of system properties is
 360 first created and initialized in the same manner as for the getProperties
 361 method.
 362
 363
 364     key - the name of the system property.
 365
 366     Returns: the string value of the system property, or null if there is no property with
 367              that key.
 368
 369 *java.lang.System.getProperty(String,String)*
 370
 371 public static |java.lang.String| getProperty(
 372   java.lang.String key,
 373   java.lang.String def)
 374
 375 Gets the system property indicated by the specified key.
 376
 377 First, if there is a security manager, its checkPropertyAccess method is called
 378 with the key as its argument.
 379
 380 If there is no current set of system properties, a set of system properties is
 381 first created and initialized in the same manner as for the getProperties
 382 method.
 383
 384
 385     key - the name of the system property.
 386     def - a default value.
 387
 388     Returns: the string value of the system property, or the default value if there is no
 389              property with that key.
 390
 391 *java.lang.System.getSecurityManager()*
 392
 393 public static |java.lang.SecurityManager| getSecurityManager()
 394
 395 Gets the system security interface.
 396
 397
 398
 399     Returns: if a security manager has already been established for the current application,
 400              then that security manager is returned; otherwise, null is
 401              returned.
 402
 403 *java.lang.System.identityHashCode(Object)*
 404
 405 public static native int identityHashCode(java.lang.Object x)
 406
 407 Returns the same hash code for the given object as would be returned by the
 408 default method hashCode(), whether or not the given object's class overrides
 409 hashCode(). The hash code for the null reference is zero.
 410
 411
 412     x - object for which the hashCode is to be calculated
 413
 414     Returns:
 415
 416 *java.lang.System.inheritedChannel()*
 417
 418 public static |java.nio.channels.Channel| inheritedChannel()
 419   throws |java.io.IOException|
 420
 421 Returns the channel inherited from the entity that created this Java virtual
 422 machine.
 423
 424 This method returns the channel obtained by invoking the
 425 inheritedChannel(|java.nio.channels.spi.SelectorProvider|) method of the
 426 system-wide default (|java.nio.channels.spi.SelectorProvider|) object.
 427
 428 In addition to the network-oriented channels described in
 429 inheritedChannel(|java.nio.channels.spi.SelectorProvider|) , this method may
 430 return other kinds of channels in the future.
 431
 432
 433
 434     Returns: The inherited channel, if any, otherwise null.
 435
 436 *java.lang.System.load(String)*
 437
 438 public static void load(java.lang.String filename)
 439
 440 Loads a code file with the specified filename from the local file system as a
 441 dynamic library. The filename argument must be a complete path name.
 442
 443 The call System.load(name) is effectively equivalent to the call:
 444
 445 Runtime.getRuntime().load(name)
 446
 447
 448     filename - the file to load.
 449
 450 *java.lang.System.loadLibrary(String)*
 451
 452 public static void loadLibrary(java.lang.String libname)
 453
 454 Loads the system library specified by the libname argument. The manner in which
 455 a library name is mapped to the actual system library is system dependent.
 456
 457 The call System.loadLibrary(name) is effectively equivalent to the call
 458
 459 Runtime.getRuntime().loadLibrary(name)
 460
 461
 462     libname - the name of the library.
 463
 464 *java.lang.System.mapLibraryName(String)*
 465
 466 public static native |java.lang.String| mapLibraryName(java.lang.String libname)
 467
 468 Maps a library name into a platform-specific string representing a native
 469 library.
 470
 471
 472     libname - the name of the library.
 473
 474     Returns: a platform-dependent native library name.
 475
 476 *java.lang.System.nanoTime()*
 477
 478 public static native long nanoTime()
 479
 480 Returns the current value of the most precise available system timer, in
 481 nanoseconds.
 482
 483 This method can only be used to measure elapsed time and is not related to any
 484 other notion of system or wall-clock time. The value returned represents
 485 nanoseconds since some fixed but arbitrary time (perhaps in the future, so
 486 values may be negative). This method provides nanosecond precision, but not
 487 necessarily nanosecond accuracy. No guarantees are made about how frequently
 488 values change. Differences in successive calls that span greater than
 489 approximately 292 years (263 nanoseconds) will not accurately compute elapsed
 490 time due to numerical overflow.
 491
 492 For example, to measure how long some code takes to execute:
 493
 494 long startTime = System.nanoTime(); // ... the code being measured ... long
 495 estimatedTime = System.nanoTime() - startTime;
 496
 497
 498
 499     Returns: The current value of the system timer, in nanoseconds.
 500
 501 *java.lang.System.runFinalization()*
 502
 503 public static void runFinalization()
 504
 505 Runs the finalization methods of any objects pending finalization.
 506
 507 Calling this method suggests that the Java Virtual Machine expend effort toward
 508 running the finalize methods of objects that have been found to be discarded
 509 but whose finalize methods have not yet been run. When control returns from the
 510 method call, the Java Virtual Machine has made a best effort to complete all
 511 outstanding finalizations.
 512
 513 The call System.runFinalization() is effectively equivalent to the call:
 514
 515 Runtime.getRuntime().runFinalization()
 516
 517
 518
 519 *java.lang.System.runFinalizersOnExit(boolean)*
 520
 521 public static void runFinalizersOnExit(boolean value)
 522
 523 Enable or disable finalization on exit; doing so specifies that the finalizers
 524 of all objects that have finalizers that have not yet been automatically
 525 invoked are to be run before the Java runtime exits. By default, finalization
 526 on exit is disabled.
 527
 528 If there is a security manager, its checkExit method is first called with 0 as
 529 its argument to ensure the exit is allowed. This could result in a
 530 SecurityException.
 531
 532     Deprecated: This method is inherently unsafe.  It may result in
 533             finalizers being called on live objects while other threads are
 534       concurrently manipulating those objects, resulting in erratic
 535             behavior or deadlock.
 536
 537     value - indicating enabling or disabling of finalization
 538
 539 *java.lang.System.setErr(PrintStream)*
 540
 541 public static void setErr(java.io.PrintStream err)
 542
 543 Reassigns the "standard" error output stream.
 544
 545 First, if there is a security manager, its checkPermission method is called
 546 with a RuntimePermission("setIO") permission to see if it's ok to reassign the
 547 "standard" error output stream.
 548
 549
 550     err - the new standard error output stream.
 551
 552 *java.lang.System.setIn(InputStream)*
 553
 554 public static void setIn(java.io.InputStream in)
 555
 556 Reassigns the "standard" input stream.
 557
 558 First, if there is a security manager, its checkPermission method is called
 559 with a RuntimePermission("setIO") permission to see if it's ok to reassign the
 560 "standard" input stream.
 561
 562
 563     in - the new standard input stream.
 564
 565 *java.lang.System.setOut(PrintStream)*
 566
 567 public static void setOut(java.io.PrintStream out)
 568
 569 Reassigns the "standard" output stream.
 570
 571 First, if there is a security manager, its checkPermission method is called
 572 with a RuntimePermission("setIO") permission to see if it's ok to reassign the
 573 "standard" output stream.
 574
 575
 576     out - the new standard output stream
 577
 578 *java.lang.System.setProperties(Properties)*
 579
 580 public static void setProperties(java.util.Properties props)
 581
 582 Sets the system properties to the Properties argument.
 583
 584 First, if there is a security manager, its checkPropertiesAccess method is
 585 called with no arguments. This may result in a security exception.
 586
 587 The argument becomes the current set of system properties for use by the
 588 (|java.lang.System|) method. If the argument is null, then the current set of
 589 system properties is forgotten.
 590
 591
 592     props - the new system properties.
 593
 594 *java.lang.System.setProperty(String,String)*
 595
 596 public static |java.lang.String| setProperty(
 597   java.lang.String key,
 598   java.lang.String value)
 599
 600 Sets the system property indicated by the specified key.
 601
 602 First, if a security manager exists, its SecurityManager.checkPermission method
 603 is called with a PropertyPermission(key, "write") permission. This may result
 604 in a SecurityException being thrown. If no exception is thrown, the specified
 605 property is set to the given value.
 606
 607
 608     key - the name of the system property.
 609     value - the value of the system property.
 610
 611     Returns: the previous value of the system property, or null if it did not have one.
 612
 613 *java.lang.System.setSecurityManager(SecurityManager)*
 614
 615 public static void setSecurityManager(java.lang.SecurityManager s)
 616
 617 Sets the System security.
 618
 619 If there is a security manager already installed, this method first calls the
 620 security manager's checkPermission method with a
 621 RuntimePermission("setSecurityManager") permission to ensure it's ok to replace
 622 the existing security manager. This may result in throwing a SecurityException.
 623
 624 Otherwise, the argument is established as the current security manager. If the
 625 argument is null and no security manager has been established, then no action
 626 is taken and the method simply returns.
 627
 628
 629     s - the security manager.
 630
 631