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