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