View Javadoc
1   package org.opentrafficsim.base.parameters.constraint;
2   
3   /**
4    * In order to define default constraints within a Parameter Type, an <tt>enum</tt> is available. This interface supplies easy
5    * access to the values of this <tt>enum</tt>. To use this interface, simply implement it as below. The value <tt>POSITIVE</tt>
6    * is a property of this interface pointing to the <tt>enum</tt> field <tt>POSITIVE</tt>. As a result, the value that is set for
7    * <tt>X</tt> is checked to be above zero. Note that model and parameterType do not have to be defined in the same class.
8    * 
9    * <pre>
10   * public class myModel implements ConstraintInterface
11   * {
12   * 
13   *     public static final ParameterTypeLength X = new ParameterTypeLength(&quot;x&quot;, &quot;My x parameter.&quot;, POSITIVE);
14   * 
15   *     // ... model that uses parameter of type X.
16   * 
17   * }
18   * </pre>
19   * 
20   * Another way to access the <tt>enum</tt> fields is to import them, e.g.:
21   * 
22   * <pre>
23   * import static org.opentrafficsim.core.gtu.drivercharacteristics.AbstractParameterType.Constraint.POSITIVE;
24   * </pre>
25   * 
26   * <br>
27   * In order to implement <i>custom</i> checks, any Parameter Type must extend the <tt>check</tt> method of its super. An example
28   * is given below. The method should throw a <tt>ParameterException</tt> whenever a constraint is not met. The static
29   * <tt>throwIf</tt> method is used to do this. The first check is a simple check on the SI value being above 2. The second check
30   * compares the value with the value of another parameter in the <tt>Parameters</tt>. These checks can only be performed if the
31   * other parameter is present in the <tt>Parameters</tt>. <b>Checks with other parameter type values should always check whether
32   * <tt>Parameters</tt> contains the other parameter type</b>. i.e. <tt>params.contains()</tt>.<br>
33   * 
34   * <pre>
35   * public static final ParameterTypeLength X = new ParameterTypeLength(&quot;x&quot;, &quot;My x parameter.&quot;)
36   * {
37   *     public void check(Length value, Parameters params) throws ParameterException
38   *     {
39   *         Throw.when(value.si &lt;= 2, ParameterException.class, &quot;Value of X is not above 2.&quot;);
40   *         Throw.when(params.contains(Y) &amp;&amp; value.si &gt; params.getParameter(Y).si, ParameterException.class,
41   *                 &quot;Value of X is larger than value of Y.&quot;);
42   *     }
43   * };
44   * </pre>
45   * 
46   * Checks are invoked on default values (if given), in which case an empty <tt>Parameters</tt> is forwarded. At construction of
47   * a Parameter Type, no <tt>Parameters</tt> is available. Checks are also invoked when value are set into <tt>Parameters</tt>,
48   * in which case that <tt>Parameters</tt> forwards itself. Even still, if in the above case X is set before Y, the check is
49   * never performed. Therefore, Y should also compare itself to X. <b>Two parameters that are checked with each other, should
50   * both implement a check which is consistent with and mirrored to the the others' check.</b> <br>
51   * <br>
52   * The type of the first argument in the <tt>check()</tt> method depends on the super Parameter Type. For example:<br>
53   * <ul>
54   * <li><tt>double</tt> for <tt>ParameterTypeDouble</tt></li>
55   * <li><tt>int</tt> for <tt>ParameterTypeInteger</tt></li>
56   * <li><tt>Speed</tt> for <tt>ParameterTypeSpeed</tt></li>
57   * <li><tt>Length</tt> for <tt>ParameterTypeLength</tt></li>
58   * <li><tt>T</tt> for <tt>ParameterType&lt;T&gt;</tt></li>
59   * </ul>
60   * Note that <tt>ParameterTypeBoolean</tt> has no check method as checks on booleans are senseless.<br>
61   * <br>
62   * <p>
63   * Copyright (c) 2013-2018 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved. <br>
64   * BSD-style license. See <a href="http://opentrafficsim.org/docs/current/license.html">OpenTrafficSim License</a>.
65   * <p>
66   * @version $Revision$, $LastChangedDate$, by $Author$, initial version Apr 13, 2016 <br>
67   * @author <a href="http://www.tbm.tudelft.nl/averbraeck">Alexander Verbraeck</a>
68   * @author <a href="http://www.transport.citg.tudelft.nl">Wouter Schakel</a>
69   */
70  @SuppressWarnings({ "checkstyle:interfaceistype", "checkstyle:javadoctype", "checkstyle:javadocvariable", "javadoc" })
71  public interface ConstraintInterface
72  {
73  
74      // @formatter:off
75      Constraint<Number> POSITIVE     = NumericConstraint.POSITIVE;
76      Constraint<Number> NEGATIVE     = NumericConstraint.NEGATIVE;
77      Constraint<Number> POSITIVEZERO = NumericConstraint.POSITIVEZERO;
78      Constraint<Number> NEGATIVEZERO = NumericConstraint.NEGATIVEZERO;
79      Constraint<Number> NONZERO      = NumericConstraint.NONZERO;
80      Constraint<Number> ATLEASTONE   = NumericConstraint.ATLEASTONE;
81      Constraint<Number> UNITINTERVAL = DualBound.UNITINTERVAL;
82      
83  }