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 < 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 < 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