1 package org.sim0mq.message.federationmanager;
2
3 import org.djutils.exceptions.Throw;
4 import org.sim0mq.Sim0MQException;
5 import org.sim0mq.message.Sim0MQMessage;
6
7 /**
8 * RequestStatistics, FM.6. Message sent by the Federation Manager to collect the output.
9 * <p>
10 * Copyright (c) 2019-2024 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved. <br>
11 * BSD-style license. See <a href="http://sim0mq.org/docs/current/license.html">Sim0MQ License</a>.
12 * </p>
13 * @author <a href="http://www.tbm.tudelft.nl/averbraeck">Alexander Verbraeck</a>
14 */
15 public class FM6RequestStatisticsMessage extends Sim0MQMessage
16 {
17 /**
18 * The name of the output variable whose value is requested. That should match with the name in the model. For a tallied
19 * variable, several statistics are possible, e.g., average, variance, minimum, maximum, time series, etc. The name should
20 * clearly indicate what the Model Controller expects and what the model should produce.
21 */
22 private final String variableName;
23
24 /** the unique message id. */
25 private static final String MESSAGETYPE = "FM.6";
26
27 /** */
28 private static final long serialVersionUID = 20190712L;
29
30 /**
31 * @param federationId the federation id can be coded using different types. Examples are two 64-bit longs indicating a
32 * UUID, or a String with a UUID number, a String with meaningful identification, or a short or an int with a
33 * simulation run number.
34 * @param senderId The sender id can be used to send back a message to the sender at some later time.
35 * @param receiverId The receiver id can be used to check whether the message is meant for us, or should be discarded (or an
36 * error can be sent if we receive a message not meant for us).
37 * @param messageId The unique message number is meant to confirm with a callback that the message has been received
38 * correctly. The number is unique for the sender, so not globally within the federation.
39 * @param variableName String; The name of the output variable whose value is requested. That should match with the name in
40 * the model. For a tallied variable, several statistics are possible, e.g., average, variance, minimum, maximum,
41 * time series, etc. The name should clearly indicate what the Model Controller expects and what the model should
42 * produce.
43 * @throws Sim0MQException on unknown data type
44 * @throws NullPointerException when one of the parameters is null
45 */
46 @SuppressWarnings("checkstyle:parameternumber")
47 public FM6RequestStatisticsMessage(final Object federationId, final Object senderId, final Object receiverId,
48 final Object messageId, final String variableName) throws Sim0MQException, NullPointerException
49 {
50 this(new Object[] {Sim0MQMessage.VERSION, true, federationId, senderId, receiverId, MESSAGETYPE, messageId, 1,
51 variableName});
52 }
53
54 /**
55 * @param objectArray Object[]; Full message object array
56 * @throws Sim0MQException on unknown data type
57 * @throws NullPointerException when one of the parameters is null
58 */
59 public FM6RequestStatisticsMessage(final Object[] objectArray) throws Sim0MQException, NullPointerException
60 {
61 super(objectArray, 1, MESSAGETYPE);
62 Throw.when(!(objectArray[8] instanceof String), Sim0MQException.class, "variableName (field 8) should be String");
63 this.variableName = objectArray[8].toString();
64 }
65
66 /**
67 * @return variableName
68 */
69 public String getVariableName()
70 {
71 return this.variableName;
72 }
73
74 /**
75 * Builder for the RequestStatistics Message. Can string setters together, and call build() at the end to build the actual
76 * message.
77 * <p>
78 * Copyright (c) 2019-2024 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved.
79 * <br>
80 * BSD-style license. See <a href="http://sim0mq.org/docs/current/license.html">Sim0MQ License</a>.
81 * </p>
82 * @author <a href="http://www.tbm.tudelft.nl/averbraeck">Alexander Verbraeck</a>
83 */
84 public static class Builder extends Sim0MQMessage.Builder<FM6RequestStatisticsMessage.Builder>
85 {
86 /**
87 * The name of the output variable whose value is requested. That should match with the name in the model. For a tallied
88 * variable, several statistics are possible, e.g., average, variance, minimum, maximum, time series, etc. The name
89 * should clearly indicate what the Model Controller expects and what the model should produce.
90 */
91 private String variableName;
92
93 /**
94 * Empty constructor.
95 */
96 public Builder()
97 {
98 // nothing to do.
99 }
100
101 /**
102 * @param newVariableName set statistics variable name
103 * @return the original object for chaining
104 */
105 public final Builder setVariableName(final String newVariableName)
106 {
107 this.variableName = newVariableName;
108 return this;
109 }
110
111 @Override
112 public FM6RequestStatisticsMessage build() throws Sim0MQException, NullPointerException
113 {
114 return new FM6RequestStatisticsMessage(this.federationId, this.senderId, this.receiverId, this.messageId,
115 this.variableName);
116 }
117
118 }
119 }