1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 /* 18 * Copyright (C) 2008 The Android Open Source Project 19 * 20 * Licensed under the Apache License, Version 2.0 (the "License"); 21 * you may not use this file except in compliance with the License. 22 * You may obtain a copy of the License at 23 * 24 * http://www.apache.org/licenses/LICENSE-2.0 25 * 26 * Unless required by applicable law or agreed to in writing, software 27 * distributed under the License is distributed on an "AS IS" BASIS, 28 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 29 * See the License for the specific language governing permissions and 30 * limitations under the License. 31 */ 32 33 package java.lang; 34 35 /** 36 * The root class of the Java class hierarchy. All non-primitive types 37 * (including arrays) inherit either directly or indirectly from this class. 38 * <p> 39 * {@code Object} provides some fundamental methods for accessing the 40 * {@link Class} of an object, getting its {@link #hashCode()}, or checking 41 * whether one object {@link #equals(Object)} another. The {@link #toString()} 42 * method can be used to convert an object reference into a printable string and 43 * is often overridden in subclasses. 44 * <p> 45 * The {@link #wait()} and {@link #notify()} methods provide a foundation for 46 * synchronization, acquiring and releasing an internal monitor associated with 47 * each {@code Object}. 48 * 49 * @since Android 1.0 50 */ 51 public class Object { 52 53 /** 54 * Constructs a new instance of {@code Object}. 55 * 56 * @since Android 1.0 57 */ Object()58 public Object() { 59 } 60 61 /** 62 * Creates and returns a copy of this {@code Object}. The default 63 * implementation returns a so-called "shallow" copy: It creates a new 64 * instance of the same class and then copies the field values (including 65 * object references) from this instance to the new instance. A "deep" copy, 66 * in contrast, would also recursively clone nested objects. A subclass that 67 * needs to implement this kind of cloning should call {@code super.clone()} 68 * to create the new instance and then create deep copies of the nested, 69 * mutable objects. 70 * 71 * @return a copy of this object. 72 * @throws CloneNotSupportedException 73 * if this object's class does not implement the {@code 74 * Cloneable} interface. 75 * @since Android 1.0 76 */ clone()77 protected Object clone() throws CloneNotSupportedException { 78 if (!(this instanceof Cloneable)) { 79 throw new CloneNotSupportedException("Class doesn't implement Cloneable"); 80 } 81 82 return internalClone((Cloneable) this); 83 } 84 85 /* 86 * Native helper method for cloning. 87 */ internalClone(Cloneable o)88 private native Object internalClone(Cloneable o); 89 90 /** 91 * Compares this instance with the specified object and indicates if they 92 * are equal. In order to be equal, {@code o} must represent the same object 93 * as this instance using a class-specific comparison. The general contract 94 * is that this comparison should be both transitive and reflexive. 95 * <p> 96 * The implementation in {@code Object} returns {@code true} only if {@code 97 * o} is the exact same object as the receiver (using the == operator for 98 * comparison). Subclasses often implement {@code equals(Object)} so that 99 * it takes into account the two object's types and states. 100 * </p> 101 * <p> 102 * The general contract for the {@code equals(Object)} and {@link 103 * #hashCode()} methods is that if {@code equals} returns {@code true} for 104 * any two objects, then {@code hashCode()} must return the same value for 105 * these objects. This means that subclasses of {@code Object} usually 106 * override either both methods or none of them. 107 * </p> 108 * 109 * @param o 110 * the object to compare this instance with. 111 * @return {@code true} if the specified object is equal to this {@code 112 * Object}; {@code false} otherwise. 113 * @see #hashCode 114 * @since Android 1.0 115 */ equals(Object o)116 public boolean equals(Object o) { 117 return this == o; 118 } 119 120 /** 121 * Is called before the object's memory is being reclaimed by the VM. This 122 * can only happen once the VM has detected, during a run of the garbage 123 * collector, that the object is no longer reachable by any thread of the 124 * running application. 125 * <p> 126 * The method can be used to free system resources or perform other cleanup 127 * before the object is garbage collected. The default implementation of the 128 * method is empty, which is also expected by the VM, but subclasses can 129 * override {@code finalize()} as required. Uncaught exceptions which are 130 * thrown during the execution of this method cause it to terminate 131 * immediately but are otherwise ignored. 132 * <p> 133 * Note that the VM does guarantee that {@code finalize()} is called at most 134 * once for any object, but it doesn't guarantee when (if at all) {@code 135 * finalize()} will be called. For example, object B's {@code finalize()} 136 * can delay the execution of object A's {@code finalize()} method and 137 * therefore it can delay the reclamation of A's memory. To be safe, use a 138 * {@link java.lang.ref.ReferenceQueue}, because it provides more control 139 * over the way the VM deals with references during garbage collection. 140 * </p> 141 * 142 * @throws Throwable 143 * any exception which is raised during finalization; these are 144 * ignored by the virtual machine. 145 * @since Android 1.0 146 */ finalize()147 protected void finalize() throws Throwable { 148 } 149 150 /** 151 * Returns the unique instance of {@link Class} which represents this 152 * object's class. Note that {@code getClass()} is a special case in that it 153 * actually returns {@code Class<? extends Foo>} where {@code Foo} is the 154 * erasure of the type of expression {@code getClass()} was called upon. 155 * <p> 156 * As an example, the following code actually compiles, although one might 157 * think it shouldn't: 158 * <p> 159 * <pre> 160 * List<Integer> l = new ArrayList<Integer>(); 161 * Class<? extends List> c = l.getClass(); 162 * </pre> 163 * 164 * @return this object's {@code Class} instance. 165 * @since Android 1.0 166 */ getClass()167 public final native Class<? extends Object> getClass(); 168 169 /** 170 * Returns an integer hash code for this object. By contract, any two 171 * objects for which {@code equals(Object)} returns {@code true} must return 172 * the same hash code value. This means that subclasses of {@code Object} 173 * usually override both methods or neither method. 174 * 175 * @return this object's hash code. 176 * @see #equals 177 * @since Android 1.0 178 */ hashCode()179 public native int hashCode(); 180 181 /** 182 * Causes a thread which is waiting on this object's monitor (by means of 183 * calling one of the {@code wait()} methods) to be woken up. If more than 184 * one thread is waiting, one of them is chosen at the discretion of the 185 * virtual machine. The chosen thread will not run immediately. The thread 186 * that called {@code notify()} has to release the object's monitor first. 187 * Also, the chosen thread still has to compete against other threads that 188 * try to synchronize on the same object. 189 * <p> 190 * This method can only be invoked by a thread which owns this object's 191 * monitor. A thread becomes owner of an object's monitor 192 * </p> 193 * <ul> 194 * <li>by executing a synchronized method of that object;</li> 195 * <li>by executing the body of a {@code synchronized} statement that 196 * synchronizes on the object;</li> 197 * <li>by executing a synchronized static method if the object is of type 198 * {@code Class}.</li> 199 * </ul> 200 * 201 * @see #notifyAll 202 * @see #wait() 203 * @see #wait(long) 204 * @see #wait(long,int) 205 * @see java.lang.Thread 206 * @since Android 1.0 207 */ notify()208 public final native void notify(); 209 210 /** 211 * Causes all threads which are waiting on this object's monitor (by means 212 * of calling one of the {@code wait()} methods) to be woken up. The threads 213 * will not run immediately. The thread that called {@code notify()} has to 214 * release the object's monitor first. Also, the threads still have to 215 * compete against other threads that try to synchronize on the same object. 216 * <p> 217 * This method can only be invoked by a thread which owns this object's 218 * monitor. A thread becomes owner of an object's monitor 219 * </p> 220 * <ul> 221 * <li>by executing a synchronized method of that object;</li> 222 * <li>by executing the body of a {@code synchronized} statement that 223 * synchronizes on the object;</li> 224 * <li>by executing a synchronized static method if the object is of type 225 * {@code Class}.</li> 226 * </ul> 227 * 228 * @throws IllegalMonitorStateException 229 * if the thread calling this method is not the owner of this 230 * object's monitor. 231 * @see #notify 232 * @see #wait() 233 * @see #wait(long) 234 * @see #wait(long,int) 235 * @see java.lang.Thread 236 */ notifyAll()237 public final native void notifyAll(); 238 239 /** 240 * Returns a string containing a concise, human-readable description of this 241 * object. Subclasses are encouraged to override this method and provide an 242 * implementation that takes into account the object's type and data. The 243 * default implementation simply concatenates the class name, the '@' sign 244 * and a hexadecimal representation of the object's {@link #hashCode()}, 245 * that is, it is equivalent to the following expression: 246 * 247 * <pre> 248 * getClass().getName() + '@' + Integer.toHexString(hashCode()) 249 * </pre> 250 * 251 * @return a printable representation of this object. 252 * @since Android 1.0 253 */ toString()254 public String toString() { 255 return getClass().getName() + '@' + Integer.toHexString(hashCode()); 256 } 257 258 /** 259 * Causes the calling thread to wait until another thread calls the {@code 260 * notify()} or {@code notifyAll()} method of this object. This method can 261 * only be invoked by a thread which owns this object's monitor; see 262 * {@link #notify()} on how a thread can become the owner of a monitor. 263 * <p> 264 * A waiting thread can be sent {@code interrupt()} to cause it to 265 * prematurely stop waiting, so {@code wait} should be called in a loop to 266 * check that the condition that has been waited for has been met before 267 * continuing. 268 * </p> 269 * <p> 270 * While the thread waits, it gives up ownership of this object's monitor. 271 * When it is notified (or interrupted), it re-acquires the monitor before 272 * it starts running. 273 * </p> 274 * 275 * @throws IllegalMonitorStateException 276 * if the thread calling this method is not the owner of this 277 * object's monitor. 278 * @throws InterruptedException 279 * if another thread interrupts this thread while it is waiting. 280 * @see #notify 281 * @see #notifyAll 282 * @see #wait(long) 283 * @see #wait(long,int) 284 * @see java.lang.Thread 285 * @since Android 1.0 286 */ wait()287 public final void wait() throws InterruptedException { 288 wait(0 ,0); 289 } 290 291 /** 292 * Causes the calling thread to wait until another thread calls the {@code 293 * notify()} or {@code notifyAll()} method of this object or until the 294 * specified timeout expires. This method can only be invoked by a thread 295 * which owns this object's monitor; see {@link #notify()} on how a thread 296 * can become the owner of a monitor. 297 * <p> 298 * A waiting thread can be sent {@code interrupt()} to cause it to 299 * prematurely stop waiting, so {@code wait} should be called in a loop to 300 * check that the condition that has been waited for has been met before 301 * continuing. 302 * </p> 303 * <p> 304 * While the thread waits, it gives up ownership of this object's monitor. 305 * When it is notified (or interrupted), it re-acquires the monitor before 306 * it starts running. 307 * </p> 308 * 309 * @param millis 310 * the maximum time to wait in milliseconds. 311 * @throws IllegalArgumentException 312 * if {@code millis < 0}. 313 * @throws IllegalMonitorStateException 314 * if the thread calling this method is not the owner of this 315 * object's monitor. 316 * @throws InterruptedException 317 * if another thread interrupts this thread while it is waiting. 318 * @see #notify 319 * @see #notifyAll 320 * @see #wait() 321 * @see #wait(long,int) 322 * @see java.lang.Thread 323 * @since Android 1.0 324 */ wait(long millis)325 public final void wait(long millis) throws InterruptedException { 326 wait(millis, 0); 327 } 328 329 /** 330 * Causes the calling thread to wait until another thread calls the {@code 331 * notify()} or {@code notifyAll()} method of this object or until the 332 * specified timeout expires. This method can only be invoked by a thread 333 * that owns this object's monitor; see {@link #notify()} on how a thread 334 * can become the owner of a monitor. 335 * <p> 336 * A waiting thread can be sent {@code interrupt()} to cause it to 337 * prematurely stop waiting, so {@code wait} should be called in a loop to 338 * check that the condition that has been waited for has been met before 339 * continuing. 340 * </p> 341 * <p> 342 * While the thread waits, it gives up ownership of this object's monitor. 343 * When it is notified (or interrupted), it re-acquires the monitor before 344 * it starts running. 345 * </p> 346 * 347 * @param millis 348 * the maximum time to wait in milliseconds. 349 * @param nanos 350 * the fraction of a millisecond to wait, specified in 351 * nanoseconds. 352 * @throws IllegalArgumentException 353 * if {@code millis < 0}, {@code nanos < 0} or {@code nanos > 354 * 999999}. 355 * @throws IllegalMonitorStateException 356 * if the thread calling this method is not the owner of this 357 * object's monitor. 358 * @throws InterruptedException 359 * if another thread interrupts this thread while it is waiting. 360 * @see #notify 361 * @see #notifyAll 362 * @see #wait() 363 * @see #wait(long,int) 364 * @see java.lang.Thread 365 * @since Android 1.0 366 */ wait(long millis, int nanos)367 public final native void wait(long millis, int nanos) throws InterruptedException; 368 } 369