1 /*
2  * Copyright (C) 2016 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.tradefed.targetprep.multi;
17 
18 import com.android.tradefed.device.DeviceNotAvailableException;
19 import com.android.tradefed.invoker.IInvocationContext;
20 import com.android.tradefed.invoker.TestInformation;
21 import com.android.tradefed.targetprep.BuildError;
22 import com.android.tradefed.targetprep.ITargetPreparer;
23 import com.android.tradefed.targetprep.TargetSetupError;
24 import com.android.tradefed.util.IDisableable;
25 
26 /**
27  * Prepares the test environment for several devices together. Only use for a setup that requires
28  * multiple devices, otherwise use the regular {@link ITargetPreparer} on each device.
29  *
30  * <p>Note that multiple {@link IMultiTargetPreparer}s can be specified in a configuration. It is
31  * recommended that each IMultiTargetPreparer clearly document its expected environment pre-setup
32  * and post-setUp.
33  */
34 public interface IMultiTargetPreparer extends IDisableable {
35 
36     /**
37      * Perform the targets setup for testing.
38      *
39      * @param context the {@link IInvocationContext} describing the invocation, devices, builds.
40      * @throws TargetSetupError if fatal error occurred setting up environment
41      * @throws BuildError In case of build related error
42      * @throws DeviceNotAvailableException if device became unresponsive
43      * @deprecated Use {@link #setUp(TestInformation)} instead.
44      */
45     @Deprecated
setUp(IInvocationContext context)46     public default void setUp(IInvocationContext context)
47             throws TargetSetupError, BuildError, DeviceNotAvailableException {
48         // default do nothing.
49     }
50 
51     /**
52      * Perform the targets setup for testing.
53      *
54      * @param testInformation the {@link TestInformation} describing the invocation, devices,
55      *     builds.
56      * @throws TargetSetupError if fatal error occurred setting up environment
57      * @throws BuildError In case of build related error
58      * @throws DeviceNotAvailableException if device became unresponsive
59      */
setUp(TestInformation testInformation)60     public default void setUp(TestInformation testInformation)
61             throws TargetSetupError, BuildError, DeviceNotAvailableException {
62         setUp(testInformation.getContext());
63     }
64 
65     /**
66      * Perform the targets cleanup/teardown after testing.
67      *
68      * @param context the {@link IInvocationContext} describing the invocation, devices, builds.
69      * @param e if the invocation ended with an exception, this will be the exception that was
70      *     caught at the Invocation level. Otherwise, will be <code>null</code>.
71      * @throws DeviceNotAvailableException if device became unresponsive
72      * @deprecated Use {@link #tearDown(TestInformation, Throwable)} instead.
73      */
74     @Deprecated
tearDown(IInvocationContext context, Throwable e)75     public default void tearDown(IInvocationContext context, Throwable e)
76             throws DeviceNotAvailableException {
77         // default do nothing.
78     }
79 
80     /**
81      * Perform the targets cleanup/teardown after testing.
82      *
83      * @param testInformation the {@link TestInformation} describing the invocation, devices,
84      *     builds.
85      * @param e if the invocation ended with an exception, this will be the exception that was
86      *     caught at the Invocation level. Otherwise, will be <code>null</code>.
87      * @throws DeviceNotAvailableException if device became unresponsive
88      */
tearDown(TestInformation testInformation, Throwable e)89     public default void tearDown(TestInformation testInformation, Throwable e)
90             throws DeviceNotAvailableException {
91         tearDown(testInformation.getContext(), e);
92     }
93 }