1 |
/* java.lang.Object - The universal superclass in Java |
/* java.lang.Object - The universal superclass in Java |
2 |
Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc. |
Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc. |
3 |
|
|
4 |
This file is part of GNU Classpath. |
This file is part of GNU Classpath. |
5 |
|
|
46 |
* does not extend any other class, it implicitly extends |
* does not extend any other class, it implicitly extends |
47 |
* java.lang.Object. Also, an anonymous class based on |
* java.lang.Object. Also, an anonymous class based on |
48 |
* an interface will extend Object. |
* an interface will extend Object. |
|
* <p> |
|
49 |
* |
* |
50 |
* It provides general-purpose methods that every single |
* <p>It provides general-purpose methods that every single |
51 |
* Object, regardless of race, sex or creed, implements. |
* Object, regardless of race, sex or creed, implements. |
52 |
* All of the public methods may be invoked on arrays or |
* All of the public methods may be invoked on arrays or |
53 |
* interfaces. The protected methods <code>clone</code> |
* interfaces. The protected methods <code>clone</code> |
90 |
/** |
/** |
91 |
* Determine whether this Object is semantically equal |
* Determine whether this Object is semantically equal |
92 |
* to another Object. |
* to another Object. |
|
* <p> |
|
93 |
* |
* |
94 |
* There are some fairly strict requirements on this |
* <p>There are some fairly strict requirements on this |
95 |
* method which subclasses must follow:<br> |
* method which subclasses must follow:<br> |
|
* |
|
96 |
* <ul> |
* <ul> |
97 |
* <li>It must be transitive. If <code>a.equals(b)</code> and |
* <li>It must be transitive. If <code>a.equals(b)</code> and |
98 |
* <code>b.equals(c)</code>, then <code>a.equals(c)</code> |
* <code>b.equals(c)</code>, then <code>a.equals(c)</code> |
111 |
* The reverse is not true; two objects that are not |
* The reverse is not true; two objects that are not |
112 |
* equal may have the same hashcode, but that has |
* equal may have the same hashcode, but that has |
113 |
* the potential to harm hashing performance.</li> |
* the potential to harm hashing performance.</li> |
114 |
* </ul><p> |
* </ul> |
115 |
* |
* |
116 |
* This is typically overridden to throw a {@link ClassCastException} |
* <p>This is typically overridden to throw a {@link ClassCastException} |
117 |
* if the argument is not comparable to the class performing |
* if the argument is not comparable to the class performing |
118 |
* the comparison, but that is not a requirement. It is legal |
* the comparison, but that is not a requirement. It is legal |
119 |
* for <code>a.equals(b)</code> to be true even though |
* for <code>a.equals(b)</code> to be true even though |
120 |
* <code>a.getClass() != b.getClass()</code>. Also, it |
* <code>a.getClass() != b.getClass()</code>. Also, it |
121 |
* is typical to never cause a {@link NullPointerException}. |
* is typical to never cause a {@link NullPointerException}. |
|
* <p> |
|
122 |
* |
* |
123 |
* In general, the Collections API ({@link java.util}) use the |
* <p>In general, the Collections API ({@link java.util}) use the |
124 |
* <code>equals</code> method rather than the <code>==</code> |
* <code>equals</code> method rather than the <code>==</code> |
125 |
* operator to compare objects. However, {@link java.util.IdentityHashMap} |
* operator to compare objects. However, {@link java.util.IdentityHashMap} |
126 |
* is an exception to this rule, for its own good reasons. |
* is an exception to this rule, for its own good reasons. |
|
* <p> |
|
127 |
* |
* |
128 |
* The default implementation returns <code>this == o</code>. |
* <p>The default implementation returns <code>this == o</code>. |
129 |
* |
* |
130 |
* @param o the Object to compare to. |
* @param o the Object to compare to |
131 |
* @return whether this Object is semantically equal to another. |
* @return whether this Object is semantically equal to another |
132 |
* @see #hashCode() |
* @see #hashCode() |
133 |
*/ |
*/ |
134 |
public boolean equals(Object o) |
public boolean equals(Object o) |
139 |
/** |
/** |
140 |
* Get a value that represents this Object, as uniquely as |
* Get a value that represents this Object, as uniquely as |
141 |
* possible within the confines of an int. |
* possible within the confines of an int. |
|
* <p> |
|
142 |
* |
* |
143 |
* There are some requirements on this method which |
* <p>There are some requirements on this method which |
144 |
* subclasses must follow:<br> |
* subclasses must follow:<br> |
145 |
* |
* |
146 |
* <ul> |
* <ul> |
155 |
* exists. Notice, however, that the result of hashCode may |
* exists. Notice, however, that the result of hashCode may |
156 |
* change between separate executions of a Virtual Machine, |
* change between separate executions of a Virtual Machine, |
157 |
* because it is not invoked on the same object.</li> |
* because it is not invoked on the same object.</li> |
158 |
* </ul><p> |
* </ul> |
159 |
* |
* |
160 |
* Notice that since <code>hashCode</code> is used in |
* <p>Notice that since <code>hashCode</code> is used in |
161 |
* {@link java.util.Hashtable} and other hashing classes, |
* {@link java.util.Hashtable} and other hashing classes, |
162 |
* a poor implementation will degrade the performance of hashing |
* a poor implementation will degrade the performance of hashing |
163 |
* (so don't blindly implement it as returning a constant!). Also, |
* (so don't blindly implement it as returning a constant!). Also, |
164 |
* if calculating the hash is time-consuming, a class may consider |
* if calculating the hash is time-consuming, a class may consider |
165 |
* caching the results. |
* caching the results. |
|
* <p> |
|
166 |
* |
* |
167 |
* The default implementation returns |
* <p>The default implementation returns |
168 |
* <code>System.identityHashCode(this)</code> |
* <code>System.identityHashCode(this)</code> |
169 |
* |
* |
170 |
* @return the hash code for this Object. |
* @return the hash code for this Object |
171 |
* @see #equals(Object) |
* @see #equals(Object) |
172 |
* @see System#identityHashCode(Object) |
* @see System#identityHashCode(Object) |
173 |
*/ |
*/ |
183 |
* make it as intuitive as possible to be able to place |
* make it as intuitive as possible to be able to place |
184 |
* it into {@link java.io.PrintStream#println() System.out.println()} |
* it into {@link java.io.PrintStream#println() System.out.println()} |
185 |
* and such. |
* and such. |
|
* <p> |
|
186 |
* |
* |
187 |
* It is typical, but not required, to ensure that this method |
* <p>It is typical, but not required, to ensure that this method |
188 |
* never completes abruptly with a {@link RuntimeException}. |
* never completes abruptly with a {@link RuntimeException}. |
|
* <p> |
|
189 |
* |
* |
190 |
* This method will be called when performing string |
* <p>This method will be called when performing string |
191 |
* concatenation with this object. If the result is |
* concatenation with this object. If the result is |
192 |
* <code>null</code>, string concatenation will instead |
* <code>null</code>, string concatenation will instead |
193 |
* use <code>"null"</code>. |
* use <code>"null"</code>. |
|
* <p> |
|
194 |
* |
* |
195 |
* The default implementation returns |
* <p>The default implementation returns |
196 |
* <code>getClass().getName() + "@" + |
* <code>getClass().getName() + "@" + |
197 |
* Integer.toHexString(hashCode())</code>. |
* Integer.toHexString(hashCode())</code>. |
198 |
* |
* |
199 |
* @return the String representing this Object, which may be null. |
* @return the String representing this Object, which may be null |
200 |
* @throws OutOfMemoryError The default implementation creates a new |
* @throws OutOfMemoryError The default implementation creates a new |
201 |
* String object, therefore it must allocate memory. |
* String object, therefore it must allocate memory |
202 |
* @see #getClass() |
* @see #getClass() |
203 |
* @see #hashCode() |
* @see #hashCode() |
204 |
* @see Class#getName() |
* @see Class#getName() |
219 |
* Thus you cannot rely on this method to always work. |
* Thus you cannot rely on this method to always work. |
220 |
* For finer control over garbage collection, use references |
* For finer control over garbage collection, use references |
221 |
* from the {@link java.lang.ref} package. |
* from the {@link java.lang.ref} package. |
|
* <p> |
|
222 |
* |
* |
223 |
* Virtual Machines are free to not call this method if |
* <p>Virtual Machines are free to not call this method if |
224 |
* they can determine that it does nothing important; for |
* they can determine that it does nothing important; for |
225 |
* example, if your class extends Object and overrides |
* example, if your class extends Object and overrides |
226 |
* finalize to do simply <code>super.finalize()</code>. |
* finalize to do simply <code>super.finalize()</code>. |
|
* <p> |
|
227 |
* |
* |
228 |
* finalize() will be called by a {@link Thread} that has no |
* <p>finalize() will be called by a {@link Thread} that has no |
229 |
* locks on any Objects, and may be called concurrently. |
* locks on any Objects, and may be called concurrently. |
230 |
* There are no guarantees on the order in which multiple |
* There are no guarantees on the order in which multiple |
231 |
* objects are finalized. This means that finalize() is |
* objects are finalized. This means that finalize() is |
232 |
* usually unsuited for performing actions that must be |
* usually unsuited for performing actions that must be |
233 |
* thread-safe, and that your implementation must be |
* thread-safe, and that your implementation must be |
234 |
* use defensive programming if it is to always work. |
* use defensive programming if it is to always work. |
|
* <p> |
|
235 |
* |
* |
236 |
* If an Exception is thrown from finalize() during garbage |
* <p>If an Exception is thrown from finalize() during garbage |
237 |
* collection, it will be patently ignored and the Object will |
* collection, it will be patently ignored and the Object will |
238 |
* still be destroyed. |
* still be destroyed. |
|
* <p> |
|
239 |
* |
* |
240 |
* It is allowed, although not typical, for user code to call |
* <p>It is allowed, although not typical, for user code to call |
241 |
* finalize() directly. User invocation does not affect whether |
* finalize() directly. User invocation does not affect whether |
242 |
* automatic invocation will occur. It is also permitted, |
* automatic invocation will occur. It is also permitted, |
243 |
* although not recommended, for a finalize() method to "revive" |
* although not recommended, for a finalize() method to "revive" |
244 |
* an object by making it reachable from normal code again. |
* an object by making it reachable from normal code again. |
|
* <p> |
|
245 |
* |
* |
246 |
* Unlike constructors, finalize() does not get called |
* <p>Unlike constructors, finalize() does not get called |
247 |
* for an object's superclass unless the implementation |
* for an object's superclass unless the implementation |
248 |
* specifically calls <code>super.finalize()</code>. |
* specifically calls <code>super.finalize()</code>. |
|
* <p> |
|
249 |
* |
* |
250 |
* The default implementation does nothing. |
* <p>The default implementation does nothing. |
251 |
* |
* |
252 |
* @throws Throwable permits a subclass to throw anything in an |
* @throws Throwable permits a subclass to throw anything in an |
253 |
* overridden version; but the default throws nothing. |
* overridden version; but the default throws nothing |
254 |
* @see System#gc() |
* @see System#gc() |
255 |
* @see System#runFinalizersOnExit(boolean) |
* @see System#runFinalizersOnExit(boolean) |
256 |
* @see java.lang.ref |
* @see java.lang.ref |
262 |
/** |
/** |
263 |
* This method may be called to create a new copy of the |
* This method may be called to create a new copy of the |
264 |
* Object. The typical behavior is as follows:<br> |
* Object. The typical behavior is as follows:<br> |
|
* |
|
265 |
* <ul> |
* <ul> |
266 |
* <li><code>o == o.clone()</code> is false</li> |
* <li><code>o == o.clone()</code> is false</li> |
267 |
* <li><code>o.getClass() == o.clone().getClass()</code> |
* <li><code>o.getClass() == o.clone().getClass()</code> |
268 |
* is true</li> |
* is true</li> |
269 |
* <li><code>o.equals(o)</code> is true</li> |
* <li><code>o.equals(o)</code> is true</li> |
270 |
* </ul><p> |
* </ul> |
271 |
* |
* |
272 |
* However, these are not strict requirements, and may |
* <p>However, these are not strict requirements, and may |
273 |
* be violated if necessary. Of the three requirements, the |
* be violated if necessary. Of the three requirements, the |
274 |
* last is the most commonly violated, particularly if the |
* last is the most commonly violated, particularly if the |
275 |
* subclass does not override {@link #equals(Object)}. |
* subclass does not override {@link #equals(Object)}. |
|
* <p> |
|
276 |
* |
* |
277 |
* If the Object you call clone() on does not implement |
* <p>If the Object you call clone() on does not implement |
278 |
* {@link Cloneable} (which is a placeholder interface), then |
* {@link Cloneable} (which is a placeholder interface), then |
279 |
* a CloneNotSupportedException is thrown. Notice that |
* a CloneNotSupportedException is thrown. Notice that |
280 |
* Object does not implement Cloneable; this method exists |
* Object does not implement Cloneable; this method exists |
281 |
* as a convenience for subclasses that do. |
* as a convenience for subclasses that do. |
|
* <p> |
|
282 |
* |
* |
283 |
* Object's implementation of clone allocates space for the |
* <p>Object's implementation of clone allocates space for the |
284 |
* new Object using the correct class, without calling any |
* new Object using the correct class, without calling any |
285 |
* constructors, and then fills in all of the new field values |
* constructors, and then fills in all of the new field values |
286 |
* with the old field values. Thus, it is a shallow copy. |
* with the old field values. Thus, it is a shallow copy. |
287 |
* However, subclasses are permitted to make a deep copy. |
* However, subclasses are permitted to make a deep copy. |
|
* <p> |
|
288 |
* |
* |
289 |
* All array types implement Cloneable, and override |
* <p>All array types implement Cloneable, and override |
290 |
* this method as follows (it should never fail):<br> |
* this method as follows (it should never fail):<br> |
291 |
* <pre> |
* <pre> |
292 |
* public Object clone() |
* public Object clone() |
302 |
* } |
* } |
303 |
* </pre> |
* </pre> |
304 |
* |
* |
305 |
* @return a copy of the Object. |
* @return a copy of the Object |
306 |
* @throws CloneNotSupportedException If this Object does not |
* @throws CloneNotSupportedException If this Object does not |
307 |
* implement Cloneable. |
* implement Cloneable |
308 |
* @throws OutOfMemoryError Since cloning involves memory allocation, |
* @throws OutOfMemoryError Since cloning involves memory allocation, |
309 |
* even though it may bypass constructors, you might run |
* even though it may bypass constructors, you might run |
310 |
* out of memory. |
* out of memory |
311 |
* @see Cloneable |
* @see Cloneable |
312 |
*/ |
*/ |
313 |
protected Object clone() throws CloneNotSupportedException |
protected Object clone() throws CloneNotSupportedException |
314 |
{ |
{ |
315 |
if (this instanceof Cloneable) |
if (this instanceof Cloneable) |
316 |
return VMObject.clone(this); |
return VMObject.clone((Cloneable) this); |
317 |
throw new CloneNotSupportedException("Object not cloneable"); |
throw new CloneNotSupportedException("Object not cloneable"); |
318 |
} |
} |
319 |
|
|
320 |
/** |
/** |
321 |
* Returns the runtime {@link Class} of this Object. |
* Returns the runtime {@link Class} of this Object. |
|
* <p> |
|
322 |
* |
* |
323 |
* The class object can also be obtained without a runtime |
* <p>The class object can also be obtained without a runtime |
324 |
* instance by using the class literal, as in: |
* instance by using the class literal, as in: |
325 |
* <code>Foo.class</code>. Notice that the class literal |
* <code>Foo.class</code>. Notice that the class literal |
326 |
* also works on primitive types, making it useful for |
* also works on primitive types, making it useful for |
327 |
* reflection purposes. |
* reflection purposes. |
328 |
* |
* |
329 |
* @return the class of this Object. |
* @return the class of this Object |
330 |
*/ |
*/ |
331 |
public final native Class getClass(); |
public final native Class getClass(); |
332 |
|
|
335 |
* <code>wait</code> on this Object. Only the owner |
* <code>wait</code> on this Object. Only the owner |
336 |
* of a lock on this Object may call this method. This lock |
* of a lock on this Object may call this method. This lock |
337 |
* is obtained by a <code>synchronized</code> method or statement. |
* is obtained by a <code>synchronized</code> method or statement. |
|
* <p> |
|
338 |
* |
* |
339 |
* The Thread to wake up is chosen arbitrarily. The |
* <p>The Thread to wake up is chosen arbitrarily. The |
340 |
* awakened thread is not guaranteed to be the next thread |
* awakened thread is not guaranteed to be the next thread |
341 |
* to actually obtain the lock on this object. |
* to actually obtain the lock on this object. |
|
* <p> |
|
342 |
* |
* |
343 |
* This thread still holds a lock on the object, so it is |
* <p>This thread still holds a lock on the object, so it is |
344 |
* typical to release the lock by exiting the synchronized |
* typical to release the lock by exiting the synchronized |
345 |
* code, calling wait(), or calling {@link Thread#sleep()}, so |
* code, calling wait(), or calling {@link Thread#sleep()}, so |
346 |
* that the newly awakened thread can actually resume. The |
* that the newly awakened thread can actually resume. The |
347 |
* awakened thread will most likely be awakened with an |
* awakened thread will most likely be awakened with an |
348 |
* {@link InterruptedException}, but that is not guaranteed. |
* {@link InterruptedException}, but that is not guaranteed. |
|
* <p> |
|
349 |
* |
* |
350 |
* @throws IllegalMonitorStateException if this Thread |
* @throws IllegalMonitorStateException if this Thread |
351 |
* does not own the lock on the Object. |
* does not own the lock on the Object |
352 |
* @see #notifyAll() |
* @see #notifyAll() |
353 |
* @see #wait() |
* @see #wait() |
354 |
* @see #wait(long) |
* @see #wait(long) |
365 |
* <code>wait</code> on this Object. Only the owner |
* <code>wait</code> on this Object. Only the owner |
366 |
* of a lock on this Object may call this method. This lock |
* of a lock on this Object may call this method. This lock |
367 |
* is obtained by a <code>synchronized</code> method or statement. |
* is obtained by a <code>synchronized</code> method or statement. |
|
* <p> |
|
368 |
* |
* |
369 |
* There are no guarantees as to which thread will next |
* <p>There are no guarantees as to which thread will next |
370 |
* obtain the lock on the object. |
* obtain the lock on the object. |
|
* <p> |
|
371 |
* |
* |
372 |
* This thread still holds a lock on the object, so it is |
* <p>This thread still holds a lock on the object, so it is |
373 |
* typical to release the lock by exiting the synchronized |
* typical to release the lock by exiting the synchronized |
374 |
* code, calling wait(), or calling {@link Thread#sleep()}, so |
* code, calling wait(), or calling {@link Thread#sleep()}, so |
375 |
* that one of the newly awakened threads can actually resume. |
* that one of the newly awakened threads can actually resume. |
377 |
* {@link InterruptedException}, but that is not guaranteed. |
* {@link InterruptedException}, but that is not guaranteed. |
378 |
* |
* |
379 |
* @throws IllegalMonitorStateException if this Thread |
* @throws IllegalMonitorStateException if this Thread |
380 |
* does not own the lock on the Object. |
* does not own the lock on the Object |
381 |
* @see #notify() |
* @see #notify() |
382 |
* @see #wait() |
* @see #wait() |
383 |
* @see #wait(long) |
* @see #wait(long) |
393 |
* Waits indefinitely for notify() or notifyAll() to be |
* Waits indefinitely for notify() or notifyAll() to be |
394 |
* called on the Object in question. Implementation is |
* called on the Object in question. Implementation is |
395 |
* identical to wait(0). |
* identical to wait(0). |
|
* <p> |
|
396 |
* |
* |
397 |
* The Thread that calls wait must have a lock on this Object, |
* <p>The Thread that calls wait must have a lock on this Object, |
398 |
* obtained by a <code>synchronized</code> method or statement. |
* obtained by a <code>synchronized</code> method or statement. |
399 |
* After calling wait, the thread loses the lock on this |
* After calling wait, the thread loses the lock on this |
400 |
* object until the method completes (abruptly or normally), |
* object until the method completes (abruptly or normally), |
401 |
* at which time it regains the lock. All locks held on |
* at which time it regains the lock. All locks held on |
402 |
* other objects remain in force, even though the thread is |
* other objects remain in force, even though the thread is |
403 |
* inactive. Therefore, caution must be used to avoid deadlock. |
* inactive. Therefore, caution must be used to avoid deadlock. |
|
* <p> |
|
404 |
* |
* |
405 |
* While it is typical that this method will complete abruptly |
* <p>While it is typical that this method will complete abruptly |
406 |
* with an {@link InterruptedException}, it is not guaranteed. So, |
* with an {@link InterruptedException}, it is not guaranteed. So, |
407 |
* it is typical to call wait inside an infinite loop:<br> |
* it is typical to call wait inside an infinite loop:<br> |
408 |
* |
* |
418 |
* </pre> |
* </pre> |
419 |
* |
* |
420 |
* @throws IllegalMonitorStateException if this Thread |
* @throws IllegalMonitorStateException if this Thread |
421 |
* does not own a lock on this Object. |
* does not own a lock on this Object |
422 |
* @throws InterruptedException if some other Thread |
* @throws InterruptedException if some other Thread |
423 |
* interrupts this Thread. |
* interrupts this Thread |
424 |
* @see #notify() |
* @see #notify() |
425 |
* @see #notifyAll() |
* @see #notifyAll() |
426 |
* @see #wait(long) |
* @see #wait(long) |
437 |
* Waits a specified amount of time (or indefinitely if |
* Waits a specified amount of time (or indefinitely if |
438 |
* the time specified is 0) for someone to call notify() |
* the time specified is 0) for someone to call notify() |
439 |
* or notifyAll() on this Object, waking up this Thread. |
* or notifyAll() on this Object, waking up this Thread. |
|
* <p> |
|
440 |
* |
* |
441 |
* The Thread that calls wait must have a lock on this Object, |
* <p>The Thread that calls wait must have a lock on this Object, |
442 |
* obtained by a <code>synchronized</code> method or statement. |
* obtained by a <code>synchronized</code> method or statement. |
443 |
* After calling wait, the thread loses the lock on this |
* After calling wait, the thread loses the lock on this |
444 |
* object until the method completes (abruptly or normally), |
* object until the method completes (abruptly or normally), |
445 |
* at which time it regains the lock. All locks held on |
* at which time it regains the lock. All locks held on |
446 |
* other objects remain in force, even though the thread is |
* other objects remain in force, even though the thread is |
447 |
* inactive. Therefore, caution must be used to avoid deadlock. |
* inactive. Therefore, caution must be used to avoid deadlock. |
|
* <p> |
|
448 |
* |
* |
449 |
* Usually, this call will complete normally if the time |
* <p>Usually, this call will complete normally if the time |
450 |
* expires, or abruptly with {@link InterruptedException} |
* expires, or abruptly with {@link InterruptedException} |
451 |
* if another thread called notify, but neither result |
* if another thread called notify, but neither result |
452 |
* is guaranteed. |
* is guaranteed. |
|
* <p> |
|
453 |
* |
* |
454 |
* The waiting period is only *roughly* the amount of time |
* <p>The waiting period is only *roughly* the amount of time |
455 |
* you requested. It cannot be exact because of the overhead |
* you requested. It cannot be exact because of the overhead |
456 |
* of the call itself. Most Virtual Machiness treat the |
* of the call itself. Most Virtual Machiness treat the |
457 |
* argument as a lower limit on the time spent waiting, but |
* argument as a lower limit on the time spent waiting, but |
461 |
* lock. |
* lock. |
462 |
* |
* |
463 |
* @param ms the minimum number of milliseconds to wait (1000 |
* @param ms the minimum number of milliseconds to wait (1000 |
464 |
* milliseconds = 1 second), or 0 for an indefinite wait. |
* milliseconds = 1 second), or 0 for an indefinite wait |
465 |
* @throws IllegalArgumentException if ms < 0. |
* @throws IllegalArgumentException if ms < 0 |
466 |
* @throws IllegalMonitorStateException if this Thread |
* @throws IllegalMonitorStateException if this Thread |
467 |
* does not own a lock on this Object. |
* does not own a lock on this Object |
468 |
* @throws InterruptedException if some other Thread |
* @throws InterruptedException if some other Thread |
469 |
* interrupts this Thread. |
* interrupts this Thread |
470 |
* @see #notify() |
* @see #notify() |
471 |
* @see #notifyAll() |
* @see #notifyAll() |
472 |
* @see #wait() |
* @see #wait() |
483 |
* Waits a specified amount of time (or indefinitely if |
* Waits a specified amount of time (or indefinitely if |
484 |
* the time specified is 0) for someone to call notify() |
* the time specified is 0) for someone to call notify() |
485 |
* or notifyAll() on this Object, waking up this Thread. |
* or notifyAll() on this Object, waking up this Thread. |
|
* <p> |
|
486 |
* |
* |
487 |
* The Thread that calls wait must have a lock on this Object, |
* <p>The Thread that calls wait must have a lock on this Object, |
488 |
* obtained by a <code>synchronized</code> method or statement. |
* obtained by a <code>synchronized</code> method or statement. |
489 |
* After calling wait, the thread loses the lock on this |
* After calling wait, the thread loses the lock on this |
490 |
* object until the method completes (abruptly or normally), |
* object until the method completes (abruptly or normally), |
491 |
* at which time it regains the lock. All locks held on |
* at which time it regains the lock. All locks held on |
492 |
* other objects remain in force, even though the thread is |
* other objects remain in force, even though the thread is |
493 |
* inactive. Therefore, caution must be used to avoid deadlock. |
* inactive. Therefore, caution must be used to avoid deadlock. |
|
* <p> |
|
494 |
* |
* |
495 |
* Usually, this call will complete normally if the time |
* <p>Usually, this call will complete normally if the time |
496 |
* expires, or abruptly with {@link InterruptedException} |
* expires, or abruptly with {@link InterruptedException} |
497 |
* if another thread called notify, but neither result |
* if another thread called notify, but neither result |
498 |
* is guaranteed. |
* is guaranteed. |
|
* <p> |
|
499 |
* |
* |
500 |
* The waiting period is nowhere near as precise as |
* <p>The waiting period is nowhere near as precise as |
501 |
* nanoseconds; considering that even wait(int) is inaccurate, |
* nanoseconds; considering that even wait(int) is inaccurate, |
502 |
* how much can you expect? But on supporting |
* how much can you expect? But on supporting |
503 |
* implementations, this offers somewhat more granularity |
* implementations, this offers somewhat more granularity |
504 |
* than milliseconds. |
* than milliseconds. |
505 |
* |
* |
506 |
* @param ms the number of milliseconds to wait (1,000 |
* @param ms the number of milliseconds to wait (1,000 |
507 |
* milliseconds = 1 second). |
* milliseconds = 1 second) |
508 |
* @param ns the number of nanoseconds to wait over and |
* @param ns the number of nanoseconds to wait over and |
509 |
* above ms (1,000,000 nanoseconds = 1 millisecond). |
* above ms (1,000,000 nanoseconds = 1 millisecond) |
510 |
* @throws IllegalArgumentException if ms < 0 or ns is not |
* @throws IllegalArgumentException if ms < 0 or ns is not |
511 |
* in the range 0 to 999,999 |
* in the range 0 to 999,999 |
512 |
* @throws IllegalMonitorStateException if this Thread |
* @throws IllegalMonitorStateException if this Thread |
513 |
* does not own a lock on this Object. |
* does not own a lock on this Object |
514 |
* @throws InterruptedException if some other Thread |
* @throws InterruptedException if some other Thread |
515 |
* interrupts this Thread. |
* interrupts this Thread |
516 |
* @see #notify() |
* @see #notify() |
517 |
* @see #notifyAll() |
* @see #notifyAll() |
518 |
* @see #wait() |
* @see #wait() |