1ffd0cb04f97e62d286d185c520580d81a9c328b1Fred Quintana/* 2ffd0cb04f97e62d286d185c520580d81a9c328b1Fred Quintana * Copyright (C) 2009 The Android Open Source Project 3ffd0cb04f97e62d286d185c520580d81a9c328b1Fred Quintana * 4ffd0cb04f97e62d286d185c520580d81a9c328b1Fred Quintana * Licensed under the Apache License, Version 2.0 (the "License"); 5ffd0cb04f97e62d286d185c520580d81a9c328b1Fred Quintana * you may not use this file except in compliance with the License. 6ffd0cb04f97e62d286d185c520580d81a9c328b1Fred Quintana * You may obtain a copy of the License at 7ffd0cb04f97e62d286d185c520580d81a9c328b1Fred Quintana * 8ffd0cb04f97e62d286d185c520580d81a9c328b1Fred Quintana * http://www.apache.org/licenses/LICENSE-2.0 9ffd0cb04f97e62d286d185c520580d81a9c328b1Fred Quintana * 10ffd0cb04f97e62d286d185c520580d81a9c328b1Fred Quintana * Unless required by applicable law or agreed to in writing, software 11ffd0cb04f97e62d286d185c520580d81a9c328b1Fred Quintana * distributed under the License is distributed on an "AS IS" BASIS, 12ffd0cb04f97e62d286d185c520580d81a9c328b1Fred Quintana * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13ffd0cb04f97e62d286d185c520580d81a9c328b1Fred Quintana * See the License for the specific language governing permissions and 14ffd0cb04f97e62d286d185c520580d81a9c328b1Fred Quintana * limitations under the License. 15ffd0cb04f97e62d286d185c520580d81a9c328b1Fred Quintana */ 16ffd0cb04f97e62d286d185c520580d81a9c328b1Fred Quintanapackage android.accounts; 17ffd0cb04f97e62d286d185c520580d81a9c328b1Fred Quintana 18ffd0cb04f97e62d286d185c520580d81a9c328b1Fred Quintanaimport java.util.concurrent.Future; 19ffd0cb04f97e62d286d185c520580d81a9c328b1Fred Quintanaimport java.util.concurrent.TimeUnit; 20ffd0cb04f97e62d286d185c520580d81a9c328b1Fred Quintanaimport java.util.concurrent.ExecutionException; 21ffd0cb04f97e62d286d185c520580d81a9c328b1Fred Quintanaimport java.util.concurrent.TimeoutException; 22ffd0cb04f97e62d286d185c520580d81a9c328b1Fred Quintanaimport java.io.IOException; 23ffd0cb04f97e62d286d185c520580d81a9c328b1Fred Quintana 24ffd0cb04f97e62d286d185c520580d81a9c328b1Fred Quintana/** 25f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana * A <tt>AccountManagerFuture</tt> represents the result of an asynchronous 26f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana * {@link AccountManager} call. Methods are provided to check if the computation is 27f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana * complete, to wait for its completion, and to retrieve the result of 28f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana * the computation. The result can only be retrieved using method 29f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana * <tt>get</tt> when the computation has completed, blocking if 30f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana * necessary until it is ready. Cancellation is performed by the 31f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana * <tt>cancel</tt> method. Additional methods are provided to 32f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana * determine if the task completed normally or was cancelled. Once a 33f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana * computation has completed, the computation cannot be cancelled. 34f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana * If you would like to use a <tt>Future</tt> for the sake 35f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana * of cancellability but not provide a usable result, you can 36f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana * declare types of the form <tt>Future<?></tt> and 37f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana * return <tt>null</tt> as a result of the underlying task. 38ffd0cb04f97e62d286d185c520580d81a9c328b1Fred Quintana */ 39f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintanapublic interface AccountManagerFuture<V> { 40f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana /** 41f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana * Attempts to cancel execution of this task. This attempt will 42f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana * fail if the task has already completed, has already been cancelled, 43f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana * or could not be cancelled for some other reason. If successful, 44f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana * and this task has not started when <tt>cancel</tt> is called, 45f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana * this task should never run. If the task has already started, 46f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana * then the <tt>mayInterruptIfRunning</tt> parameter determines 47f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana * whether the thread executing this task should be interrupted in 48f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana * an attempt to stop the task. 49f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana * 50f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana * <p>After this method returns, subsequent calls to {@link #isDone} will 51f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana * always return <tt>true</tt>. Subsequent calls to {@link #isCancelled} 52f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana * will always return <tt>true</tt> if this method returned <tt>true</tt>. 53f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana * 54f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana * @param mayInterruptIfRunning <tt>true</tt> if the thread executing this 55f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana * task should be interrupted; otherwise, in-progress tasks are allowed 56f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana * to complete 57f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana * @return <tt>false</tt> if the task could not be cancelled, 58f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana * typically because it has already completed normally; 59f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana * <tt>true</tt> otherwise 60f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana */ 61f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana boolean cancel(boolean mayInterruptIfRunning); 62f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana 63f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana /** 64f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana * Returns <tt>true</tt> if this task was cancelled before it completed 65f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana * normally. 66f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana * 67f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana * @return <tt>true</tt> if this task was cancelled before it completed 68f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana */ 69f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana boolean isCancelled(); 70f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana 71f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana /** 72f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana * Returns <tt>true</tt> if this task completed. 73f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana * 74f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana * Completion may be due to normal termination, an exception, or 75f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana * cancellation -- in all of these cases, this method will return 76f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana * <tt>true</tt>. 77f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana * 78f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana * @return <tt>true</tt> if this task completed 79f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana */ 80f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana boolean isDone(); 81f7ae77cd67f1a3993b8e56c1af4720a7adf4e69dFred Quintana 82ffd0cb04f97e62d286d185c520580d81a9c328b1Fred Quintana /** 83756b735e9312ee52618158270f0bdd0ec691a712Fred Quintana * Accessor for the future result the {@link AccountManagerFuture} represents. This 84756b735e9312ee52618158270f0bdd0ec691a712Fred Quintana * call will block until the result is available. In order to check if the result is 85756b735e9312ee52618158270f0bdd0ec691a712Fred Quintana * available without blocking, one may call {@link #isDone()} and {@link #isCancelled()}. 86756b735e9312ee52618158270f0bdd0ec691a712Fred Quintana * If the request that generated this result fails or is canceled then an exception 87756b735e9312ee52618158270f0bdd0ec691a712Fred Quintana * will be thrown rather than the call returning normally. 88756b735e9312ee52618158270f0bdd0ec691a712Fred Quintana * @return the actual result 89756b735e9312ee52618158270f0bdd0ec691a712Fred Quintana * @throws android.accounts.OperationCanceledException if the request was canceled for any 90756b735e9312ee52618158270f0bdd0ec691a712Fred Quintana * reason 91756b735e9312ee52618158270f0bdd0ec691a712Fred Quintana * @throws android.accounts.AuthenticatorException if there was an error communicating with 92756b735e9312ee52618158270f0bdd0ec691a712Fred Quintana * the authenticator or if the authenticator returned an invalid response 93756b735e9312ee52618158270f0bdd0ec691a712Fred Quintana * @throws java.io.IOException if the authenticator returned an error response that indicates 94756b735e9312ee52618158270f0bdd0ec691a712Fred Quintana * that it encountered an IOException while communicating with the authentication server 95ffd0cb04f97e62d286d185c520580d81a9c328b1Fred Quintana */ 96ffd0cb04f97e62d286d185c520580d81a9c328b1Fred Quintana V getResult() throws OperationCanceledException, IOException, AuthenticatorException; 97ffd0cb04f97e62d286d185c520580d81a9c328b1Fred Quintana 98ffd0cb04f97e62d286d185c520580d81a9c328b1Fred Quintana /** 99756b735e9312ee52618158270f0bdd0ec691a712Fred Quintana * Accessor for the future result the {@link AccountManagerFuture} represents. This 100756b735e9312ee52618158270f0bdd0ec691a712Fred Quintana * call will block until the result is available. In order to check if the result is 101756b735e9312ee52618158270f0bdd0ec691a712Fred Quintana * available without blocking, one may call {@link #isDone()} and {@link #isCancelled()}. 102756b735e9312ee52618158270f0bdd0ec691a712Fred Quintana * If the request that generated this result fails or is canceled then an exception 103756b735e9312ee52618158270f0bdd0ec691a712Fred Quintana * will be thrown rather than the call returning normally. If a timeout is specified then 104756b735e9312ee52618158270f0bdd0ec691a712Fred Quintana * the request will automatically be canceled if it does not complete in that amount of time. 105ffd0cb04f97e62d286d185c520580d81a9c328b1Fred Quintana * @param timeout the maximum time to wait 106756b735e9312ee52618158270f0bdd0ec691a712Fred Quintana * @param unit the time unit of the timeout argument. This must not be null. 107756b735e9312ee52618158270f0bdd0ec691a712Fred Quintana * @return the actual result 108756b735e9312ee52618158270f0bdd0ec691a712Fred Quintana * @throws android.accounts.OperationCanceledException if the request was canceled for any 109756b735e9312ee52618158270f0bdd0ec691a712Fred Quintana * reason 110756b735e9312ee52618158270f0bdd0ec691a712Fred Quintana * @throws android.accounts.AuthenticatorException if there was an error communicating with 111756b735e9312ee52618158270f0bdd0ec691a712Fred Quintana * the authenticator or if the authenticator returned an invalid response 112756b735e9312ee52618158270f0bdd0ec691a712Fred Quintana * @throws java.io.IOException if the authenticator returned an error response that indicates 113756b735e9312ee52618158270f0bdd0ec691a712Fred Quintana * that it encountered an IOException while communicating with the authentication server 114ffd0cb04f97e62d286d185c520580d81a9c328b1Fred Quintana */ 115ffd0cb04f97e62d286d185c520580d81a9c328b1Fred Quintana V getResult(long timeout, TimeUnit unit) 116ffd0cb04f97e62d286d185c520580d81a9c328b1Fred Quintana throws OperationCanceledException, IOException, AuthenticatorException; 117ffd0cb04f97e62d286d185c520580d81a9c328b1Fred Quintana}