1 package org.sim0mq.message.federatestarter;
2
3 import org.djutils.exceptions.Throw;
4 import org.sim0mq.Sim0MQException;
5 import org.sim0mq.message.Sim0MQMessage;
6
7 /**
8 * FederateStarted, FS.2. Message sent by the Federate Starter to the Federation Manager in response to message FM.1.
9 * <p>
10 * Copyright (c) 2016-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 FS2FederateStartedMessage extends Sim0MQMessage
16 {
17 /** */
18 private static final long serialVersionUID = 20170422L;
19
20 /**
21 * The sender id of the model that was started or had an error while starting. This is exactly the same as the instanceId
22 * sent by the Federation Manager in the StartFederate message.
23 */
24 private final Object instanceId;
25
26 /** A string that refers to the model status. Four options: "started", "running", "ended", "error". */
27 private final String status;
28
29 /** The model port number. We use an int in Java due to the fact there is no unsigned short. */
30 private final int modelPort;
31
32 /** Optional. If there is an error, the error message is sent as well. Otherwise this field is an empty string. */
33 private final String error;
34
35 /** the unique message id. */
36 private static final String MESSAGETYPE = "FS.2";
37
38 /**
39 * @param federationId the federation id can be coded using different types. Examples are two 64-bit longs indicating a
40 * UUID, or a String with a UUID number, a String with meaningful identification, or a short or an int with a
41 * simulation run number.
42 * @param senderId The sender id can be used to send back a message to the sender at some later time.
43 * @param receiverId The receiver id can be used to check whether the message is meant for us, or should be discarded (or an
44 * error can be sent if we receive a message not meant for us).
45 * @param messageId The unique message number is meant to confirm with a callback that the message has been received
46 * correctly. The number is unique for the sender, so not globally within the federation.
47 * @param instanceId The sender id of the model that was started or had an error while starting. This is exactly the same as
48 * the instanceId sent by the Federation Manager in the StartFederate message.
49 * @param status A string that refers to the model status. Four options: "started", "running", "ended", "error".
50 * @param modelPort The model port number. We use an int in Java due to the fact there is no unsigned short.
51 * @param error Optional. If there is an error, the error message is sent as well. Otherwise this field is an empty string.
52 * @throws Sim0MQException on unknown data type
53 * @throws NullPointerException when one of the parameters is null
54 */
55 @SuppressWarnings("checkstyle:parameternumber")
56 public FS2FederateStartedMessage(final Object federationId, final Object senderId, final Object receiverId,
57 final Object messageId, final Object instanceId, final String status, final int modelPort, final String error)
58 throws Sim0MQException, NullPointerException
59 {
60 this(new Object[] {Sim0MQMessage.VERSION, true, federationId, senderId, receiverId, MESSAGETYPE, messageId, 4,
61 instanceId, status, modelPort, error});
62 }
63
64 /**
65 * @param objectArray Object[]; the fields that constitute the message
66 * @throws Sim0MQException on unknown data type
67 * @throws NullPointerException when one of the parameters is null
68 */
69 public FS2FederateStartedMessage(final Object[] objectArray) throws Sim0MQException, NullPointerException
70 {
71 super(objectArray, 4, MESSAGETYPE);
72
73 this.instanceId = objectArray[8];
74 Throw.when(!(objectArray[9] instanceof String), Sim0MQException.class, "status (field 9) should be a String");
75 this.status = objectArray[9].toString();
76 Throw.when(this.status.isEmpty(), Sim0MQException.class, "status cannot be empty");
77 Throw.when(
78 !this.status.equals("started") && !this.status.equals("running") && !this.status.equals("ended")
79 && !this.status.equals("error"),
80 Sim0MQException.class, "status should be one of 'started', 'running', 'ended', 'error'");
81 Throw.when(!(objectArray[10] instanceof Integer), Sim0MQException.class, "modelPort (field 10) should be an Integer");
82 this.modelPort = (Integer) objectArray[10];
83 Throw.when(this.modelPort < 0 || this.modelPort > 65535, Sim0MQException.class,
84 "modelPort should be between 0 and 65535");
85 Throw.when(!(objectArray[11] instanceof String), Sim0MQException.class, "error (field 11) should be a String");
86 this.error = objectArray[11].toString();
87 }
88
89 /**
90 * @return instanceId
91 */
92 public Object getInstanceId()
93 {
94 return this.instanceId;
95 }
96
97 /**
98 * @return status
99 */
100 public String getStatus()
101 {
102 return this.status;
103 }
104
105 /**
106 * @return modelPort
107 */
108 public int getModelPort()
109 {
110 return this.modelPort;
111 }
112
113 /**
114 * @return error
115 */
116 public String getError()
117 {
118 return this.error;
119 }
120
121 /**
122 * Builder for the FederateStarted Message. Can string setters together, and call build() at the end to build the actual
123 * message.
124 * <p>
125 * Copyright (c) 2016-2024 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved.
126 * <br>
127 * BSD-style license. See <a href="http://sim0mq.org/docs/current/license.html">Sim0MQ License</a>.
128 * </p>
129 * @author <a href="http://www.tbm.tudelft.nl/averbraeck">Alexander Verbraeck</a>
130 */
131 public static class Builder extends Sim0MQMessage.Builder<FS2FederateStartedMessage.Builder>
132 {
133 /**
134 * The sender id of the model that was started or had an error while starting. This is exactly the same as the
135 * instanceId sent by the Federation Manager in the StartFederate message.
136 */
137 private Object instanceId;
138
139 /** A string that refers to the model status. Four options: "started", "running", "ended", "error". */
140 private String status;
141
142 /** The model port number. We use an int in Java due to the fact there is no unsigned short. */
143 private int modelPort;
144
145 /** Optional. If there is an error, the error message is sent as well. Otherwise this field is an empty string. */
146 private String error;
147
148 /**
149 * Empty constructor.
150 */
151 public Builder()
152 {
153 // nothing to do.
154 }
155
156 /**
157 * @param newInstanceId set instanceId
158 * @return the original object for chaining
159 */
160 public final Builder setInstanceId(final Object newInstanceId)
161 {
162 this.instanceId = newInstanceId;
163 return this;
164 }
165
166 /**
167 * @param newStatus set status
168 * @return the original object for chaining
169 */
170 public final Builder setStatus(final String newStatus)
171 {
172 this.status = newStatus;
173 return this;
174 }
175
176 /**
177 * @param newModelPort set modelPort (int instead of short because of signed short in Java)
178 * @return the original object for chaining
179 */
180 public final Builder setModelPort(final int newModelPort)
181 {
182 this.modelPort = newModelPort;
183 return this;
184 }
185
186 /**
187 * @param newError set error
188 * @return the original object for chaining
189 */
190 public final Builder setError(final String newError)
191 {
192 this.error = newError;
193 return this;
194 }
195
196 @Override
197 public FS2FederateStartedMessage build() throws Sim0MQException, NullPointerException
198 {
199 return new FS2FederateStartedMessage(this.federationId, this.senderId, this.receiverId, this.messageId,
200 this.instanceId, this.status, this.modelPort, this.error);
201 }
202
203 }
204 }