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 17 package com.android.tradefed.config; 18 19 import com.android.tradefed.build.BuildRetrievalError; 20 import com.android.tradefed.build.IBuildProvider; 21 import com.android.tradefed.command.ICommandOptions; 22 import com.android.tradefed.device.IDeviceRecovery; 23 import com.android.tradefed.device.IDeviceSelection; 24 import com.android.tradefed.device.TestDeviceOptions; 25 import com.android.tradefed.device.metric.IMetricCollector; 26 import com.android.tradefed.log.ILeveledLogOutput; 27 import com.android.tradefed.postprocessor.IPostProcessor; 28 import com.android.tradefed.result.ILogSaver; 29 import com.android.tradefed.result.ITestInvocationListener; 30 import com.android.tradefed.retry.IRetryDecision; 31 import com.android.tradefed.suite.checker.ISystemStatusChecker; 32 import com.android.tradefed.targetprep.ITargetPreparer; 33 import com.android.tradefed.targetprep.multi.IMultiTargetPreparer; 34 import com.android.tradefed.testtype.IRemoteTest; 35 import com.android.tradefed.testtype.coverage.CoverageOptions; 36 import com.android.tradefed.util.keystore.IKeyStoreClient; 37 38 import java.io.File; 39 import java.io.IOException; 40 import java.io.PrintStream; 41 import java.io.PrintWriter; 42 import java.util.Collection; 43 import java.util.List; 44 import java.util.Set; 45 46 /** 47 * Configuration information for a TradeFederation invocation. 48 * 49 * Each TradeFederation invocation has a single {@link IConfiguration}. An {@link IConfiguration} 50 * stores all the delegate objects that should be used during the invocation, and their associated 51 * {@link Option}'s 52 */ 53 public interface IConfiguration { 54 55 /** Returns the name of the configuration. */ getName()56 public String getName(); 57 58 /** 59 * Gets the {@link IBuildProvider} from the configuration. 60 * 61 * @return the {@link IBuildProvider} provided in the configuration 62 */ getBuildProvider()63 public IBuildProvider getBuildProvider(); 64 65 /** 66 * Gets the {@link ITargetPreparer}s from the configuration. 67 * 68 * @return the {@link ITargetPreparer}s provided in order in the configuration 69 */ getTargetPreparers()70 public List<ITargetPreparer> getTargetPreparers(); 71 72 /** 73 * Gets the {@link IRemoteTest}s to run from the configuration. 74 * 75 * @return the tests provided in the configuration 76 */ getTests()77 public List<IRemoteTest> getTests(); 78 79 /** 80 * Gets the {@link ITestInvocationListener}s to use from the configuration. 81 * 82 * @return the {@link ITestInvocationListener}s provided in the configuration. 83 */ getTestInvocationListeners()84 public List<ITestInvocationListener> getTestInvocationListeners(); 85 86 /** 87 * Gets the {@link IDeviceRecovery} to use from the configuration. 88 * 89 * @return the {@link IDeviceRecovery} provided in the configuration. 90 */ getDeviceRecovery()91 public IDeviceRecovery getDeviceRecovery(); 92 93 /** 94 * Gets the {@link TestDeviceOptions} to use from the configuration. 95 * 96 * @return the {@link TestDeviceOptions} provided in the configuration. 97 */ getDeviceOptions()98 public TestDeviceOptions getDeviceOptions(); 99 100 /** 101 * Gets the {@link ILeveledLogOutput} to use from the configuration. 102 * 103 * @return the {@link ILeveledLogOutput} provided in the configuration. 104 */ getLogOutput()105 public ILeveledLogOutput getLogOutput(); 106 107 /** 108 * Gets the {@link ILogSaver} to use from the configuration. 109 * 110 * @return the {@link ILogSaver} provided in the configuration. 111 */ getLogSaver()112 public ILogSaver getLogSaver(); 113 114 /** Returns the {@link IRetryDecision} used for the invocation. */ getRetryDecision()115 public IRetryDecision getRetryDecision(); 116 117 /** 118 * Gets the {@link IMultiTargetPreparer}s from the configuration. 119 * 120 * @return the {@link IMultiTargetPreparer}s provided in order in the configuration 121 */ getMultiTargetPreparers()122 public List<IMultiTargetPreparer> getMultiTargetPreparers(); 123 124 /** 125 * Gets the {@link IMultiTargetPreparer}s from the configuration that should be executed before 126 * any of the devices target_preparers. 127 * 128 * @return the {@link IMultiTargetPreparer}s provided in order in the configuration 129 */ getMultiPreTargetPreparers()130 public List<IMultiTargetPreparer> getMultiPreTargetPreparers(); 131 132 /** 133 * Gets the {@link ISystemStatusChecker}s from the configuration. 134 * 135 * @return the {@link ISystemStatusChecker}s provided in order in the configuration 136 */ getSystemStatusCheckers()137 public List<ISystemStatusChecker> getSystemStatusCheckers(); 138 139 /** Gets the {@link IMetricCollector}s from the configuration. */ getMetricCollectors()140 public List<IMetricCollector> getMetricCollectors(); 141 142 /** Gets the {@link IPostProcessor}s from the configuration. */ getPostProcessors()143 public List<IPostProcessor> getPostProcessors(); 144 145 /** 146 * Gets the {@link ICommandOptions} to use from the configuration. 147 * 148 * @return the {@link ICommandOptions} provided in the configuration. 149 */ getCommandOptions()150 public ICommandOptions getCommandOptions(); 151 152 /** Returns the {@link ConfigurationDescriptor} provided in the configuration. */ getConfigurationDescription()153 public ConfigurationDescriptor getConfigurationDescription(); 154 155 /** 156 * Gets the {@link IDeviceSelection} to use from the configuration. 157 * 158 * @return the {@link IDeviceSelection} provided in the configuration. 159 */ getDeviceRequirements()160 public IDeviceSelection getDeviceRequirements(); 161 162 /** 163 * Gets the {@link CoverageOptions} to use from the configuration. 164 * 165 * @return the {@link CoverageOptions} provided in the configuration. 166 */ getCoverageOptions()167 public CoverageOptions getCoverageOptions(); 168 169 /** 170 * Generic interface to get the configuration object with the given type name. 171 * 172 * @param typeName the unique type of the configuration object 173 * 174 * @return the configuration object or <code>null</code> if the object type with given name 175 * does not exist. 176 */ getConfigurationObject(String typeName)177 public Object getConfigurationObject(String typeName); 178 179 /** 180 * Generic interface to get all the object of one given type name across devices. 181 * 182 * @param typeName the unique type of the configuration object 183 * @return The list of configuration objects of the given type. 184 */ getAllConfigurationObjectsOfType(String typeName)185 public Collection<Object> getAllConfigurationObjectsOfType(String typeName); 186 187 /** 188 * Similar to {@link #getConfigurationObject(String)}, but for configuration 189 * object types that support multiple objects. 190 * 191 * @param typeName the unique type name of the configuration object 192 * 193 * @return the list of configuration objects or <code>null</code> if the object type with 194 * given name does not exist. 195 */ getConfigurationObjectList(String typeName)196 public List<?> getConfigurationObjectList(String typeName); 197 198 /** 199 * Gets the {@link IDeviceConfiguration}s from the configuration. 200 * 201 * @return the {@link IDeviceConfiguration}s provided in order in the configuration 202 */ getDeviceConfig()203 public List<IDeviceConfiguration> getDeviceConfig(); 204 205 /** 206 * Return the {@link IDeviceConfiguration} associated to the name provided, null if not found. 207 */ getDeviceConfigByName(String nameDevice)208 public IDeviceConfiguration getDeviceConfigByName(String nameDevice); 209 210 /** 211 * Inject a option value into the set of configuration objects. 212 * <p/> 213 * Useful to provide values for options that are generated dynamically. 214 * 215 * @param optionName the option name 216 * @param optionValue the option value 217 * @throws ConfigurationException if failed to set the option's value 218 */ injectOptionValue(String optionName, String optionValue)219 public void injectOptionValue(String optionName, String optionValue) 220 throws ConfigurationException; 221 222 /** 223 * Inject a option value into the set of configuration objects. 224 * <p/> 225 * Useful to provide values for options that are generated dynamically. 226 * 227 * @param optionName the option name 228 * @param optionKey the optional key for map options, or null 229 * @param optionValue the map option value 230 * @throws ConfigurationException if failed to set the option's value 231 */ injectOptionValue(String optionName, String optionKey, String optionValue)232 public void injectOptionValue(String optionName, String optionKey, String optionValue) 233 throws ConfigurationException; 234 235 /** 236 * Inject a option value into the set of configuration objects. 237 * <p/> 238 * Useful to provide values for options that are generated dynamically. 239 * 240 * @param optionName the option name 241 * @param optionKey the optional key for map options, or null 242 * @param optionValue the map option value 243 * @param optionSource the source config that provided this option value 244 * @throws ConfigurationException if failed to set the option's value 245 */ injectOptionValueWithSource(String optionName, String optionKey, String optionValue, String optionSource)246 public void injectOptionValueWithSource(String optionName, String optionKey, String optionValue, 247 String optionSource) throws ConfigurationException; 248 249 /** 250 * Inject multiple option values into the set of configuration objects. 251 * <p/> 252 * Useful to inject many option values at once after creating a new object. 253 * 254 * @param optionDefs a list of option defs to inject 255 * @throws ConfigurationException if failed to set option values 256 */ injectOptionValues(List<OptionDef> optionDefs)257 public void injectOptionValues(List<OptionDef> optionDefs) throws ConfigurationException; 258 259 /** 260 * Create a shallow copy of this object. 261 * 262 * @return a {link IConfiguration} copy 263 */ clone()264 public IConfiguration clone(); 265 266 /** 267 * Create a base clone from {@link #clone()} then deep clone the list of given config object. 268 * 269 * @param objectToDeepClone The list of configuration object to deep clone. 270 * @param client The keystore client. 271 * @return The partially deep cloned config. 272 * @throws ConfigurationException 273 */ partialDeepClone(List<String> objectToDeepClone, IKeyStoreClient client)274 public IConfiguration partialDeepClone(List<String> objectToDeepClone, IKeyStoreClient client) 275 throws ConfigurationException; 276 277 /** 278 * Replace the current {@link IBuildProvider} in the configuration. 279 * 280 * @param provider the new {@link IBuildProvider} 281 */ setBuildProvider(IBuildProvider provider)282 public void setBuildProvider(IBuildProvider provider); 283 284 /** 285 * Set the {@link ILeveledLogOutput}, replacing any existing value. 286 * 287 * @param logger 288 */ setLogOutput(ILeveledLogOutput logger)289 public void setLogOutput(ILeveledLogOutput logger); 290 291 /** 292 * Set the {@link IRetryDecision}, replacing any existing value. 293 * 294 * @param decisionRetry 295 */ setRetryDecision(IRetryDecision decisionRetry)296 public void setRetryDecision(IRetryDecision decisionRetry); 297 298 /** 299 * Set the {@link ILogSaver}, replacing any existing value. 300 * 301 * @param logSaver 302 */ setLogSaver(ILogSaver logSaver)303 public void setLogSaver(ILogSaver logSaver); 304 305 /** 306 * Set the {@link IDeviceRecovery}, replacing any existing value. 307 * 308 * @param recovery 309 */ setDeviceRecovery(IDeviceRecovery recovery)310 public void setDeviceRecovery(IDeviceRecovery recovery); 311 312 /** 313 * Set the {@link ITargetPreparer}, replacing any existing value. 314 * 315 * @param preparer 316 */ setTargetPreparer(ITargetPreparer preparer)317 public void setTargetPreparer(ITargetPreparer preparer); 318 319 /** 320 * Set the list of {@link ITargetPreparer}s, replacing any existing value. 321 * 322 * @param preparers 323 */ setTargetPreparers(List<ITargetPreparer> preparers)324 public void setTargetPreparers(List<ITargetPreparer> preparers); 325 326 /** 327 * Set a {@link IDeviceConfiguration}, replacing any existing value. 328 * 329 * @param deviceConfig 330 */ setDeviceConfig(IDeviceConfiguration deviceConfig)331 public void setDeviceConfig(IDeviceConfiguration deviceConfig); 332 333 /** 334 * Set the {@link IDeviceConfiguration}s, replacing any existing value. 335 * 336 * @param deviceConfigs 337 */ setDeviceConfigList(List<IDeviceConfiguration> deviceConfigs)338 public void setDeviceConfigList(List<IDeviceConfiguration> deviceConfigs); 339 340 /** 341 * Convenience method to set a single {@link IRemoteTest} in this configuration, replacing any 342 * existing values 343 * 344 * @param test 345 */ setTest(IRemoteTest test)346 public void setTest(IRemoteTest test); 347 348 /** 349 * Set the list of {@link IRemoteTest}s in this configuration, replacing any 350 * existing values 351 * 352 * @param tests 353 */ setTests(List<IRemoteTest> tests)354 public void setTests(List<IRemoteTest> tests); 355 356 /** 357 * Set the list of {@link IMultiTargetPreparer}s in this configuration, replacing any 358 * existing values 359 * 360 * @param multiTargPreps 361 */ setMultiTargetPreparers(List<IMultiTargetPreparer> multiTargPreps)362 public void setMultiTargetPreparers(List<IMultiTargetPreparer> multiTargPreps); 363 364 /** 365 * Convenience method to set a single {@link IMultiTargetPreparer} in this configuration, 366 * replacing any existing values 367 * 368 * @param multiTargPrep 369 */ setMultiTargetPreparer(IMultiTargetPreparer multiTargPrep)370 public void setMultiTargetPreparer(IMultiTargetPreparer multiTargPrep); 371 372 /** 373 * Set the list of {@link IMultiTargetPreparer}s in this configuration that should be executed 374 * before any of the devices target_preparers, replacing any existing values 375 * 376 * @param multiPreTargPreps 377 */ setMultiPreTargetPreparers(List<IMultiTargetPreparer> multiPreTargPreps)378 public void setMultiPreTargetPreparers(List<IMultiTargetPreparer> multiPreTargPreps); 379 380 /** 381 * Convenience method to set a single {@link IMultiTargetPreparer} in this configuration that 382 * should be executed before any of the devices target_preparers, replacing any existing values 383 * 384 * @param multiPreTargPreps 385 */ setMultiPreTargetPreparer(IMultiTargetPreparer multiPreTargPreps)386 public void setMultiPreTargetPreparer(IMultiTargetPreparer multiPreTargPreps); 387 388 /** 389 * Set the list of {@link ISystemStatusChecker}s in this configuration, replacing any 390 * existing values 391 * 392 * @param systemCheckers 393 */ setSystemStatusCheckers(List<ISystemStatusChecker> systemCheckers)394 public void setSystemStatusCheckers(List<ISystemStatusChecker> systemCheckers); 395 396 /** 397 * Convenience method to set a single {@link ISystemStatusChecker} in this configuration, 398 * replacing any existing values 399 * 400 * @param systemChecker 401 */ setSystemStatusChecker(ISystemStatusChecker systemChecker)402 public void setSystemStatusChecker(ISystemStatusChecker systemChecker); 403 404 /** 405 * Set the list of {@link ITestInvocationListener}s, replacing any existing values 406 * 407 * @param listeners 408 */ setTestInvocationListeners(List<ITestInvocationListener> listeners)409 public void setTestInvocationListeners(List<ITestInvocationListener> listeners); 410 411 /** 412 * Convenience method to set a single {@link ITestInvocationListener} 413 * 414 * @param listener 415 */ setTestInvocationListener(ITestInvocationListener listener)416 public void setTestInvocationListener(ITestInvocationListener listener); 417 418 /** Set the list of {@link IMetricCollector}s, replacing any existing values. */ setDeviceMetricCollectors(List<IMetricCollector> collectors)419 public void setDeviceMetricCollectors(List<IMetricCollector> collectors); 420 421 /** Set the list of {@link IPostProcessor}s, replacing any existing values. */ setPostProcessors(List<IPostProcessor> processors)422 public void setPostProcessors(List<IPostProcessor> processors); 423 424 /** 425 * Set the {@link ICommandOptions}, replacing any existing values 426 * 427 * @param cmdOptions 428 */ setCommandOptions(ICommandOptions cmdOptions)429 public void setCommandOptions(ICommandOptions cmdOptions); 430 431 /** 432 * Set the {@link IDeviceSelection}, replacing any existing values 433 * 434 * @param deviceSelection 435 */ setDeviceRequirements(IDeviceSelection deviceSelection)436 public void setDeviceRequirements(IDeviceSelection deviceSelection); 437 438 /** 439 * Set the {@link TestDeviceOptions}, replacing any existing values 440 */ setDeviceOptions(TestDeviceOptions deviceOptions)441 public void setDeviceOptions(TestDeviceOptions deviceOptions); 442 443 /** Set the {@link CoverageOptions}, replacing any existing values. */ setCoverageOptions(CoverageOptions coverageOptions)444 public void setCoverageOptions(CoverageOptions coverageOptions); 445 446 /** 447 * Generic method to set the config object with the given name, replacing any existing value. 448 * 449 * @param name the unique name of the config object type. 450 * @param configObject the config object 451 * @throws ConfigurationException if the configObject was not the correct type 452 */ setConfigurationObject(String name, Object configObject)453 public void setConfigurationObject(String name, Object configObject) 454 throws ConfigurationException; 455 456 /** 457 * Generic method to set the config object list for the given name, replacing any existing 458 * value. 459 * 460 * @param name the unique name of the config object type. 461 * @param configList the config object list 462 * @throws ConfigurationException if any objects in the list are not the correct type 463 */ setConfigurationObjectList(String name, List<?> configList)464 public void setConfigurationObjectList(String name, List<?> configList) 465 throws ConfigurationException; 466 467 /** Returns whether or not a configured device is tagged isFake=true or not. */ isDeviceConfiguredFake(String deviceName)468 public boolean isDeviceConfiguredFake(String deviceName); 469 470 /** 471 * Set the config {@link Option} fields with given set of command line arguments 472 * <p/> 473 * {@link ArgsOptionParser} for expected format 474 * 475 * @param listArgs the command line arguments 476 * @return the unconsumed arguments 477 */ setOptionsFromCommandLineArgs(List<String> listArgs)478 public List<String> setOptionsFromCommandLineArgs(List<String> listArgs) 479 throws ConfigurationException; 480 481 /** 482 * Set the config {@link Option} fields with given set of command line arguments 483 * <p/> 484 * See {@link ArgsOptionParser} for expected format 485 * 486 * @param listArgs the command line arguments 487 * @param keyStoreClient {@link IKeyStoreClient} to use. 488 * @return the unconsumed arguments 489 */ setOptionsFromCommandLineArgs(List<String> listArgs, IKeyStoreClient keyStoreClient)490 public List<String> setOptionsFromCommandLineArgs(List<String> listArgs, 491 IKeyStoreClient keyStoreClient) 492 throws ConfigurationException; 493 494 /** 495 * Outputs a command line usage help text for this configuration to given printStream. 496 * 497 * @param importantOnly if <code>true</code> only print help for the important options 498 * @param out the {@link PrintStream} to use. 499 * @throws ConfigurationException 500 */ printCommandUsage(boolean importantOnly, PrintStream out)501 public void printCommandUsage(boolean importantOnly, PrintStream out) 502 throws ConfigurationException; 503 504 /** 505 * Validate option values. 506 * <p/> 507 * Currently this will just validate that all mandatory options have been set 508 * 509 * @throws ConfigurationException if config is not valid 510 */ validateOptions()511 public void validateOptions() throws ConfigurationException; 512 513 /** 514 * Resolve options of {@link File} pointing to a remote location. This requires {@link 515 * #cleanConfigurationData()} to be called to clean up the files. 516 * 517 * @param resolver the {@link DynamicRemoteFileResolver} to resolve the files 518 * @throws BuildRetrievalError 519 * @throws ConfigurationException 520 */ resolveDynamicOptions(DynamicRemoteFileResolver resolver)521 public void resolveDynamicOptions(DynamicRemoteFileResolver resolver) 522 throws ConfigurationException, BuildRetrievalError; 523 524 /** Delete any files that was downloaded to resolved Option fields of remote files. */ cleanConfigurationData()525 public void cleanConfigurationData(); 526 527 /** Add files that must be cleaned during {@link #cleanConfigurationData()} */ addFilesToClean(Set<File> toBeCleaned)528 public void addFilesToClean(Set<File> toBeCleaned); 529 530 /** Get the list of files that will be cleaned during {@link #cleanConfigurationData()} */ getFilesToClean()531 public Set<File> getFilesToClean(); 532 533 /** 534 * Sets the command line used to create this {@link IConfiguration}. 535 * This stores the whole command line, including the configuration name, 536 * unlike setOptionsFromCommandLineArgs. 537 * 538 * @param arrayArgs the command line 539 */ setCommandLine(String[] arrayArgs)540 public void setCommandLine(String[] arrayArgs); 541 542 /** 543 * Gets the command line used to create this {@link IConfiguration}. 544 * 545 * @return the command line used to create this {@link IConfiguration}. 546 */ getCommandLine()547 public String getCommandLine(); 548 549 /** 550 * Gets the expanded XML file for the config with all options shown for this 551 * {@link IConfiguration} as a {@link String}. 552 * 553 * @param output the writer to print the xml to. 554 * @throws IOException 555 */ dumpXml(PrintWriter output)556 public void dumpXml(PrintWriter output) throws IOException; 557 558 /** 559 * Gets the expanded XML file for the config with all options shown for this {@link 560 * IConfiguration} minus the objects filters by their key name. 561 * 562 * <p>Filter example: {@link Configuration#TARGET_PREPARER_TYPE_NAME}. 563 * 564 * @param output the writer to print the xml to. 565 * @param excludeFilters the list of object type that should not be dumped. 566 * @throws IOException 567 */ dumpXml(PrintWriter output, List<String> excludeFilters)568 public void dumpXml(PrintWriter output, List<String> excludeFilters) throws IOException; 569 570 /** 571 * Gets the expanded XML file for the config with all options shown for this {@link 572 * IConfiguration} minus the objects filters by their key name. 573 * 574 * <p>Filter example: {@link Configuration#TARGET_PREPARER_TYPE_NAME}. 575 * 576 * @param output the writer to print the xml to. 577 * @param excludeFilters the list of object type that should not be dumped. 578 * @param printDeprecatedOptions Whether or not to print options marked as deprecated 579 * @throws IOException 580 */ dumpXml( PrintWriter output, List<String> excludeFilters, boolean printDeprecatedOptions, boolean printUnchangedOptions)581 public void dumpXml( 582 PrintWriter output, 583 List<String> excludeFilters, 584 boolean printDeprecatedOptions, 585 boolean printUnchangedOptions) 586 throws IOException; 587 } 588