View Javadoc
1   package org.opentrafficsim.sim0mq.publisher;
2   
3   import java.rmi.RemoteException;
4   
5   import org.djunits.Throw;
6   import org.djutils.metadata.MetaData;
7   import org.djutils.serialization.SerializationException;
8   import org.opentrafficsim.base.Identifiable;
9   import org.sim0mq.Sim0MQException;
10  
11  /**
12   * Transceivers with machine interpretable description of address and result types. A transceiver converts DSOL events to Sim0MQ
13   * messages and Sim0MQ messages to DJUTILS event (un-)subscriptions, or DSOL events.
14   * <p>
15   * Copyright (c) 2020-2020 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved. <br>
16   * BSD-style license. See <a href="http://opentrafficsim.org/docs/license.html">OpenTrafficSim License</a>.
17   * <p>
18   * $LastChangedDate: 2020-02-13 11:08:16 +0100 (Thu, 13 Feb 2020) $, @version $Revision: 6383 $, by $Author: pknoppers $,
19   * @author <a href="http://www.tbm.tudelft.nl/averbraeck">Alexander Verbraeck</a>
20   * @author <a href="http://www.tudelft.nl/pknoppers">Peter Knoppers</a>
21   */
22  public interface TransceiverInterface extends Identifiable
23  {
24      /**
25       * Specification of arguments needed in a request.
26       * @return MetaData; the specification of arguments needed in a request
27       */
28      MetaData getAddressFields();
29  
30      /**
31       * Retrieve the TransceiverInterface that can be used to get detailed information about a single object.
32       * @param addressLevel int; index of the argument in the address fields
33       * @param returnWrapper ReturnWrapper; to be used to report problems
34       * @return TransceiverInterface; to be used to get valid values for argument <code>addressLevel</code>, or null if valid
35       *         values for the argument at index <code>addressLevel</code> can not be obtained through a TransceiverInterface
36       *         object
37       * @throws SerializationException when the ReturnWrapper fails
38       * @throws Sim0MQException when the ReturnWrapper fails
39       */
40      default TransceiverInterface getIdSource(int addressLevel, ReturnWrapper returnWrapper)
41              throws Sim0MQException, SerializationException
42      {
43          // There is no id source by default. Override this method (and the hasIdSource method) if there is one.
44          Throw.whenNull(returnWrapper, "returnWrapper may not be null");
45          throw new IndexOutOfBoundsException("No id source");
46      }
47      
48      /**
49       * Report if this transceiver has an id source.
50       * @return boolean; true if this transceiver has an id source; false if this transceiver does not have an id source
51       */
52      default boolean hasIdSource()
53      {
54          // There is no id source by default. Override this method if there is one.
55          return false;
56      }
57  
58      /**
59       * Report the specification of a result of the transceiver.
60       * @return MetaData; the specification of a result from the transceiver
61       */
62      MetaData getResultFields();
63  
64      /**
65       * Retrieve the data.
66       * @param address Object[]; the address of the data to retrieve
67       * @param returnWrapper ReturnWrapper; to be used to report problems
68       * @return Object[]; the retrieved data, or null when no object with the address could be found
69       * @throws RemoteException when communication needed to retrieve the data failed
70       * @throws SerializationException when encoding an error message fails
71       * @throws Sim0MQException when encoding an error message fails
72       */
73      Object[] get(Object[] address, ReturnWrapper returnWrapper) throws RemoteException, Sim0MQException, SerializationException;
74  
75  }