1 package org.opentrafficsim.base.parameters.constraint;
2
3 /**
4 * In order to define default constraints within a Parameter Type, an <code>enum</code> is available. This interface supplies easy
5 * access to the values of this <code>enum</code>. To use this interface, simply implement it as below. The value <code>POSITIVE</code>
6 * is a property of this interface pointing to the <code>enum</code> field <code>POSITIVE</code>. As a result, the value that is set for
7 * <code>X</code> 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("x", "My x parameter.", POSITIVE);
14 *
15 * // ... model that uses parameter of type X.
16 *
17 * }
18 * </pre>
19 *
20 * Another way to access the <code>enum</code> 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 <code>check</code> method of its super. An example
28 * is given below. The method should throw a <code>ParameterException</code> whenever a constraint is not met. The static
29 * <code>throwIf</code> 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 <code>Parameters</code>. These checks can only be performed if the
31 * other parameter is present in the <code>Parameters</code>. <b>Checks with other parameter type values should always check whether
32 * <code>Parameters</code> contains the other parameter type</b>. i.e. <code>params.contains()</code>.<br>
33 *
34 * <pre>
35 * public static final ParameterTypeLength X = new ParameterTypeLength("x", "My x parameter.")
36 * {
37 * public void check(Length value, Parameters params) throws ParameterException
38 * {
39 * Throw.when(value.si <= 2, ParameterException.class, "Value of X is not above 2.");
40 * Throw.when(params.contains(Y) && value.si > params.getParameter(Y).si, ParameterException.class,
41 * "Value of X is larger than value of Y.");
42 * }
43 * };
44 * </pre>
45 *
46 * Checks are invoked on default values (if given), in which case an empty <code>Parameters</code> is forwarded. At construction of
47 * a Parameter Type, no <code>Parameters</code> is available. Checks are also invoked when value are set into <code>Parameters</code>,
48 * in which case that <code>Parameters</code> 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 <code>check()</code> method depends on the super Parameter Type. For example:<br>
53 * <ul>
54 * <li><code>double</code> for <code>ParameterTypeDouble</code></li>
55 * <li><code>int</code> for <code>ParameterTypeInteger</code></li>
56 * <li><code>Speed</code> for <code>ParameterTypeSpeed</code></li>
57 * <li><code>Length</code> for <code>ParameterTypeLength</code></li>
58 * <li><code>T</code> for <code>ParameterType<T></code></li>
59 * </ul>
60 * Note that <code>ParameterTypeBoolean</code> has no check method as checks on booleans are senseless.<br>
61 * <br>
62 * <p>
63 * Copyright (c) 2013-2020 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 }