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