Source for java.lang.Object

   1: /* java.lang.Object - The universal superclass in Java
   2:    Copyright (C) 1998, 1999, 2000, 2001, 2002, 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: 
  43: /**
  44:  * Object is the ultimate superclass of every class
  45:  * (excepting interfaces).  When you define a class that
  46:  * does not extend any other class, it implicitly extends
  47:  * java.lang.Object.  Also, an anonymous class based on
  48:  * an interface will extend Object.
  49:  *
  50:  * <p>It provides general-purpose methods that every single
  51:  * Object, regardless of race, sex or creed, implements.
  52:  * All of the public methods may be invoked on arrays or
  53:  * interfaces.  The protected methods <code>clone</code>
  54:  * and <code>finalize</code> are not accessible on arrays
  55:  * or interfaces, but all array types have a public version
  56:  * of <code>clone</code> which is accessible.
  57:  *
  58:  * @author John Keiser
  59:  * @author Eric Blake (ebb9@email.byu.edu)
  60:  * @author Tom Tromey (tromey@cygnus.com)
  61:  */
  62: public class Object
  63: {
  64:   // WARNING: Object is a CORE class in the bootstrap cycle. See the comments
  65:   // in vm/reference/java/lang/Runtime for implications of this fact.
  66: 
  67:   // Many JVMs do not allow for static initializers in this class,
  68:   // hence we do not use them in the default implementation.
  69: 
  70:   // Some VM's rely on the order that these methods appear when laying
  71:   // out their internal structure.  Therefore, do not haphazardly
  72:   // rearrange these methods.
  73: 
  74:   /**
  75:    * The basic constructor.  Object is special, because it has no
  76:    * superclass, so there is no call to super().
  77:    *
  78:    * @throws OutOfMemoryError Technically, this constructor never
  79:    *         throws an OutOfMemoryError, because the memory has
  80:    *         already been allocated by this point.  But as all
  81:    *         instance creation expressions eventually trace back
  82:    *         to this constructor, and creating an object allocates
  83:    *         memory, we list that possibility here.
  84:    */
  85:   // This could be implicit, but then javadoc would not document it!
  86:   public Object() {}
  87: 
  88:   /**
  89:    * Determine whether this Object is semantically equal
  90:    * to another Object.
  91:    *
  92:    * <p>There are some fairly strict requirements on this
  93:    * method which subclasses must follow:<br>
  94:    * <ul>
  95:    * <li>It must be transitive.  If <code>a.equals(b)</code> and
  96:    *     <code>b.equals(c)</code>, then <code>a.equals(c)</code>
  97:    *     must be true as well.</li>
  98:    * <li>It must be symmetric.  <code>a.equals(b)</code> and
  99:    *     <code>b.equals(a)</code> must have the same value.</li>
 100:    * <li>It must be reflexive.  <code>a.equals(a)</code> must
 101:    *     always be true.</li>
 102:    * <li>It must be consistent.  Whichever value a.equals(b)
 103:    *     returns on the first invocation must be the value
 104:    *     returned on all later invocations.</li>
 105:    * <li><code>a.equals(null)</code> must be false.</li>
 106:    * <li>It must be consistent with hashCode().  That is,
 107:    *     <code>a.equals(b)</code> must imply
 108:    *     <code>a.hashCode() == b.hashCode()</code>.
 109:    *     The reverse is not true; two objects that are not
 110:    *     equal may have the same hashcode, but that has
 111:    *     the potential to harm hashing performance.</li>
 112:    * </ul>
 113:    *
 114:    * <p>This is typically overridden to throw a {@link ClassCastException}
 115:    * if the argument is not comparable to the class performing
 116:    * the comparison, but that is not a requirement.  It is legal
 117:    * for <code>a.equals(b)</code> to be true even though
 118:    * <code>a.getClass() != b.getClass()</code>.  Also, it
 119:    * is typical to never cause a {@link NullPointerException}.
 120:    *
 121:    * <p>In general, the Collections API ({@link java.util}) use the
 122:    * <code>equals</code> method rather than the <code>==</code>
 123:    * operator to compare objects.  However, {@link java.util.IdentityHashMap}
 124:    * is an exception to this rule, for its own good reasons.
 125:    *
 126:    * <p>The default implementation returns <code>this == o</code>.
 127:    *
 128:    * @param obj the Object to compare to
 129:    * @return whether this Object is semantically equal to another
 130:    * @see #hashCode()
 131:    */
 132:   public boolean equals(Object obj)
 133:   {
 134:     return this == obj;
 135:   }
 136: 
 137:   /**
 138:    * Get a value that represents this Object, as uniquely as
 139:    * possible within the confines of an int.
 140:    *
 141:    * <p>There are some requirements on this method which
 142:    * subclasses must follow:<br>
 143:    *
 144:    * <ul>
 145:    * <li>Semantic equality implies identical hashcodes.  In other
 146:    *     words, if <code>a.equals(b)</code> is true, then
 147:    *     <code>a.hashCode() == b.hashCode()</code> must be as well.
 148:    *     However, the reverse is not necessarily true, and two
 149:    *     objects may have the same hashcode without being equal.</li>
 150:    * <li>It must be consistent.  Whichever value o.hashCode()
 151:    *     returns on the first invocation must be the value
 152:    *     returned on all later invocations as long as the object
 153:    *     exists.  Notice, however, that the result of hashCode may
 154:    *     change between separate executions of a Virtual Machine,
 155:    *     because it is not invoked on the same object.</li>
 156:    * </ul>
 157:    *
 158:    * <p>Notice that since <code>hashCode</code> is used in
 159:    * {@link java.util.Hashtable} and other hashing classes,
 160:    * a poor implementation will degrade the performance of hashing
 161:    * (so don't blindly implement it as returning a constant!). Also,
 162:    * if calculating the hash is time-consuming, a class may consider
 163:    * caching the results.
 164:    *
 165:    * <p>The default implementation returns
 166:    * <code>System.identityHashCode(this)</code>
 167:    *
 168:    * @return the hash code for this Object
 169:    * @see #equals(Object)
 170:    * @see System#identityHashCode(Object)
 171:    */
 172:   public int hashCode()
 173:   {
 174:     return System.identityHashCode(this);
 175:   }
 176: 
 177:   /**
 178:    * Convert this Object to a human-readable String.
 179:    * There are no limits placed on how long this String
 180:    * should be or what it should contain.  We suggest you
 181:    * make it as intuitive as possible to be able to place
 182:    * it into {@link java.io.PrintStream#println() System.out.println()}
 183:    * and such.
 184:    *
 185:    * <p>It is typical, but not required, to ensure that this method
 186:    * never completes abruptly with a {@link RuntimeException}.
 187:    *
 188:    * <p>This method will be called when performing string
 189:    * concatenation with this object.  If the result is
 190:    * <code>null</code>, string concatenation will instead
 191:    * use <code>"null"</code>.
 192:    *
 193:    * <p>The default implementation returns
 194:    * <code>getClass().getName() + "@" +
 195:    *      Integer.toHexString(hashCode())</code>.
 196:    *
 197:    * @return the String representing this Object, which may be null
 198:    * @throws OutOfMemoryError The default implementation creates a new
 199:    *         String object, therefore it must allocate memory
 200:    * @see #getClass()
 201:    * @see #hashCode()
 202:    * @see Class#getName()
 203:    * @see Integer#toHexString(int)
 204:    */
 205:   public String toString()
 206:   {
 207:     return getClass().getName() + '@' + Integer.toHexString(hashCode());
 208:   }
 209: 
 210:   /**
 211:    * Called on an object by the Virtual Machine at most once,
 212:    * at some point after the Object is determined unreachable
 213:    * but before it is destroyed. You would think that this
 214:    * means it eventually is called on every Object, but this is
 215:    * not necessarily the case.  If execution terminates
 216:    * abnormally, garbage collection does not always happen.
 217:    * Thus you cannot rely on this method to always work.
 218:    * For finer control over garbage collection, use references
 219:    * from the {@link java.lang.ref} package.
 220:    *
 221:    * <p>Virtual Machines are free to not call this method if
 222:    * they can determine that it does nothing important; for
 223:    * example, if your class extends Object and overrides
 224:    * finalize to do simply <code>super.finalize()</code>.
 225:    *
 226:    * <p>finalize() will be called by a {@link Thread} that has no
 227:    * locks on any Objects, and may be called concurrently.
 228:    * There are no guarantees on the order in which multiple
 229:    * objects are finalized.  This means that finalize() is
 230:    * usually unsuited for performing actions that must be
 231:    * thread-safe, and that your implementation must be
 232:    * use defensive programming if it is to always work.
 233:    *
 234:    * <p>If an Exception is thrown from finalize() during garbage
 235:    * collection, it will be patently ignored and the Object will
 236:    * still be destroyed.
 237:    *
 238:    * <p>It is allowed, although not typical, for user code to call
 239:    * finalize() directly.  User invocation does not affect whether
 240:    * automatic invocation will occur.  It is also permitted,
 241:    * although not recommended, for a finalize() method to "revive"
 242:    * an object by making it reachable from normal code again.
 243:    *
 244:    * <p>Unlike constructors, finalize() does not get called
 245:    * for an object's superclass unless the implementation
 246:    * specifically calls <code>super.finalize()</code>.
 247:    *
 248:    * <p>The default implementation does nothing.
 249:    *
 250:    * @throws Throwable permits a subclass to throw anything in an
 251:    *         overridden version; but the default throws nothing
 252:    * @see System#gc()
 253:    * @see System#runFinalizersOnExit(boolean)
 254:    * @see java.lang.ref
 255:    */
 256:   protected void finalize() throws Throwable
 257:   {
 258:   }
 259: 
 260:   /**
 261:    * This method may be called to create a new copy of the
 262:    * Object.  The typical behavior is as follows:<br>
 263:    * <ul>
 264:    *  <li><code>o == o.clone()</code> is false</li>
 265:    *  <li><code>o.getClass() == o.clone().getClass()</code>
 266:    *      is true</li>
 267:    *  <li><code>o.equals(o)</code> is true</li>
 268:    * </ul>
 269:    *
 270:    * <p>However, these are not strict requirements, and may
 271:    * be violated if necessary.  Of the three requirements, the
 272:    * last is the most commonly violated, particularly if the
 273:    * subclass does not override {@link #equals(Object)}.
 274:    *
 275:    * <p>If the Object you call clone() on does not implement
 276:    * {@link Cloneable} (which is a placeholder interface), then
 277:    * a CloneNotSupportedException is thrown.  Notice that
 278:    * Object does not implement Cloneable; this method exists
 279:    * as a convenience for subclasses that do.
 280:    *
 281:    * <p>Object's implementation of clone allocates space for the
 282:    * new Object using the correct class, without calling any
 283:    * constructors, and then fills in all of the new field values
 284:    * with the old field values.  Thus, it is a shallow copy.
 285:    * However, subclasses are permitted to make a deep copy.
 286:    *
 287:    * <p>All array types implement Cloneable, and override
 288:    * this method as follows (it should never fail):<br>
 289:    * <pre>
 290:    * public Object clone()
 291:    * {
 292:    *   try
 293:    *     {
 294:    *       super.clone();
 295:    *     }
 296:    *   catch (CloneNotSupportedException e)
 297:    *     {
 298:    *       throw new InternalError(e.getMessage());
 299:    *     }
 300:    * }
 301:    * </pre>
 302:    *
 303:    * @return a copy of the Object
 304:    * @throws CloneNotSupportedException If this Object does not
 305:    *         implement Cloneable
 306:    * @throws OutOfMemoryError Since cloning involves memory allocation,
 307:    *         even though it may bypass constructors, you might run
 308:    *         out of memory
 309:    * @see Cloneable
 310:    */
 311:   protected Object clone() throws CloneNotSupportedException
 312:   {
 313:     if (this instanceof Cloneable)
 314:       return VMObject.clone((Cloneable) this);
 315:     throw new CloneNotSupportedException("Object not cloneable");
 316:   }
 317: 
 318:   /**
 319:    * Returns the runtime {@link Class} of this Object.
 320:    *
 321:    * <p>The class object can also be obtained without a runtime
 322:    * instance by using the class literal, as in:
 323:    * <code>Foo.class</code>.  Notice that the class literal
 324:    * also works on primitive types, making it useful for
 325:    * reflection purposes.
 326:    *
 327:    * @return the class of this Object
 328:    */
 329:   public final Class<? extends Object> getClass()
 330:   {
 331:     return VMObject.getClass(this);
 332:   }
 333: 
 334:   /**
 335:    * Wakes up one of the {@link Thread}s that has called
 336:    * <code>wait</code> on this Object.  Only the owner
 337:    * of a lock on this Object may call this method.  This lock
 338:    * is obtained by a <code>synchronized</code> method or statement.
 339:    *
 340:    * <p>The Thread to wake up is chosen arbitrarily.  The
 341:    * awakened thread is not guaranteed to be the next thread
 342:    * to actually obtain the lock on this object.
 343:    *
 344:    * <p>This thread still holds a lock on the object, so it is
 345:    * typical to release the lock by exiting the synchronized
 346:    * code, calling wait(), or calling {@link Thread#sleep(long)}, so
 347:    * that the newly awakened thread can actually resume.  The
 348:    * awakened thread will most likely be awakened with an
 349:    * {@link InterruptedException}, but that is not guaranteed.
 350:    *
 351:    * @throws IllegalMonitorStateException if this Thread
 352:    *         does not own the lock on the Object
 353:    * @see #notifyAll()
 354:    * @see #wait()
 355:    * @see #wait(long)
 356:    * @see #wait(long, int)
 357:    * @see Thread
 358:    */
 359:   public final void notify() throws IllegalMonitorStateException
 360:   {
 361:     VMObject.notify(this);
 362:   }
 363: 
 364:   /**
 365:    * Wakes up all of the {@link Thread}s that have called
 366:    * <code>wait</code> on this Object.  Only the owner
 367:    * of a lock on this Object may call this method.  This lock
 368:    * is obtained by a <code>synchronized</code> method or statement.
 369:    *
 370:    * <p>There are no guarantees as to which thread will next
 371:    * obtain the lock on the object.
 372:    *
 373:    * <p>This thread still holds a lock on the object, so it is
 374:    * typical to release the lock by exiting the synchronized
 375:    * code, calling wait(), or calling {@link Thread#sleep(long)}, so
 376:    * that one of the newly awakened threads can actually resume.
 377:    * The resuming thread will most likely be awakened with an
 378:    * {@link InterruptedException}, but that is not guaranteed.
 379:    *
 380:    * @throws IllegalMonitorStateException if this Thread
 381:    *         does not own the lock on the Object
 382:    * @see #notify()
 383:    * @see #wait()
 384:    * @see #wait(long)
 385:    * @see #wait(long, int)
 386:    * @see Thread
 387:    */
 388:   public final void notifyAll() throws IllegalMonitorStateException
 389:   {
 390:     VMObject.notifyAll(this);
 391:   }
 392: 
 393:   /**
 394:    * Waits indefinitely for notify() or notifyAll() to be
 395:    * called on the Object in question.  Implementation is
 396:    * identical to wait(0).
 397:    *
 398:    * <p>The Thread that calls wait must have a lock on this Object,
 399:    * obtained by a <code>synchronized</code> method or statement.
 400:    * After calling wait, the thread loses the lock on this
 401:    * object until the method completes (abruptly or normally),
 402:    * at which time it regains the lock.  All locks held on
 403:    * other objects remain in force, even though the thread is
 404:    * inactive. Therefore, caution must be used to avoid deadlock.
 405:    *
 406:    * <p>While it is typical that this method will complete abruptly
 407:    * with an {@link InterruptedException}, it is not guaranteed.  So,
 408:    * it is typical to call wait inside an infinite loop:<br>
 409:    *
 410:    * <pre>
 411:    * try
 412:    *   {
 413:    *     while (true)
 414:    *       lock.wait();
 415:    *   }
 416:    * catch (InterruptedException e)
 417:    *   {
 418:    *   }
 419:    * </pre>
 420:    *
 421:    * @throws IllegalMonitorStateException if this Thread
 422:    *         does not own a lock on this Object
 423:    * @throws InterruptedException if some other Thread
 424:    *         interrupts this Thread
 425:    * @see #notify()
 426:    * @see #notifyAll()
 427:    * @see #wait(long)
 428:    * @see #wait(long, int)
 429:    * @see Thread
 430:    */
 431:   public final void wait()
 432:     throws IllegalMonitorStateException, InterruptedException
 433:   {
 434:     VMObject.wait(this, 0, 0);
 435:   }
 436: 
 437:   /**
 438:    * Waits a specified amount of time (or indefinitely if
 439:    * the time specified is 0) for someone to call notify()
 440:    * or notifyAll() on this Object, waking up this Thread.
 441:    *
 442:    * <p>The Thread that calls wait must have a lock on this Object,
 443:    * obtained by a <code>synchronized</code> method or statement.
 444:    * After calling wait, the thread loses the lock on this
 445:    * object until the method completes (abruptly or normally),
 446:    * at which time it regains the lock.  All locks held on
 447:    * other objects remain in force, even though the thread is
 448:    * inactive. Therefore, caution must be used to avoid deadlock.
 449:    *
 450:    * <p>Usually, this call will complete normally if the time
 451:    * expires, or abruptly with {@link InterruptedException}
 452:    * if another thread called notify, but neither result
 453:    * is guaranteed.
 454:    *
 455:    * <p>The waiting period is only *roughly* the amount of time
 456:    * you requested.  It cannot be exact because of the overhead
 457:    * of the call itself.  Most Virtual Machiness treat the
 458:    * argument as a lower limit on the time spent waiting, but
 459:    * even that is not guaranteed.  Besides, some other thread
 460:    * may hold the lock on the object when the time expires, so
 461:    * the current thread may still have to wait to reobtain the
 462:    * lock.
 463:    *
 464:    * @param ms the minimum number of milliseconds to wait (1000
 465:    *        milliseconds = 1 second), or 0 for an indefinite wait
 466:    * @throws IllegalArgumentException if ms &lt; 0
 467:    * @throws IllegalMonitorStateException if this Thread
 468:    *         does not own a lock on this Object
 469:    * @throws InterruptedException if some other Thread
 470:    *         interrupts this Thread
 471:    * @see #notify()
 472:    * @see #notifyAll()
 473:    * @see #wait()
 474:    * @see #wait(long, int)
 475:    * @see Thread
 476:    */
 477:   public final void wait(long ms)
 478:     throws IllegalMonitorStateException, InterruptedException
 479:   {
 480:     wait(ms, 0);
 481:   }
 482: 
 483:   /**
 484:    * Waits a specified amount of time (or indefinitely if
 485:    * the time specified is 0) for someone to call notify()
 486:    * or notifyAll() on this Object, waking up this Thread.
 487:    *
 488:    * <p>The Thread that calls wait must have a lock on this Object,
 489:    * obtained by a <code>synchronized</code> method or statement.
 490:    * After calling wait, the thread loses the lock on this
 491:    * object until the method completes (abruptly or normally),
 492:    * at which time it regains the lock.  All locks held on
 493:    * other objects remain in force, even though the thread is
 494:    * inactive. Therefore, caution must be used to avoid deadlock.
 495:    *
 496:    * <p>Usually, this call will complete normally if the time
 497:    * expires, or abruptly with {@link InterruptedException}
 498:    * if another thread called notify, but neither result
 499:    * is guaranteed.
 500:    *
 501:    * <p>The waiting period is nowhere near as precise as
 502:    * nanoseconds; considering that even wait(int) is inaccurate,
 503:    * how much can you expect?  But on supporting
 504:    * implementations, this offers somewhat more granularity
 505:    * than milliseconds.
 506:    *
 507:    * @param ms the number of milliseconds to wait (1,000
 508:    *        milliseconds = 1 second)
 509:    * @param ns the number of nanoseconds to wait over and
 510:    *        above ms (1,000,000 nanoseconds = 1 millisecond)
 511:    * @throws IllegalArgumentException if ms &lt; 0 or ns is not
 512:    *         in the range 0 to 999,999
 513:    * @throws IllegalMonitorStateException if this Thread
 514:    *         does not own a lock on this Object
 515:    * @throws InterruptedException if some other Thread
 516:    *         interrupts this Thread
 517:    * @see #notify()
 518:    * @see #notifyAll()
 519:    * @see #wait()
 520:    * @see #wait(long)
 521:    * @see Thread
 522:    */
 523:   public final void wait(long ms, int ns)
 524:     throws IllegalMonitorStateException, InterruptedException
 525:   {
 526:     if (ms < 0 || ns < 0 || ns > 999999)
 527:       throw new IllegalArgumentException("argument out of range");
 528:     VMObject.wait(this, ms, ns);
 529:   }
 530: } // class Object