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 17 package com.android.camera.one.v2.sharedimagereader.ticketpool; 18 19 import com.android.camera.async.Observable; 20 21 import java.util.Collection; 22 23 import javax.annotation.CheckReturnValue; 24 import javax.annotation.Nonnull; 25 import javax.annotation.Nullable; 26 27 /** 28 * Stores a collection of {@link Ticket}s. Tickets may be acquired from the 29 * pool. When closed, tickets return themselves to the pool. 30 */ 31 public interface TicketPool extends TicketProvider { 32 /** 33 * Indicates that the requested number of tickets will never be available, 34 * possibly because the Pool has been closed, or because the request exceeds 35 * the maximum number of tickets which exist in the context of the pool. 36 */ 37 public static class NoCapacityAvailableException extends Exception { 38 } 39 40 /** 41 * Acquires and returns the specified number of tickets. The caller owns all 42 * returned tickets and is responsible for eventually closing them. 43 * <p> 44 * Implementations must be fair w.r.t. other calls to acquire. 45 */ 46 @Nonnull 47 public Collection<Ticket> acquire(int tickets) throws InterruptedException, 48 NoCapacityAvailableException; 49 50 /** 51 * @return The number of tickets readily-available for immediate 52 * acquisition, as an observable object. 53 */ 54 @Nonnull 55 public Observable<Integer> getAvailableTicketCount(); 56 57 /** 58 * Attempts to acquire and return a ticket. The caller owns the resulting 59 * ticket (if not null) and is responsible for eventually closing it. 60 * <p> 61 * Implementations must be fair w.r.t. {@link #acquire}. 62 * 63 * @return The acquired ticket, or null if no ticket is readily available. 64 */ 65 @Override 66 @Nullable 67 @CheckReturnValue 68 public Ticket tryAcquire(); 69 } 70
