1 /* 2 * Copyright (C) 2012 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 17 package com.android.tradefed.config; 18 19 import com.android.tradefed.command.ICommandScheduler; 20 import com.android.tradefed.device.DeviceManager; 21 import com.android.tradefed.device.IDeviceManager; 22 import com.android.tradefed.device.IDeviceMonitor; 23 import com.android.tradefed.device.IDeviceSelection; 24 import com.android.tradefed.device.IMultiDeviceRecovery; 25 import com.android.tradefed.host.IHostOptions; 26 import com.android.tradefed.host.IHostResourceManager; 27 import com.android.tradefed.host.LocalHostResourceManager; 28 import com.android.tradefed.invoker.shard.IShardHelper; 29 import com.android.tradefed.log.ITerribleFailureHandler; 30 import com.android.tradefed.sandbox.ISandboxFactory; 31 import com.android.tradefed.util.hostmetric.IHostMonitor; 32 import com.android.tradefed.util.keystore.IKeyStoreFactory; 33 34 import java.io.File; 35 import java.io.IOException; 36 import java.util.List; 37 import java.util.Set; 38 39 /** 40 * A class to encompass global configuration information for a single Trade Federation instance 41 * (encompassing any number of invocations of actual configurations). 42 */ 43 public interface IGlobalConfiguration { 44 /** 45 * Gets the {@link IHostOptions} to use from the configuration. 46 * 47 * @return the {@link IDeviceManager} provided in the configuration. 48 */ getHostOptions()49 public IHostOptions getHostOptions(); 50 51 /** 52 * Gets the {@link IHostResourceManager} from the global config. 53 * 54 * @return the {@link IHostResourceManager} from the global config, or default implementation 55 * {@link LocalHostResourceManager} if none is specified in host config. 56 */ getHostResourceManager()57 public IHostResourceManager getHostResourceManager(); 58 59 /** 60 * Gets the list of {@link IDeviceMonitor} from the global config. 61 * 62 * @return the list of {@link IDeviceMonitor} from the global config, or <code>null</code> if 63 * none was specified. 64 */ getDeviceMonitors()65 public List<IDeviceMonitor> getDeviceMonitors(); 66 67 /** 68 * Gets the list of {@link IHostMonitor} from the global config. 69 * 70 * @return the list of {@link IHostMonitor} from the global config, or <code>null</code> if none 71 * was specified. 72 */ getHostMonitors()73 public List<IHostMonitor> getHostMonitors(); 74 75 /** 76 * Set the {@link IDeviceMonitor}. 77 * 78 * @param deviceMonitor The monitor 79 * @throws ConfigurationException if an {@link IDeviceMonitor} has already been set. 80 */ setDeviceMonitor(IDeviceMonitor deviceMonitor)81 public void setDeviceMonitor(IDeviceMonitor deviceMonitor) throws ConfigurationException; 82 83 /** 84 * Set the {@link IHostMonitor} list. 85 * 86 * @param hostMonitors The list of monitors 87 * @throws ConfigurationException if an {@link IHostMonitor} has already been set. 88 */ setHostMonitors(List<IHostMonitor> hostMonitors)89 public void setHostMonitors(List<IHostMonitor> hostMonitors) throws ConfigurationException; 90 91 /** 92 * Set the {@link ITerribleFailureHandler}. 93 * 94 * @param wtfHandler the WTF handler 95 * @throws ConfigurationException if an {@link ITerribleFailureHandler} has 96 * already been set. 97 */ setWtfHandler(ITerribleFailureHandler wtfHandler)98 public void setWtfHandler(ITerribleFailureHandler wtfHandler) throws ConfigurationException; 99 100 /** 101 * Generic method to set the config object list for the given name, replacing any existing 102 * value. 103 * 104 * @param typeName the unique name of the config object type. 105 * @param configList the config object list 106 * @throws ConfigurationException if any objects in the list are not the correct type 107 */ setConfigurationObjectList(String typeName, List<?> configList)108 public void setConfigurationObjectList(String typeName, List<?> configList) 109 throws ConfigurationException; 110 111 /** 112 * Inject a option value into the set of configuration objects. 113 * <p/> 114 * Useful to provide values for options that are generated dynamically. 115 * 116 * @param optionName the option name 117 * @param optionValue the option value(s) 118 * @throws ConfigurationException if failed to set the option's value 119 */ injectOptionValue(String optionName, String optionValue)120 public void injectOptionValue(String optionName, String optionValue) 121 throws ConfigurationException; 122 123 /** 124 * Inject a option value into the set of configuration objects. 125 * <p/> 126 * Useful to provide values for options that are generated dynamically. 127 * 128 * @param optionName the map option name 129 * @param optionKey the map option key 130 * @param optionValue the map option value 131 * @throws ConfigurationException if failed to set the option's value 132 */ injectOptionValue(String optionName, String optionKey, String optionValue)133 public void injectOptionValue(String optionName, String optionKey, String optionValue) 134 throws ConfigurationException; 135 136 /** 137 * Get a list of option's values. 138 * 139 * @param optionName the map option name 140 * @return a list of the given option's values. <code>null</code> if the option name does not 141 * exist. 142 */ getOptionValues(String optionName)143 public List<String> getOptionValues(String optionName); 144 145 /** 146 * Set the global config {@link Option} fields with given set of command line arguments 147 * <p/> 148 * See {@link ArgsOptionParser} for expected format 149 * 150 * @param listArgs the command line arguments 151 * @return the unconsumed arguments 152 */ setOptionsFromCommandLineArgs(List<String> listArgs)153 public List<String> setOptionsFromCommandLineArgs(List<String> listArgs) 154 throws ConfigurationException; 155 156 /** 157 * Set the {@link IDeviceSelection}, replacing any existing values. This sets a global device 158 * filter on which devices the {@link DeviceManager} can see. 159 * 160 * @param deviceSelection 161 */ setDeviceRequirements(IDeviceSelection deviceSelection)162 public void setDeviceRequirements(IDeviceSelection deviceSelection); 163 164 /** 165 * Gets the {@link IDeviceSelection} to use from the configuration. Represents a global filter 166 * on which devices the {@link DeviceManager} can see. 167 * 168 * @return the {@link IDeviceSelection} provided in the configuration. 169 */ getDeviceRequirements()170 public IDeviceSelection getDeviceRequirements(); 171 172 /** 173 * Gets the {@link IDeviceManager} to use from the configuration. Manages the set of available 174 * devices for testing 175 * 176 * @return the {@link IDeviceManager} provided in the configuration. 177 */ getDeviceManager()178 public IDeviceManager getDeviceManager(); 179 180 /** 181 * Gets the {@link ITerribleFailureHandler} to use from the configuration. 182 * Handles what to do in the event that a WTF (What a Terrible Failure) 183 * occurs. 184 * 185 * @return the {@link ITerribleFailureHandler} provided in the 186 * configuration, or null if no handler is set 187 */ getWtfHandler()188 public ITerribleFailureHandler getWtfHandler(); 189 190 /** 191 * Gets the {@link ICommandScheduler} to use from the configuration. 192 * 193 * @return the {@link ICommandScheduler}. Will never return null. 194 */ getCommandScheduler()195 public ICommandScheduler getCommandScheduler(); 196 197 /** 198 * Gets the list of {@link IMultiDeviceRecovery} to use from the configuration. 199 * 200 * @return the list of {@link IMultiDeviceRecovery}, or <code>null</code> if not set. 201 */ getMultiDeviceRecoveryHandlers()202 public List<IMultiDeviceRecovery> getMultiDeviceRecoveryHandlers(); 203 204 205 /** 206 * Gets the {@link IKeyStoreFactory} to use from the configuration. 207 * 208 * @return the {@link IKeyStoreFactory} or null if no key store factory is set. 209 */ getKeyStoreFactory()210 public IKeyStoreFactory getKeyStoreFactory(); 211 212 /** Returns the {@link IShardHelper} that defines the way to shard a configuration. */ getShardingStrategy()213 public IShardHelper getShardingStrategy(); 214 215 /** 216 * Set the {@link IHostOptions}, replacing any existing values. 217 * 218 * @param hostOptions 219 */ setHostOptions(IHostOptions hostOptions)220 public void setHostOptions(IHostOptions hostOptions); 221 222 /** 223 * Set the {@link IHostResourceManager}, replacing any existing values. 224 * 225 * @param hostResourceManager 226 */ setHostResourceManager(IHostResourceManager hostResourceManager)227 public void setHostResourceManager(IHostResourceManager hostResourceManager); 228 229 /** 230 * Set the {@link IDeviceManager}, replacing any existing values. This sets the manager for the 231 * test devices 232 * 233 * @param deviceManager 234 */ setDeviceManager(IDeviceManager deviceManager)235 public void setDeviceManager(IDeviceManager deviceManager); 236 237 /** 238 * Set the {@link ICommandScheduler}, replacing any existing values. 239 * 240 * @param scheduler 241 */ setCommandScheduler(ICommandScheduler scheduler)242 public void setCommandScheduler(ICommandScheduler scheduler); 243 244 /** 245 * Set the {@link ISandboxFactory}, replacing any existing values. 246 * 247 * @param factory 248 */ setSandboxFactory(ISandboxFactory factory)249 public void setSandboxFactory(ISandboxFactory factory); 250 251 /** 252 * Set the {@link IKeyStoreFactory}, replacing any existing values. 253 * 254 * @param factory 255 */ setKeyStoreFactory(IKeyStoreFactory factory)256 public void setKeyStoreFactory(IKeyStoreFactory factory); 257 258 /** Sets the {@link IShardHelper} to be used when sharding a configuration. */ setShardingStrategy(IShardHelper sharding)259 public void setShardingStrategy(IShardHelper sharding); 260 261 /** 262 * Generic method to set the config object with the given name, replacing any existing value. 263 * 264 * @param name the unique name of the config object type. 265 * @param configObject the config object 266 * @throws ConfigurationException if the configObject was not the correct type 267 */ setConfigurationObject(String name, Object configObject)268 public void setConfigurationObject(String name, Object configObject) 269 throws ConfigurationException; 270 271 /** 272 * Gets the custom configuration object with given name. 273 * 274 * @param typeName the unique type of the configuration object 275 * @return the object or null if object with that name is not found 276 */ getConfigurationObject(String typeName)277 public Object getConfigurationObject(String typeName); 278 279 /** 280 * Gets global config server. Global config server is used to get host configs from a server 281 * instead of getting it from local files. 282 */ getGlobalConfigServer()283 public IConfigurationServer getGlobalConfigServer(); 284 285 /** Get a sandbox factory that can be used to run an invocation */ getSandboxFactory()286 public ISandboxFactory getSandboxFactory(); 287 288 /** 289 * Validate option values. 290 * 291 * <p>Currently this will just validate that all mandatory options have been set 292 * 293 * @throws ConfigurationException if configuration is missing mandatory fields 294 */ validateOptions()295 public void validateOptions() throws ConfigurationException; 296 297 /** 298 * Filter the GlobalConfiguration based on a allowed list and output to an XML file. 299 * 300 * <p>For example, for following configuration: 301 * {@code 302 * <xml> 303 * <configuration> 304 * <device_monitor class="com.android.tradefed.device.DeviceMonitorMultiplexer" /> 305 * <wtf_handler class="com.android.tradefed.log.TerribleFailureEmailHandler" /> 306 * <key_store class="com.android.tradefed.util.keystore.JSONFileKeyStoreFactory" /> 307 * </configuration> 308 * </xml> 309 * } 310 * 311 * <p>all config except "key_store" will be filtered out, and result a config file with 312 * following content: 313 * {@code 314 * <xml> 315 * <configuration> 316 * <key_store class="com.android.tradefed.util.keystore.JSONFileKeyStoreFactory" /> 317 * </configuration> 318 * </xml> 319 * } 320 * 321 * @param allowlistConfigs a {@link String} array of configs to be included in the new XML file. 322 * If it's set to <code>null<code/>, a default list should be used. 323 * @return the File containing the new filtered global config. 324 * @throws IOException 325 */ cloneConfigWithFilter(String... allowlistConfigs)326 public File cloneConfigWithFilter(String... allowlistConfigs) throws IOException; 327 328 /** 329 * Filter the GlobalConfiguration based on a white list and output to an XML file. 330 * @see #cloneConfigWithFilter(String...) 331 * 332 * @param exclusionPatterns The pattern of class name to exclude from the dump. 333 * @param allowlistConfigs a {@link String} array of configs to be included in the new XML file. 334 * If it's set to <code>null<code/>, a default list should be used. 335 * @return the File containing the new filtered global config. 336 * @throws IOException 337 */ cloneConfigWithFilter(Set<String> exclusionPatterns, String... allowlistConfigs)338 public File cloneConfigWithFilter(Set<String> exclusionPatterns, String... allowlistConfigs) 339 throws IOException; 340 341 /** 342 * Proper setup at the start of tradefed. 343 * 344 * @throws ConfigurationException 345 */ setup()346 public void setup() throws ConfigurationException; 347 348 /** Proper cleanup when tradefed shutdown. */ cleanup()349 public void cleanup(); 350 351 /** Sets the original config used to create the global configuration. */ setOriginalConfig(String config)352 public void setOriginalConfig(String config); 353 354 /** Set the {@link IConfigurationFactory} for this configuration. */ setConfigurationFactory(IConfigurationFactory configFactory)355 public void setConfigurationFactory(IConfigurationFactory configFactory); 356 } 357