/*
* Copyright (c) 2005-2010 KOM – Multimedia Communications Lab
*
* This file is part of PeerfactSim.KOM.
*
* PeerfactSim.KOM is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* any later version.
*
* PeerfactSim.KOM is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with PeerfactSim.KOM. If not, see .
*
*/
package de.tud.kom.p2psim.api.topology.views;
import java.util.Collection;
import java.util.List;
import de.tud.kom.p2psim.api.linklayer.mac.Link;
import de.tud.kom.p2psim.api.linklayer.mac.MacAddress;
import de.tud.kom.p2psim.api.linklayer.mac.MacLayer;
import de.tud.kom.p2psim.api.linklayer.mac.PhyType;
import de.tud.kom.p2psim.api.topology.TopologyListener;
import de.tud.kom.p2psim.api.topology.movement.MovementListener;
import de.tudarmstadt.maki.simonstrator.api.component.sensor.location.Location;
/**
* Each MAC has a view on the global topology of hosts (ie. the
* interconnectivity of the hosts in the given Medium). This provides an adapter
* between the Topology-class and the MAC that needs to know the neighbors of a
* Host. The View itself is instantiated in the Topology-Section, there has to
* be a view for each PHY that is used, otherwise an Exception is thrown
*
*
* @author Bjoern Richerzhagen
* @version 1.0, 21.02.2012
*/
public interface TopologyView extends TopologyListener, MovementListener {
/**
* The {@link PhyType} this View represents
*
* @return
*/
public PhyType getPhyType();
/**
* Return a Link-Object to use for data transmission between a source and a
* destination. For performance-reasons you will always receive a valid link
* object, even if from the topologies perspective the link is not available
* anymore. Before sending a message via the link we therefore have to check
* if Link.isConnected() returns true.
*
* If source == destionation isConnected() of the Link has to return false!
*
* @param source
* @param destination
* @return A Link-Object
*/
public Link getLinkBetween(MacAddress source, MacAddress destination);
/**
* For some topology views it might be much faster to just return the next
* hop rather than to calculate the whole path every time. Therefore, it is
* encouraged to use this method when operating with global knowledge in
* routing. The method should return null, if no path between source and
* destination is found, otherwise we would still send a message, even if it
* is never reaching the destination.
*
* @param source
* the originator of the NetMessage
* @param lastHop
* the originator of the LinkMessage (last Hop)
* @param currentHop
* the current node
* @param destination
* the target of the NetMessage
* @return
*/
public Link getBestNextLink(MacAddress source, MacAddress lastHop,
MacAddress currentHop, MacAddress destination);
/**
* Returns the MAC-Layer with the given MacAddress
*
* @param address
* @return
*/
public MacLayer getMac(MacAddress address);
/**
* Returns a List of 1-hop-neighbors of the given {@link MacAddress} (this
* should only return neighbors to which we have a TX-connection). It does
* NOT imply that we are also in the neighborhood of all nodes in the
* returned list, as links do not need to be symmetric!
*
* @param address
* @return an unmodifiable view on the current neighbors
*/
public List getNeighbors(MacAddress address);
/**
* Returns all MACs that are currently in the TopologyView.
* @return
*/
public Collection getAllMacs();
/**
* Gets the real Position of the host.
*
* @param address
* The {@link MacAddress} of the host
* @return The real Position of the Host.
*/
public Location getPosition(MacAddress address);
/**
* Gets the real distance between the two hosts.
*
* @param addressA
* The first {@link MacAddress}
* @param addressB
* The second {@link MacAddress}
* @return The real distance between the two hosts.
*/
public double getDistance(MacAddress addressA, MacAddress addressB);
}