CreoleParameter.java
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 16723 2013-07-05 10:37:59Z domrout $
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 in one of two ways:
029  
030  <ol>
031  <li>To annotate the <code>set</code> method corresponding to the parameter.
032  * The parameter's name is inferred from the method name, and its type is
033  * inferred from the type of the method's argument.</li>
034  <li>To annotate the field for the parameter itself. The corresponding get and
035  * set methods must exist for the field</li>
036  </ol>
037  
038  * When annotating a method whose argument type is a subtype of
039  {@link Collection}, GATE also attempts to infer the collection element type
040  * from any generic type arguments given. If the collection type is a raw type
041  * then you will need to supply the collectionElementType explicitly in the
042  * annotation.
043  </p>
044  
045  <p>
046  * Parameters can be marked as optional or runtime parameters using the
047  * appropriate additional annotations.
048  </p>
049  
050  @see Optional
051  @see RunTime
052  */
053 @Documented
054 @Target( {ElementType.METHOD, ElementType.FIELD})
055 @Retention(RetentionPolicy.RUNTIME)
056 public @interface CreoleParameter {
057   /**
058    * Dummy type used to signify that no value has been supplied for {@link #collectionElementType()}.
059    */
060   public static interface NoElementType {}
061   
062   /**
063    * Special value used to signify the absence of a default value for a
064    * parameter.
065    */
066   public static final String NO_DEFAULT_VALUE = "____NO_DEFAULT____";
067   
068   /**
069    * The default priority value assumed if no explicit priority
070    * is set.
071    */
072   public static final int DEFAULT_PRIORITY = Integer.MAX_VALUE;
073   
074   /**
075    * The item class name for parameters whose type is a Collection, Set
076    * or List. When annotating a field or get method with a parameterised type
077    * (e.g. <code>List&lt;String&gt;</code>), the correct value can often be
078    * inferred automatically, but if a value is specified here it takes
079    * precedence.
080    */
081   Class<?> collectionElementType() default NoElementType.class;
082 
083   /**
084    * The default value for the parameter, expressed as a string. For
085    * non-string parameters, follow the rules given in the <a
086    * href="http://gate.ac.uk/userguide/sec:creole-model:config:xml">user
087    * guide</a>. If not specified, the default is <code>null</code>.
088    */
089   String defaultValue() default NO_DEFAULT_VALUE;
090 
091   /**
092    * A descriptive comment about this parameter.
093    */
094   String comment() default "";
095 
096   /**
097    * Semicolon-separated list of file suffixes accepted by default for
098    * this parameter. For parameters of type {@link java.net.URL}, the
099    * GUI provides a button to locate the desired file in a Java file
100    * chooser. The suffixes list defines the default file name filter
101    * used by the file chooser.
102    */
103   String suffixes() default "";
104 
105   /**
106    * If this parameter is part of a disjunction, set an ID here. All
107    * parameters sharing the same disjunction ID will be grouped together
108    * in a single disjunction. If not specified, the parameter will not
109    * be considered as part of a disjunction.
110    */
111   String disjunction() default "";
112   
113   /**
114    * If this parameter is part of a disjunction, the order in which
115    * the disjunctive parameters are listed is determined by their
116    * priority values.  Parameters with smaller priority values are
117    * considered "more important" than those with larger values (i.e.
118    * 1 is higher priority than 10).  When creating a new resource
119    * instance in GATE Developer, the parameters dialog offers the
120    * parameters in each disjunction in priority order, so you should
121    * assign priorities to your parameters such that the most important
122    * parameter in each disjunction is the most frequent use case.  For
123    * example, in a JAPE transducer the grammarURL parameter (for
124    * loading a .jape file) is considered more important than the
125    * binaryGrammarURL (for loading a serialized transducer).
126    */
127   int priority() default Integer.MAX_VALUE;
128 }