/* * Copyright (c) 2006, Swedish Institute of Computer Science. * All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * 1. Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * 2. Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in the * documentation and/or other materials provided with the distribution. * 3. Neither the name of the Institute nor the names of its contributors * may be used to endorse or promote products derived from this software * without specific prior written permission. * * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE * ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF * SUCH DAMAGE. * * $Id: RadioMedium.java,v 1.1 2006/08/21 12:12:55 fros4943 Exp $ */ package se.sics.cooja; import java.util.Collection; import java.util.Observer; import org.jdom.Element; import se.sics.cooja.interfaces.Position; import se.sics.cooja.interfaces.Radio; /** * This interface represents a radio medium. Radios registered to this medium * can both send and receive radio data. Depending on the implementation of this * interface, more or less accurate radio behaviour imitation is aquired. * * Often a radio medium, at initialization, registers one or several dynamic * plugins. These plugins shows the user some radio medium specific details, * such as radio transmission radius etc. * * @author Fredrik Osterlind */ public abstract class RadioMedium { /** * Registers a mote to this medium. * * How radio data will be received from and sent to this mote depends on the * medium implementation. Common factors may be random, distance from sending * to receiving mote and interference with other radio transmitters in some * range. * * @param mote * Mote to register * @param sim * Simulation holding mote */ public abstract void registerMote(Mote mote, Simulation sim); /** * Unregisters a mote from this medium. * * @param mote * Mote to unregister * @param sim * Simulation holding mote */ public abstract void unregisterMote(Mote mote, Simulation sim); /** * Register a radio to this medium at a given position. * * Concerning radio data, this radio will be treated the same way as a mote's * radio. This method can be used to add non-mote radio devices, such as a * packet generator or a sniffer. * * @param radio * Radio * @param position * Position * @param sim * Simulation holding radio */ public abstract void registerRadioInterface(Radio radio, Position position, Simulation sim); /** * Unregisters a radio interface from this medium. * * @param radio * Radio interface to unregister * @param sim * Simulation holding radio */ public abstract void unregisterRadioInterface(Radio radio, Simulation sim); /** * Adds an observer which is notified after the radio connections has been * calculated. Often a radio medium is a tick observer and makes these * calculations after each tick loop. A radio medium observer may then gather * network data by being notified every time the radio medium has delivered * data. The radio medium observable MUST notify observers every time the * getLastTickConnections returns a new value, even if the new value is null. * * @see #getLastTickConnections() * @see #deleteRadioMediumObserver(Observer) * @param observer * New observer */ public abstract void addRadioMediumObserver(Observer observer); /** * Deletes an radio medium observer. * * @see #addRadioMediumObserver(Observer) * @param observer * Observer to delete */ public abstract void deleteRadioMediumObserver(Observer observer); /** * Returns all connections made during last tick loop. * * Typically a radio medium is a tick observer and transfers data between * radios after each tick loop. When these calculations are finished, it will * in turn notify all radio medium observers. A radio medium observer may get * information about which connections were made by using this method. Observe * that this method may return null of no connections were made. * * @see RadioConnection * @return All connections made during last tick loop or null if none */ public abstract RadioConnection[] getLastTickConnections(); /** * Set an overall connection logger. This logger will see all connections in * the radio medium. * * @param logger * New overall connection logger. */ public abstract void setConnectionLogger(ConnectionLogger logger); /** * Returns XML elements representing the current config of this radio medium. * This is fetched by the simulator for example when saving a simulation * configuration file. For example a radio medium may return user altered * range parameters. This method should however not return state specific * information such as a current radio status. (All nodes are restarted when * loading a simulation.) * * @see #setConfigXML(Collection) * @return XML elements representing the current radio medium config */ public abstract Collection getConfigXML(); /** * Sets the current radio medium config depending on the given XML elements. * * @see #getConfigXML() * @param configXML * Config XML elements * @return True if config was set successfully, false otherwise */ public abstract boolean setConfigXML(Collection configXML); }