/** * Implemented by the user to determine whether {@code a} and {@code b} are considered equivalent, * subject to the requirements specified in {@link #equivalent}. * * <p>This method should not be called except by {@link #equivalent}. When {@link #equivalent} * calls this method, {@code a} and {@code b} are guaranteed to be distinct, non-null instances. * * @since 10.0 (previously, subclasses would override equivalent()) */ @ForOverride protected abstract boolean doEquivalent(T a, T b);
/** * Implemented by the user to return a hash code for {@code t}, subject to the requirements * specified in {@link #hash}. * * <p>This method should not be called except by {@link #hash}. When {@link #hash} calls this * method, {@code t} is guaranteed to be non-null. * * @since 10.0 (previously, subclasses would override hash()) */ @ForOverride protected abstract int doHash(T t);
/** * This method is called by {@link #startAsync} to initiate service startup. The invocation of * this method should cause a call to {@link #notifyStarted()}, either during this method's run, * or after it has returned. If startup fails, the invocation should cause a call to {@link * #notifyFailed(Throwable)} instead. * * <p>This method should return promptly; prefer to do work on a different thread where it is * convenient. It is invoked exactly once on service startup, even when {@link #startAsync} is * called multiple times. */ @ForOverride protected abstract void doStart();
/** * Returns a representation of {@code a} as an instance of type {@code B}. If {@code a} cannot be * converted, an unchecked exception (such as {@link IllegalArgumentException}) should be thrown. * * @param a the instance to convert; will never be null * @return the converted instance; <b>must not</b> be null */ @ForOverride protected abstract B doForward(A a);
/** * Returns a representation of {@code b} as an instance of type {@code A}. If {@code b} cannot be * converted, an unchecked exception (such as {@link IllegalArgumentException}) should be thrown. * * @param b the instance to convert; will never be null * @return the converted instance; <b>must not</b> be null * @throws UnsupportedOperationException if backward conversion is not implemented; this should be * very rare. Note that if backward conversion is not only unimplemented but * unimplement<i>able</i> (for example, consider a {@code Converter<Chicken, ChickenNugget>}), * then this is not logically a {@code Converter} at all, and should just implement {@link * Function}. */ @ForOverride protected abstract A doBackward(B b);
/** * This method should be used to initiate service shutdown. The invocation of this method should * cause a call to {@link #notifyStopped()}, either during this method's run, or after it has * returned. If shutdown fails, the invocation should cause a call to {@link * #notifyFailed(Throwable)} instead. * * <p>This method should return promptly; prefer to do work on a different thread where it is * convenient. It is invoked exactly once on service shutdown, even when {@link #stopAsync} is * called multiple times. * * <p>If {@link #stopAsync} is called on a {@link State#STARTING} service, this method is not * invoked immediately. Instead, it will be deferred until after the service is {@link * State#RUNNING}. Services that need to cancel startup work can override {#link #doCancelStart}. */ @ForOverride protected abstract void doStop();
/** * This method is called by {@link #stopAsync} when the service is still starting (i.e. {@link * #startAsync} has been called but {@link #notifyStarted} has not). Subclasses can override the * method to cancel pending work and then call {@link #notifyStopped} to stop the service. * * <p>This method should return promptly; prefer to do work on a different thread where it is * convenient. It is invoked exactly once on service shutdown, even when {@link #stopAsync} is * called multiple times. * * <p>When this method is called {@link #state()} will return {@link State#STOPPING}, which * is the external state observable by the caller of {@link #stopAsync}. * * @since 27.0 */ @ForOverride protected void doCancelStart() {}
/** * Returns a representation of {@code a} as an instance of type {@code B}. If {@code a} cannot be * converted, an unchecked exception (such as {@link IllegalArgumentException}) should be thrown. * * @param a the instance to convert; will never be null * @return the converted instance; <b>must not</b> be null */ @ForOverride protected abstract B doForward(A a);
/** * This method should be used to initiate service shutdown. The invocation of this method should * cause a call to {@link #notifyStopped()}, either during this method's run, or after it has * returned. If shutdown fails, the invocation should cause a call to {@link * #notifyFailed(Throwable)} instead. * * <p>This method should return promptly; prefer to do work on a different thread where it is * convenient. It is invoked exactly once on service shutdown, even when {@link #stopAsync} is * called multiple times. */ @ForOverride protected abstract void doStop();
/** * Implemented by the user to determine whether {@code a} and {@code b} are considered equivalent, * subject to the requirements specified in {@link #equivalent}. * * <p>This method should not be called except by {@link #equivalent}. When {@link #equivalent} * calls this method, {@code a} and {@code b} are guaranteed to be distinct, non-null instances. * * @since 10.0 (previously, subclasses would override equivalent()) */ @ForOverride protected abstract boolean doEquivalent(T a, T b);
/** * This method is called by {@link #startAsync} to initiate service startup. The invocation of * this method should cause a call to {@link #notifyStarted()}, either during this method's run, * or after it has returned. If startup fails, the invocation should cause a call to {@link * #notifyFailed(Throwable)} instead. * * <p>This method should return promptly; prefer to do work on a different thread where it is * convenient. It is invoked exactly once on service startup, even when {@link #startAsync} is * called multiple times. */ @ForOverride protected abstract void doStart();
/** * Implemented by the user to return a hash code for {@code t}, subject to the requirements * specified in {@link #hash}. * * <p>This method should not be called except by {@link #hash}. When {@link #hash} calls this * method, {@code t} is guaranteed to be non-null. * * @since 10.0 (previously, subclasses would override hash()) */ @ForOverride protected abstract int doHash(T t);
/** * Callback method that is called exactly once after the future is completed. * * <p>If {@link #interruptTask} is also run during completion, {@link #afterDone} runs after it. * * <p>The default implementation of this method in {@code AbstractFuture} does nothing. This is * intended for very lightweight cleanup work, for example, timing statistics or clearing fields. * If your task does anything heavier consider, just using a listener with an executor. * * @since 20.0 */ @Beta @ForOverride protected void afterDone() {}
/** Template method for subtypes to actually run the fallback. */ @ForOverride abstract @Nullable T doFallback(F fallback, X throwable) throws Exception;
/** Template method for subtypes to actually set the result. */ @ForOverride abstract void setResult(@Nullable T result);
/** Template method for subtypes to actually set the result. */ @ForOverride abstract void setResult(@Nullable T result);
/** Template method for subtypes to actually run the fallback. */ @ForOverride @NullableDecl abstract T doFallback(F fallback, X throwable) throws Exception;
/** Template method for subtypes to actually set the result. */ @ForOverride abstract void setResult(@NullableDecl T result);
/** Template method for subtypes to actually run the transform. */ @ForOverride abstract @Nullable T doTransform(F function, @Nullable I result) throws Exception;
/** Template method for subtypes to actually run the transform. */ @ForOverride @NullableDecl abstract T doTransform(F function, @NullableDecl I result) throws Exception;