GNU Classpath (0.92) | |
Frames | No Frames |
1: /* System.java -- useful methods to interface with the system 2: Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005 3: Free Software Foundation, Inc. 4: 5: This file is part of GNU Classpath. 6: 7: GNU Classpath is free software; you can redistribute it and/or modify 8: it under the terms of the GNU General Public License as published by 9: the Free Software Foundation; either version 2, or (at your option) 10: any later version. 11: 12: GNU Classpath is distributed in the hope that it will be useful, but 13: WITHOUT ANY WARRANTY; without even the implied warranty of 14: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 15: General Public License for more details. 16: 17: You should have received a copy of the GNU General Public License 18: along with GNU Classpath; see the file COPYING. If not, write to the 19: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 20: 02110-1301 USA. 21: 22: Linking this library statically or dynamically with other modules is 23: making a combined work based on this library. Thus, the terms and 24: conditions of the GNU General Public License cover the whole 25: combination. 26: 27: As a special exception, the copyright holders of this library give you 28: permission to link this library with independent modules to produce an 29: executable, regardless of the license terms of these independent 30: modules, and to copy and distribute the resulting executable under 31: terms of your choice, provided that you also meet, for each linked 32: independent module, the terms and conditions of the license of that 33: module. An independent module is a module which is not derived from 34: or based on this library. If you modify this library, you may extend 35: this exception to your version of the library, but you are not 36: obligated to do so. If you do not wish to do so, delete this 37: exception statement from your version. */ 38: 39: 40: package java.lang; 41: 42: import gnu.classpath.SystemProperties; 43: import gnu.classpath.VMStackWalker; 44: 45: import java.io.InputStream; 46: import java.io.PrintStream; 47: import java.util.Properties; 48: import java.util.PropertyPermission; 49: 50: /** 51: * System represents system-wide resources; things that represent the 52: * general environment. As such, all methods are static. 53: * 54: * @author John Keiser 55: * @author Eric Blake (ebb9@email.byu.edu) 56: * @since 1.0 57: * @status still missing 1.4 functionality 58: */ 59: public final class System 60: { 61: // WARNING: System is a CORE class in the bootstrap cycle. See the comments 62: // in vm/reference/java/lang/Runtime for implications of this fact. 63: 64: /** 65: * The standard InputStream. This is assigned at startup and starts its 66: * life perfectly valid. Although it is marked final, you can change it 67: * using {@link #setIn(InputStream)} through some hefty VM magic. 68: * 69: * <p>This corresponds to the C stdin and C++ cin variables, which 70: * typically input from the keyboard, but may be used to pipe input from 71: * other processes or files. That should all be transparent to you, 72: * however. 73: */ 74: public static final InputStream in = VMSystem.makeStandardInputStream(); 75: 76: /** 77: * The standard output PrintStream. This is assigned at startup and 78: * starts its life perfectly valid. Although it is marked final, you can 79: * change it using {@link #setOut(PrintStream)} through some hefty VM magic. 80: * 81: * <p>This corresponds to the C stdout and C++ cout variables, which 82: * typically output normal messages to the screen, but may be used to pipe 83: * output to other processes or files. That should all be transparent to 84: * you, however. 85: */ 86: public static final PrintStream out = VMSystem.makeStandardOutputStream(); 87: 88: /** 89: * The standard output PrintStream. This is assigned at startup and 90: * starts its life perfectly valid. Although it is marked final, you can 91: * change it using {@link #setErr(PrintStream)} through some hefty VM magic. 92: * 93: * <p>This corresponds to the C stderr and C++ cerr variables, which 94: * typically output error messages to the screen, but may be used to pipe 95: * output to other processes or files. That should all be transparent to 96: * you, however. 97: */ 98: public static final PrintStream err = VMSystem.makeStandardErrorStream(); 99: 100: /** 101: * This class is uninstantiable. 102: */ 103: private System() 104: { 105: } 106: 107: /** 108: * Set {@link #in} to a new InputStream. This uses some VM magic to change 109: * a "final" variable, so naturally there is a security check, 110: * <code>RuntimePermission("setIO")</code>. 111: * 112: * @param in the new InputStream 113: * @throws SecurityException if permission is denied 114: * @since 1.1 115: */ 116: public static void setIn(InputStream in) 117: { 118: SecurityManager sm = SecurityManager.current; // Be thread-safe. 119: if (sm != null) 120: sm.checkPermission(new RuntimePermission("setIO")); 121: VMSystem.setIn(in); 122: } 123: 124: /** 125: * Set {@link #out} to a new PrintStream. This uses some VM magic to change 126: * a "final" variable, so naturally there is a security check, 127: * <code>RuntimePermission("setIO")</code>. 128: * 129: * @param out the new PrintStream 130: * @throws SecurityException if permission is denied 131: * @since 1.1 132: */ 133: public static void setOut(PrintStream out) 134: { 135: SecurityManager sm = SecurityManager.current; // Be thread-safe. 136: if (sm != null) 137: sm.checkPermission(new RuntimePermission("setIO")); 138: 139: VMSystem.setOut(out); 140: } 141: 142: /** 143: * Set {@link #err} to a new PrintStream. This uses some VM magic to change 144: * a "final" variable, so naturally there is a security check, 145: * <code>RuntimePermission("setIO")</code>. 146: * 147: * @param err the new PrintStream 148: * @throws SecurityException if permission is denied 149: * @since 1.1 150: */ 151: public static void setErr(PrintStream err) 152: { 153: SecurityManager sm = SecurityManager.current; // Be thread-safe. 154: if (sm != null) 155: sm.checkPermission(new RuntimePermission("setIO")); 156: VMSystem.setErr(err); 157: } 158: 159: /** 160: * Set the current SecurityManager. If a security manager already exists, 161: * then <code>RuntimePermission("setSecurityManager")</code> is checked 162: * first. Since this permission is denied by the default security manager, 163: * setting the security manager is often an irreversible action. 164: * 165: * <STRONG>Spec Note:</STRONG> Don't ask me, I didn't write it. It looks 166: * pretty vulnerable; whoever gets to the gate first gets to set the policy. 167: * There is probably some way to set the original security manager as a 168: * command line argument to the VM, but I don't know it. 169: * 170: * @param sm the new SecurityManager 171: * @throws SecurityException if permission is denied 172: */ 173: public static synchronized void setSecurityManager(SecurityManager sm) 174: { 175: // Implementation note: the field lives in SecurityManager because of 176: // bootstrap initialization issues. This method is synchronized so that 177: // no other thread changes it to null before this thread makes the change. 178: if (SecurityManager.current != null) 179: SecurityManager.current.checkPermission 180: (new RuntimePermission("setSecurityManager")); 181: 182: // java.security.Security's class initialiser loads and parses the 183: // policy files. If it hasn't been run already it will be run 184: // during the first permission check. That initialisation will 185: // fail if a very restrictive security manager is in force, so we 186: // preload it here. 187: if (SecurityManager.current == null) 188: { 189: try 190: { 191: Class.forName("java.security.Security"); 192: } 193: catch (ClassNotFoundException e) 194: { 195: } 196: } 197: 198: SecurityManager.current = sm; 199: } 200: 201: /** 202: * Get the current SecurityManager. If the SecurityManager has not been 203: * set yet, then this method returns null. 204: * 205: * @return the current SecurityManager, or null 206: */ 207: public static SecurityManager getSecurityManager() 208: { 209: return SecurityManager.current; 210: } 211: 212: /** 213: * Get the current time, measured in the number of milliseconds from the 214: * beginning of Jan. 1, 1970. This is gathered from the system clock, with 215: * any attendant incorrectness (it may be timezone dependent). 216: * 217: * @return the current time 218: * @see java.util.Date 219: */ 220: public static long currentTimeMillis() 221: { 222: return VMSystem.currentTimeMillis(); 223: } 224: 225: /** 226: * <p> 227: * Returns the current value of a nanosecond-precise system timer. 228: * The value of the timer is an offset relative to some arbitrary fixed 229: * time, which may be in the future (making the value negative). This 230: * method is useful for timing events where nanosecond precision is 231: * required. This is achieved by calling this method before and after the 232: * event, and taking the difference betweent the two times: 233: * </p> 234: * <p> 235: * <code>long startTime = System.nanoTime();</code><br /> 236: * <code>... <emph>event code</emph> ...</code><br /> 237: * <code>long endTime = System.nanoTime();</code><br /> 238: * <code>long duration = endTime - startTime;</code><br /> 239: * </p> 240: * <p> 241: * Note that the value is only nanosecond-precise, and not accurate; there 242: * is no guarantee that the difference between two values is really a 243: * nanosecond. Also, the value is prone to overflow if the offset 244: * exceeds 2^63. 245: * </p> 246: * 247: * @return the time of a system timer in nanoseconds. 248: * @since 1.5 249: */ 250: public static long nanoTime() 251: { 252: return VMSystem.nanoTime(); 253: } 254: 255: /** 256: * Copy one array onto another from <code>src[srcStart]</code> ... 257: * <code>src[srcStart+len-1]</code> to <code>dest[destStart]</code> ... 258: * <code>dest[destStart+len-1]</code>. First, the arguments are validated: 259: * neither array may be null, they must be of compatible types, and the 260: * start and length must fit within both arrays. Then the copying starts, 261: * and proceeds through increasing slots. If src and dest are the same 262: * array, this will appear to copy the data to a temporary location first. 263: * An ArrayStoreException in the middle of copying will leave earlier 264: * elements copied, but later elements unchanged. 265: * 266: * @param src the array to copy elements from 267: * @param srcStart the starting position in src 268: * @param dest the array to copy elements to 269: * @param destStart the starting position in dest 270: * @param len the number of elements to copy 271: * @throws NullPointerException if src or dest is null 272: * @throws ArrayStoreException if src or dest is not an array, if they are 273: * not compatible array types, or if an incompatible runtime type 274: * is stored in dest 275: * @throws IndexOutOfBoundsException if len is negative, or if the start or 276: * end copy position in either array is out of bounds 277: */ 278: public static void arraycopy(Object src, int srcStart, 279: Object dest, int destStart, int len) 280: { 281: VMSystem.arraycopy(src, srcStart, dest, destStart, len); 282: } 283: 284: /** 285: * Get a hash code computed by the VM for the Object. This hash code will 286: * be the same as Object's hashCode() method. It is usually some 287: * convolution of the pointer to the Object internal to the VM. It 288: * follows standard hash code rules, in that it will remain the same for a 289: * given Object for the lifetime of that Object. 290: * 291: * @param o the Object to get the hash code for 292: * @return the VM-dependent hash code for this Object 293: * @since 1.1 294: */ 295: public static int identityHashCode(Object o) 296: { 297: return VMSystem.identityHashCode(o); 298: } 299: 300: /** 301: * Get all the system properties at once. A security check may be performed, 302: * <code>checkPropertiesAccess</code>. Note that a security manager may 303: * allow getting a single property, but not the entire group. 304: * 305: * <p>The required properties include: 306: * <dl> 307: * <dt>java.version</dt> <dd>Java version number</dd> 308: * <dt>java.vendor</dt> <dd>Java vendor specific string</dd> 309: * <dt>java.vendor.url</dt> <dd>Java vendor URL</dd> 310: * <dt>java.home</dt> <dd>Java installation directory</dd> 311: * <dt>java.vm.specification.version</dt> <dd>VM Spec version</dd> 312: * <dt>java.vm.specification.vendor</dt> <dd>VM Spec vendor</dd> 313: * <dt>java.vm.specification.name</dt> <dd>VM Spec name</dd> 314: * <dt>java.vm.version</dt> <dd>VM implementation version</dd> 315: * <dt>java.vm.vendor</dt> <dd>VM implementation vendor</dd> 316: * <dt>java.vm.name</dt> <dd>VM implementation name</dd> 317: * <dt>java.specification.version</dt> <dd>Java Runtime Environment version</dd> 318: * <dt>java.specification.vendor</dt> <dd>Java Runtime Environment vendor</dd> 319: * <dt>java.specification.name</dt> <dd>Java Runtime Environment name</dd> 320: * <dt>java.class.version</dt> <dd>Java class version number</dd> 321: * <dt>java.class.path</dt> <dd>Java classpath</dd> 322: * <dt>java.library.path</dt> <dd>Path for finding Java libraries</dd> 323: * <dt>java.io.tmpdir</dt> <dd>Default temp file path</dd> 324: * <dt>java.compiler</dt> <dd>Name of JIT to use</dd> 325: * <dt>java.ext.dirs</dt> <dd>Java extension path</dd> 326: * <dt>os.name</dt> <dd>Operating System Name</dd> 327: * <dt>os.arch</dt> <dd>Operating System Architecture</dd> 328: * <dt>os.version</dt> <dd>Operating System Version</dd> 329: * <dt>file.separator</dt> <dd>File separator ("/" on Unix)</dd> 330: * <dt>path.separator</dt> <dd>Path separator (":" on Unix)</dd> 331: * <dt>line.separator</dt> <dd>Line separator ("\n" on Unix)</dd> 332: * <dt>user.name</dt> <dd>User account name</dd> 333: * <dt>user.home</dt> <dd>User home directory</dd> 334: * <dt>user.dir</dt> <dd>User's current working directory</dd> 335: * </dl> 336: * 337: * In addition, gnu defines several other properties, where ? stands for 338: * each character in '0' through '9': 339: * <dl> 340: * <dt>gnu.classpath.home</dt> <dd>Path to the classpath libraries.</dd> 341: * <dt>gnu.classpath.version</dt> <dd>Version of the classpath libraries.</dd> 342: * <dt>gnu.classpath.vm.shortname</dt> <dd>Succinct version of the VM name; 343: * used for finding property files in file system</dd> 344: * <dt>gnu.classpath.home.url</dt> <dd> Base URL; used for finding 345: * property files in file system</dd> 346: * <dt>gnu.cpu.endian</dt> <dd>big or little</dd> 347: * <dt>gnu.java.io.encoding_scheme_alias.iso-8859-?</dt> <dd>8859_?</dd> 348: * <dt>gnu.java.io.encoding_scheme_alias.iso8859_?</dt> <dd>8859_?</dd> 349: * <dt>gnu.java.io.encoding_scheme_alias.iso-latin-_?</dt> <dd>8859_?</dd> 350: * <dt>gnu.java.io.encoding_scheme_alias.latin?</dt> <dd>8859_?</dd> 351: * <dt>gnu.java.io.encoding_scheme_alias.utf-8</dt> <dd>UTF8</dd> 352: * <dt>gnu.javax.print.server</dt> <dd>Hostname of external CUPS server.</dd> 353: * </dl> 354: * 355: * @return the system properties, will never be null 356: * @throws SecurityException if permission is denied 357: */ 358: public static Properties getProperties() 359: { 360: SecurityManager sm = SecurityManager.current; // Be thread-safe. 361: if (sm != null) 362: sm.checkPropertiesAccess(); 363: return SystemProperties.getProperties(); 364: } 365: 366: /** 367: * Set all the system properties at once. A security check may be performed, 368: * <code>checkPropertiesAccess</code>. Note that a security manager may 369: * allow setting a single property, but not the entire group. An argument 370: * of null resets the properties to the startup default. 371: * 372: * @param properties the new set of system properties 373: * @throws SecurityException if permission is denied 374: */ 375: public static void setProperties(Properties properties) 376: { 377: SecurityManager sm = SecurityManager.current; // Be thread-safe. 378: if (sm != null) 379: sm.checkPropertiesAccess(); 380: SystemProperties.setProperties(properties); 381: } 382: 383: /** 384: * Get a single system property by name. A security check may be performed, 385: * <code>checkPropertyAccess(key)</code>. 386: * 387: * @param key the name of the system property to get 388: * @return the property, or null if not found 389: * @throws SecurityException if permission is denied 390: * @throws NullPointerException if key is null 391: * @throws IllegalArgumentException if key is "" 392: */ 393: public static String getProperty(String key) 394: { 395: SecurityManager sm = SecurityManager.current; // Be thread-safe. 396: if (sm != null) 397: sm.checkPropertyAccess(key); 398: if (key.length() == 0) 399: throw new IllegalArgumentException("key can't be empty"); 400: return SystemProperties.getProperty(key); 401: } 402: 403: /** 404: * Get a single system property by name. A security check may be performed, 405: * <code>checkPropertyAccess(key)</code>. 406: * 407: * @param key the name of the system property to get 408: * @param def the default 409: * @return the property, or def if not found 410: * @throws SecurityException if permission is denied 411: * @throws NullPointerException if key is null 412: * @throws IllegalArgumentException if key is "" 413: */ 414: public static String getProperty(String key, String def) 415: { 416: SecurityManager sm = SecurityManager.current; // Be thread-safe. 417: if (sm != null) 418: sm.checkPropertyAccess(key); 419: // This handles both the null pointer exception and the illegal 420: // argument exception. 421: if (key.length() == 0) 422: throw new IllegalArgumentException("key can't be empty"); 423: return SystemProperties.getProperty(key, def); 424: } 425: 426: /** 427: * Set a single system property by name. A security check may be performed, 428: * <code>checkPropertyAccess(key, "write")</code>. 429: * 430: * @param key the name of the system property to set 431: * @param value the new value 432: * @return the previous value, or null 433: * @throws SecurityException if permission is denied 434: * @throws NullPointerException if key is null 435: * @throws IllegalArgumentException if key is "" 436: * @since 1.2 437: */ 438: public static String setProperty(String key, String value) 439: { 440: SecurityManager sm = SecurityManager.current; // Be thread-safe. 441: if (sm != null) 442: sm.checkPermission(new PropertyPermission(key, "write")); 443: // This handles both the null pointer exception and the illegal 444: // argument exception. 445: if (key.length() == 0) 446: throw new IllegalArgumentException("key can't be empty"); 447: return SystemProperties.setProperty(key, value); 448: } 449: 450: /** 451: * Remove a single system property by name. A security check may be 452: * performed, <code>checkPropertyAccess(key, "write")</code>. 453: * 454: * @param key the name of the system property to remove 455: * @return the previous value, or null 456: * @throws SecurityException if permission is denied 457: * @throws NullPointerException if key is null 458: * @throws IllegalArgumentException if key is "" 459: * @since 1.5 460: */ 461: public static String clearProperty(String key) 462: { 463: SecurityManager sm = SecurityManager.current; // Be thread-safe. 464: if (sm != null) 465: sm.checkPermission(new PropertyPermission(key, "write")); 466: // This handles both the null pointer exception and the illegal 467: // argument exception. 468: if (key.length() == 0) 469: throw new IllegalArgumentException("key can't be empty"); 470: return SystemProperties.remove(key); 471: } 472: 473: /** 474: * Gets the value of an environment variable. 475: * 476: * @param name the name of the environment variable 477: * @return the string value of the variable or null when the 478: * environment variable is not defined. 479: * @throws NullPointerException 480: * @throws SecurityException if permission is denied 481: * @since 1.5 482: * @specnote This method was deprecated in some JDK releases, but 483: * was restored in 1.5. 484: */ 485: public static String getenv(String name) 486: { 487: if (name == null) 488: throw new NullPointerException(); 489: SecurityManager sm = SecurityManager.current; // Be thread-safe. 490: if (sm != null) 491: sm.checkPermission(new RuntimePermission("getenv." + name)); 492: return VMSystem.getenv(name); 493: } 494: 495: /** 496: * Terminate the Virtual Machine. This just calls 497: * <code>Runtime.getRuntime().exit(status)</code>, and never returns. 498: * Obviously, a security check is in order, <code>checkExit</code>. 499: * 500: * @param status the exit status; by convention non-zero is abnormal 501: * @throws SecurityException if permission is denied 502: * @see Runtime#exit(int) 503: */ 504: public static void exit(int status) 505: { 506: Runtime.getRuntime().exit(status); 507: } 508: 509: /** 510: * Calls the garbage collector. This is only a hint, and it is up to the 511: * implementation what this hint suggests, but it usually causes a 512: * best-effort attempt to reclaim unused memory from discarded objects. 513: * This calls <code>Runtime.getRuntime().gc()</code>. 514: * 515: * @see Runtime#gc() 516: */ 517: public static void gc() 518: { 519: Runtime.getRuntime().gc(); 520: } 521: 522: /** 523: * Runs object finalization on pending objects. This is only a hint, and 524: * it is up to the implementation what this hint suggests, but it usually 525: * causes a best-effort attempt to run finalizers on all objects ready 526: * to be reclaimed. This calls 527: * <code>Runtime.getRuntime().runFinalization()</code>. 528: * 529: * @see Runtime#runFinalization() 530: */ 531: public static void runFinalization() 532: { 533: Runtime.getRuntime().runFinalization(); 534: } 535: 536: /** 537: * Tell the Runtime whether to run finalization before exiting the 538: * JVM. This is inherently unsafe in multi-threaded applications, 539: * since it can force initialization on objects which are still in use 540: * by live threads, leading to deadlock; therefore this is disabled by 541: * default. There may be a security check, <code>checkExit(0)</code>. This 542: * calls <code>Runtime.runFinalizersOnExit()</code>. 543: * 544: * @param finalizeOnExit whether to run finalizers on exit 545: * @throws SecurityException if permission is denied 546: * @see Runtime#runFinalizersOnExit(boolean) 547: * @since 1.1 548: * @deprecated never rely on finalizers to do a clean, thread-safe, 549: * mop-up from your code 550: */ 551: public static void runFinalizersOnExit(boolean finalizeOnExit) 552: { 553: Runtime.runFinalizersOnExit(finalizeOnExit); 554: } 555: 556: /** 557: * Load a code file using its explicit system-dependent filename. A security 558: * check may be performed, <code>checkLink</code>. This just calls 559: * <code>Runtime.getRuntime().load(filename)</code>. 560: * 561: * <p> 562: * The library is loaded using the class loader associated with the 563: * class associated with the invoking method. 564: * 565: * @param filename the code file to load 566: * @throws SecurityException if permission is denied 567: * @throws UnsatisfiedLinkError if the file cannot be loaded 568: * @see Runtime#load(String) 569: */ 570: public static void load(String filename) 571: { 572: Runtime.getRuntime().load(filename, VMStackWalker.getCallingClassLoader()); 573: } 574: 575: /** 576: * Load a library using its explicit system-dependent filename. A security 577: * check may be performed, <code>checkLink</code>. This just calls 578: * <code>Runtime.getRuntime().load(filename)</code>. 579: * 580: * <p> 581: * The library is loaded using the class loader associated with the 582: * class associated with the invoking method. 583: * 584: * @param libname the library file to load 585: * @throws SecurityException if permission is denied 586: * @throws UnsatisfiedLinkError if the file cannot be loaded 587: * @see Runtime#load(String) 588: */ 589: public static void loadLibrary(String libname) 590: { 591: Runtime.getRuntime().loadLibrary(libname, 592: VMStackWalker.getCallingClassLoader()); 593: } 594: 595: /** 596: * Convert a library name to its platform-specific variant. 597: * 598: * @param libname the library name, as used in <code>loadLibrary</code> 599: * @return the platform-specific mangling of the name 600: * @since 1.2 601: */ 602: public static String mapLibraryName(String libname) 603: { 604: return VMRuntime.mapLibraryName(libname); 605: } 606: 607: } // class System
GNU Classpath (0.92) |