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 }