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-2026 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 Alexander Verbraeck
12 * @author Peter Knoppers
13 * @author Wouter Schakel
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. Different locations of a single logical unit may set the same parameter (with claim) if they share a
31 * common key to do so.
32 * @param parameterType the parameter type
33 * @param value new value for the parameter of type {@code parameterType}
34 * @param key key object for unique right to set the parameter value
35 * @param <T> class of value
36 * @throws ParameterException if the value does not comply with value type constraints or is claimed by another key
37 */
38 <T> void setClaimedParameter(ParameterType<T> parameterType, T value, Object key) throws ParameterException;
39
40 /**
41 * Set parameter value of given parameter type, store old value to allow a reset. This method ignores any claim on the
42 * parameter, and should always be followed by a reset.
43 * @param parameterType the parameter type
44 * @param value new value for the parameter of type {@code parameterType}
45 * @param <T> class of value
46 * @throws ParameterException if the value does not comply with value type constraints
47 */
48 <T> void setParameterResettable(ParameterType<T> parameterType, T value) throws ParameterException;
49
50 /**
51 * Resets the parameter value to the value from before the last resettable set. This goes only a single value back.
52 * @param parameterType the parameter type
53 * @throws ParameterException if the parameter was never set
54 * @throws NullPointerException when any input is null
55 */
56 void resetParameter(ParameterType<?> parameterType) throws ParameterException;
57
58 /**
59 * Get parameter of given type.
60 * @param parameterType the parameter type
61 * @param <T> class of value
62 * @return parameter of the requested type if it exists
63 * @throws ParameterException if the parameter was never set
64 */
65 // @docs/06-behavior/parameters.md (without throws)
66 <T> T getParameter(ParameterType<T> parameterType) throws ParameterException;
67
68 /**
69 * Returns a parameter value, or {@code null} if not present. This can be used to prevent frequent calls to both
70 * {@code contains()} and {@code getParameter()} in performance critical code.
71 * @param parameterType parameter type
72 * @param <T> type of parameter value
73 * @return parameter value, empty if not present
74 */
75 <T> Optional<T> getOptionalParameter(ParameterType<T> parameterType);
76
77 /**
78 * Indicate whether the given parameter type has been set.
79 * @param parameterType the parameter type to check
80 * @return true if {@code parameterType} has been set; false if {@code parameterType} has not been set
81 */
82 boolean contains(ParameterType<?> parameterType);
83
84 /**
85 * Sets the parameters of this set in the given set.
86 * @param parameters parameters to set the values in
87 */
88 void setAllIn(Parameters parameters);
89
90 }