View Javadoc
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 }