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://github.com/peter-knoppers">Peter Knoppers</a>
20 */
21 public interface TransceiverInterface extends Identifiable
22 {
23 /**
24 * Specification of arguments needed in a request.
25 * @return 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 index of the argument in the address fields
32 * @param returnWrapper to be used to report problems
33 * @return to be used to get valid values for argument <code>addressLevel</code>, or null if valid values for the argument
34 * at index <code>addressLevel</code> can not be obtained through a TransceiverInterface object
35 * @throws SerializationException when the ReturnWrapper fails
36 * @throws Sim0MQException when the ReturnWrapper fails
37 */
38 default TransceiverInterface getIdSource(final int addressLevel, final ReturnWrapper returnWrapper)
39 throws Sim0MQException, SerializationException
40 {
41 // There is no id source by default. Override this method (and the hasIdSource method) if there is one.
42 Throw.whenNull(returnWrapper, "returnWrapper may not be null");
43 throw new IndexOutOfBoundsException("No id source");
44 }
45
46 /**
47 * Report if this transceiver has an id source.
48 * @return true if this transceiver has an id source; false if this transceiver does not have an id source
49 */
50 default boolean hasIdSource()
51 {
52 // There is no id source by default. Override this method if there is one.
53 return false;
54 }
55
56 /**
57 * Report the specification of a result of the transceiver.
58 * @return the specification of a result from the transceiver
59 */
60 MetaData getResultFields();
61
62 /**
63 * Retrieve the data.
64 * @param address the address of the data to retrieve
65 * @param returnWrapper to be used to report problems
66 * @return the retrieved data, or null when no object with the address could be found
67 * @throws RemoteException when communication needed to retrieve the data failed
68 * @throws SerializationException when encoding an error message fails
69 * @throws Sim0MQException when encoding an error message fails
70 */
71 Object[] get(Object[] address, ReturnWrapper returnWrapper) throws RemoteException, Sim0MQException, SerializationException;
72
73 }