001: /*
002: *
003: *
004: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: */
026:
027: package java.lang;
028:
029: /**
030: * Class <code>Object</code> is the root of the class hierarchy.
031: * Every class has <code>Object</code> as a superclass. All objects,
032: * including arrays, implement the methods of this class.
033: *
034: * @version 12/17/01 (CLDC 1.1)
035: * @see java.lang.Class
036: * @since JDK1.0, CLDC 1.0
037: */
038: public class Object {
039:
040: /**
041: * Returns the runtime class of an object. That <tt>Class</tt>
042: * object is the object that is locked by <tt>static synchronized</tt>
043: * methods of the represented class.
044: *
045: * @return the object of type <code>Class</code> that represents the
046: * runtime class of the object.
047: */
048: public final native Class getClass();
049:
050: /**
051: * Returns a hash code value for the object. This method is
052: * supported for the benefit of hashtables such as those provided by
053: * <code>java.util.Hashtable</code>.
054: * <p>
055: * The general contract of <code>hashCode</code> is:
056: * <ul>
057: * <li>Whenever it is invoked on the same object more than once during
058: * an execution of a Java application, the <tt>hashCode</tt> method
059: * must consistently return the same integer, provided no information
060: * used in <tt>equals</tt> comparisons on the object is modified.
061: * This integer need not remain consistent from one execution of an
062: * application to another execution of the same application.
063: * <li>If two objects are equal according to the <tt>equals(Object)</tt>
064: * method, then calling the <code>hashCode</code> method on each of
065: * the two objects must produce the same integer result.
066: * <li>It is <em>not</em> required that if two objects are unequal
067: * according to the {@link java.lang.Object#equals(java.lang.Object)}
068: * method, then calling the <tt>hashCode</tt> method on each of the
069: * two objects must produce distinct integer results. However, the
070: * programmer should be aware that producing distinct integer results
071: * for unequal objects may improve the performance of hashtables.
072: * </ul>
073: * <p>
074: * As much as is reasonably practical, the hashCode method defined by
075: * class <tt>Object</tt> does return distinct integers for distinct
076: * objects. (This is typically implemented by converting the internal
077: * address of the object into an integer, but this implementation
078: * technique is not required by the
079: * Java<font size="-2"><sup>TM</sup></font> programming language.)
080: *
081: * @return a hash code value for this object.
082: * @see java.lang.Object#equals(java.lang.Object)
083: * @see java.util.Hashtable
084: */
085: public native int hashCode();
086:
087: /**
088: * Indicates whether some other object is "equal to" this one.
089: * <p>
090: * The <code>equals</code> method implements an equivalence relation:
091: * <ul>
092: * <li>It is <i>reflexive</i>: for any reference value <code>x</code>,
093: * <code>x.equals(x)</code> should return <code>true</code>.
094: * <li>It is <i>symmetric</i>: for any reference values <code>x</code> and
095: * <code>y</code>, <code>x.equals(y)</code> should return
096: * <code>true</code> if and only if <code>y.equals(x)</code> returns
097: * <code>true</code>.
098: * <li>It is <i>transitive</i>: for any reference values <code>x</code>,
099: * <code>y</code>, and <code>z</code>, if <code>x.equals(y)</code>
100: * returns <code>true</code> and <code>y.equals(z)</code> returns
101: * <code>true</code>, then <code>x.equals(z)</code> should return
102: * <code>true</code>.
103: * <li>It is <i>consistent</i>: for any reference values <code>x</code>
104: * and <code>y</code>, multiple invocations of <tt>x.equals(y)</tt>
105: * consistently return <code>true</code> or consistently return
106: * <code>false</code>, provided no information used in
107: * <code>equals</code> comparisons on the object is modified.
108: * <li>For any non-null reference value <code>x</code>,
109: * <code>x.equals(null)</code> should return <code>false</code>.
110: * </ul>
111: * <p>
112: * The <tt>equals</tt> method for class <code>Object</code> implements
113: * the most discriminating possible equivalence relation on objects;
114: * that is, for any reference values <code>x</code> and <code>y</code>,
115: * this method returns <code>true</code> if and only if <code>x</code> and
116: * <code>y</code> refer to the same object (<code>x==y</code> has the
117: * value <code>true</code>).
118: *
119: * @param obj the reference object with which to compare.
120: * @return <code>true</code> if this object is the same as the obj
121: * argument; <code>false</code> otherwise.
122: * @see java.lang.Boolean#hashCode()
123: * @see java.util.Hashtable
124: */
125: public boolean equals(Object obj) {
126: return (this == obj);
127: }
128:
129: /**
130: * Returns a string representation of the object. In general, the
131: * <code>toString</code> method returns a string that
132: * "textually represents" this object. The result should
133: * be a concise but informative representation that is easy for a
134: * person to read.
135: * It is recommended that all subclasses override this method.
136: * <p>
137: * The <code>toString</code> method for class <code>Object</code>
138: * returns a string consisting of the name of the class of which the
139: * object is an instance, the at-sign character `<code>@</code>', and
140: * the unsigned hexadecimal representation of the hash code of the
141: * object. In other words, this method returns a string equal to the
142: * value of:
143: * <blockquote>
144: * <pre>
145: * getClass().getName() + '@' + Integer.toHexString(hashCode())
146: * </pre></blockquote>
147: *
148: * @return a string representation of the object.
149: */
150: public String toString() {
151: return getClass().getName() + "@"
152: + Integer.toHexString(hashCode());
153: }
154:
155: /**
156: * Wakes up a single thread that is waiting on this object's
157: * monitor. If any threads are waiting on this object, one of them
158: * is chosen to be awakened. The choice is arbitrary and occurs at
159: * the discretion of the implementation. A thread waits on an object's
160: * monitor by calling one of the <code>wait</code> methods.
161: * <p>
162: * The awakened thread will not be able to proceed until the current
163: * thread relinquishes the lock on this object. The awakened thread will
164: * compete in the usual manner with any other threads that might be
165: * actively competing to synchronize on this object; for example, the
166: * awakened thread enjoys no reliable privilege or disadvantage in being
167: * the next thread to lock this object.
168: * <p>
169: * This method should only be called by a thread that is the owner
170: * of this object's monitor. A thread becomes the owner of the
171: * object's monitor in one of three ways:
172: * <ul>
173: * <li>By executing a synchronized instance method of that object.
174: * <li>By executing the body of a <code>synchronized</code> statement
175: * that synchronizes on the object.
176: * <li>For objects of type <code>Class,</code> by executing a
177: * synchronized static method of that class.
178: * </ul>
179: * <p>
180: * Only one thread at a time can own an object's monitor.
181: *
182: * @exception IllegalMonitorStateException if the current thread is not
183: * the owner of this object's monitor.
184: * @see java.lang.Object#notifyAll()
185: * @see java.lang.Object#wait()
186: */
187: public final native void notify();
188:
189: /**
190: * Wakes up all threads that are waiting on this object's monitor. A
191: * thread waits on an object's monitor by calling one of the
192: * <code>wait</code> methods.
193: * <p>
194: * The awakened threads will not be able to proceed until the current
195: * thread relinquishes the lock on this object. The awakened threads
196: * will compete in the usual manner with any other threads that might
197: * be actively competing to synchronize on this object; for example,
198: * the awakened threads enjoy no reliable privilege or disadvantage in
199: * being the next thread to lock this object.
200: * <p>
201: * This method should only be called by a thread that is the owner
202: * of this object's monitor. See the <code>notify</code> method for a
203: * description of the ways in which a thread can become the owner of
204: * a monitor.
205: *
206: * @exception IllegalMonitorStateException if the current thread is
207: * not the owner of this object's monitor.
208: * @see java.lang.Object#notify()
209: * @see java.lang.Object#wait()
210: */
211: public final native void notifyAll();
212:
213: /**
214: * Causes current thread to wait until either another thread invokes the
215: * {@link java.lang.Object#notify()} method or the
216: * {@link java.lang.Object#notifyAll()} method for this object, or a
217: * specified amount of time has elapsed.
218: * <p>
219: * The current thread must own this object's monitor.
220: * <p>
221: * This method causes the current thread (call it <var>T</var>) to
222: * place itself in the wait set for this object and then to relinquish
223: * any and all synchronization claims on this object. Thread <var>T</var>
224: * becomes disabled for thread scheduling purposes and lies dormant
225: * until one of four things happens:
226: * <ul>
227: * <li>Some other thread invokes the <tt>notify</tt> method for this
228: * object and thread <var>T</var> happens to be arbitrarily chosen as
229: * the thread to be awakened.
230: * <li>Some other thread invokes the <tt>notifyAll</tt> method for this
231: * object.
232: * <li>Some other thread {@link java.lang.Thread#interrupt() interrupts}
233: * thread <var>T</var>.
234: * <li>The specified amount of real time has elapsed, more or less. If
235: * <tt>timeout</tt> is zero, however, then real time is not taken into
236: * consideration and the thread simply waits until notified.
237: * </ul><p>
238: * The thread <var>T</var> is then removed from the wait set for this
239: * object and re-enabled for thread scheduling. It then competes in the
240: * usual manner with other threads for the right to synchronize on the
241: * object; once it has gained control of the object, all its
242: * synchronization claims on the object are restored to the status quo
243: * ante - that is, to the situation as of the time that the <tt>wait</tt>
244: * method was invoked. Thread <var>T</var> then returns from the
245: * invocation of the <tt>wait</tt> method. Thus, on return from the
246: * <tt>wait</tt> method, the synchronization state of the object and of
247: * thread <var>T</var> is exactly as it was when the <tt>wait</tt> method
248: * was invoked.
249: * <p>
250: * If the current thread is
251: * {@link java.lang.Thread#interrupt() interrupted} by another thread
252: * while it is waiting, then an <tt>InterruptedException</tt> is thrown.
253: * This exception is not thrown until the lock status of this object has
254: * been restored as described above.
255: * <p>
256: * Note that the <tt>wait</tt> method, as it places the current thread
257: * into the wait set for this object, unlocks only this object; any
258: * other objects on which the current thread may be synchronized remain
259: * locked while the thread waits.
260: * <p>
261: * This method should only be called by a thread that is the owner
262: * of this object's monitor. See the <code>notify</code> method for a
263: * description of the ways in which a thread can become the owner of
264: * a monitor.
265: *
266: * @param timeout the maximum time to wait in milliseconds.
267: * @exception IllegalArgumentException if the value of timeout is
268: * negative.
269: * @exception IllegalMonitorStateException if the current thread is not
270: * the owner of the object's monitor.
271: * @exception InterruptedException if another thread has interrupted
272: * the current thread. The <i>interrupted status</i> of the
273: * current thread is cleared when this exception is thrown.
274: * @see java.lang.Object#notify()
275: * @see java.lang.Object#notifyAll()
276: */
277: public final native void wait(long timeout)
278: throws InterruptedException;
279:
280: /**
281: * Causes current thread to wait until another thread invokes the
282: * {@link java.lang.Object#notify()} method or the
283: * {@link java.lang.Object#notifyAll()} method for this object, or
284: * some other thread interrupts the current thread, or a certain
285: * amount of real time has elapsed.
286: * <p>
287: * This method is similar to the <code>wait</code> method of one
288: * argument, but it allows finer control over the amount of time to
289: * wait for a notification before giving up. The amount of real time,
290: * measured in nanoseconds, is given by:
291: * <blockquote>
292: * <pre>
293: * 1000000*timeout+nanos</pre></blockquote>
294: * <p>
295: * In all other respects, this method does the same thing as the
296: * method {@link #wait(long)} of one argument. In particular,
297: * <tt>wait(0, 0)</tt> means the same thing as <tt>wait(0)</tt>.
298: * <p>
299: * The current thread must own this object's monitor. The thread
300: * releases ownership of this monitor and waits until either of the
301: * following two conditions has occurred:
302: * <ul>
303: * <li>Another thread notifies threads waiting on this object's monitor
304: * to wake up either through a call to the <code>notify</code> method
305: * or the <code>notifyAll</code> method.
306: * <li>The timeout period, specified by <code>timeout</code>
307: * milliseconds plus <code>nanos</code> nanoseconds arguments, has
308: * elapsed.
309: * </ul>
310: * <p>
311: * The thread then waits until it can re-obtain ownership of the
312: * monitor and resumes execution
313: * <p>
314: * This method should only be called by a thread that is the owner
315: * of this object's monitor. See the <code>notify</code> method for a
316: * description of the ways in which a thread can become the owner of
317: * a monitor.
318: *
319: * @param timeout the maximum time to wait in milliseconds.
320: * @param nanos additional time, in nanoseconds range
321: * 0-999999.
322: * @exception IllegalArgumentException if the value of timeout is
323: * negative or the value of nanos is
324: * not in the range 0-999999.
325: * @exception IllegalMonitorStateException if the current thread is not
326: * the owner of this object's monitor.
327: * @exception InterruptedException if another thread has interrupted
328: * the current thread. The <i>interrupted status</i> of the
329: * current thread is cleared when this exception is thrown.
330: */
331: public final void wait(long timeout, int nanos)
332: throws InterruptedException {
333: if (timeout < 0) {
334: throw new IllegalArgumentException(
335: /* #ifdef VERBOSE_EXCEPTIONS */
336: /// skipped "timeout value is negative"
337: /* #endif */
338: );
339: }
340:
341: if (nanos < 0 || nanos > 999999) {
342: throw new IllegalArgumentException(
343: /* #ifdef VERBOSE_EXCEPTIONS */
344: /// skipped "nanosecond timeout value out of range"
345: /* #endif */
346: );
347: }
348:
349: if (nanos >= 500000 || (nanos != 0 && timeout == 0)) {
350: timeout++;
351: }
352:
353: wait(timeout);
354: }
355:
356: /**
357: * Causes current thread to wait until another thread invokes the
358: * {@link java.lang.Object#notify()} method or the
359: * {@link java.lang.Object#notifyAll()} method for this object.
360: * In other word's this method behaves exactly as if it simply
361: * performs the call <tt>wait(0)</tt>.
362: * <p>
363: * The current thread must own this object's monitor. The thread
364: * releases ownership of this monitor and waits until another thread
365: * notifies threads waiting on this object's monitor to wake up
366: * either through a call to the <code>notify</code> method or the
367: * <code>notifyAll</code> method. The thread then waits until it can
368: * re-obtain ownership of the monitor and resumes execution.
369: * <p>
370: * This method should only be called by a thread that is the owner
371: * of this object's monitor. See the <code>notify</code> method for a
372: * description of the ways in which a thread can become the owner of
373: * a monitor.
374: *
375: * @exception IllegalMonitorStateException if the current thread is not
376: * the owner of the object's monitor.
377: * @exception InterruptedException if another thread has interrupted
378: * the current thread. The <i>interrupted status</i> of the
379: * current thread is cleared when this exception is thrown.
380: * @see java.lang.Object#notify()
381: * @see java.lang.Object#notifyAll()
382: */
383: public final void wait() throws InterruptedException {
384: wait(0);
385: }
386:
387: }
|