1 /*
2  * Copyright (C) 2024 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 package com.android.adservices.shared.testing.concurrency;
17 
18 import com.android.adservices.shared.testing.Identifiable;
19 
20 /* Usage examples (not in the javadoc because of the <> inside)
21 
22    // Result-less
23    SimpleSyncCallback callback = new SimpleSyncCallback();
24    mExecutor.execute(() -> callback.setCalled());
25    callback.assertCalled();
26 
27    // Result-oriented
28    ResultSyncCallback<String> callback = new ResultSyncCallback<>();
29    mExecutor.execute(() -> callback.injectResult("dqw4w9wxcq"));
30    String videoId = callback.assertResultReceived();
31    expect.withMessage("video id").that(videoId).isEqualTo("dqw4w9wxcq!");
32 
33    // Internal
34    AnswerSyncCallback<Void> answer = AnswerSyncCallback.forVoidAnswer();
35    doAnswer(answer).when(mMockExecutor).execute(any());
36    mMockExecutor.execute(null);
37    answer.assertCalled();
38 */
39 
40 /**
41  * Base interface for all sync callbacks.
42  *
43  * <p>A {@code SyncCallback} has 2 types of methods, which are used to:
44  *
45  * <ol>
46  *   <li>Block the test until the callback is called.
47  *   <li>Unblock the test (i.e., call the callback).
48  * </ol>
49  *
50  * <p>Hence, it's typical usage in a test method is:
51  *
52  * <ol>
53  *   <li>Gets a callback.
54  *   <li>Do something in the background that calls the callback.
55  *   <li>Call a callback method that will block the test until the callback is called.
56  * </ol>
57  *
58  * <p>The first type includes {@link #assertCalled()}, although subclasses can provide other methods
59  * that are more specialized (like {@code assertResultReceived()} and/or {@code
60  * assertFailureReceived()}.
61  *
62  * <p>The second type depends on the callback, but it can be divided in 3 categories:
63  *
64  * <ol>
65  *   <li>Methods that don't take a result.
66  *   <li>Methods that take a result.
67  *   <li>Internal methods (i.e., they're not called by tests, but internally by the callback).
68  * </ol>
69  *
70  * <p>See a few concrete examples in the code, above the class javadoc...
71  */
72 public interface SyncCallback extends Identifiable {
73 
74     /** Tag used on {@code logcat} calls. */
75     String LOG_TAG = "SyncCallback";
76 
77     /**
78      * Asserts the callback was called or throw if it times out - the timeout value is defined by
79      * the constructor and can be obtained through {@link #getSettings()}.
80      */
assertCalled()81     void assertCalled() throws InterruptedException;
82 
83     /** Returns whether the callback was called (at least) the expected number of times. */
isCalled()84     boolean isCalled();
85 
86     /** Gets the total number of calls so far. */
getNumberActualCalls()87     int getNumberActualCalls();
88 
89     /** Gets the callback settings. */
getSettings()90     SyncCallbackSettings getSettings();
91 }
92