/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/*
* Copyright (C) 2008 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package java.lang;
/**
* The root class of the Java class hierarchy. All non-primitive types
* (including arrays) inherit either directly or indirectly from this class.
* <p>
* {@code Object} provides some fundamental methods for accessing the
* {@link Class} of an object, getting its {@link #hashCode()}, or checking
* whether one object {@link #equals(Object)} another. The {@link #toString()}
* method can be used to convert an object reference into a printable string and
* is often overridden in subclasses.
* <p>
* The {@link #wait()} and {@link #notify()} methods provide a foundation for
* synchronization, acquiring and releasing an internal monitor associated with
* each {@code Object}.
*
* @since Android 1.0
*/
public class Object {
/**
* Constructs a new instance of {@code Object}.
*
* @since Android 1.0
*/
public Object() {
}
/**
* Creates and returns a copy of this {@code Object}. The default
* implementation returns a so-called "shallow" copy: It creates a new
* instance of the same class and then copies the field values (including
* object references) from this instance to the new instance. A "deep" copy,
* in contrast, would also recursively clone nested objects. A subclass that
* needs to implement this kind of cloning should call {@code super.clone()}
* to create the new instance and then create deep copies of the nested,
* mutable objects.
*
* @return a copy of this object.
* @throws CloneNotSupportedException
* if this object's class does not implement the {@code
* Cloneable} interface.
* @since Android 1.0
*/
protected Object clone() throws CloneNotSupportedException {
if (!(this instanceof Cloneable)) {
throw new CloneNotSupportedException("Class doesn't implement Cloneable");
}
return internalClone((Cloneable) this);
}
/*
* Native helper method for cloning.
*/
private native Object internalClone(Cloneable o);
/**
* Compares this instance with the specified object and indicates if they
* are equal. In order to be equal, {@code o} must represent the same object
* as this instance using a class-specific comparison. The general contract
* is that this comparison should be both transitive and reflexive.
* <p>
* The implementation in {@code Object} returns {@code true} only if {@code
* o} is the exact same object as the receiver (using the == operator for
* comparison). Subclasses often implement {@code equals(Object)} so that
* it takes into account the two object's types and states.
* </p>
* <p>
* The general contract for the {@code equals(Object)} and {@link
* #hashCode()} methods is that if {@code equals} returns {@code true} for
* any two objects, then {@code hashCode()} must return the same value for
* these objects. This means that subclasses of {@code Object} usually
* override either both methods or none of them.
* </p>
*
* @param o
* the object to compare this instance with.
* @return {@code true} if the specified object is equal to this {@code
* Object}; {@code false} otherwise.
* @see #hashCode
* @since Android 1.0
*/
public boolean equals(Object o) {
return this == o;
}
/**
* Is called before the object's memory is being reclaimed by the VM. This
* can only happen once the VM has detected, during a run of the garbage
* collector, that the object is no longer reachable by any thread of the
* running application.
* <p>
* The method can be used to free system resources or perform other cleanup
* before the object is garbage collected. The default implementation of the
* method is empty, which is also expected by the VM, but subclasses can
* override {@code finalize()} as required. Uncaught exceptions which are
* thrown during the execution of this method cause it to terminate
* immediately but are otherwise ignored.
* <p>
* Note that the VM does guarantee that {@code finalize()} is called at most
* once for any object, but it doesn't guarantee when (if at all) {@code
* finalize()} will be called. For example, object B's {@code finalize()}
* can delay the execution of object A's {@code finalize()} method and
* therefore it can delay the reclamation of A's memory. To be safe, use a
* {@link java.lang.ref.ReferenceQueue}, because it provides more control
* over the way the VM deals with references during garbage collection.
* </p>
*
* @throws Throwable
* any exception which is raised during finalization; these are
* ignored by the virtual machine.
* @since Android 1.0
*/
protected void finalize() throws Throwable {
}
/**
* Returns the unique instance of {@link Class} which represents this
* object's class. Note that {@code getClass()} is a special case in that it
* actually returns {@code Class<? extends Foo>} where {@code Foo} is the
* erasure of the type of expression {@code getClass()} was called upon.
* <p>
* As an example, the following code actually compiles, although one might
* think it shouldn't:
* <p>
* <pre>
* List<Integer> l = new ArrayList<Integer>();
* Class<? extends List> c = l.getClass();
* </pre>
*
* @return this object's {@code Class} instance.
* @since Android 1.0
*/
public final native Class<? extends Object> getClass();
/**
* Returns an integer hash code for this object. By contract, any two
* objects for which {@code equals(Object)} returns {@code true} must return
* the same hash code value. This means that subclasses of {@code Object}
* usually override both methods or neither method.
*
* @return this object's hash code.
* @see #equals
* @since Android 1.0
*/
public native int hashCode();
/**
* Causes a thread which is waiting on this object's monitor (by means of
* calling one of the {@code wait()} methods) to be woken up. If more than
* one thread is waiting, one of them is chosen at the discretion of the
* virtual machine. The chosen thread will not run immediately. The thread
* that called {@code notify()} has to release the object's monitor first.
* Also, the chosen thread still has to compete against other threads that
* try to synchronize on the same object.
* <p>
* This method can only be invoked by a thread which owns this object's
* monitor. A thread becomes owner of an object's monitor
* </p>
* <ul>
* <li>by executing a synchronized method of that object;</li>
* <li>by executing the body of a {@code synchronized} statement that
* synchronizes on the object;</li>
* <li>by executing a synchronized static method if the object is of type
* {@code Class}.</li>
* </ul>
*
* @see #notifyAll
* @see #wait()
* @see #wait(long)
* @see #wait(long,int)
* @see java.lang.Thread
* @since Android 1.0
*/
public final native void notify();
/**
* Causes all threads which are waiting on this object's monitor (by means
* of calling one of the {@code wait()} methods) to be woken up. The threads
* will not run immediately. The thread that called {@code notify()} has to
* release the object's monitor first. Also, the threads still have to
* compete against other threads that try to synchronize on the same object.
* <p>
* This method can only be invoked by a thread which owns this object's
* monitor. A thread becomes owner of an object's monitor
* </p>
* <ul>
* <li>by executing a synchronized method of that object;</li>
* <li>by executing the body of a {@code synchronized} statement that
* synchronizes on the object;</li>
* <li>by executing a synchronized static method if the object is of type
* {@code Class}.</li>
* </ul>
*
* @throws IllegalMonitorStateException
* if the thread calling this method is not the owner of this
* object's monitor.
* @see #notify
* @see #wait()
* @see #wait(long)
* @see #wait(long,int)
* @see java.lang.Thread
*/
public final native void notifyAll();
/**
* Returns a string containing a concise, human-readable description of this
* object. Subclasses are encouraged to override this method and provide an
* implementation that takes into account the object's type and data. The
* default implementation simply concatenates the class name, the '@' sign
* and a hexadecimal representation of the object's {@link #hashCode()},
* that is, it is equivalent to the following expression:
*
* <pre>
* getClass().getName() + '@' + Integer.toHexString(hashCode())
* </pre>
*
* @return a printable representation of this object.
* @since Android 1.0
*/
public String toString() {
return getClass().getName() + '@' + Integer.toHexString(hashCode());
}
/**
* Causes the calling thread to wait until another thread calls the {@code
* notify()} or {@code notifyAll()} method of this object. This method can
* only be invoked by a thread which owns this object's monitor; see
* {@link #notify()} on how a thread can become the owner of a monitor.
* <p>
* A waiting thread can be sent {@code interrupt()} to cause it to
* prematurely stop waiting, so {@code wait} should be called in a loop to
* check that the condition that has been waited for has been met before
* continuing.
* </p>
* <p>
* While the thread waits, it gives up ownership of this object's monitor.
* When it is notified (or interrupted), it re-acquires the monitor before
* it starts running.
* </p>
*
* @throws IllegalMonitorStateException
* if the thread calling this method is not the owner of this
* object's monitor.
* @throws InterruptedException
* if another thread interrupts this thread while it is waiting.
* @see #notify
* @see #notifyAll
* @see #wait(long)
* @see #wait(long,int)
* @see java.lang.Thread
* @since Android 1.0
*/
public final void wait() throws InterruptedException {
wait(0 ,0);
}
/**
* Causes the calling thread to wait until another thread calls the {@code
* notify()} or {@code notifyAll()} method of this object or until the
* specified timeout expires. This method can only be invoked by a thread
* which owns this object's monitor; see {@link #notify()} on how a thread
* can become the owner of a monitor.
* <p>
* A waiting thread can be sent {@code interrupt()} to cause it to
* prematurely stop waiting, so {@code wait} should be called in a loop to
* check that the condition that has been waited for has been met before
* continuing.
* </p>
* <p>
* While the thread waits, it gives up ownership of this object's monitor.
* When it is notified (or interrupted), it re-acquires the monitor before
* it starts running.
* </p>
*
* @param millis
* the maximum time to wait in milliseconds.
* @throws IllegalArgumentException
* if {@code millis < 0}.
* @throws IllegalMonitorStateException
* if the thread calling this method is not the owner of this
* object's monitor.
* @throws InterruptedException
* if another thread interrupts this thread while it is waiting.
* @see #notify
* @see #notifyAll
* @see #wait()
* @see #wait(long,int)
* @see java.lang.Thread
* @since Android 1.0
*/
public final void wait(long millis) throws InterruptedException {
wait(millis, 0);
}
/**
* Causes the calling thread to wait until another thread calls the {@code
* notify()} or {@code notifyAll()} method of this object or until the
* specified timeout expires. This method can only be invoked by a thread
* that owns this object's monitor; see {@link #notify()} on how a thread
* can become the owner of a monitor.
* <p>
* A waiting thread can be sent {@code interrupt()} to cause it to
* prematurely stop waiting, so {@code wait} should be called in a loop to
* check that the condition that has been waited for has been met before
* continuing.
* </p>
* <p>
* While the thread waits, it gives up ownership of this object's monitor.
* When it is notified (or interrupted), it re-acquires the monitor before
* it starts running.
* </p>
*
* @param millis
* the maximum time to wait in milliseconds.
* @param nanos
* the fraction of a millisecond to wait, specified in
* nanoseconds.
* @throws IllegalArgumentException
* if {@code millis < 0}, {@code nanos < 0} or {@code nanos >
* 999999}.
* @throws IllegalMonitorStateException
* if the thread calling this method is not the owner of this
* object's monitor.
* @throws InterruptedException
* if another thread interrupts this thread while it is waiting.
* @see #notify
* @see #notifyAll
* @see #wait()
* @see #wait(long,int)
* @see java.lang.Thread
* @since Android 1.0
*/
public final native void wait(long millis, int nanos) throws InterruptedException;
}