1 /*
2  * Copyright (C) 2010 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;
17 
18 import com.android.tradefed.build.IBuildInfo;
19 import com.android.tradefed.device.DeviceNotAvailableException;
20 import com.android.tradefed.device.ITestDevice;
21 import com.android.tradefed.invoker.TestInformation;
22 import com.android.tradefed.util.IDisableable;
23 
24 /**
25  * Prepares the test environment for the test run.
26  *
27  * <p>For example, installs software, tweaks env settings for testing, launches targets etc.
28  *
29  * <p>Note that multiple {@link ITargetPreparer}s can be specified in a configuration. It is
30  * recommended that each ITargetPreparer clearly document its expected environment pre-setup and
31  * post-setUp. e.g. a ITargetPreparer that configures a device for testing must be run after the
32  * ITargetPreparer that installs software.
33  */
34 public interface ITargetPreparer extends IDisableable {
35 
36     /**
37      * Perform the target setup for testing.
38      *
39      * @param device the {@link ITestDevice} to prepare.
40      * @param buildInfo data about the build under test.
41      * @throws TargetSetupError if fatal error occurred setting up environment
42      * @throws BuildError If an error related to the BuildInfo occurs
43      * @throws DeviceNotAvailableException if device became unresponsive
44      * @deprecated Use {@link #setUp(TestInformation)} instead
45      */
46     @Deprecated
setUp(ITestDevice device, IBuildInfo buildInfo)47     public default void setUp(ITestDevice device, IBuildInfo buildInfo)
48             throws TargetSetupError, BuildError, DeviceNotAvailableException {
49         // Throw if not implemented: If the new interface is implemented this won't be called. If
50         // something is calling the old interface instead of new one, then it will throw and report
51         // the error.
52         throw new UnsupportedOperationException(
53                 "setUp(ITestDevice, IBuildInfo) is deprecated. You need to update to the "
54                         + "new setUp(TestInformation).");
55     }
56 
57     /**
58      * Perform the target setup for testing.
59      *
60      * @param testInformation The {@link TestInformation} of the invocation.
61      * @throws TargetSetupError if fatal error occurred setting up environment
62      * @throws BuildError If an error occurs due to the build being prepared
63      * @throws DeviceNotAvailableException if device became unresponsive
64      */
setUp(TestInformation testInformation)65     public default void setUp(TestInformation testInformation)
66             throws TargetSetupError, BuildError, DeviceNotAvailableException {
67         setUp(testInformation.getDevice(), testInformation.getBuildInfo());
68     }
69 
70     /**
71      * Perform the target cleanup/teardown after testing.
72      *
73      * @param device the {@link ITestDevice} to prepare.
74      * @param buildInfo data about the build under test.
75      * @param e if the invocation ended with an exception, this will be the exception that was
76      *     caught at the Invocation level. Otherwise, will be <code>null</code>.
77      * @throws DeviceNotAvailableException if device became unresponsive
78      * @deprecated Use {@link #tearDown(TestInformation, Throwable)} instead
79      */
80     @Deprecated
tearDown(ITestDevice device, IBuildInfo buildInfo, Throwable e)81     public default void tearDown(ITestDevice device, IBuildInfo buildInfo, Throwable e)
82             throws DeviceNotAvailableException {
83         // Nothing by default.
84     }
85 
86     /**
87      * Perform the target cleanup/teardown after testing.
88      *
89      * @param testInformation The {@link TestInformation} of the invocation.
90      * @param e if the invocation ended with an exception, this will be the exception that was
91      *     caught at the Invocation level. Otherwise, will be <code>null</code>.
92      * @throws DeviceNotAvailableException if device became unresponsive
93      */
tearDown(TestInformation testInformation, Throwable e)94     public default void tearDown(TestInformation testInformation, Throwable e)
95             throws DeviceNotAvailableException {
96         tearDown(testInformation.getDevice(), testInformation.getBuildInfo(), e);
97     }
98 }
99