From 0b4349327228aa12a34dbb4d940ee313a488d327 Mon Sep 17 00:00:00 2001 From: Michael Koch Date: Tue, 16 Nov 2004 21:37:29 +0000 Subject: [PATCH] Object.java: Added javadocs all over (merged from GNU classpath). 2004-11-16 Michael Koch * java/lang/Object.java: Added javadocs all over (merged from GNU classpath). From-SVN: r90766 --- libjava/ChangeLog | 5 + libjava/java/lang/Object.java | 449 ++++++++++++++++++++++++++++++++-- 2 files changed, 435 insertions(+), 19 deletions(-) diff --git a/libjava/ChangeLog b/libjava/ChangeLog index 1f649b3a1ed..dace13d9a53 100644 --- a/libjava/ChangeLog +++ b/libjava/ChangeLog @@ -1,3 +1,8 @@ +2004-11-16 Michael Koch + + * java/lang/Object.java: Added javadocs all over (merged from GNU + classpath). + 2004-11-16 Andreas Tobler * java/security/Security.java (Security): Silence the warning about no diff --git a/libjava/java/lang/Object.java b/libjava/java/lang/Object.java index 0c96b88cf26..4eee4510f45 100644 --- a/libjava/java/lang/Object.java +++ b/libjava/java/lang/Object.java @@ -39,11 +39,6 @@ exception statement from your version. */ package java.lang; -/** - * @author Tom Tromey - * @date September 30, 1998 - */ - /* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3 * "The Java Language Specification", ISBN 0-201-63451-1 * plus online API docs for JDK 1.2 beta from http://www.javasoft.com. @@ -51,49 +46,465 @@ package java.lang; * Status: Complete to version 1.1 */ +/** + * Object is the ultimate superclass of every class + * (excepting interfaces). When you define a class that + * does not extend any other class, it implicitly extends + * java.lang.Object. Also, an anonymous class based on + * an interface will extend Object. + * + *

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 { } - public final native Class getClass (); - public native int hashCode (); - public final native void notify (); - public final native void notifyAll (); - public final native void wait (long timeout, int nanos) + /** + * 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:
+ * + *

    + *
  • Semantic equality implies identical hashcodes. In other + * words, if 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.
    • + *
  • It must be consistent. Whichever value o.hashCode() + * returns on the first invocation must be the value + * returned on all later invocations as long as the object + * exists. Notice, however, that the result of hashCode may + * change between separate executions of a Virtual Machine, + * because it is not invoked on the same object.
    • + *
+ * + *

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; - public boolean equals (Object obj) + /** + * Determine whether this Object is semantically equal + * to another Object. + * + *

There are some fairly strict requirements on this + * method which subclasses must follow:
+ *

    + *
  • It must be transitive. If a.equals(b) and + * b.equals(c), then a.equals(c) + * must be true as well.
    • + *
  • It must be symmetric. a.equals(b) and + * b.equals(a) must have the same value.
    • + *
  • It must be reflexive. a.equals(a) must + * always be true.
    • + *
  • It must be consistent. Whichever value a.equals(b) + * returns on the first invocation must be the value + * returned on all later invocations.
    • + *
  • a.equals(null) must be false.
    • + *
  • It must be consistent with hashCode(). That is, + * 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; } - public Object () + /** + * 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() { } - public String toString () + /** + * 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()); } - public final void wait () throws InterruptedException + /** + * 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); + wait(0, 0); } - public final void wait (long timeout) throws InterruptedException + /** + * 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); + wait(timeout, 0); } - protected native Object clone () throws CloneNotSupportedException; + /** + * This method may be called to create a new copy of the + * Object. The typical behavior is as follows:
+ *

    + *
  • o == o.clone() is false
    • + *
  • o.getClass() == o.clone().getClass() + * is true
    • + *
  • o.equals(o) is true
    • + *
+ * + *

However, 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 (); + 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.