--- old/src/share/classes/java/lang/Object.java Thu Jan 29 09:05:07 2009 +++ new/src/share/classes/java/lang/Object.java Thu Jan 29 09:05:06 2009 @@ -26,8 +26,8 @@ package java.lang; /** - * Class Object is the root of the class hierarchy. - * Every class has Object as a superclass. All objects, + * Class {@code Object} is the root of the class hierarchy. + * Every class has {@code Object} as a superclass. All objects, * including arrays, implement the methods of this class. * * @author unascribed @@ -66,30 +66,30 @@ /** * Returns a hash code value for the object. This method is - * supported for the benefit of hashtables such as those provided by - * java.util.Hashtable. + * supported for the benefit of hash tables such as those provided by + * {@link java.util.HashMap}. *

- * The general contract of hashCode is: + * The general contract of {@code hashCode} is: *

*

* As much as is reasonably practical, the hashCode method defined by - * class Object does return distinct integers for distinct + * class {@code Object} does return distinct integers for distinct * objects. (This is typically implemented by converting the internal * address of the object into an integer, but this implementation * technique is not required by the @@ -97,7 +97,7 @@ * * @return a hash code value for this object. * @see java.lang.Object#equals(java.lang.Object) - * @see java.util.Hashtable + * @see java.lang.System#identityHashCode */ public native int hashCode(); @@ -104,48 +104,48 @@ /** * Indicates whether some other object is "equal to" this one. *

- * The equals method implements an equivalence relation + * The {@code equals} method implements an equivalence relation * on non-null object references: *

*

- * The equals method for class Object implements + * The {@code equals} method for class {@code Object} implements * the most discriminating possible equivalence relation on objects; - * that is, for any non-null reference values x and - * y, this method returns true if and only - * if x and y refer to the same object - * (x == y has the value true). + * that is, for any non-null reference values {@code x} and + * {@code y}, this method returns {@code true} if and only + * if {@code x} and {@code y} refer to the same object + * ({@code x == y} has the value {@code true}). *

- * Note that it is generally necessary to override the hashCode + * Note that it is generally necessary to override the {@code hashCode} * method whenever this method is overridden, so as to maintain the - * general contract for the hashCode method, which states + * general contract for the {@code hashCode} method, which states * that equal objects must have equal hash codes. * * @param obj the reference object with which to compare. - * @return true if this object is the same as the obj - * argument; false otherwise. + * @return {@code true} if this object is the same as the obj + * argument; {@code false} otherwise. * @see #hashCode() - * @see java.util.Hashtable + * @see java.util.HashMap */ public boolean equals(Object obj) { return (this == obj); @@ -154,7 +154,7 @@ /** * Creates and returns a copy of this object. The precise meaning * of "copy" may depend on the class of the object. The general - * intent is that, for any object x, the expression: + * intent is that, for any object {@code x}, the expression: *

* 
      * x.clone() != x
@@ -162,34 +162,34 @@ *
* 
      * x.clone().getClass() == x.getClass()
- * will be true, but these are not absolute requirements. + * will be {@code true}, but these are not absolute requirements. * While it is typically the case that: *
* 
      * x.clone().equals(x)
- * will be true, this is not an absolute requirement. + * will be {@code true}, this is not an absolute requirement. *

* By convention, the returned object should be obtained by calling - * super.clone. If a class and all of its superclasses (except - * Object) obey this convention, it will be the case that - * x.clone().getClass() == x.getClass(). + * {@code super.clone}. If a class and all of its superclasses (except + * {@code Object}) obey this convention, it will be the case that + * {@code x.clone().getClass() == x.getClass()}. *

* By convention, the object returned by this method should be independent * of this object (which is being cloned). To achieve this independence, * it may be necessary to modify one or more fields of the object returned - * by super.clone before returning it. Typically, this means + * by {@code super.clone} before returning it. Typically, this means * copying any mutable objects that comprise the internal "deep structure" * of the object being cloned and replacing the references to these * objects with references to the copies. If a class contains only * primitive fields or references to immutable objects, then it is usually - * the case that no fields in the object returned by super.clone + * the case that no fields in the object returned by {@code super.clone} * need to be modified. *

- * The method clone for class Object performs a + * The method {@code clone} for class {@code Object} performs a * specific cloning operation. First, if the class of this object does - * not implement the interface Cloneable, then a - * CloneNotSupportedException is thrown. Note that all arrays - * are considered to implement the interface Cloneable. + * not implement the interface {@code Cloneable}, then a + * {@code CloneNotSupportedException} is thrown. Note that all arrays + * are considered to implement the interface {@code Cloneable}. * Otherwise, this method creates a new instance of the class of this * object and initializes all its fields with exactly the contents of * the corresponding fields of this object, as if by assignment; the @@ -196,15 +196,15 @@ * contents of the fields are not themselves cloned. Thus, this method * performs a "shallow copy" of this object, not a "deep copy" operation. *

- * The class Object does not itself implement the interface - * Cloneable, so calling the clone method on an object - * whose class is Object will result in throwing an + * The class {@code Object} does not itself implement the interface + * {@code Cloneable}, so calling the {@code clone} method on an object + * whose class is {@code Object} will result in throwing an * exception at run time. * * @return a clone of this instance. * @exception CloneNotSupportedException if the object's class does not - * support the Cloneable interface. Subclasses - * that override the clone method can also + * support the {@code Cloneable} interface. Subclasses + * that override the {@code clone} method can also * throw this exception to indicate that an instance cannot * be cloned. * @see java.lang.Cloneable @@ -213,15 +213,15 @@ /** * Returns a string representation of the object. In general, the - * toString method returns a string that + * {@code toString} method returns a string that * "textually represents" this object. The result should * be a concise but informative representation that is easy for a * person to read. * It is recommended that all subclasses override this method. *

- * The toString method for class Object + * The {@code toString} method for class {@code Object} * returns a string consisting of the name of the class of which the - * object is an instance, the at-sign character `@', and + * object is an instance, the at-sign character `{@code @}', and * the unsigned hexadecimal representation of the hash code of the * object. In other words, this method returns a string equal to the * value of: @@ -241,7 +241,7 @@ * monitor. If any threads are waiting on this object, one of them * is chosen to be awakened. The choice is arbitrary and occurs at * the discretion of the implementation. A thread waits on an object's - * monitor by calling one of the wait methods. + * monitor by calling one of the {@code wait} methods. *

* The awakened thread will not be able to proceed until the current * thread relinquishes the lock on this object. The awakened thread will @@ -255,9 +255,9 @@ * object's monitor in one of three ways: *

*

@@ -273,7 +273,7 @@ /** * Wakes up all threads that are waiting on this object's monitor. A * thread waits on an object's monitor by calling one of the - * wait methods. + * {@code wait} methods. *

* The awakened threads will not be able to proceed until the current * thread relinquishes the lock on this object. The awakened threads @@ -283,7 +283,7 @@ * being the next thread to lock this object. *

* This method should only be called by a thread that is the owner - * of this object's monitor. See the notify method for a + * of this object's monitor. See the {@code notify} method for a * description of the ways in which a thread can become the owner of * a monitor. * @@ -308,15 +308,15 @@ * becomes disabled for thread scheduling purposes and lies dormant * until one of four things happens: *

* The thread T is then removed from the wait set for this @@ -324,11 +324,11 @@ * usual manner with other threads for the right to synchronize on the * object; once it has gained control of the object, all its * synchronization claims on the object are restored to the status quo - * ante - that is, to the situation as of the time that the wait + * ante - that is, to the situation as of the time that the {@code wait} * method was invoked. Thread T then returns from the - * invocation of the wait method. Thus, on return from the - * wait method, the synchronization state of the object and of - * thread T is exactly as it was when the wait method + * invocation of the {@code wait} method. Thus, on return from the + * {@code wait} method, the synchronization state of the object and of + * thread {@code T} is exactly as it was when the {@code wait} method * was invoked. *

* A thread can also wake up without being notified, interrupted, or @@ -351,18 +351,18 @@ * *

If the current thread is {@linkplain java.lang.Thread#interrupt() * interrupted} by any thread before or while it is waiting, then an - * InterruptedException is thrown. This exception is not + * {@code InterruptedException} is thrown. This exception is not * thrown until the lock status of this object has been restored as * described above. * *

- * Note that the wait method, as it places the current thread + * Note that the {@code wait} method, as it places the current thread * into the wait set for this object, unlocks only this object; any * other objects on which the current thread may be synchronized remain * locked while the thread waits. *

* This method should only be called by a thread that is the owner - * of this object's monitor. See the notify method for a + * of this object's monitor. See the {@code notify} method for a * description of the ways in which a thread can become the owner of * a monitor. * @@ -388,7 +388,7 @@ * some other thread interrupts the current thread, or a certain * amount of real time has elapsed. *

- * This method is similar to the wait method of one + * This method is similar to the {@code wait} method of one * argument, but it allows finer control over the amount of time to * wait for a notification before giving up. The amount of real time, * measured in nanoseconds, is given by: @@ -398,7 +398,7 @@ *

* In all other respects, this method does the same thing as the * method {@link #wait(long)} of one argument. In particular, - * wait(0, 0) means the same thing as wait(0). + * {@code wait(0, 0)} means the same thing as {@code wait(0)}. *

* The current thread must own this object's monitor. The thread * releases ownership of this monitor and waits until either of the @@ -405,10 +405,10 @@ * following two conditions has occurred: *

*

@@ -425,7 +425,7 @@ * } * * This method should only be called by a thread that is the owner - * of this object's monitor. See the notify method for a + * of this object's monitor. See the {@code notify} method for a * description of the ways in which a thread can become the owner of * a monitor. * @@ -465,13 +465,13 @@ * {@link java.lang.Object#notify()} method or the * {@link java.lang.Object#notifyAll()} method for this object. * In other words, this method behaves exactly as if it simply - * performs the call wait(0). + * performs the call {@code wait(0)}. *

* The current thread must own this object's monitor. The thread * releases ownership of this monitor and waits until another thread * notifies threads waiting on this object's monitor to wake up - * either through a call to the notify method or the - * notifyAll method. The thread then waits until it can + * either through a call to the {@code notify} method or the + * {@code notifyAll} method. The thread then waits until it can * re-obtain ownership of the monitor and resumes execution. *

* As in the one argument version, interrupts and spurious wakeups are @@ -484,7 +484,7 @@ * } * * This method should only be called by a thread that is the owner - * of this object's monitor. See the notify method for a + * of this object's monitor. See the {@code notify} method for a * description of the ways in which a thread can become the owner of * a monitor. * @@ -505,35 +505,35 @@ /** * Called by the garbage collector on an object when garbage collection * determines that there are no more references to the object. - * A subclass overrides the finalize method to dispose of + * A subclass overrides the {@code finalize} method to dispose of * system resources or to perform other cleanup. *

- * The general contract of finalize is that it is invoked + * The general contract of {@code finalize} is that it is invoked * if and when the JavaTM virtual * machine has determined that there is no longer any * means by which this object can be accessed by any thread that has * not yet died, except as a result of an action taken by the * finalization of some other object or class which is ready to be - * finalized. The finalize method may take any action, including + * finalized. The {@code finalize} method may take any action, including * making this object available again to other threads; the usual purpose - * of finalize, however, is to perform cleanup actions before + * of {@code finalize}, however, is to perform cleanup actions before * the object is irrevocably discarded. For example, the finalize method * for an object that represents an input/output connection might perform * explicit I/O transactions to break the connection before the object is * permanently discarded. *

- * The finalize method of class Object performs no + * The {@code finalize} method of class {@code Object} performs no * special action; it simply returns normally. Subclasses of - * Object may override this definition. + * {@code Object} may override this definition. *

* The Java programming language does not guarantee which thread will - * invoke the finalize method for any given object. It is + * invoke the {@code finalize} method for any given object. It is * guaranteed, however, that the thread that invokes finalize will not * be holding any user-visible synchronization locks when finalize is * invoked. If an uncaught exception is thrown by the finalize method, * the exception is ignored and finalization of that object terminates. *

- * After the finalize method has been invoked for an object, no + * After the {@code finalize} method has been invoked for an object, no * further action is taken until the Java virtual machine has again * determined that there is no longer any means by which this object can * be accessed by any thread that has not yet died, including possible @@ -540,14 +540,14 @@ * actions by other objects or classes which are ready to be finalized, * at which point the object may be discarded. *

- * The finalize method is never invoked more than once by a Java + * The {@code finalize} method is never invoked more than once by a Java * virtual machine for any given object. *

- * Any exception thrown by the finalize method causes + * Any exception thrown by the {@code finalize} method causes * the finalization of this object to be halted, but is otherwise * ignored. * - * @throws Throwable the Exception raised by this method + * @throws Throwable the {@code Exception} raised by this method */ protected void finalize() throws Throwable { } }