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