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