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.config.ConfigurationException; 19 import com.android.tradefed.config.IConfiguration; 20 import com.android.tradefed.invoker.IInvocationContext; 21 import com.android.tradefed.log.ITestLogger; 22 import com.android.tradefed.result.ITestInvocationListener; 23 import com.android.tradefed.util.CommandResult; 24 import com.android.tradefed.util.IRunUtil; 25 import com.android.tradefed.util.keystore.IKeyStoreClient; 26 27 import java.io.File; 28 29 /** Interface defining a sandbox that can be used to run an invocation. */ 30 public interface ISandbox { 31 32 /** 33 * Prepare the environment for the sandbox to run properly. 34 * 35 * @param context the current invocation {@link IInvocationContext}. 36 * @param configuration the {@link IConfiguration} for the command to run. 37 * @param listener the current invocation {@link ITestInvocationListener} where final results 38 * should be piped. 39 * @return an {@link Exception} containing the failure. or Null if successful. 40 */ prepareEnvironment( IInvocationContext context, IConfiguration configuration, ITestInvocationListener listener)41 public Exception prepareEnvironment( 42 IInvocationContext context, 43 IConfiguration configuration, 44 ITestInvocationListener listener); 45 46 /** 47 * Run the sandbox with the environment that was set. 48 * 49 * @param configuration the {@link IConfiguration} for the command to run. 50 * @param logger an {@link ITestLogger} where we can log files. 51 * @return a {@link CommandResult} with the status of the sandbox run and logs. 52 */ run(IConfiguration configuration, ITestLogger logger)53 public CommandResult run(IConfiguration configuration, ITestLogger logger) throws Throwable; 54 55 /** Clean up any states, files or environment that may have been changed. */ tearDown()56 public void tearDown(); 57 58 /** 59 * Returns the sandbox environment TF to be used based on the command line arguments. 60 * 61 * @param context the {@link IInvocationContext} of the parent. 62 * @param nonVersionedConfig the {@link IConfiguration} representing the non versioned objects. 63 * @param args the command line arguments. 64 * @return a {@link File} directory containing the TF sandbox environment jars. 65 */ getTradefedSandboxEnvironment( IInvocationContext context, IConfiguration nonVersionedConfig, String[] args)66 public File getTradefedSandboxEnvironment( 67 IInvocationContext context, IConfiguration nonVersionedConfig, String[] args) 68 throws ConfigurationException; 69 70 /** 71 * Create a classpath based on the environment and the working directory returned by {@link 72 * #getTradefedSandboxEnvironment(IInvocationContext, IConfiguration, String[])}. 73 * 74 * @param workingDir the current working directory for the sandbox. 75 * @return The classpath to be use. 76 */ createClasspath(File workingDir)77 public String createClasspath(File workingDir) throws ConfigurationException; 78 79 /** 80 * Special mode disconnected from main run: When a configuration does not appear to exists in 81 * the parent, we fallback to thin launcher where we attempt to setup the sandbox with currently 82 * known informations and fill up the working directory to create the config fully in the 83 * versioned dir. 84 * 85 * @param args The original command line args. 86 * @param keyStoreClient the current keystore client to use to create configurations. 87 * @param runUtil the current {@link IRunUtil} to run host commands. 88 * @param globalConfig The global configuration to use to run subprocesses of TF. 89 * @return a File pointing to the configuration XML of TF for NON_VERSIONED objects. Returns 90 * null if no thin launcher config could be created. 91 */ createThinLauncherConfig( String[] args, IKeyStoreClient keyStoreClient, IRunUtil runUtil, File globalConfig)92 public IConfiguration createThinLauncherConfig( 93 String[] args, IKeyStoreClient keyStoreClient, IRunUtil runUtil, File globalConfig); 94 } 95