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