View Javadoc

1   /*
2    * This file is part of hyphenType. hyphenType is free software: you can
3    * redistribute it and/or modify it under the terms of the GNU General Public
4    * License as published by the Free Software Foundation, either version 3 of the
5    * License, or (at your option) any later version. hyphenType is distributed in
6    * the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the
7    * implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
8    * the GNU General Public License for more details. You should have received a
9    * copy of the GNU General Public License along with hyphenType. If not, see
10   * <http://www.gnu.org/licenses/>.
11   */
12  package org.hyphenType.optionprocessors;
13  
14  import java.lang.annotation.Annotation;
15  
16  import org.hyphenType.datastructure.Options;
17  import org.hyphenType.optionprocessors.lib.BooleanValidatorEngine;
18  
19  /**
20   * A processor for arguments parsed. A processor is an object that will check an
21   * option object to search for inconsistencies. All processor are called before
22   * option objects are made available for the main application, representing part
23   * of a contract the arguments must met in order to be accepted into the main
24   * application. As in design by contract, the main application does not need to
25   * have defensive source code. In other words, the main application does not
26   * need to protect itself from malformed option objects. <br/>
27   * <br/>
28   * Argument processor classes should declare an inner annotation that is to be
29   * added to the options interface. When such annotation is detected, the
30   * extractor will search for the class in which the annotation was declared
31   * using {@link Class#getEnclosingClass()}. After the processor class was found,
32   * a new instance of the processor class the extractor will create a new
33   * instance of this class using the default constructor.<br/>
34   * <br/>
35   * The method {@link ArgumentsProcessorEngine#process(Class, Options, Enum)},
36   * should search for contract violations. When the first violation is found,
37   * this method should call either {@link Options#exit(Enum)} or
38   * {@link Options#exit(int)} to terminate the JVM. <br/>
39   * <br/>
40   * Although a good example of implementation of {@link ArgumentsProcessorEngine}
41   * is the class {@link BooleanValidatorEngine}, maybe the following pseudo code
42   * clarifies our explanation:<br/>
43   * 
44   * <pre>
45   * <code>
46   * public class FooValidatorEngine&lt;T extends Options&lt;?&gt;&gt; implements ArgumentValidator&lt;T, FooValidator&gt; {
47   * 
48   * 	&#64;Retention(RetentionPolicy.RUNTIME)
49   * 	&#64;Target(ElementType.TYPE)
50   * 	public &#64;interface FooValidator {
51   * 
52   * 		String propertyA() default "ABC";
53   * 
54   * 		String propertyB();
55   * 	}
56   * 
57   * 	&#64;Override
58   * 	public void run(Class&lt;T&gt; interfaceClass, T options, FooValidator config) {
59   * 		
60   * 		if(options are <strong>NOT</strong> OK)
61   * 			options.exit(returnCode);
62   * 	}
63   * }
64   * </code>
65   * </pre>
66   * 
67   * Properties with default values (such as propertyA above) will come with the
68   * default value filled even if the user did not specify any value for this
69   * property explicitly.<br/>
70   * <br/>
71   * When writing an argument processor engine keep in mind that users will
72   * interface only with the inner annotation and the processor itself will be
73   * invisible. Which means the annotation, not the processor, should have a
74   * friendly name.
75   * 
76   * @author Aurelio Akira M. Matsui
77   * @param <T>
78   */
79  //public interface ArgumentsProcessorEngine<T extends Options<?>, U extends Annotation> {
80  public interface ArgumentsProcessorEngine<U extends Annotation> {
81  
82      /**
83       * Must call {@link Options#exit(Enum)} or {@link Options#exit(int)} if, and
84       * only if, the options violate the contract represented by this argument
85       * validator engine.
86       * 
87       * @param interfaceClass The options interface class
88       * @param options The options object
89       * @param config The configuration annotation
90       */
91      <T extends Options<?>> void process(Class<T> interfaceClass, T options, U config);
92  }