001 /*
002 * CreoleParameter.java
003 *
004 * Copyright (c) 2008, The University of Sheffield.
005 *
006 * This file is part of GATE (see http://gate.ac.uk/), and is free
007 * software, licenced under the GNU Library General Public License,
008 * Version 2, June 1991 (in the distribution as file licence.html,
009 * and also available at http://gate.ac.uk/gate/licence.html).
010 *
011 * Ian Roberts, 27/Jul/2008
012 *
013 * $Id: CreoleParameter.java 13419 2011-02-08 08:35:24Z markagreenwood $
014 */
015
016 package gate.creole.metadata;
017
018 import java.lang.annotation.Documented;
019 import java.lang.annotation.ElementType;
020 import java.lang.annotation.Retention;
021 import java.lang.annotation.RetentionPolicy;
022 import java.lang.annotation.Target;
023 import java.util.Collection;
024
025 /**
026 * <p>
027 * Annotation used to define a parameter to a CREOLE resource. This annotation
028 * should be used to annotate the <code>set</code> method corresponding to the
029 * parameter. The parameter's name is inferred from the method name, and its
030 * type is inferred from the type of the method's argument. When annotating a
031 * method whose argument type is a subtype of {@link Collection}, GATE also
032 * attempts to infer the collection element type from any generic type
033 * arguments given. If the collection type is a raw type then you will need to
034 * supply the collectionElementType explicitly in the annotation.
035 * </p>
036 *
037 * <p>
038 * Parameters can be marked as optional or runtime parameters using the
039 * appropriate additional annotations.
040 * </p>
041 *
042 * @see Optional
043 * @see RunTime
044 */
045 @Documented
046 @Target( {ElementType.METHOD})
047 @Retention(RetentionPolicy.RUNTIME)
048 public @interface CreoleParameter {
049 /**
050 * Dummy type used to signify that no value has been supplied for {@link
051 * collectionElementType()}.
052 */
053 public static interface NoElementType {}
054
055 /**
056 * Special value used to signify the absence of a default value for a
057 * parameter.
058 */
059 public static final String NO_DEFAULT_VALUE = "____NO_DEFAULT____";
060
061 /**
062 * The default priority value assumed if no explicit priority
063 * is set.
064 */
065 public static final int DEFAULT_PRIORITY = Integer.MAX_VALUE;
066
067 /**
068 * The item class name for parameters whose type is a Collection, Set
069 * or List. When annotating a field or get method with a parameterised type
070 * (e.g. <code>List<String></code>), the correct value can often be
071 * inferred automatically, but if a value is specified here it takes
072 * precedence.
073 */
074 Class<?> collectionElementType() default NoElementType.class;
075
076 /**
077 * The default value for the parameter, expressed as a string. For
078 * non-string parameters, follow the rules given in the <a
079 * href="http://gate.ac.uk/userguide/sec:creole-model:config:xml">user
080 * guide</a>. If not specified, the default is <code>null</code>.
081 */
082 String defaultValue() default NO_DEFAULT_VALUE;
083
084 /**
085 * A descriptive comment about this parameter.
086 */
087 String comment() default "";
088
089 /**
090 * Semicolon-separated list of file suffixes accepted by default for
091 * this parameter. For parameters of type {@link java.net.URL}, the
092 * GUI provides a button to locate the desired file in a Java file
093 * chooser. The suffixes list defines the default file name filter
094 * used by the file chooser.
095 */
096 String suffixes() default "";
097
098 /**
099 * If this parameter is part of a disjunction, set an ID here. All
100 * parameters sharing the same disjunction ID will be grouped together
101 * in a single disjunction. If not specified, the parameter will not
102 * be considered as part of a disjunction.
103 */
104 String disjunction() default "";
105
106 /**
107 * If this parameter is part of a disjunction, the order in which
108 * the disjunctive parameters are listed is determined by their
109 * priority values. Parameters with smaller priority values are
110 * considered "more important" than those with larger values (i.e.
111 * 1 is higher priority than 10). When creating a new resource
112 * instance in GATE Developer, the parameters dialog offers the
113 * parameters in each disjunction in priority order, so you should
114 * assign priorities to your parameters such that the most important
115 * parameter in each disjunction is the most frequent use case. For
116 * example, in a JAPE transducer the grammarURL parameter (for
117 * loading a .jape file) is considered more important than the
118 * binaryGrammarURL (for loading a serialized transducer).
119 */
120 int priority() default Integer.MAX_VALUE;
121 }
|