It provides general-purpose methods that every single
* Object, regardless of race, sex or creed, implements.
* All of the public methods may be invoked on arrays or
* interfaces. The protected methods clone
* and finalize are not accessible on arrays
* or interfaces, but all array types have a public version
* of clone which is accessible.
*
* @author John Keiser
* @author Eric Blake (ebb9@email.byu.edu)
* @author Tom Tromey (tromey@cygnus.com)
*/
public class Object
{
/**
* Called on an object by the Virtual Machine at most once,
* at some point after the Object is determined unreachable
* but before it is destroyed. You would think that this
* means it eventually is called on every Object, but this is
* not necessarily the case. If execution terminates
* abnormally, garbage collection does not always happen.
* Thus you cannot rely on this method to always work.
* For finer control over garbage collection, use references
* from the {@link java.lang.ref} package.
*
*
Virtual Machines are free to not call this method if
* they can determine that it does nothing important; for
* example, if your class extends Object and overrides
* finalize to do simply super.finalize().
*
*
finalize() will be called by a {@link Thread} that has no * locks on any Objects, and may be called concurrently. * There are no guarantees on the order in which multiple * objects are finalized. This means that finalize() is * usually unsuited for performing actions that must be * thread-safe, and that your implementation must be * use defensive programming if it is to always work. * *
If an Exception is thrown from finalize() during garbage * collection, it will be patently ignored and the Object will * still be destroyed. * *
It is allowed, although not typical, for user code to call * finalize() directly. User invocation does not affect whether * automatic invocation will occur. It is also permitted, * although not recommended, for a finalize() method to "revive" * an object by making it reachable from normal code again. * *
Unlike constructors, finalize() does not get called
* for an object's superclass unless the implementation
* specifically calls super.finalize().
*
*
The default implementation does nothing. * * @throws Throwable permits a subclass to throw anything in an * overridden version; but the default throws nothing * @see System#gc() * @see System#runFinalizersOnExit(boolean) * @see java.lang.ref */ // This must come first. See _JvObjectPrefix in Object.h. protected void finalize () throws Throwable { } /** * Returns the runtime {@link Class} of this Object. * *
The class object can also be obtained without a runtime
* instance by using the class literal, as in:
* Foo.class. Notice that the class literal
* also works on primitive types, making it useful for
* reflection purposes.
*
* @return the class of this Object
*/
public final native Class getClass();
/**
* Get a value that represents this Object, as uniquely as
* possible within the confines of an int.
*
*
There are some requirements on this method which
* subclasses must follow:
*
*
a.equals(b) is true, then
* a.hashCode() == b.hashCode() must be as well.
* However, the reverse is not necessarily true, and two
* objects may have the same hashcode without being equal.Notice that since hashCode is used in
* {@link java.util.Hashtable} and other hashing classes,
* a poor implementation will degrade the performance of hashing
* (so don't blindly implement it as returning a constant!). Also,
* if calculating the hash is time-consuming, a class may consider
* caching the results.
*
*
The default implementation returns
* System.identityHashCode(this)
*
* @return the hash code for this Object
* @see #equals(Object)
* @see System#identityHashCode(Object)
*/
public native int hashCode();
/**
* Wakes up one of the {@link Thread}s that has called
* wait on this Object. Only the owner
* of a lock on this Object may call this method. This lock
* is obtained by a synchronized method or statement.
*
*
The Thread to wake up is chosen arbitrarily. The * awakened thread is not guaranteed to be the next thread * to actually obtain the lock on this object. * *
This thread still holds a lock on the object, so it is
* typical to release the lock by exiting the synchronized
* code, calling wait(), or calling {@link Thread#sleep()}, so
* that the newly awakened thread can actually resume. The
* awakened thread will most likely be awakened with an
* {@link InterruptedException}, but that is not guaranteed.
*
* @throws IllegalMonitorStateException if this Thread
* does not own the lock on the Object
* @see #notifyAll()
* @see #wait()
* @see #wait(long)
* @see #wait(long, int)
* @see Thread
*/
public final native void notify();
/**
* Wakes up all of the {@link Thread}s that have called
* wait on this Object. Only the owner
* of a lock on this Object may call this method. This lock
* is obtained by a synchronized method or statement.
*
*
There are no guarantees as to which thread will next * obtain the lock on the object. * *
This thread still holds a lock on the object, so it is * typical to release the lock by exiting the synchronized * code, calling wait(), or calling {@link Thread#sleep()}, so * that one of the newly awakened threads can actually resume. * The resuming thread will most likely be awakened with an * {@link InterruptedException}, but that is not guaranteed. * * @throws IllegalMonitorStateException if this Thread * does not own the lock on the Object * @see #notify() * @see #wait() * @see #wait(long) * @see #wait(long, int) * @see Thread */ public final native void notifyAll(); /** * Waits a specified amount of time (or indefinitely if * the time specified is 0) for someone to call notify() * or notifyAll() on this Object, waking up this Thread. * *
The Thread that calls wait must have a lock on this Object,
* obtained by a synchronized method or statement.
* After calling wait, the thread loses the lock on this
* object until the method completes (abruptly or normally),
* at which time it regains the lock. All locks held on
* other objects remain in force, even though the thread is
* inactive. Therefore, caution must be used to avoid deadlock.
*
*
Usually, this call will complete normally if the time * expires, or abruptly with {@link InterruptedException} * if another thread called notify, but neither result * is guaranteed. * *
The waiting period is nowhere near as precise as * nanoseconds; considering that even wait(int) is inaccurate, * how much can you expect? But on supporting * implementations, this offers somewhat more granularity * than milliseconds. * * @param ms the number of milliseconds to wait (1,000 * milliseconds = 1 second) * @param ns the number of nanoseconds to wait over and * above ms (1,000,000 nanoseconds = 1 millisecond) * @throws IllegalArgumentException if ms < 0 or ns is not * in the range 0 to 999,999 * @throws IllegalMonitorStateException if this Thread * does not own a lock on this Object * @throws InterruptedException if some other Thread * interrupts this Thread * @see #notify() * @see #notifyAll() * @see #wait() * @see #wait(long) * @see Thread */ public final native void wait(long timeout, int nanos) throws InterruptedException; /** * Determine whether this Object is semantically equal * to another Object. * *
There are some fairly strict requirements on this
* method which subclasses must follow:
*
a.equals(b) and
* b.equals(c), then a.equals(c)
* must be true as well.a.equals(b) and
* b.equals(a) must have the same value.a.equals(a) must
* always be true.a.equals(null) must be false.a.equals(b) must imply
* a.hashCode() == b.hashCode().
* The reverse is not true; two objects that are not
* equal may have the same hashcode, but that has
* the potential to harm hashing performance.This is typically overridden to throw a {@link ClassCastException}
* if the argument is not comparable to the class performing
* the comparison, but that is not a requirement. It is legal
* for a.equals(b) to be true even though
* a.getClass() != b.getClass(). Also, it
* is typical to never cause a {@link NullPointerException}.
*
*
In general, the Collections API ({@link java.util}) use the
* equals method rather than the ==
* operator to compare objects. However, {@link java.util.IdentityHashMap}
* is an exception to this rule, for its own good reasons.
*
*
The default implementation returns this == o.
*
* @param obj the Object to compare to
* @return whether this Object is semantically equal to another
* @see #hashCode()
*/
public boolean equals(Object obj)
{
return this == obj;
}
/**
* The basic constructor. Object is special, because it has no
* superclass, so there is no call to super().
*
* @throws OutOfMemoryError Technically, this constructor never
* throws an OutOfMemoryError, because the memory has
* already been allocated by this point. But as all
* instance creation expressions eventually trace back
* to this constructor, and creating an object allocates
* memory, we list that possibility here.
*/
public Object()
{
}
/**
* Convert this Object to a human-readable String.
* There are no limits placed on how long this String
* should be or what it should contain. We suggest you
* make it as intuitive as possible to be able to place
* it into {@link java.io.PrintStream#println() System.out.println()}
* and such.
*
*
It is typical, but not required, to ensure that this method * never completes abruptly with a {@link RuntimeException}. * *
This method will be called when performing string
* concatenation with this object. If the result is
* null, string concatenation will instead
* use "null".
*
*
The default implementation returns
* getClass().getName() + "@" +
* Integer.toHexString(hashCode()).
*
* @return the String representing this Object, which may be null
* @throws OutOfMemoryError The default implementation creates a new
* String object, therefore it must allocate memory
* @see #getClass()
* @see #hashCode()
* @see Class#getName()
* @see Integer#toHexString(int)
*/
public String toString()
{
return getClass().getName() + '@' + Integer.toHexString(hashCode());
}
/**
* Waits indefinitely for notify() or notifyAll() to be
* called on the Object in question. Implementation is
* identical to wait(0).
*
*
The Thread that calls wait must have a lock on this Object,
* obtained by a synchronized method or statement.
* After calling wait, the thread loses the lock on this
* object until the method completes (abruptly or normally),
* at which time it regains the lock. All locks held on
* other objects remain in force, even though the thread is
* inactive. Therefore, caution must be used to avoid deadlock.
*
*
While it is typical that this method will complete abruptly
* with an {@link InterruptedException}, it is not guaranteed. So,
* it is typical to call wait inside an infinite loop:
*
*
* try
* {
* while (true)
* lock.wait();
* }
* catch (InterruptedException e)
* {
* }
*
*
* @throws IllegalMonitorStateException if this Thread
* does not own a lock on this Object
* @throws InterruptedException if some other Thread
* interrupts this Thread
* @see #notify()
* @see #notifyAll()
* @see #wait(long)
* @see #wait(long, int)
* @see Thread
*/
public final void wait() throws InterruptedException
{
wait(0, 0);
}
/**
* Waits a specified amount of time (or indefinitely if
* the time specified is 0) for someone to call notify()
* or notifyAll() on this Object, waking up this Thread.
*
* The Thread that calls wait must have a lock on this Object,
* obtained by a synchronized method or statement.
* After calling wait, the thread loses the lock on this
* object until the method completes (abruptly or normally),
* at which time it regains the lock. All locks held on
* other objects remain in force, even though the thread is
* inactive. Therefore, caution must be used to avoid deadlock.
*
*
Usually, this call will complete normally if the time * expires, or abruptly with {@link InterruptedException} * if another thread called notify, but neither result * is guaranteed. * *
The waiting period is only *roughly* the amount of time
* you requested. It cannot be exact because of the overhead
* of the call itself. Most Virtual Machiness treat the
* argument as a lower limit on the time spent waiting, but
* even that is not guaranteed. Besides, some other thread
* may hold the lock on the object when the time expires, so
* the current thread may still have to wait to reobtain the
* lock.
*
* @param timeout the minimum number of milliseconds to wait (1000
* milliseconds = 1 second), or 0 for an indefinite wait
* @throws IllegalArgumentException if ms < 0
* @throws IllegalMonitorStateException if this Thread
* does not own a lock on this Object
* @throws InterruptedException if some other Thread
* interrupts this Thread
* @see #notify()
* @see #notifyAll()
* @see #wait()
* @see #wait(long, int)
* @see Thread
*/
public final void wait(long timeout) throws InterruptedException
{
wait(timeout, 0);
}
/**
* This method may be called to create a new copy of the
* Object. The typical behavior is as follows:
*
o == o.clone() is falseo.getClass() == o.clone().getClass()
* is trueo.equals(o) is trueHowever, these are not strict requirements, and may * be violated if necessary. Of the three requirements, the * last is the most commonly violated, particularly if the * subclass does not override {@link #equals(Object)}. * *
If the Object you call clone() on does not implement * {@link Cloneable} (which is a placeholder interface), then * a CloneNotSupportedException is thrown. Notice that * Object does not implement Cloneable; this method exists * as a convenience for subclasses that do. * *
Object's implementation of clone allocates space for the * new Object using the correct class, without calling any * constructors, and then fills in all of the new field values * with the old field values. Thus, it is a shallow copy. * However, subclasses are permitted to make a deep copy. * *
All array types implement Cloneable, and override
* this method as follows (it should never fail):
*
* public Object clone()
* {
* try
* {
* super.clone();
* }
* catch (CloneNotSupportedException e)
* {
* throw new InternalError(e.getMessage());
* }
* }
*
*
* @return a copy of the Object
* @throws CloneNotSupportedException If this Object does not
* implement Cloneable
* @throws OutOfMemoryError Since cloning involves memory allocation,
* even though it may bypass constructors, you might run
* out of memory
* @see Cloneable
*/
protected native Object clone() throws CloneNotSupportedException;
// This initializes the sync_info member. It is here for
// completeness (some day we'll be able to auto-generate Object.h).
private final native void sync_init();
// Note that we don't mention the sync_info field here. If we do,
// jc1 will not work correctly.
}