461 }
462
463 if (nanos < 0 || nanos > 999999) {
464 throw new IllegalArgumentException(
465 "nanosecond timeout value out of range");
466 }
467
468 if (nanos > 0 && timeoutMillis < Long.MAX_VALUE) {
469 timeoutMillis++;
470 }
471
472 wait(timeoutMillis);
473 }
474
475 /**
476 * Called by the garbage collector on an object when garbage collection
477 * determines that there are no more references to the object.
478 * A subclass overrides the {@code finalize} method to dispose of
479 * system resources or to perform other cleanup.
480 * <p>
481 * The general contract of {@code finalize} is that it is invoked
482 * if and when the Java virtual
483 * machine has determined that there is no longer any
484 * means by which this object can be accessed by any thread that has
485 * not yet died, except as a result of an action taken by the
486 * finalization of some other object or class which is ready to be
487 * finalized. The {@code finalize} method may take any action, including
488 * making this object available again to other threads; the usual purpose
489 * of {@code finalize}, however, is to perform cleanup actions before
490 * the object is irrevocably discarded. For example, the finalize method
491 * for an object that represents an input/output connection might perform
492 * explicit I/O transactions to break the connection before the object is
493 * permanently discarded.
494 * <p>
495 * The {@code finalize} method of class {@code Object} performs no
496 * special action; it simply returns normally. Subclasses of
497 * {@code Object} may override this definition.
498 * <p>
499 * The Java programming language does not guarantee which thread will
500 * invoke the {@code finalize} method for any given object. It is
526 * <p>
527 * A subclass should avoid overriding the {@code finalize} method
528 * unless the subclass embeds non-heap resources that must be cleaned up
529 * before the instance is collected.
530 * Finalizer invocations are not automatically chained, unlike constructors.
531 * If a subclass overrides {@code finalize} it must invoke the superclass
532 * finalizer explicitly.
533 * To guard against exceptions prematurely terminating the finalize chain,
534 * the subclass should use a {@code try-finally} block to ensure
535 * {@code super.finalize()} is always invoked. For example,
536 * <pre>{@code @Override
537 * protected void finalize() throws Throwable {
538 * try {
539 * ... // cleanup subclass state
540 * } finally {
541 * super.finalize();
542 * }
543 * }
544 * }</pre>
545 *
546 * @deprecated The finalization mechanism is inherently problematic.
547 * Finalization can lead to performance issues, deadlocks, and hangs.
548 * Errors in finalizers can lead to resource leaks; there is no way to cancel
549 * finalization if it is no longer necessary; and no ordering is specified
550 * among calls to {@code finalize} methods of different objects.
551 * Furthermore, there are no guarantees regarding the timing of finalization.
552 * The {@code finalize} method might be called on a finalizable object
553 * only after an indefinite delay, if at all.
554 *
555 * Classes whose instances hold non-heap resources should provide a method
556 * to enable explicit release of those resources, and they should also
557 * implement {@link AutoCloseable} if appropriate.
558 * The {@link java.lang.ref.Cleaner} and {@link java.lang.ref.PhantomReference}
559 * provide more flexible and efficient ways to release resources when an object
560 * becomes unreachable.
561 *
562 * @throws Throwable the {@code Exception} raised by this method
563 * @see java.lang.ref.WeakReference
564 * @see java.lang.ref.PhantomReference
565 * @jls 12.6 Finalization of Class Instances
566 */
567 @Deprecated(since="9")
568 protected void finalize() throws Throwable { }
569 }
|
461 }
462
463 if (nanos < 0 || nanos > 999999) {
464 throw new IllegalArgumentException(
465 "nanosecond timeout value out of range");
466 }
467
468 if (nanos > 0 && timeoutMillis < Long.MAX_VALUE) {
469 timeoutMillis++;
470 }
471
472 wait(timeoutMillis);
473 }
474
475 /**
476 * Called by the garbage collector on an object when garbage collection
477 * determines that there are no more references to the object.
478 * A subclass overrides the {@code finalize} method to dispose of
479 * system resources or to perform other cleanup.
480 * <p>
481 * <b>When running in a Java virtual machine in which finalization has been
482 * disabled or removed, the garbage collector will never call
483 * {@code finalize()}. In a Java virtual machine in which finalization is
484 * enabled, the garbage collector might call {@code finalize} only after an
485 * indefinite delay.</b>
486 * <p>
487 * The general contract of {@code finalize} is that it is invoked
488 * if and when the Java virtual
489 * machine has determined that there is no longer any
490 * means by which this object can be accessed by any thread that has
491 * not yet died, except as a result of an action taken by the
492 * finalization of some other object or class which is ready to be
493 * finalized. The {@code finalize} method may take any action, including
494 * making this object available again to other threads; the usual purpose
495 * of {@code finalize}, however, is to perform cleanup actions before
496 * the object is irrevocably discarded. For example, the finalize method
497 * for an object that represents an input/output connection might perform
498 * explicit I/O transactions to break the connection before the object is
499 * permanently discarded.
500 * <p>
501 * The {@code finalize} method of class {@code Object} performs no
502 * special action; it simply returns normally. Subclasses of
503 * {@code Object} may override this definition.
504 * <p>
505 * The Java programming language does not guarantee which thread will
506 * invoke the {@code finalize} method for any given object. It is
532 * <p>
533 * A subclass should avoid overriding the {@code finalize} method
534 * unless the subclass embeds non-heap resources that must be cleaned up
535 * before the instance is collected.
536 * Finalizer invocations are not automatically chained, unlike constructors.
537 * If a subclass overrides {@code finalize} it must invoke the superclass
538 * finalizer explicitly.
539 * To guard against exceptions prematurely terminating the finalize chain,
540 * the subclass should use a {@code try-finally} block to ensure
541 * {@code super.finalize()} is always invoked. For example,
542 * <pre>{@code @Override
543 * protected void finalize() throws Throwable {
544 * try {
545 * ... // cleanup subclass state
546 * } finally {
547 * super.finalize();
548 * }
549 * }
550 * }</pre>
551 *
552 * @deprecated Finalization is deprecated and subject to removal in a future
553 * release. The use of finalization can lead to problems with security,
554 * performance, and reliability.
555 * See <a href="https://openjdk.java.net/jeps/421">JEP 421</a> for
556 * discussion and alternatives.
557 * <p>
558 * Subclasses that override {@code finalize} to perform cleanup should use
559 * alternative cleanup mechanisms and remove the {@code finalize} method.
560 * Use {@link java.lang.ref.Cleaner} and
561 * {@link java.lang.ref.PhantomReference} as safer ways to release resources
562 * when an object becomes unreachable. Alternatively, add a {@code close}
563 * method to explicitly release resources, and implement
564 * {@code AutoCloseable} to enable use of the {@code try}-with-resources
565 * statement.
566 * <p>
567 * This method will remain in place until finalizers have been removed from
568 * most existing code.
569 *
570 * @throws Throwable the {@code Exception} raised by this method
571 * @see java.lang.ref.WeakReference
572 * @see java.lang.ref.PhantomReference
573 * @jls 12.6 Finalization of Class Instances
574 */
575 @Deprecated(since="9", forRemoval=true)
576 protected void finalize() throws Throwable { }
577 }
|