001: /*
002: * Copyright 1994-2006 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025:
026: package java.lang;
027:
028: /**
029: * Class <code>Object</code> is the root of the class hierarchy.
030: * Every class has <code>Object</code> as a superclass. All objects,
031: * including arrays, implement the methods of this class.
032: *
033: * @author unascribed
034: * @version 1.79, 05/05/07
035: * @see java.lang.Class
036: * @since JDK1.0
037: */
038: public class Object {
039:
040: private static native void registerNatives();
041:
042: static {
043: registerNatives();
044: }
045:
046: /**
047: * Returns the runtime class of this {@code Object}. The returned
048: * {@code Class} object is the object that is locked by {@code
049: * static synchronized} methods of the represented class.
050: *
051: * <p><b>The actual result type is {@code Class<? extends |X|>}
052: * where {@code |X|} is the erasure of the static type of the
053: * expression on which {@code getClass} is called.</b> For
054: * example, no cast is required in this code fragment:</p>
055: *
056: * <p>
057: * {@code Number n = 0; }<br>
058: * {@code Class<? extends Number> c = n.getClass(); }
059: * </p>
060: *
061: * @return The {@code Class} object that represents the runtime
062: * class of this object.
063: * @see <a href="http://java.sun.com/docs/books/jls/">The Java
064: * Language Specification, Third Edition (15.8.2 Class
065: * Literals)</a>
066: */
067: public final native Class<?> getClass();
068:
069: /**
070: * Returns a hash code value for the object. This method is
071: * supported for the benefit of hashtables such as those provided by
072: * <code>java.util.Hashtable</code>.
073: * <p>
074: * The general contract of <code>hashCode</code> is:
075: * <ul>
076: * <li>Whenever it is invoked on the same object more than once during
077: * an execution of a Java application, the <tt>hashCode</tt> method
078: * must consistently return the same integer, provided no information
079: * used in <tt>equals</tt> comparisons on the object is modified.
080: * This integer need not remain consistent from one execution of an
081: * application to another execution of the same application.
082: * <li>If two objects are equal according to the <tt>equals(Object)</tt>
083: * method, then calling the <code>hashCode</code> method on each of
084: * the two objects must produce the same integer result.
085: * <li>It is <em>not</em> required that if two objects are unequal
086: * according to the {@link java.lang.Object#equals(java.lang.Object)}
087: * method, then calling the <tt>hashCode</tt> method on each of the
088: * two objects must produce distinct integer results. However, the
089: * programmer should be aware that producing distinct integer results
090: * for unequal objects may improve the performance of hashtables.
091: * </ul>
092: * <p>
093: * As much as is reasonably practical, the hashCode method defined by
094: * class <tt>Object</tt> does return distinct integers for distinct
095: * objects. (This is typically implemented by converting the internal
096: * address of the object into an integer, but this implementation
097: * technique is not required by the
098: * Java<font size="-2"><sup>TM</sup></font> programming language.)
099: *
100: * @return a hash code value for this object.
101: * @see java.lang.Object#equals(java.lang.Object)
102: * @see java.util.Hashtable
103: */
104: public native int hashCode();
105:
106: /**
107: * Indicates whether some other object is "equal to" this one.
108: * <p>
109: * The <code>equals</code> method implements an equivalence relation
110: * on non-null object references:
111: * <ul>
112: * <li>It is <i>reflexive</i>: for any non-null reference value
113: * <code>x</code>, <code>x.equals(x)</code> should return
114: * <code>true</code>.
115: * <li>It is <i>symmetric</i>: for any non-null reference values
116: * <code>x</code> and <code>y</code>, <code>x.equals(y)</code>
117: * should return <code>true</code> if and only if
118: * <code>y.equals(x)</code> returns <code>true</code>.
119: * <li>It is <i>transitive</i>: for any non-null reference values
120: * <code>x</code>, <code>y</code>, and <code>z</code>, if
121: * <code>x.equals(y)</code> returns <code>true</code> and
122: * <code>y.equals(z)</code> returns <code>true</code>, then
123: * <code>x.equals(z)</code> should return <code>true</code>.
124: * <li>It is <i>consistent</i>: for any non-null reference values
125: * <code>x</code> and <code>y</code>, multiple invocations of
126: * <tt>x.equals(y)</tt> consistently return <code>true</code>
127: * or consistently return <code>false</code>, provided no
128: * information used in <code>equals</code> comparisons on the
129: * objects is modified.
130: * <li>For any non-null reference value <code>x</code>,
131: * <code>x.equals(null)</code> should return <code>false</code>.
132: * </ul>
133: * <p>
134: * The <tt>equals</tt> method for class <code>Object</code> implements
135: * the most discriminating possible equivalence relation on objects;
136: * that is, for any non-null reference values <code>x</code> and
137: * <code>y</code>, this method returns <code>true</code> if and only
138: * if <code>x</code> and <code>y</code> refer to the same object
139: * (<code>x == y</code> has the value <code>true</code>).
140: * <p>
141: * Note that it is generally necessary to override the <tt>hashCode</tt>
142: * method whenever this method is overridden, so as to maintain the
143: * general contract for the <tt>hashCode</tt> method, which states
144: * that equal objects must have equal hash codes.
145: *
146: * @param obj the reference object with which to compare.
147: * @return <code>true</code> if this object is the same as the obj
148: * argument; <code>false</code> otherwise.
149: * @see #hashCode()
150: * @see java.util.Hashtable
151: */
152: public boolean equals(Object obj) {
153: return (this == obj);
154: }
155:
156: /**
157: * Creates and returns a copy of this object. The precise meaning
158: * of "copy" may depend on the class of the object. The general
159: * intent is that, for any object <tt>x</tt>, the expression:
160: * <blockquote>
161: * <pre>
162: * x.clone() != x</pre></blockquote>
163: * will be true, and that the expression:
164: * <blockquote>
165: * <pre>
166: * x.clone().getClass() == x.getClass()</pre></blockquote>
167: * will be <tt>true</tt>, but these are not absolute requirements.
168: * While it is typically the case that:
169: * <blockquote>
170: * <pre>
171: * x.clone().equals(x)</pre></blockquote>
172: * will be <tt>true</tt>, this is not an absolute requirement.
173: * <p>
174: * By convention, the returned object should be obtained by calling
175: * <tt>super.clone</tt>. If a class and all of its superclasses (except
176: * <tt>Object</tt>) obey this convention, it will be the case that
177: * <tt>x.clone().getClass() == x.getClass()</tt>.
178: * <p>
179: * By convention, the object returned by this method should be independent
180: * of this object (which is being cloned). To achieve this independence,
181: * it may be necessary to modify one or more fields of the object returned
182: * by <tt>super.clone</tt> before returning it. Typically, this means
183: * copying any mutable objects that comprise the internal "deep structure"
184: * of the object being cloned and replacing the references to these
185: * objects with references to the copies. If a class contains only
186: * primitive fields or references to immutable objects, then it is usually
187: * the case that no fields in the object returned by <tt>super.clone</tt>
188: * need to be modified.
189: * <p>
190: * The method <tt>clone</tt> for class <tt>Object</tt> performs a
191: * specific cloning operation. First, if the class of this object does
192: * not implement the interface <tt>Cloneable</tt>, then a
193: * <tt>CloneNotSupportedException</tt> is thrown. Note that all arrays
194: * are considered to implement the interface <tt>Cloneable</tt>.
195: * Otherwise, this method creates a new instance of the class of this
196: * object and initializes all its fields with exactly the contents of
197: * the corresponding fields of this object, as if by assignment; the
198: * contents of the fields are not themselves cloned. Thus, this method
199: * performs a "shallow copy" of this object, not a "deep copy" operation.
200: * <p>
201: * The class <tt>Object</tt> does not itself implement the interface
202: * <tt>Cloneable</tt>, so calling the <tt>clone</tt> method on an object
203: * whose class is <tt>Object</tt> will result in throwing an
204: * exception at run time.
205: *
206: * @return a clone of this instance.
207: * @exception CloneNotSupportedException if the object's class does not
208: * support the <code>Cloneable</code> interface. Subclasses
209: * that override the <code>clone</code> method can also
210: * throw this exception to indicate that an instance cannot
211: * be cloned.
212: * @see java.lang.Cloneable
213: */
214: protected native Object clone() throws CloneNotSupportedException;
215:
216: /**
217: * Returns a string representation of the object. In general, the
218: * <code>toString</code> method returns a string that
219: * "textually represents" this object. The result should
220: * be a concise but informative representation that is easy for a
221: * person to read.
222: * It is recommended that all subclasses override this method.
223: * <p>
224: * The <code>toString</code> method for class <code>Object</code>
225: * returns a string consisting of the name of the class of which the
226: * object is an instance, the at-sign character `<code>@</code>', and
227: * the unsigned hexadecimal representation of the hash code of the
228: * object. In other words, this method returns a string equal to the
229: * value of:
230: * <blockquote>
231: * <pre>
232: * getClass().getName() + '@' + Integer.toHexString(hashCode())
233: * </pre></blockquote>
234: *
235: * @return a string representation of the object.
236: */
237: public String toString() {
238: return getClass().getName() + "@"
239: + Integer.toHexString(hashCode());
240: }
241:
242: /**
243: * Wakes up a single thread that is waiting on this object's
244: * monitor. If any threads are waiting on this object, one of them
245: * is chosen to be awakened. The choice is arbitrary and occurs at
246: * the discretion of the implementation. A thread waits on an object's
247: * monitor by calling one of the <code>wait</code> methods.
248: * <p>
249: * The awakened thread will not be able to proceed until the current
250: * thread relinquishes the lock on this object. The awakened thread will
251: * compete in the usual manner with any other threads that might be
252: * actively competing to synchronize on this object; for example, the
253: * awakened thread enjoys no reliable privilege or disadvantage in being
254: * the next thread to lock this object.
255: * <p>
256: * This method should only be called by a thread that is the owner
257: * of this object's monitor. A thread becomes the owner of the
258: * object's monitor in one of three ways:
259: * <ul>
260: * <li>By executing a synchronized instance method of that object.
261: * <li>By executing the body of a <code>synchronized</code> statement
262: * that synchronizes on the object.
263: * <li>For objects of type <code>Class,</code> by executing a
264: * synchronized static method of that class.
265: * </ul>
266: * <p>
267: * Only one thread at a time can own an object's monitor.
268: *
269: * @exception IllegalMonitorStateException if the current thread is not
270: * the owner of this object's monitor.
271: * @see java.lang.Object#notifyAll()
272: * @see java.lang.Object#wait()
273: */
274: public final native void notify();
275:
276: /**
277: * Wakes up all threads that are waiting on this object's monitor. A
278: * thread waits on an object's monitor by calling one of the
279: * <code>wait</code> methods.
280: * <p>
281: * The awakened threads will not be able to proceed until the current
282: * thread relinquishes the lock on this object. The awakened threads
283: * will compete in the usual manner with any other threads that might
284: * be actively competing to synchronize on this object; for example,
285: * the awakened threads enjoy no reliable privilege or disadvantage in
286: * being the next thread to lock this object.
287: * <p>
288: * This method should only be called by a thread that is the owner
289: * of this object's monitor. See the <code>notify</code> method for a
290: * description of the ways in which a thread can become the owner of
291: * a monitor.
292: *
293: * @exception IllegalMonitorStateException if the current thread is not
294: * the owner of this object's monitor.
295: * @see java.lang.Object#notify()
296: * @see java.lang.Object#wait()
297: */
298: public final native void notifyAll();
299:
300: /**
301: * Causes the current thread to wait until either another thread invokes the
302: * {@link java.lang.Object#notify()} method or the
303: * {@link java.lang.Object#notifyAll()} method for this object, or a
304: * specified amount of time has elapsed.
305: * <p>
306: * The current thread must own this object's monitor.
307: * <p>
308: * This method causes the current thread (call it <var>T</var>) to
309: * place itself in the wait set for this object and then to relinquish
310: * any and all synchronization claims on this object. Thread <var>T</var>
311: * becomes disabled for thread scheduling purposes and lies dormant
312: * until one of four things happens:
313: * <ul>
314: * <li>Some other thread invokes the <tt>notify</tt> method for this
315: * object and thread <var>T</var> happens to be arbitrarily chosen as
316: * the thread to be awakened.
317: * <li>Some other thread invokes the <tt>notifyAll</tt> method for this
318: * object.
319: * <li>Some other thread {@linkplain Thread#interrupt() interrupts}
320: * thread <var>T</var>.
321: * <li>The specified amount of real time has elapsed, more or less. If
322: * <tt>timeout</tt> is zero, however, then real time is not taken into
323: * consideration and the thread simply waits until notified.
324: * </ul>
325: * The thread <var>T</var> is then removed from the wait set for this
326: * object and re-enabled for thread scheduling. It then competes in the
327: * usual manner with other threads for the right to synchronize on the
328: * object; once it has gained control of the object, all its
329: * synchronization claims on the object are restored to the status quo
330: * ante - that is, to the situation as of the time that the <tt>wait</tt>
331: * method was invoked. Thread <var>T</var> then returns from the
332: * invocation of the <tt>wait</tt> method. Thus, on return from the
333: * <tt>wait</tt> method, the synchronization state of the object and of
334: * thread <tt>T</tt> is exactly as it was when the <tt>wait</tt> method
335: * was invoked.
336: * <p>
337: * A thread can also wake up without being notified, interrupted, or
338: * timing out, a so-called <i>spurious wakeup</i>. While this will rarely
339: * occur in practice, applications must guard against it by testing for
340: * the condition that should have caused the thread to be awakened, and
341: * continuing to wait if the condition is not satisfied. In other words,
342: * waits should always occur in loops, like this one:
343: * <pre>
344: * synchronized (obj) {
345: * while (<condition does not hold>)
346: * obj.wait(timeout);
347: * ... // Perform action appropriate to condition
348: * }
349: * </pre>
350: * (For more information on this topic, see Section 3.2.3 in Doug Lea's
351: * "Concurrent Programming in Java (Second Edition)" (Addison-Wesley,
352: * 2000), or Item 50 in Joshua Bloch's "Effective Java Programming
353: * Language Guide" (Addison-Wesley, 2001).
354: *
355: * <p>If the current thread is {@linkplain java.lang.Thread#interrupt()
356: * interrupted} by any thread before or while it is waiting, then an
357: * <tt>InterruptedException</tt> is thrown. This exception is not
358: * thrown until the lock status of this object has been restored as
359: * described above.
360: *
361: * <p>
362: * Note that the <tt>wait</tt> method, as it places the current thread
363: * into the wait set for this object, unlocks only this object; any
364: * other objects on which the current thread may be synchronized remain
365: * locked while the thread waits.
366: * <p>
367: * This method should only be called by a thread that is the owner
368: * of this object's monitor. See the <code>notify</code> method for a
369: * description of the ways in which a thread can become the owner of
370: * a monitor.
371: *
372: * @param timeout the maximum time to wait in milliseconds.
373: * @exception IllegalArgumentException if the value of timeout is
374: * negative.
375: * @exception IllegalMonitorStateException if the current thread is not
376: * the owner of the object's monitor.
377: * @exception InterruptedException if any thread interrupted the
378: * current thread before or while the current thread
379: * was waiting for a notification. The <i>interrupted
380: * status</i> of the current thread is cleared when
381: * this exception is thrown.
382: * @see java.lang.Object#notify()
383: * @see java.lang.Object#notifyAll()
384: */
385: public final native void wait(long timeout)
386: throws InterruptedException;
387:
388: /**
389: * Causes the current thread to wait until another thread invokes the
390: * {@link java.lang.Object#notify()} method or the
391: * {@link java.lang.Object#notifyAll()} method for this object, or
392: * some other thread interrupts the current thread, or a certain
393: * amount of real time has elapsed.
394: * <p>
395: * This method is similar to the <code>wait</code> method of one
396: * argument, but it allows finer control over the amount of time to
397: * wait for a notification before giving up. The amount of real time,
398: * measured in nanoseconds, is given by:
399: * <blockquote>
400: * <pre>
401: * 1000000*timeout+nanos</pre></blockquote>
402: * <p>
403: * In all other respects, this method does the same thing as the
404: * method {@link #wait(long)} of one argument. In particular,
405: * <tt>wait(0, 0)</tt> means the same thing as <tt>wait(0)</tt>.
406: * <p>
407: * The current thread must own this object's monitor. The thread
408: * releases ownership of this monitor and waits until either of the
409: * following two conditions has occurred:
410: * <ul>
411: * <li>Another thread notifies threads waiting on this object's monitor
412: * to wake up either through a call to the <code>notify</code> method
413: * or the <code>notifyAll</code> method.
414: * <li>The timeout period, specified by <code>timeout</code>
415: * milliseconds plus <code>nanos</code> nanoseconds arguments, has
416: * elapsed.
417: * </ul>
418: * <p>
419: * The thread then waits until it can re-obtain ownership of the
420: * monitor and resumes execution.
421: * <p>
422: * As in the one argument version, interrupts and spurious wakeups are
423: * possible, and this method should always be used in a loop:
424: * <pre>
425: * synchronized (obj) {
426: * while (<condition does not hold>)
427: * obj.wait(timeout, nanos);
428: * ... // Perform action appropriate to condition
429: * }
430: * </pre>
431: * This method should only be called by a thread that is the owner
432: * of this object's monitor. See the <code>notify</code> method for a
433: * description of the ways in which a thread can become the owner of
434: * a monitor.
435: *
436: * @param timeout the maximum time to wait in milliseconds.
437: * @param nanos additional time, in nanoseconds range
438: * 0-999999.
439: * @exception IllegalArgumentException if the value of timeout is
440: * negative or the value of nanos is
441: * not in the range 0-999999.
442: * @exception IllegalMonitorStateException if the current thread is not
443: * the owner of this object's monitor.
444: * @exception InterruptedException if any thread interrupted the
445: * current thread before or while the current thread
446: * was waiting for a notification. The <i>interrupted
447: * status</i> of the current thread is cleared when
448: * this exception is thrown.
449: */
450: public final void wait(long timeout, int nanos)
451: throws InterruptedException {
452: if (timeout < 0) {
453: throw new IllegalArgumentException(
454: "timeout value is negative");
455: }
456:
457: if (nanos < 0 || nanos > 999999) {
458: throw new IllegalArgumentException(
459: "nanosecond timeout value out of range");
460: }
461:
462: if (nanos >= 500000 || (nanos != 0 && timeout == 0)) {
463: timeout++;
464: }
465:
466: wait(timeout);
467: }
468:
469: /**
470: * Causes the current thread to wait until another thread invokes the
471: * {@link java.lang.Object#notify()} method or the
472: * {@link java.lang.Object#notifyAll()} method for this object.
473: * In other words, this method behaves exactly as if it simply
474: * performs the call <tt>wait(0)</tt>.
475: * <p>
476: * The current thread must own this object's monitor. The thread
477: * releases ownership of this monitor and waits until another thread
478: * notifies threads waiting on this object's monitor to wake up
479: * either through a call to the <code>notify</code> method or the
480: * <code>notifyAll</code> method. The thread then waits until it can
481: * re-obtain ownership of the monitor and resumes execution.
482: * <p>
483: * As in the one argument version, interrupts and spurious wakeups are
484: * possible, and this method should always be used in a loop:
485: * <pre>
486: * synchronized (obj) {
487: * while (<condition does not hold>)
488: * obj.wait();
489: * ... // Perform action appropriate to condition
490: * }
491: * </pre>
492: * This method should only be called by a thread that is the owner
493: * of this object's monitor. See the <code>notify</code> method for a
494: * description of the ways in which a thread can become the owner of
495: * a monitor.
496: *
497: * @exception IllegalMonitorStateException if the current thread is not
498: * the owner of the object's monitor.
499: * @exception InterruptedException if any thread interrupted the
500: * current thread before or while the current thread
501: * was waiting for a notification. The <i>interrupted
502: * status</i> of the current thread is cleared when
503: * this exception is thrown.
504: * @see java.lang.Object#notify()
505: * @see java.lang.Object#notifyAll()
506: */
507: public final void wait() throws InterruptedException {
508: wait(0);
509: }
510:
511: /**
512: * Called by the garbage collector on an object when garbage collection
513: * determines that there are no more references to the object.
514: * A subclass overrides the <code>finalize</code> method to dispose of
515: * system resources or to perform other cleanup.
516: * <p>
517: * The general contract of <tt>finalize</tt> is that it is invoked
518: * if and when the Java<font size="-2"><sup>TM</sup></font> virtual
519: * machine has determined that there is no longer any
520: * means by which this object can be accessed by any thread that has
521: * not yet died, except as a result of an action taken by the
522: * finalization of some other object or class which is ready to be
523: * finalized. The <tt>finalize</tt> method may take any action, including
524: * making this object available again to other threads; the usual purpose
525: * of <tt>finalize</tt>, however, is to perform cleanup actions before
526: * the object is irrevocably discarded. For example, the finalize method
527: * for an object that represents an input/output connection might perform
528: * explicit I/O transactions to break the connection before the object is
529: * permanently discarded.
530: * <p>
531: * The <tt>finalize</tt> method of class <tt>Object</tt> performs no
532: * special action; it simply returns normally. Subclasses of
533: * <tt>Object</tt> may override this definition.
534: * <p>
535: * The Java programming language does not guarantee which thread will
536: * invoke the <tt>finalize</tt> method for any given object. It is
537: * guaranteed, however, that the thread that invokes finalize will not
538: * be holding any user-visible synchronization locks when finalize is
539: * invoked. If an uncaught exception is thrown by the finalize method,
540: * the exception is ignored and finalization of that object terminates.
541: * <p>
542: * After the <tt>finalize</tt> method has been invoked for an object, no
543: * further action is taken until the Java virtual machine has again
544: * determined that there is no longer any means by which this object can
545: * be accessed by any thread that has not yet died, including possible
546: * actions by other objects or classes which are ready to be finalized,
547: * at which point the object may be discarded.
548: * <p>
549: * The <tt>finalize</tt> method is never invoked more than once by a Java
550: * virtual machine for any given object.
551: * <p>
552: * Any exception thrown by the <code>finalize</code> method causes
553: * the finalization of this object to be halted, but is otherwise
554: * ignored.
555: *
556: * @throws Throwable the <code>Exception</code> raised by this method
557: */
558: protected void finalize() throws Throwable {
559: }
560: }
|
