BufferQueue.java revision de15a5ad14da2e9069642e6f616b66b4ae660e01 
1/*
2 * Copyright (C) 2014 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package com.android.camera.async;
18
19import java.util.concurrent.TimeUnit;
20import java.util.concurrent.TimeoutException;
21
22/**
23 * An input stream of objects which can be closed from either the producer or
24 * the consumer.
25 */
26public interface BufferQueue<T> extends SafeCloseable {
27    @Override
28    public void close();
29
30    /**
31     * Blocks, returning the next available value.
32     *
33     * @return The next available value.
34     * @throws InterruptedException If interrupted while waiting for the next
35     *             value.
36     * @throws com.android.camera.async.BufferQueue.BufferQueueClosedException If the stream is closed and no more values
37     *             will be available.
38     */
39    public T getNext() throws InterruptedException, BufferQueueClosedException;
40
41    /**
42     * Blocks, returning the next available value.
43     *
44     * @param timeout The maximum amount of time to wait.
45     * @param unit The unit associated with the timeout.
46     * @return The next available value.
47     * @throws InterruptedException If interrupted while waiting for the next
48     *             value.
49     * @throws com.android.camera.async.BufferQueue.BufferQueueClosedException If the stream is closed and no more values
50     *             will be available.
51     * @throws TimeoutException If no new value is made available within the
52     *             specified time limit.
53     */
54    public T getNext(long timeout, TimeUnit unit) throws InterruptedException, TimeoutException,
55            BufferQueueClosedException;
56
57    /**
58     * Immediately returns the next available value without removing it from the
59     * stream.
60     *
61     * @return The next available value if one exists, or null if no value
62     *         exists yet or the stream is closed.
63     */
64    public T peekNext();
65
66    /**
67     * Immediately discards the next available value, if one exists.
68     */
69    public void discardNext();
70
71    /**
72     * @return True if the stream has been closed by either the producer or the
73     *         consumer.
74     */
75    public boolean isClosed();
76
77    /**
78     * Indicates that the stream is closed and no more results are available.
79     */
80    public static class BufferQueueClosedException extends Exception {
81    }
82}
83