Source for java.lang.System

   1: /* System.java -- useful methods to interface with the system
   2:    Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006
   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: 
  44: import java.io.BufferedInputStream;
  45: import java.io.BufferedOutputStream;
  46: import java.io.FileDescriptor;
  47: import java.io.FileInputStream;
  48: import java.io.FileOutputStream;
  49: import java.io.InputStream;
  50: import java.io.PrintStream;
  51: import java.util.Properties;
  52: import java.util.PropertyPermission;
  53: 
  54: /**
  55:  * System represents system-wide resources; things that represent the
  56:  * general environment.  As such, all methods are static.
  57:  *
  58:  * @author John Keiser
  59:  * @author Eric Blake (ebb9@email.byu.edu)
  60:  * @since 1.0
  61:  * @status still missing 1.4 functionality
  62:  */
  63: public final class System
  64: {
  65:   // WARNING: System is a CORE class in the bootstrap cycle. See the comments
  66:   // in vm/reference/java/lang/Runtime for implications of this fact.
  67: 
  68:   /**
  69:    * The standard InputStream. This is assigned at startup and starts its
  70:    * life perfectly valid. Although it is marked final, you can change it
  71:    * using {@link #setIn(InputStream)} through some hefty VM magic.
  72:    *
  73:    * <p>This corresponds to the C stdin and C++ cin variables, which
  74:    * typically input from the keyboard, but may be used to pipe input from
  75:    * other processes or files.  That should all be transparent to you,
  76:    * however.
  77:    */
  78:   public static final InputStream in
  79:     = new BufferedInputStream(new FileInputStream(FileDescriptor.in));
  80:   /**
  81:    * The standard output PrintStream.  This is assigned at startup and
  82:    * starts its life perfectly valid. Although it is marked final, you can
  83:    * change it using {@link #setOut(PrintStream)} through some hefty VM magic.
  84:    *
  85:    * <p>This corresponds to the C stdout and C++ cout variables, which
  86:    * typically output normal messages to the screen, but may be used to pipe
  87:    * output to other processes or files.  That should all be transparent to
  88:    * you, however.
  89:    */
  90:   public static final PrintStream out
  91:     = new PrintStream(new BufferedOutputStream(new FileOutputStream(FileDescriptor.out)), true);
  92:   /**
  93:    * The standard output PrintStream.  This is assigned at startup and
  94:    * starts its life perfectly valid. Although it is marked final, you can
  95:    * change it using {@link #setErr(PrintStream)} through some hefty VM magic.
  96:    *
  97:    * <p>This corresponds to the C stderr and C++ cerr variables, which
  98:    * typically output error messages to the screen, but may be used to pipe
  99:    * output to other processes or files.  That should all be transparent to
 100:    * you, however.
 101:    */
 102:   public static final PrintStream err
 103:     = new PrintStream(new BufferedOutputStream(new FileOutputStream(FileDescriptor.err)), true);
 104: 
 105:   /**
 106:    * This class is uninstantiable.
 107:    */
 108:   private System()
 109:   {
 110:   }
 111: 
 112:   /**
 113:    * Set {@link #in} to a new InputStream. This uses some VM magic to change
 114:    * a "final" variable, so naturally there is a security check,
 115:    * <code>RuntimePermission("setIO")</code>.
 116:    *
 117:    * @param in the new InputStream
 118:    * @throws SecurityException if permission is denied
 119:    * @since 1.1
 120:    */
 121:   public static void setIn(InputStream in)
 122:   {
 123:     SecurityManager sm = SecurityManager.current; // Be thread-safe.
 124:     if (sm != null)
 125:       sm.checkPermission(new RuntimePermission("setIO"));
 126:     setIn0(in);
 127:   }
 128: 
 129:   /**
 130:    * Set {@link #out} to a new PrintStream. This uses some VM magic to change
 131:    * a "final" variable, so naturally there is a security check,
 132:    * <code>RuntimePermission("setIO")</code>.
 133:    *
 134:    * @param out the new PrintStream
 135:    * @throws SecurityException if permission is denied
 136:    * @since 1.1
 137:    */
 138:   public static void setOut(PrintStream out)
 139:   {
 140:     SecurityManager sm = SecurityManager.current; // Be thread-safe.
 141:     if (sm != null)
 142:       sm.checkPermission(new RuntimePermission("setIO"));
 143:     
 144:     setOut0(out);
 145:   }
 146: 
 147:   /**
 148:    * Set {@link #err} to a new PrintStream. This uses some VM magic to change
 149:    * a "final" variable, so naturally there is a security check,
 150:    * <code>RuntimePermission("setIO")</code>.
 151:    *
 152:    * @param err the new PrintStream
 153:    * @throws SecurityException if permission is denied
 154:    * @since 1.1
 155:    */
 156:   public static void setErr(PrintStream err)
 157:   {
 158:     SecurityManager sm = SecurityManager.current; // Be thread-safe.
 159:     if (sm != null)
 160:       sm.checkPermission(new RuntimePermission("setIO"));
 161:     setErr0(err);
 162:   }
 163: 
 164:   /**
 165:    * Set the current SecurityManager. If a security manager already exists,
 166:    * then <code>RuntimePermission("setSecurityManager")</code> is checked
 167:    * first. Since this permission is denied by the default security manager,
 168:    * setting the security manager is often an irreversible action.
 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:     SecurityManager.current = sm;
 182:   }
 183: 
 184:   /**
 185:    * Get the current SecurityManager. If the SecurityManager has not been
 186:    * set yet, then this method returns null.
 187:    *
 188:    * @return the current SecurityManager, or null
 189:    */
 190:   public static SecurityManager getSecurityManager()
 191:   {
 192:     return SecurityManager.current;
 193:   }
 194: 
 195:   /**
 196:    * Get the current time, measured in the number of milliseconds from the
 197:    * beginning of Jan. 1, 1970. This is gathered from the system clock, with
 198:    * any attendant incorrectness (it may be timezone dependent).
 199:    *
 200:    * @return the current time
 201:    * @see java.util.Date
 202:    */
 203:   public static native long currentTimeMillis();
 204: 
 205:   /**
 206:    * Get the current time, measured in nanoseconds.  The result is as
 207:    * precise as possible, and is measured against a fixed epoch.
 208:    * However, unlike currentTimeMillis(), the epoch chosen is
 209:    * arbitrary and may vary by platform, etc.
 210:    * @since 1.5
 211:    */
 212:   public static native long nanoTime();
 213: 
 214:   /**
 215:    * Copy one array onto another from <code>src[srcStart]</code> ...
 216:    * <code>src[srcStart+len-1]</code> to <code>dest[destStart]</code> ...
 217:    * <code>dest[destStart+len-1]</code>. First, the arguments are validated:
 218:    * neither array may be null, they must be of compatible types, and the
 219:    * start and length must fit within both arrays. Then the copying starts,
 220:    * and proceeds through increasing slots.  If src and dest are the same
 221:    * array, this will appear to copy the data to a temporary location first.
 222:    * An ArrayStoreException in the middle of copying will leave earlier
 223:    * elements copied, but later elements unchanged.
 224:    *
 225:    * @param src the array to copy elements from
 226:    * @param srcStart the starting position in src
 227:    * @param dest the array to copy elements to
 228:    * @param destStart the starting position in dest
 229:    * @param len the number of elements to copy
 230:    * @throws NullPointerException if src or dest is null
 231:    * @throws ArrayStoreException if src or dest is not an array, if they are
 232:    *         not compatible array types, or if an incompatible runtime type
 233:    *         is stored in dest
 234:    * @throws IndexOutOfBoundsException if len is negative, or if the start or
 235:    *         end copy position in either array is out of bounds
 236:    */
 237:   public static native void arraycopy(Object src, int srcStart,
 238:                       Object dest, int destStart, int len);
 239: 
 240:   /**
 241:    * Get a hash code computed by the VM for the Object. This hash code will
 242:    * be the same as Object's hashCode() method.  It is usually some
 243:    * convolution of the pointer to the Object internal to the VM.  It
 244:    * follows standard hash code rules, in that it will remain the same for a
 245:    * given Object for the lifetime of that Object.
 246:    *
 247:    * @param o the Object to get the hash code for
 248:    * @return the VM-dependent hash code for this Object
 249:    * @since 1.1
 250:    */
 251:   public static native int identityHashCode(Object o);
 252: 
 253:   /**
 254:    * Get all the system properties at once. A security check may be performed,
 255:    * <code>checkPropertiesAccess</code>. Note that a security manager may
 256:    * allow getting a single property, but not the entire group.
 257:    *
 258:    * <p>The required properties include:
 259:    * <dl>
 260:    * <dt>java.version</dt>         <dd>Java version number</dd>
 261:    * <dt>java.vendor</dt>          <dd>Java vendor specific string</dd>
 262:    * <dt>java.vendor.url</dt>      <dd>Java vendor URL</dd>
 263:    * <dt>java.home</dt>            <dd>Java installation directory</dd>
 264:    * <dt>java.vm.specification.version</dt> <dd>VM Spec version</dd>
 265:    * <dt>java.vm.specification.vendor</dt>  <dd>VM Spec vendor</dd>
 266:    * <dt>java.vm.specification.name</dt>    <dd>VM Spec name</dd>
 267:    * <dt>java.vm.version</dt>      <dd>VM implementation version</dd>
 268:    * <dt>java.vm.vendor</dt>       <dd>VM implementation vendor</dd>
 269:    * <dt>java.vm.name</dt>         <dd>VM implementation name</dd>
 270:    * <dt>java.specification.version</dt>    <dd>Java Runtime Environment version</dd>
 271:    * <dt>java.specification.vendor</dt>     <dd>Java Runtime Environment vendor</dd>
 272:    * <dt>java.specification.name</dt>       <dd>Java Runtime Environment name</dd>
 273:    * <dt>java.class.version</dt>   <dd>Java class version number</dd>
 274:    * <dt>java.class.path</dt>      <dd>Java classpath</dd>
 275:    * <dt>java.library.path</dt>    <dd>Path for finding Java libraries</dd>
 276:    * <dt>java.io.tmpdir</dt>       <dd>Default temp file path</dd>
 277:    * <dt>java.compiler</dt>        <dd>Name of JIT to use</dd>
 278:    * <dt>java.ext.dirs</dt>        <dd>Java extension path</dd>
 279:    * <dt>os.name</dt>              <dd>Operating System Name</dd>
 280:    * <dt>os.arch</dt>              <dd>Operating System Architecture</dd>
 281:    * <dt>os.version</dt>           <dd>Operating System Version</dd>
 282:    * <dt>file.separator</dt>       <dd>File separator ("/" on Unix)</dd>
 283:    * <dt>path.separator</dt>       <dd>Path separator (":" on Unix)</dd>
 284:    * <dt>line.separator</dt>       <dd>Line separator ("\n" on Unix)</dd>
 285:    * <dt>user.name</dt>            <dd>User account name</dd>
 286:    * <dt>user.home</dt>            <dd>User home directory</dd>
 287:    * <dt>user.dir</dt>             <dd>User's current working directory</dd>
 288:    * </dl>
 289:    *
 290:    * In addition, gnu defines several other properties, where ? stands for
 291:    * each character in '0' through '9':
 292:    * <dl>
 293:    * <dt>gnu.classpath.home</dt>         <dd>Path to the classpath libraries.</dd>
 294:    * <dt>gnu.classpath.version</dt>      <dd>Version of the classpath libraries.</dd>
 295:    * <dt>gnu.classpath.vm.shortname</dt> <dd>Succinct version of the VM name;
 296:    *     used for finding property files in file system</dd>
 297:    * <dt>gnu.classpath.home.url</dt>     <dd> Base URL; used for finding
 298:    *     property files in file system</dd>
 299:    * <dt>gnu.cpu.endian</dt>             <dd>big or little</dd>
 300:    * <dt>gnu.java.io.encoding_scheme_alias.ISO-8859-?</dt>   <dd>8859_?</dd>
 301:    * <dt>gnu.java.io.encoding_scheme_alias.iso-8859-?</dt>   <dd>8859_?</dd>
 302:    * <dt>gnu.java.io.encoding_scheme_alias.iso8859_?</dt>    <dd>8859_?</dd>
 303:    * <dt>gnu.java.io.encoding_scheme_alias.iso-latin-_?</dt> <dd>8859_?</dd>
 304:    * <dt>gnu.java.io.encoding_scheme_alias.latin?</dt>       <dd>8859_?</dd>
 305:    * <dt>gnu.java.io.encoding_scheme_alias.UTF-8</dt>        <dd>UTF8</dd>
 306:    * <dt>gnu.java.io.encoding_scheme_alias.utf-8</dt>        <dd>UTF8</dd>
 307:    * <dt>gnu.java.util.zoneinfo.dir</dt>    <dd>Root of zoneinfo tree</dd>
 308:    * </dl>
 309:    *
 310:    * @return the system properties, will never be null
 311:    * @throws SecurityException if permission is denied
 312:    */
 313:   public static Properties getProperties()
 314:   {
 315:     SecurityManager sm = SecurityManager.current; // Be thread-safe.
 316:     if (sm != null)
 317:       sm.checkPropertiesAccess();
 318:     return SystemProperties.getProperties();
 319:   }
 320: 
 321:   /**
 322:    * Set all the system properties at once. A security check may be performed,
 323:    * <code>checkPropertiesAccess</code>. Note that a security manager may
 324:    * allow setting a single property, but not the entire group. An argument
 325:    * of null resets the properties to the startup default.
 326:    *
 327:    * @param properties the new set of system properties
 328:    * @throws SecurityException if permission is denied
 329:    */
 330:   public static void setProperties(Properties properties)
 331:   {
 332:     SecurityManager sm = SecurityManager.current; // Be thread-safe.
 333:     if (sm != null)
 334:       sm.checkPropertiesAccess();
 335:     SystemProperties.setProperties(properties);
 336:   }
 337: 
 338:   /**
 339:    * Get a single system property by name. A security check may be performed,
 340:    * <code>checkPropertyAccess(key)</code>.
 341:    *
 342:    * @param key the name of the system property to get
 343:    * @return the property, or null if not found
 344:    * @throws SecurityException if permission is denied
 345:    * @throws NullPointerException if key is null
 346:    * @throws IllegalArgumentException if key is ""
 347:    */
 348:   public static String getProperty(String key)
 349:   {
 350:     SecurityManager sm = SecurityManager.current; // Be thread-safe.
 351:     if (sm != null)
 352:       sm.checkPropertyAccess(key);
 353:     else if (key.length() == 0)
 354:       throw new IllegalArgumentException("key can't be empty");
 355:     return SystemProperties.getProperty(key);
 356:   }
 357: 
 358:   /**
 359:    * Get a single system property by name. A security check may be performed,
 360:    * <code>checkPropertyAccess(key)</code>.
 361:    *
 362:    * @param key the name of the system property to get
 363:    * @param def the default
 364:    * @return the property, or def if not found
 365:    * @throws SecurityException if permission is denied
 366:    * @throws NullPointerException if key is null
 367:    * @throws IllegalArgumentException if key is ""
 368:    */
 369:   public static String getProperty(String key, String def)
 370:   {
 371:     SecurityManager sm = SecurityManager.current; // Be thread-safe.
 372:     if (sm != null)
 373:       sm.checkPropertyAccess(key);
 374:     return SystemProperties.getProperty(key, def);
 375:   }
 376: 
 377:   /**
 378:    * Set a single system property by name. A security check may be performed,
 379:    * <code>checkPropertyAccess(key, "write")</code>.
 380:    *
 381:    * @param key the name of the system property to set
 382:    * @param value the new value
 383:    * @return the previous value, or null
 384:    * @throws SecurityException if permission is denied
 385:    * @throws NullPointerException if key is null
 386:    * @throws IllegalArgumentException if key is ""
 387:    * @since 1.2
 388:    */
 389:   public static String setProperty(String key, String value)
 390:   {
 391:     SecurityManager sm = SecurityManager.current; // Be thread-safe.
 392:     if (sm != null)
 393:       sm.checkPermission(new PropertyPermission(key, "write"));
 394:     return SystemProperties.setProperty(key, value);
 395:   }
 396: 
 397:   /**
 398:    * Gets the value of an environment variable.
 399:    *
 400:    * @param name the name of the environment variable
 401:    * @return the string value of the variable or null when the
 402:    *         environment variable is not defined.
 403:    * @throws NullPointerException
 404:    * @throws SecurityException if permission is denied
 405:    * @since 1.5
 406:    * @specnote This method was deprecated in some JDK releases, but
 407:    *           was restored in 1.5.
 408:    */
 409:   public static String getenv(String name)
 410:   {
 411:     if (name == null)
 412:       throw new NullPointerException();
 413:     SecurityManager sm = SecurityManager.current; // Be thread-safe.
 414:     if (sm != null)
 415:       sm.checkPermission(new RuntimePermission("getenv." + name));
 416:     return getenv0(name);
 417:   }
 418: 
 419:   /**
 420:    * Terminate the Virtual Machine. This just calls
 421:    * <code>Runtime.getRuntime().exit(status)</code>, and never returns.
 422:    * Obviously, a security check is in order, <code>checkExit</code>.
 423:    *
 424:    * @param status the exit status; by convention non-zero is abnormal
 425:    * @throws SecurityException if permission is denied
 426:    * @see Runtime#exit(int)
 427:    */
 428:   public static void exit(int status)
 429:   {
 430:     Runtime.getRuntime().exit(status);
 431:   }
 432: 
 433:   /**
 434:    * Calls the garbage collector. This is only a hint, and it is up to the
 435:    * implementation what this hint suggests, but it usually causes a
 436:    * best-effort attempt to reclaim unused memory from discarded objects.
 437:    * This calls <code>Runtime.getRuntime().gc()</code>.
 438:    *
 439:    * @see Runtime#gc()
 440:    */
 441:   public static void gc()
 442:   {
 443:     Runtime.getRuntime().gc();
 444:   }
 445: 
 446:   /**
 447:    * Runs object finalization on pending objects. This is only a hint, and
 448:    * it is up to the implementation what this hint suggests, but it usually
 449:    * causes a best-effort attempt to run finalizers on all objects ready
 450:    * to be reclaimed. This calls
 451:    * <code>Runtime.getRuntime().runFinalization()</code>.
 452:    *
 453:    * @see Runtime#runFinalization()
 454:    */
 455:   public static void runFinalization()
 456:   {
 457:     Runtime.getRuntime().runFinalization();
 458:   }
 459: 
 460:   /**
 461:    * Tell the Runtime whether to run finalization before exiting the
 462:    * JVM.  This is inherently unsafe in multi-threaded applications,
 463:    * since it can force initialization on objects which are still in use
 464:    * by live threads, leading to deadlock; therefore this is disabled by
 465:    * default. There may be a security check, <code>checkExit(0)</code>. This
 466:    * calls <code>Runtime.getRuntime().runFinalizersOnExit()</code>.
 467:    *
 468:    * @param finalizeOnExit whether to run finalizers on exit
 469:    * @throws SecurityException if permission is denied
 470:    * @see Runtime#runFinalizersOnExit()
 471:    * @since 1.1
 472:    * @deprecated never rely on finalizers to do a clean, thread-safe,
 473:    *             mop-up from your code
 474:    */
 475:   public static void runFinalizersOnExit(boolean finalizeOnExit)
 476:   {
 477:     Runtime.getRuntime().runFinalizersOnExit(finalizeOnExit);
 478:   }
 479: 
 480:   /**
 481:    * Load a code file using its explicit system-dependent filename. A security
 482:    * check may be performed, <code>checkLink</code>. This just calls
 483:    * <code>Runtime.getRuntime().load(filename)</code>.
 484:    *
 485:    * <p>
 486:    * The library is loaded using the class loader associated with the
 487:    * class associated with the invoking method.
 488:    *
 489:    * @param filename the code file to load
 490:    * @throws SecurityException if permission is denied
 491:    * @throws UnsatisfiedLinkError if the file cannot be loaded
 492:    * @see Runtime#load(String)
 493:    */
 494:   public static void load(String filename)
 495:   {
 496:     Runtime.getRuntime().load(filename);
 497:   }
 498: 
 499:   /**
 500:    * Load a library using its explicit system-dependent filename. A security
 501:    * check may be performed, <code>checkLink</code>. This just calls
 502:    * <code>Runtime.getRuntime().load(filename)</code>.
 503:    *
 504:    * <p>
 505:    * The library is loaded using the class loader associated with the
 506:    * class associated with the invoking method.
 507:    *
 508:    * @param libname the library file to load
 509:    * @throws SecurityException if permission is denied
 510:    * @throws UnsatisfiedLinkError if the file cannot be loaded
 511:    * @see Runtime#load(String)
 512:    */
 513:   public static void loadLibrary(String libname)
 514:   {
 515:     Runtime.getRuntime().loadLibrary(libname);
 516:   }
 517: 
 518:   /**
 519:    * Convert a library name to its platform-specific variant.
 520:    *
 521:    * @param libname the library name, as used in <code>loadLibrary</code>
 522:    * @return the platform-specific mangling of the name
 523:    * @since 1.2
 524:    */
 525:   public static String mapLibraryName(String libname)
 526:   {
 527:     // XXX Fix this!!!!
 528:     return Runtime.nativeGetLibname("", libname);
 529:   }
 530: 
 531:   /**
 532:    * Set {@link #in} to a new InputStream.
 533:    *
 534:    * @param in the new InputStream
 535:    * @see #setIn(InputStream)
 536:    */
 537:   private static native void setIn0(InputStream in);
 538: 
 539:   /**
 540:    * Set {@link #out} to a new PrintStream.
 541:    *
 542:    * @param out the new PrintStream
 543:    * @see #setOut(PrintStream)
 544:    */
 545:   private static native void setOut0(PrintStream out);
 546: 
 547:   /**
 548:    * Set {@link #err} to a new PrintStream.
 549:    *
 550:    * @param err the new PrintStream
 551:    * @see #setErr(PrintStream)
 552:    */
 553:   private static native void setErr0(PrintStream err);
 554: 
 555:   /**
 556:    * Gets the value of an environment variable.
 557:    *
 558:    * @see #getenv(String)
 559:    */
 560:   static native String getenv0(String name);
 561: } // class System