1 /* 2 * Copyright (C) 2017 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.sandbox; 17 18 import com.android.tradefed.build.BuildRetrievalError; 19 import com.android.tradefed.build.IFolderBuildInfo; 20 import com.android.tradefed.config.ConfigurationException; 21 import com.android.tradefed.config.IConfiguration; 22 import com.android.tradefed.invoker.IInvocationContext; 23 import com.android.tradefed.invoker.TestInformation; 24 import com.android.tradefed.log.ITestLogger; 25 import com.android.tradefed.result.ITestInvocationListener; 26 import com.android.tradefed.util.CommandResult; 27 import com.android.tradefed.util.IRunUtil; 28 import com.android.tradefed.util.keystore.IKeyStoreClient; 29 30 import java.io.File; 31 import java.io.IOException; 32 import java.util.List; 33 import java.util.Map; 34 35 /** Interface defining a sandbox that can be used to run an invocation. */ 36 public interface ISandbox { 37 38 /** 39 * Prepare the environment for the sandbox to run properly. 40 * 41 * @param context the current invocation {@link IInvocationContext}. 42 * @param configuration the {@link IConfiguration} for the command to run. 43 * @param listener the current invocation {@link ITestInvocationListener} where final results 44 * should be piped. 45 * @return an {@link Exception} containing the failure. or Null if successful. 46 */ prepareEnvironment( IInvocationContext context, IConfiguration configuration, ITestInvocationListener listener)47 public Exception prepareEnvironment( 48 IInvocationContext context, 49 IConfiguration configuration, 50 ITestInvocationListener listener); 51 52 /** 53 * Sub-step of {@link #prepareEnvironment(IInvocationContext, IConfiguration, 54 * ITestInvocationListener)} which fetch additional files needed for the sandbox. 55 * 56 * @param context the current invocation {@link IInvocationContext}. 57 * @param configuration the {@link IConfiguration} for the command to run. 58 * @param args the command line arguments. 59 * @return the fetched build for the additional sandboxed files. 60 * @throws BuildRetrievalError 61 * @throws ConfigurationException 62 * @throws IOException 63 */ fetchSandboxExtraArtifacts( IInvocationContext context, IConfiguration configuration, String[] args)64 public default IFolderBuildInfo fetchSandboxExtraArtifacts( 65 IInvocationContext context, IConfiguration configuration, String[] args) 66 throws BuildRetrievalError, ConfigurationException, IOException { 67 return null; 68 } 69 70 /** 71 * A sub-step of {@link #prepareEnvironment(IInvocationContext, IConfiguration, 72 * ITestInvocationListener)} which discovers tests if {@link 73 * SandboxOptions#shouldUseTestDiscovery()} is enabled. 74 * 75 * @param context the current invocation {@link IInvocationContext}. 76 * @param configuration the {@link IConfiguration} for the command to run. 77 * @return The map of discovered tests or null if unsupported or failed. 78 */ discoverTests( IInvocationContext context, IConfiguration configuration)79 public default Map<String, List<String>> discoverTests( 80 IInvocationContext context, IConfiguration configuration) { 81 return null; 82 } 83 discoverTests( IInvocationContext context, IConfiguration configuration, ITestLogger logger)84 public default Map<String, List<String>> discoverTests( 85 IInvocationContext context, IConfiguration configuration, ITestLogger logger) { 86 return discoverTests(context, configuration); 87 } 88 89 /** 90 * Run the sandbox with the environment that was set. 91 * 92 * @param info the {@link TestInformation} describing the invocation 93 * @param configuration the {@link IConfiguration} for the command to run. 94 * @param logger an {@link ITestLogger} where we can log files. 95 * @return a {@link CommandResult} with the status of the sandbox run and logs. 96 */ run(TestInformation info, IConfiguration configuration, ITestLogger logger)97 public CommandResult run(TestInformation info, IConfiguration configuration, ITestLogger logger) 98 throws Throwable; 99 100 /** Clean up any states, files or environment that may have been changed. */ tearDown()101 public void tearDown(); 102 103 /** 104 * Returns the sandbox environment TF to be used based on the command line arguments. 105 * 106 * @param context the {@link IInvocationContext} of the parent. 107 * @param nonVersionedConfig the {@link IConfiguration} representing the non versioned objects. 108 * @param logger the {@link ITestLogger} to log additional files. 109 * @param args the command line arguments. 110 * @return a {@link File} directory containing the TF sandbox environment jars. 111 */ getTradefedSandboxEnvironment( IInvocationContext context, IConfiguration nonVersionedConfig, String[] args)112 public default File getTradefedSandboxEnvironment( 113 IInvocationContext context, IConfiguration nonVersionedConfig, String[] args) 114 throws Exception { 115 return null; 116 } 117 getTradefedSandboxEnvironment( IInvocationContext context, IConfiguration nonVersionedConfig, ITestLogger logger, String[] args)118 public default File getTradefedSandboxEnvironment( 119 IInvocationContext context, 120 IConfiguration nonVersionedConfig, 121 ITestLogger logger, 122 String[] args) 123 throws Exception { 124 return getTradefedSandboxEnvironment(context, nonVersionedConfig, args); 125 } 126 127 /** 128 * Create a classpath based on the environment and the working directory returned by {@link 129 * #getTradefedSandboxEnvironment(IInvocationContext, IConfiguration, String[])}. 130 * 131 * @param workingDir the current working directory for the sandbox. 132 * @return The classpath to be use. 133 */ createClasspath(File workingDir)134 public String createClasspath(File workingDir) throws ConfigurationException; 135 136 /** 137 * Special mode disconnected from main run: When a configuration does not appear to exists in 138 * the parent, we fallback to thin launcher where we attempt to setup the sandbox with currently 139 * known informations and fill up the working directory to create the config fully in the 140 * versioned dir. 141 * 142 * @param args The original command line args. 143 * @param keyStoreClient the current keystore client to use to create configurations. 144 * @param runUtil the current {@link IRunUtil} to run host commands. 145 * @param globalConfig The global configuration to use to run subprocesses of TF. 146 * @return a File pointing to the configuration XML of TF for NON_VERSIONED objects. Returns 147 * null if no thin launcher config could be created. 148 */ createThinLauncherConfig( String[] args, IKeyStoreClient keyStoreClient, IRunUtil runUtil, File globalConfig)149 public IConfiguration createThinLauncherConfig( 150 String[] args, IKeyStoreClient keyStoreClient, IRunUtil runUtil, File globalConfig); 151 } 152