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.util.keystore.IKeyStoreClient; 20 21 import java.io.PrintStream; 22 import java.util.List; 23 24 /** 25 * Factory for creating {@link IConfiguration}s 26 */ 27 public interface IConfigurationFactory { 28 29 /** 30 * A convenience method which calls {@link #createConfigurationFromArgs(String[], List)} 31 * with a {@code null} second argument. Thus, it will throw {@link ConfigurationException} if 32 * any unconsumed arguments remain. 33 * 34 * @see #createConfigurationFromArgs(String[], List) 35 */ 36 public IConfiguration createConfigurationFromArgs(String[] args) throws ConfigurationException; 37 38 /** 39 * Create the {@link IConfiguration} from command line arguments. 40 * <p/> 41 * Expected format is "CONFIG [options]", where CONFIG is the built-in configuration name or 42 * a file path to a configuration xml file. 43 * 44 * @param args the command line arguments 45 * @param unconsumedArgs a List which will be populated with the arguments that were not 46 * consumed by the Objects associated with the specified config. If this 47 * is {@code null}, then the implementation will throw 48 * {@link ConfigurationException} if any unprocessed args remain. 49 * 50 * @return the loaded {@link IConfiguration}. The delegate object {@link Option} fields have 51 * been populated with values in args. 52 * @throws ConfigurationException if configuration could not be loaded 53 */ 54 public IConfiguration createConfigurationFromArgs(String[] args, List<String> unconsumedArgs) 55 throws ConfigurationException; 56 57 /** 58 * Create the {@link IConfiguration} from command line arguments with a key store. 59 * <p/> 60 * Expected format is "CONFIG [options]", where CONFIG is the built-in configuration name or 61 * a file path to a configuration xml file. 62 * 63 * @param args the command line arguments 64 * @param unconsumedArgs a List which will be populated with the arguments that were not 65 * consumed by the Objects associated with the specified config. If this 66 * is {@code null}, then the implementation will throw 67 * {@link ConfigurationException} if any unprocessed args remain. 68 * @param keyStoreClient a {@link IKeyStoreClient} which is used to obtain sensitive info in 69 * the args. 70 * 71 * @return the loaded {@link IConfiguration}. The delegate object {@link Option} fields have 72 * been populated with values in args. 73 * @throws ConfigurationException if configuration could not be loaded 74 */ 75 public IConfiguration createConfigurationFromArgs(String[] args, List<String> unconsumedArgs, 76 IKeyStoreClient keyStoreClient) throws ConfigurationException; 77 78 /** 79 * Create a {@link IGlobalConfiguration} from command line arguments. 80 * <p/> 81 * Expected format is "CONFIG [options]", where CONFIG is the built-in configuration name or 82 * a file path to a configuration xml file. 83 * 84 * @param args the command line arguments 85 * @param nonGlobalArgs a list which will be populated with the arguments that weren't 86 * processed as global arguments 87 * @return the loaded {@link IGlobalConfiguration}. The delegate object {@link Option} fields 88 * have been populated with values in args. 89 * @throws ConfigurationException if configuration could not be loaded 90 */ 91 public IGlobalConfiguration createGlobalConfigurationFromArgs(String[] args, 92 List<String> nonGlobalArgs) throws ConfigurationException; 93 94 /** 95 * Prints help output for this factory. 96 * <p/> 97 * Prints a generic help info, and lists all available configurations. 98 * 99 * @param out the {@link PrintStream} to dump output to 100 */ 101 public void printHelp(PrintStream out); 102 103 /** 104 * Prints help output for the {@link IConfiguration} specified in command line arguments, 105 * <p/> 106 * If 'args' refers to a known configuration, a {@link IConfiguration} object will be created 107 * from XML, and help for that {@link IConfiguration} will be outputted. Note all other 'args' 108 * values will be ignored (ie the help text will describe the current values of {@link Option}s 109 * as loaded from XML, and will not reflect option's values set by the command line args. 110 * <p/> 111 * If 'args' does not reference a known {@link IConfiguration}, the generic 112 * {@link #printHelp(PrintStream)} help will be displayed. 113 * <p/> 114 * 115 * @param args the command line arguments 116 * @param importantOnly if <code>true</code>, print an abbreviated help listing only the 117 * important details 118 * @param out the {@link PrintStream} to dump output to 119 */ 120 public void printHelpForConfig(String[] args, boolean importantOnly, PrintStream out); 121 122 /** 123 * Dumps the contents of the configuration to the given {@link PrintStream} 124 * 125 * @param configName the configuration name 126 * @param out the {@link PrintStream} to dump output to 127 */ 128 public void dumpConfig(String configName, PrintStream out); 129 130 /** 131 * Return the list of names of all the configs found in the JARs on the classpath. 132 * Does not attempt to load any of the configs, so it is possible to have non working config 133 * in this list. 134 */ 135 public List<String> getConfigList(); 136 137 /** 138 * Variation of {@link #getConfigList()} where we want to reduce the listing to only a 139 * subdirectory of the configuration path (res/config/). 140 * 141 * @param subPath name of the sub-directories to look in for configuration. If null, will have 142 * the same behavior as {@link #getConfigList()}. 143 */ 144 public List<String> getConfigList(String subPath); 145 146 /** 147 * Variation of {@link #getConfigList(String)} where can specify whether or not we also want to 148 * load the configuration from the environment. 149 * 150 * @param subPath name of the sub-directories to look in for configuration. If null, will have 151 * the same behavior as {@link #getConfigList()}. 152 * @param loadFromEnv True if we should load the configuration in the environment variable. 153 */ 154 public List<String> getConfigList(String subPath, boolean loadFromEnv); 155 } 156
