1 package org.opentrafficsim.base.parameters;
2
3 import java.util.Optional;
4
5 /**
6 * Interface for parameter objects containing the methods for during a simulation.
7 * <p>
8 * Copyright (c) 2013-2024 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved. <br>
9 * BSD-style license. See <a href="https://opentrafficsim.org/docs/license.html">OpenTrafficSim License</a>.
10 * </p>
11 * @author <a href="https://github.com/averbraeck">Alexander Verbraeck</a>
12 * @author <a href="https://github.com/peter-knoppers">Peter Knoppers</a>
13 * @author <a href="https://github.com/wjschakel">Wouter Schakel</a>
14 */
15 public interface Parameters
16 {
17
18 /**
19 * Set parameter value of given parameter type.
20 * @param parameterType the parameter type
21 * @param value new value for the parameter of type {@code parameterType}
22 * @param <T> class of value
23 * @throws ParameterException if the value does not comply with value type constraints or is claimed
24 */
25 // @docs/06-behavior/parameters.md (without throws)
26 <T> void setParameter(ParameterType<T> parameterType, T value) throws ParameterException;
27
28 /**
29 * Set parameter value of given parameter type. This method claims setting the value by the key. No other key may be used to
30 * set the parameter.
31 * @param parameterType the parameter type
32 * @param value new value for the parameter of type {@code parameterType}
33 * @param key key object for unique right to set the parameter value
34 * @param <T> class of value
35 * @throws ParameterException if the value does not comply with value type constraints or is claimed by another key
36 */
37 <T> void setClaimedParameter(ParameterType<T> parameterType, T value, Object key) throws ParameterException;
38
39 /**
40 * Set parameter value of given parameter type, store old value to allow a reset. This method ignores any claim on the
41 * parameter, and should always be followed by a reset.
42 * @param parameterType the parameter type
43 * @param value new value for the parameter of type {@code parameterType}
44 * @param <T> class of value
45 * @throws ParameterException if the value does not comply with value type constraints
46 */
47 <T> void setParameterResettable(ParameterType<T> parameterType, T value) throws ParameterException;
48
49 /**
50 * Resets the parameter value to the value from before the last resettable set. This goes only a single value back.
51 * @param parameterType the parameter type
52 * @throws ParameterException if the parameter was never set
53 * @throws NullPointerException when any input is null
54 */
55 void resetParameter(ParameterType<?> parameterType) throws ParameterException;
56
57 /**
58 * Get parameter of given type.
59 * @param parameterType the parameter type
60 * @param <T> class of value
61 * @return parameter of the requested type if it exists
62 * @throws ParameterException if the parameter was never set
63 */
64 // @docs/06-behavior/parameters.md (without throws)
65 <T> T getParameter(ParameterType<T> parameterType) throws ParameterException;
66
67 /**
68 * Returns a parameter value, or {@code null} if not present. This can be used to prevent frequent calls to both
69 * {@code contains()} and {@code getParameter()} in performance critical code.
70 * @param parameterType parameter type
71 * @param <T> type of parameter value
72 * @return parameter value, empty if not present
73 */
74 <T> Optional<T> getOptionalParameter(ParameterType<T> parameterType);
75
76 /**
77 * Indicate whether the given parameter type has been set.
78 * @param parameterType the parameter type to check
79 * @return true if {@code parameterType} has been set; false if {@code parameterType} has not been set
80 */
81 boolean contains(ParameterType<?> parameterType);
82
83 /**
84 * Sets the parameters of this set in the given set.
85 * @param parameters parameters to set the values in
86 */
87 void setAllIn(Parameters parameters);
88
89 }