001package arez.component;
002
003import arez.Arez;
004import arez.Disposable;
005import arez.SafeProcedure;
006import arez.annotations.CascadeDispose;
007import javax.annotation.Nonnull;
008import static org.realityforge.braincheck.Guards.*;
009
010/**
011 * Interface implemented by a component if it supports notifying listeners
012 * when the component is disposed. This notification occurs using a call-back
013 * and occurs within the dispose transaction (after {@link arez.annotations.PreDispose}
014 * is invoked if present) using a callback. Contrast this with the strategy used by
015 * {@link ComponentObservable} which uses standard Arez observables to track when
016 * a component is disposed.
017 */
018public interface DisposeNotifier
019{
020  /**
021   * Add the listener to the notify list under key.
022   * This method MUST NOT be invoked after the component has been disposed.
023   * This method should not be invoked if another listener has been added with the same key without
024   * being removed.
025   *
026   * <p>If the key implements {@link Disposable} and {@link Disposable#isDisposed()} returns <code>true</code>
027   * when invoking the calback then the callback will be skipped. This rare situation only occurs when there is
028   * circular dependency in the object model usually involving {@link CascadeDispose}.</p>
029   *
030   * @param key              the key to uniquely identify listener.
031   * @param action           the listener callback.
032   * @param errorIfDuplicate generate an assertion error if duplicate key inserted.
033   */
034  void addOnDisposeListener( @Nonnull Object key, @Nonnull SafeProcedure action, boolean errorIfDuplicate );
035
036  /**
037   * Remove the listener with the specified key from the notify list.
038   * This method should only be invoked when a listener has been added for specific key using
039   * {@link #addOnDisposeListener(Object, SafeProcedure, boolean)} and has not been removed by another
040   * call to this method.
041   *
042   * @param key            the key under which the listener was previously added.
043   * @param errorIfMissing generate an assertion error if no such key exists.
044   */
045  void removeOnDisposeListener( @Nonnull Object key, boolean errorIfMissing );
046
047  /**
048   * Cast the specified object to an instance of DisposeNotifier.
049   * Invariant checks will verify that the cast is valid before proceeding.
050   *
051   * @param object the object.
052   * @return the object cast to DisposeNotifier.
053   */
054  @Nonnull
055  static DisposeNotifier asDisposeNotifier( @Nonnull final Object object )
056  {
057    if ( Arez.shouldCheckApiInvariants() )
058    {
059      apiInvariant( () -> object instanceof DisposeNotifier,
060                    () -> "Arez-0178: Object passed to asDisposeNotifier does not implement " +
061                          "DisposeNotifier. Object: " + object );
062    }
063    return (DisposeNotifier) object;
064  }
065}