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 java.lang.annotation.ElementType; 20 import java.lang.annotation.Retention; 21 import java.lang.annotation.RetentionPolicy; 22 import java.lang.annotation.Target; 23 import java.util.Collection; 24 import java.util.Map; 25 26 /** 27 * Annotates a field as representing a {@link IConfiguration} option. 28 */ 29 @Retention(RetentionPolicy.RUNTIME) 30 @Target(ElementType.FIELD) 31 public @interface Option { 32 33 static final char NO_SHORT_NAME = '0'; 34 35 public enum Importance { 36 /** the option should never be treated as important */ 37 NEVER, 38 /** the option should be treated as important only if it has no value */ 39 IF_UNSET, 40 /** the option should always be treated as important */ 41 ALWAYS; 42 } 43 44 /** 45 * The mandatory unique name for this option. 46 * <p/> 47 * This will map to a command line argument prefixed with two '-' characters. 48 * For example, an {@link Option} with name 'help' would be specified with '--help' on the 49 * command line. 50 * <p/> 51 * Names may not contain a colon eg ':'. 52 */ name()53 String name(); 54 55 /** 56 * Optional abbreviated name for option. 57 * This will map to a command line argument prefixed with a single '-'. 58 * e.g. "-h" where h = shortName. 59 * 60 * '0' is reserved to mean the option has no shortName. 61 **/ shortName()62 char shortName() default NO_SHORT_NAME; 63 64 /** 65 * User friendly description of the option. 66 */ description()67 String description() default ""; 68 69 /** 70 * The importance of the option. 71 * <p/> 72 * An option deemed 'important' will be displayed in the abbreviated help output. Help for an 73 * unimportant option will only be displayed in the full help text. 74 */ importance()75 Importance importance() default Importance.NEVER; 76 77 /** 78 * Whether the option is mandatory or optional. 79 * <p /> 80 * The configuration framework will throw a {@code ConfigurationException} if either of the 81 * following is true of a mandatory field after options have been parsed from all sources: 82 * <ul> 83 * <li>The field is {@code null}.</li> 84 * <li>The field is an empty {@link Collection}.</li> 85 * </ul> 86 */ mandatory()87 boolean mandatory() default false; 88 89 /** 90 * Whether the option represents a time value. 91 * <p /> 92 * If this is a time value, time-specific suffixes will be parsed. The field <emph>MUST</emph> 93 * be a {@code long} or {@code Long} for this flag to be valid. A 94 * {@code ConfigurationException} will be thrown otherwise. 95 * <p /> 96 * The default unit is millis. The configuration framework will accept {@code s} for seconds 97 * (1000 millis), {@code m} for minutes (60 seconds), {@code h} for hours (60 minutes), 98 * or {@code d} for days (24 hours). 99 * <p /> 100 * Units may be mixed and matched, so long as each unit appears at most once, and so long as 101 * all units which do appear are listed in decreasing order of scale. So, for instance, 102 * {@code h} may only appear before {@code m}, and may only appear after {@code d}. As a 103 * specific example, "1d2h3m4s5ms" would be a valid time value, as would "4" or "4ms". All 104 * embedded whitespace is discarded. 105 */ isTimeVal()106 boolean isTimeVal() default false; 107 108 /** 109 * Whether the option is needed to compile instruction to rerun a test. 110 * 111 * <p>Result reporter may try to compile instruction on how to rerun a test and include the 112 * message in the result. The instruction shall include all options that applicable to a test 113 * rerun. This attribute is used to indicate if the option shall be included in such 114 * instruction. 115 */ requiredForRerun()116 boolean requiredForRerun() default false; 117 118 /** 119 * Controls the behavior when an option is specified multiple times. Note that this rule is 120 * ignored completely for options that are {@link Collection}s or {@link Map}s. 121 */ updateRule()122 OptionUpdateRule updateRule() default OptionUpdateRule.LAST; 123 } 124