org.javabits.yar.BlockingSupplier Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of yar-api Show documentation

Yar API: provide the main interfaces to manipulate the registry

There is a newer version: 3.0.1.RELEASE

package org.javabits.yar;

import com.google.common.util.concurrent.ListenableFuture;

import javax.annotation.Nullable;
import java.lang.InterruptedException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

/**
 * Date: 2/28/13
 *
 * @author Romain Gilles
 */
public interface BlockingSupplier extends Supplier {
    /**
     * Retrieves the instance of {@code T} from the registry.
     * 
     * This is a non-blocking call.
     *
     * @return the instance of {@code T}, or null if no corresponding registration.
     */
    @Nullable
    @Override
    T get();

    /**
     * Retrieves the instance of {@code T} from the registry. If no {@code T} registered,
     * the call will block until the service is registered or the thread is interrupted.
     *
     * @return the instance of {@code T}.
     * @throws InterruptedException if the thread was interrupted while waiting.
     */
    T getSync() throws InterruptedException;

    /**
     * Retrieves the instance of {@code T} from the registry. If no {@code T} registered,
     * the call will block until the service is registered or the thread is interrupted, or the
     * timeout has expired.
     *
     * @param timeout the maximum time to wait
     * @param unit    the time unit of the timeout argument
     * @return the instance of {@code T}.
     * @throws InterruptedException if the thread was interrupted while waiting.
     * @throws TimeoutException     if the wait timed out.
     */
    T getSync(long timeout, TimeUnit unit) throws InterruptedException, TimeoutException;

    /**
     * Retrieves the instance of {@code T} from the registry asynchronously. The caller will use
     * the returned future to obtain the instance of the service once it gets registered available.
     *
     * @return an instance of future result.
     */
    ListenableFuture getAsync();

    /**
     * Returns the default timeout used for blocking operations.
     * The associated time unit is provided by {@link #defaultTimeUnit()}.
     * @return default timeout used for blocking operations.
     * @see #defaultTimeUnit()
     */
    long defaultTimeout();

    /**
     * Returns the default time unit used for blocking operations.
     * The associated timeout is provided by {@link #defaultTimeout()}.
     * @return default timeout used for blocking operations.
     * @see #defaultTimeout()
     */
    TimeUnit defaultTimeUnit();

}