Merge branch 'master' into 'releases/v2-3'

Updated 2.3-release

Fixing repo-locations
Introducing TopologyIDs instead of plain Strings

See merge request !15

.gitignore

 target/
 bin/
+
+build/
+simonstratorapi.iml

build.gradle

+apply plugin: 'java'
+
+sourceSets {
+    main {
+        java {
+            srcDir 'src'
+        }
+        resources {
+            srcDir 'src/resources'
+        }
+    }
+}
+
+dependencies {
+    compile 'com.esotericsoftware:kryonet:2.22.0-RC1'
+}

pom.xml

@@ -36,7 +36,7 @@
 	<!-- simonstrator-repository -->
 	<repository>
 		<id>simonstrator</id>
-		<url>http://dev.kom.e-technik.tu-darmstadt.de/mvn/</url>
+		<url>https://dev.kom.e-technik.tu-darmstadt.de/mvn/</url>
 	</repository>
   </repositories>
   

src/de/tudarmstadt/maki/simonstrator/api/component/fossa/MetricSubscriber.java

 /*
- * Copyright (c) 2005-2010 KOM – Multimedia Communications Lab
+ * Copyright (c) 2005-2010 KOM - Multimedia Communications Lab
  *
  * This file is part of Simonstrator.KOM.
  * 

src/de/tudarmstadt/maki/simonstrator/api/component/network/ControllableNetInterface.java

+package de.tudarmstadt.maki.simonstrator.api.component.network;
+
+/**
+ * Extending the NetInterface, this interface can be turned on and off by the app/overlay.
+ * The repsective ConnectivityListener will be notified.
+ *
+ * @author Bjoern Richerzhagen
+ *
+ */
+public interface ControllableNetInterface extends NetInterface {
+
+    /**
+     * Activates the NetInterface, if it was previously disabled.
+     */
+    public void turnOn();
+
+    /**
+     * Deactivates the NetInterface, if it was previously enabled.
+     */
+    public void turnOff();
+
+}

src/de/tudarmstadt/maki/simonstrator/api/component/topology/AdaptableTopologyProvider.java

@@ -35,7 +35,7 @@ public interface AdaptableTopologyProvider extends TopologyProvider {
 	 * @param topologyIdentifier
 	 * @param node
 	 */
-	public void addNeighbor(String topologyIdentifier, Node node);
+	public void addNeighbor(TopologyID topologyIdentifier, Node node);
 
 	/**
 	 * Removes the given neighbor node for the specified topology. Has no effect
@@ -44,7 +44,7 @@ public interface AdaptableTopologyProvider extends TopologyProvider {
 	 * @param topologyIdentifier
 	 * @param node
 	 */
-	public void removeNeighbor(String topologyIdentifier, Node node);
+	public void removeNeighbor(TopologyID topologyIdentifier, Node node);
 
 	/**
 	 * Returns the collection of all possible interactions which may be done in
@@ -55,7 +55,7 @@ public interface AdaptableTopologyProvider extends TopologyProvider {
 	 * @param node
 	 */
 	public Collection<OperationalEdge> getPossibleEdgeOperations(
-			String topologyIdentifier);
+			TopologyID topologyIdentifier);
 
 	/**
 	 * Performs the given edge operation. Must be one of the operation returned
@@ -64,7 +64,7 @@ public interface AdaptableTopologyProvider extends TopologyProvider {
 	 * @param topologyidentifier
 	 * @param edgeOperation
 	 */
-	public void performOperation(String topologyidentifier,
+	public void performOperation(TopologyID topologyidentifier,
 			OperationalEdge edgeOperation);
 
 	/**

src/de/tudarmstadt/maki/simonstrator/api/component/topology/Constraint.java

 /*
- * Copyright (c) 2005-2010 KOM  Multimedia Communications Lab
+ * Copyright (c) 2005-2010 KOM - Multimedia Communications Lab
  *
  * This file is part of Simonstrator.KOM.
  * 

src/de/tudarmstadt/maki/simonstrator/api/component/topology/OperationalEdge.java

 /*
- * Copyright (c) 2005-2010 KOM  Multimedia Communications Lab
+ * Copyright (c) 2005-2010 KOM - Multimedia Communications Lab
  *
  * This file is part of Simonstrator.KOM.
  * 

src/de/tudarmstadt/maki/simonstrator/api/component/topology/TopologyID.java

+/*
+ * Copyright (c) 2005-2010 KOM – Multimedia Communications Lab
+ *
+ * This file is part of Simonstrator.KOM.
+ * 
+ * Simonstrator.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 <http://www.gnu.org/licenses/>.
+ *
+ */
+
+package de.tudarmstadt.maki.simonstrator.api.component.topology;
+
+import java.util.LinkedHashMap;
+
+/**
+ * Identifier for Topologies that is globally unique (i.e., depends on the
+ * mechanism that exports the identifier - globally, and on the respective layer
+ * within that mechanism - locally). This object is only to be used locally on a
+ * node (i.e., it is not transmitable).
+ * 
+ * In simulations, we try to maintain only one instance per ID.
+ * 
+ * @author Bjoern Richerzhagen
+ *
+ */
+public final class TopologyID {
+
+	private final String stringRepresentation;
+
+	private final int hashUnique;
+
+	private final static LinkedHashMap<Integer, TopologyID> instances = new LinkedHashMap<>();
+
+	/**
+	 * Returns the {@link TopologyID} for the given local ID and source
+	 * component (must extend {@link TopologyProvider})
+	 * 
+	 * @param id
+	 * @param sourceComponentClass
+	 * @return
+	 */
+	public static <T extends TopologyProvider> TopologyID getIdentifier(
+			String id, Class<T> sourceComponentClass) {
+		assert id != null && sourceComponentClass != null;
+		int hash = TopologyID.computeHash(id, sourceComponentClass);
+		TopologyID instance = instances.get(hash);
+		if (instance == null) {
+			instance = new TopologyID(id + sourceComponentClass.getSimpleName(), hash);
+			instances.put(hash, instance);
+		}
+		return instance;
+	}
+	
+	/**
+	 * Compute the hash for a given combination of string id and source class
+	 * 
+	 * @param id
+	 * @param sourceComponentClass
+	 * @return
+	 */
+	private static <T extends TopologyProvider> int computeHash(String id,
+			Class<T> sourceComponentClass) {
+		return (id + sourceComponentClass.getCanonicalName()).hashCode();
+	}
+
+	/**
+	 * Private constructor, as TopologyIDs have to be created via the static
+	 * method.
+	 * 
+	 * @param localId
+	 *            a local ID (within the {@link TopologyProvider}
+	 * @param sourceComponentClass
+	 *            the {@link TopologyProvider} that sourced this identifier
+	 */
+	private <T extends TopologyProvider> TopologyID(String simpleName, int hash) {
+		this.stringRepresentation = simpleName;
+		this.hashUnique = hash;
+	}
+
+	/**
+	 * String representation of the identifier. To ensure uniqueness, it is
+	 * better to not operate on that string but to use the {@link TopologyID}
+	 * object as key.
+	 */
+	@Override
+	public String toString() {
+		return stringRepresentation;
+	}
+
+	@Override
+	public int hashCode() {
+		return hashUnique;
+	}
+
+	@Override
+	public boolean equals(Object obj) {
+		if (this == obj)
+			return true;
+		if (obj == null)
+			return false;
+		if (getClass() != obj.getClass())
+			return false;
+		TopologyID other = (TopologyID) obj;
+		if (hashUnique != other.hashUnique)
+			return false;
+		return true;
+	}
+
+}

src/de/tudarmstadt/maki/simonstrator/api/component/topology/TopologyObserver.java

@@ -29,5 +29,5 @@ package de.tudarmstadt.maki.simonstrator.api.component.topology;
 public interface TopologyObserver {
 	
 	public void topologyChanged(TopologyProvider topologyProvider,
-			String topologyIdentifier);
+			TopologyID topologyIdentifier);
 }

src/de/tudarmstadt/maki/simonstrator/api/component/topology/TopologyProvider.java

@@ -27,8 +27,6 @@ import de.tudarmstadt.maki.simonstrator.api.common.graph.Graph;
 import de.tudarmstadt.maki.simonstrator.api.common.graph.Node;
 import de.tudarmstadt.maki.simonstrator.api.component.HostComponent;
 
-// TODO Is String a good choice for topology identifiers?
-
 /**
  * This interface is intended to be implemented by HostComponents that define a
  * topology.
@@ -49,26 +47,26 @@ public interface TopologyProvider extends HostComponent {
 	 * 
 	 * @return the node that represents this HostComponent
 	 */
-	public Node getNode(String identifier);
+	public Node getNode(TopologyID identifier);
 
 	/**
 	 * This method provides the 1-hop neighborhood of this TopologyProvider
 	 * 
 	 * @param topologyIdentifier
 	 */
-	public Set<DirectedEdge> getNeighbors(String topologyIdentifier);
+	public Set<DirectedEdge> getNeighbors(TopologyID topologyIdentifier);
 
 	/**
 	 * This method provides the complete local view of this topology provider,
 	 * i.e., it is not bounded by the 1-hop neighborhood. It depends on the
 	 * concrete implementation how large the local view is.
 	 */
-	public Graph getLocalView(String topologyIdentifier);
+	public Graph getLocalView(TopologyID topologyIdentifier);
 
 	/**
 	 * 
 	 * @return the types of topologies provided by the component
 	 */
-	public Iterable<String> getTopologyIdentifiers();
+	public Iterable<TopologyID> getTopologyIdentifiers();
 
 }

src/de/tudarmstadt/maki/simonstrator/api/component/topology/UnderlayTopologyProvider.java

+/*
+ * Copyright (c) 2005-2010 KOM – Multimedia Communications Lab
+ *
+ * This file is part of Simonstrator.KOM.
+ * 
+ * Simonstrator.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 <http://www.gnu.org/licenses/>.
+ *
+ */
+
+package de.tudarmstadt.maki.simonstrator.api.component.topology;
+
+import de.tudarmstadt.maki.simonstrator.api.component.network.NetworkComponent.NetInterfaceName;
+
+/**
+ * This {@link TopologyProvider} returns graphs based on the physical underlays
+ * of nodes. In case the underlay is based on wireless communication, the range
+ * can be taken into account. Please note, that the provider operates on global
+ * knowledge, it maintains only one graph. The graph can be obtained by any of
+ * the components, but there is no need to further aggregate local views, as
+ * they will all be the same for a given PHY.
+ * 
+ * @author Bjoern Richerzhagen
+ *
+ */
+public interface UnderlayTopologyProvider extends TopologyProvider {
+
+	/**
+	 * Returns a topology ID for the given {@link NetInterfaceName} (i.e., the
+	 * physical interface). Can additionally be filtered to only contain nodes
+	 * that are online (which might be the most common use case).
+	 * 
+	 * In a wireless setting, this method will rely on the neighbors as reported
+	 * by the respective underlay (1-hop) to create the graph.
+	 * 
+	 * @param netName
+	 *            the physical interface to be considered
+	 * @param onlyOnline
+	 *            true, if only online nodes are to be contained
+	 * @return
+	 */
+	public TopologyID getTopologyID(NetInterfaceName netName, boolean onlyOnline);
+
+	/**
+	 * Returns a topologyID for the given {@link NetInterfaceName}, based on the
+	 * passed communication range, completely IGNORING the real range of the
+	 * interface!
+	 * 
+	 * @param netName
+	 * @param onlyOnline
+	 * @param range
+	 *            an assumed communication range
+	 * @return
+	 */
+	public TopologyID getTopologyID(NetInterfaceName netName,
+			boolean onlyOnline, double range);
+
+}

src/de/tudarmstadt/maki/simonstrator/api/operation/PeriodicOperation.java

@@ -32,7 +32,7 @@ import de.tudarmstadt.maki.simonstrator.api.util.Distribution;
 public abstract class PeriodicOperation<T extends HostComponent, R> extends
 		AbstractOperation<T, R> {
 
-	private boolean stopped = false;
+	private boolean stopped = true;
 
 	private Distribution intervalDist;
 
@@ -157,6 +157,10 @@ public abstract class PeriodicOperation<T extends HostComponent, R> extends
 	 * Same functionality like scheduleImmediately
 	 */
 	public void start() {
+		if (!isStopped()) {
+			throw new AssertionError(
+					"Periodic Operation already running - ignoring start()!");
+		}
 		this.scheduleImmediately();
 	}
 
@@ -167,6 +171,10 @@ public abstract class PeriodicOperation<T extends HostComponent, R> extends
 	 *            The delay for the first execution
 	 */
 	public void startWithDelay(long delay) {
+		if (!isStopped()) {
+			throw new AssertionError(
+					"Periodic Operation already running - ignoring start()!");
+		}
 		this.scheduleWithDelay(delay);
 	}
 
@@ -176,12 +184,12 @@ public abstract class PeriodicOperation<T extends HostComponent, R> extends
 		super.scheduleWithDelay(delay);
 	}
 
-	@Override
-	public void scheduleImmediately() {
-		this.stopped = false;
-		super.scheduleImmediately();
-	}
-
+	/**
+	 * True, if the operation is currently stopped or was not yet scheduled to
+	 * start.
+	 * 
+	 * @return
+	 */
 	public boolean isStopped() {
 		return stopped;
 	}