home *** CD-ROM | disk | FTP | other *** search
/ Java 1.2 How-To / JavaHowTo.iso / 3rdParty / jbuilder / unsupported / JDK1.2beta3 / SOURCE / SRC.ZIP / java / lang / Object.java < prev    next >
Encoding:
Java Source  |  1998-03-20  |  13.5 KB  |  323 lines
  1. /*
  2.  * @(#)Object.java    1.42 98/03/18
  3.  *
  4.  * Copyright 1994-1997 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.lang;
  16.  
  17. /**
  18.  * Class <code>Object</code> is the root of the class hierarchy. 
  19.  * Every class has <code>Object</code> as a superclass. All objects, 
  20.  * including arrays, implement the methods of this class. 
  21.  *
  22.  * @author  unascribed
  23.  * @version 1.42, 03/18/98
  24.  * @see     java.lang.Class
  25.  * @since   JDK1.0
  26.  */
  27. public class Object {
  28.  
  29.     private static native void registerNatives();
  30.     static {
  31.         registerNatives();
  32.     }
  33.  
  34.     /**
  35.      * Returns the runtime class of an object. 
  36.      *
  37.      * @return  the object of type <code>Class</code> that represents the
  38.      *          runtime class of the object.
  39.      */
  40.     public final native Class getClass();
  41.  
  42.     /**
  43.      * Returns a hash code value for the object. This method is 
  44.      * supported for the benefit of hashtables such as those provided by 
  45.      * <code>java.util.Hashtable</code>. 
  46.      * <p>
  47.      * The general contract of <code>hashCode</code> is: 
  48.      * <ul>
  49.      * <li>Whenever it is invoked on the same object more than once during 
  50.      *     an execution of a Java application, the <code>hashCode</code> method 
  51.      *     must consistently return the same integer. This integer need not 
  52.      *     remain consistent from one execution of an application to another 
  53.      *     execution of the same application. 
  54.      * <li>If two objects are equal according to the <code>equals</code> 
  55.      *     method, then calling the <code>hashCode</code> method on each of the 
  56.      *     two objects must produce the same integer result. 
  57.      * </ul>
  58.      *
  59.      * @return  a hash code value for this object.
  60.      * @see     java.lang.Object#equals(java.lang.Object)
  61.      * @see     java.util.Hashtable
  62.      */
  63.     public native int hashCode();
  64.  
  65.     /**
  66.      * Compares two Objects for equality.
  67.      * <p>
  68.      * The <code>equals</code> method implements an equivalence relation: 
  69.      * <ul>
  70.      * <li>It is <i>reflexive</i>: for any reference value <code>x</code>, 
  71.      *     <code>x.equals(x)</code> should return <code>true</code>. 
  72.      * <li>It is <i>symmetric</i>: for any reference values <code>x</code> and 
  73.      *     <code>y</code>, <code>x.equals(y)</code> should return 
  74.      *     <code>true</code> if and only if <code>y.equals(x)</code> returns 
  75.      *     <code>true</code>. 
  76.      * <li>It is <i>transitive</i>: for any reference values <code>x</code>, 
  77.      *     <code>y</code>, and <code>z</code>, if <code>x.equals(y)</code>
  78.      *     returns  <code>true</code> and <code>y.equals(z)</code> returns 
  79.      *     <code>true</code>, then <code>x.equals(z)</code> should return 
  80.      *     <code>true</code>. 
  81.      * <li>It is <i>consistent</i>: for any reference values <code>x</code> 
  82.      *     and <code>y</code>, multiple invocations of <code>x.equals(y)</code> 
  83.      *     consistently return <code>true</code> or consistently return 
  84.      *     <code>false</code>. 
  85.      * <li>For any reference value <code>x</code>, <code>x.equals(null)</code> 
  86.      *     should return <code>false</code>.
  87.      * </ul>
  88.      * <p>
  89.      * The equals method for class <code>Object</code> implements the most 
  90.      * discriminating possible equivalence relation on objects; that is, 
  91.      * for any reference values <code>x</code> and <code>y</code>, this 
  92.      * method returns <code>true</code> if and only if <code>x</code> and 
  93.      * <code>y</code> refer to the same object (<code>x==y</code> has the 
  94.      * value <code>true</code>). 
  95.      *
  96.      * @param   obj   the reference object with which to compare.
  97.      * @return  <code>true</code> if this object is the same as the obj
  98.      *          argument; <code>false</code> otherwise.
  99.      * @see     java.lang.Boolean#hashCode()
  100.      * @see     java.util.Hashtable
  101.      */
  102.     public boolean equals(Object obj) {
  103.     return (this == obj);
  104.     }
  105.  
  106.     /**
  107.      * Creates a new object of the same class as this object. It then 
  108.      * initializes each of the new object's fields by assigning it the 
  109.      * same value as the corresponding field in this object. No 
  110.      * constructor is called. 
  111.      * <p>
  112.      * The <code>clone</code> method of class <code>Object</code> will 
  113.      * only clone an object whose class indicates that it is willing for 
  114.      * its instances to be cloned. A class indicates that its instances 
  115.      * can be cloned by declaring that it implements the 
  116.      * <code>Cloneable</code> interface. 
  117.      *
  118.      * @return     a clone of this instance.
  119.      * @exception  CloneNotSupportedException  if the object's class does not
  120.      *               support the <code>Cloneable</code> interface. Subclasses
  121.      *               that override the <code>clone</code> method can also
  122.      *               throw this exception to indicate that an instance cannot
  123.      *               be cloned.
  124.      * @exception  OutOfMemoryError            if there is not enough memory.
  125.      * @see        java.lang.Cloneable
  126.      */
  127.     protected native Object clone() throws CloneNotSupportedException;
  128.  
  129.     /**
  130.      * Returns a string representation of the object. In general, the 
  131.      * <code>toString</code> method returns a string that 
  132.      * "textually represents" this object. The result should 
  133.      * be a concise but informative representation that is easy for a 
  134.      * person to read.
  135.      * It is recommendedthat all subclasses override this method.
  136.      * <p>
  137.      * The <code>toString</code> method for class <code>Object</code> 
  138.      * returns a string consisting of the name of the class of which the 
  139.      * object is an instance, the at-sign character `<code>@</code>', and 
  140.      * the unsigned hexadecimal representation of the hash code of the 
  141.      * object. 
  142.      *
  143.      * @return  a string representation of the object.
  144.      */
  145.     public String toString() {
  146.     return getClass().getName() + "@" + Integer.toHexString(hashCode());
  147.     }
  148.  
  149.     /**
  150.      * Wakes up a single thread that is waiting on this object's 
  151.      * monitor. A thread waits on an object's monitor by calling one of 
  152.      * the <code>wait</code> methods.
  153.      * <p>
  154.      * This method should only be called by a thread that is the owner 
  155.      * of this object's monitor. A thread becomes the owner of the 
  156.      * object's monitor in one of three ways: 
  157.      * <ul>
  158.      * <li>By executing a synchronized instance method of that object. 
  159.      * <li>By executing the body of a <code>synchronized</code> statement 
  160.      *     that synchronizes on the object. 
  161.      * <li>For objects of type <code>Class,</code> by executing a 
  162.      *     synchronized static method of that class. 
  163.      * </ul>
  164.      * <p>
  165.      * Only one thread at a time can own an object's monitor. 
  166.      *
  167.      * @exception  IllegalMonitorStateException  if the current thread is not
  168.      *               the owner of this object's monitor.
  169.      * @see        java.lang.Object#notifyAll()
  170.      * @see        java.lang.Object#wait()
  171.      */
  172.     public final native void notify();
  173.  
  174.     /**
  175.      * Wakes up all threads that are waiting on this object's monitor. A 
  176.      * thread waits on an object's monitor by calling one of the 
  177.      * <code>wait</code> methods.
  178.      * <p>
  179.      * This method should only be called by a thread that is the owner 
  180.      * of this object's monitor. See the <code>notify</code> method for a 
  181.      * description of the ways in which a thread can become the owner of 
  182.      * a monitor. 
  183.      *
  184.      * @exception  IllegalMonitorStateException  if the current thread is not
  185.      *               the owner of this object's monitor.
  186.      * @see        java.lang.Object#notify()
  187.      * @see        java.lang.Object#wait()
  188.      */
  189.     public final native void notifyAll();
  190.  
  191.     /**
  192.      * Waits to be notified by another thread of a change in this object.
  193.      * <p>
  194.      * The current thread must own this object's monitor. The thread 
  195.      * releases ownership of this monitor and waits until either of the 
  196.      * following two conditions has occurred: 
  197.      * <ul>
  198.      * <li>Another thread notifies threads waiting on this object's monitor 
  199.      *     to wake up either through a call to the <code>notify</code> method 
  200.      *     or the <code>notifyAll</code> method. 
  201.      * <li>The timeout period, specified by the <code>timeout</code> 
  202.      *     argument in milliseconds, has elapsed. 
  203.      * </ul>
  204.      * <p>
  205.      * The thread then waits until it can re-obtain ownership of the 
  206.      * monitor and resumes execution. 
  207.      * <p>
  208.      * This method should only be called by a thread that is the owner 
  209.      * of this object's monitor. See the <code>notify</code> method for a 
  210.      * description of the ways in which a thread can become the owner of 
  211.      * a monitor. 
  212.      *
  213.      * @param      timeout   the maximum time to wait in milliseconds.
  214.      * @exception  IllegalArgumentException      if the value of timeout is
  215.      *             negative.
  216.      * @exception  IllegalMonitorStateException  if the current thread is not
  217.      *               the owner of the object's monitor.
  218.      * @exception  InterruptedException          if another thread has
  219.      *               interrupted this thread.
  220.      * @see        java.lang.Object#notify()
  221.      * @see        java.lang.Object#notifyAll()
  222.      */
  223.     public final native void wait(long timeout) throws InterruptedException;
  224.  
  225.     /**
  226.      * Waits to be notified by another thread of a change in this object.
  227.      * <p>
  228.      * This method is similar to the <code>wait</code> method of one 
  229.      * argument, but it allows finer control over the amount of time to 
  230.      * wait for a notification before giving up. 
  231.      * <p>
  232.      * The current thread must own this object's monitor. The thread 
  233.      * releases ownership of this monitor and waits until either of the 
  234.      * following two conditions has occurred: 
  235.      * <ul>
  236.      * <li>Another thread notifies threads waiting on this object's monitor 
  237.      *     to wake up either through a call to the <code>notify</code> method 
  238.      *     or the <code>notifyAll</code> method. 
  239.      * <li>The timeout period, specified by <code>timeout</code> 
  240.      *     milliseconds plus <code>nanos</code> nanoseconds arguments, has 
  241.      *     elapsed. 
  242.      * </ul>
  243.      * <p>
  244.      * The thread then waits until it can re-obtain ownership of the 
  245.      * monitor and resumes execution 
  246.      * <p>
  247.      * This method should only be called by a thread that is the owner 
  248.      * of this object's monitor. See the <code>notify</code> method for a 
  249.      * description of the ways in which a thread can become the owner of 
  250.      * a monitor. 
  251.      *
  252.      * @param      timeout   the maximum time to wait in milliseconds.
  253.      * @param      nano      additional time, in nanoseconds range
  254.      *                       0-999999.
  255.      * @exception  IllegalArgumentException      if the value of timeout is
  256.      *                negative or the value of nanos is
  257.      *                not in the range 0-999999.
  258.      * @exception  IllegalMonitorStateException  if the current thread is not
  259.      *               the owner of this object's monitor.
  260.      * @exception  InterruptedException          if another thread has
  261.      *               interrupted this thread.
  262.      */
  263.     public final void wait(long timeout, int nanos) throws InterruptedException {
  264.         if (timeout < 0) {
  265.             throw new IllegalArgumentException("timeout value is negative");
  266.         }
  267.  
  268.         if (nanos < 0 || nanos > 999999) {
  269.             throw new IllegalArgumentException(
  270.                 "nanosecond timeout value out of range");
  271.         }
  272.  
  273.     if (nanos >= 500000 || (nanos != 0 && timeout == 0)) {
  274.         timeout++;
  275.     }
  276.  
  277.     wait(timeout);
  278.     }
  279.  
  280.     /**
  281.      * Waits to be notified by another thread of a change in this object. 
  282.      * <p>
  283.      * The current thread must own this object's monitor. The thread 
  284.      * releases ownership of this monitor and waits until another thread 
  285.      * notifies threads waiting on this object's monitor to wake up 
  286.      * either through a call to the <code>notify</code> method or the 
  287.      * <code>notifyAll</code> method. The thread then waits until it can 
  288.      * re-obtain ownership of the monitor and resumes execution. 
  289.      * <p>
  290.      * This method should only be called by a thread that is the owner 
  291.      * of this object's monitor. See the <code>notify</code> method for a 
  292.      * description of the ways in which a thread can become the owner of 
  293.      * a monitor. 
  294.      *
  295.      * @exception  IllegalMonitorStateException  if the current thread is not
  296.      *               the owner of the object's monitor.
  297.      * @exception  InterruptedException          if another thread has
  298.      *               interrupted this thread.
  299.      * @see        java.lang.Object#notify()
  300.      * @see        java.lang.Object#notifyAll()
  301.      */
  302.     public final void wait() throws InterruptedException {
  303.     wait(0);
  304.     }
  305.  
  306.     /**
  307.      * Called by the garbage collector on an object when garbage collection
  308.      * determines that there are no more references to the object.
  309.      * A subclass overrides the <code>finalize</code> method to dispose of
  310.      * system resources or to perform other cleanup. 
  311.      * <p>
  312.      * Any exception thrown by the <code>finalize</code> method causes 
  313.      * the finalization of this object to be halted, but is otherwise 
  314.      * ignored. 
  315.      * <p>
  316.      * The <code>finalize</code> method in <code>Object</code> does 
  317.      * nothing. 
  318.      *
  319.      * @exception  java.lang.Throwable  [Need description!]
  320.      */
  321.     protected void finalize() throws Throwable { }
  322. }
  323.