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 }