Updates to Location-API

- now supporting Attraction Points via core API
- allowing location accuracy and modifications
- SiS-Error model interface

src/de/tudarmstadt/maki/simonstrator/api/component/sensor/location/AttractionPoint.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.sensor.location;
+
+/**
+ * Interface for an attraction point (basically a named location)
+ * 
+ * @author Bjoern Richerzhagen
+ *
+ */
+public interface AttractionPoint extends Location {
+
+	/**
+	 * Name of the attraction point
+	 * 
+	 * @return
+	 */
+	public String getName();
+
+	/**
+	 * Clones the current attraction point and manipulates the new AP's name.
+	 * The location of the new AP can then be manipulated through the
+	 * {@link Location} API.
+	 * 
+	 * @param newName
+	 * @return
+	 */
+	public AttractionPoint clone(String newName);
+
+}

src/de/tudarmstadt/maki/simonstrator/api/component/sensor/location/Location.java

@@ -47,7 +47,12 @@ public interface Location extends Transmitable, Cloneable {
 	 * instead of absolute coordinates, whenever it is possible. This avoids
 	 * conflicts in simulations on planar scenarios.
 	 * 
-	 * @return
+	 * In most simulation setups, instead of geographic coordinates, we simply
+	 * rely on x and y (therefore, please use distanceTo and bearingTo for
+	 * calculations)! In such circumstances, the Latitude corresponds to
+	 * <strong>y</strong>.
+	 * 
+	 * @return latitude (or y)
 	 */
 	public double getLatitude();
 
@@ -58,10 +63,37 @@ public interface Location extends Transmitable, Cloneable {
 	 * instead of absolute coordinates, whenever it is possible. This avoids
 	 * conflicts in simulations on planar scenarios.
 	 * 
-	 * @return
+	 * In most simulation setups, instead of geographic coordinates, we simply
+	 * rely on x and y (therefore, please use distanceTo and bearingTo for
+	 * calculations)! In such circumstances, the Latitude corresponds to
+	 * <strong>x</strong>.
+	 * 
+	 * @return longitude (or x)
 	 */
 	public double getLongitude();
 
+	/**
+	 * Allows manipulation of this location object. Can throw an
+	 * {@link UnsupportedOperationException}, if not permitted.
+	 * 
+	 * @param latitude
+	 *            (or y)
+	 */
+	default public void setLatitude(double latitude) throws UnsupportedOperationException {
+		throw new UnsupportedOperationException();
+	}
+
+	/**
+	 * Allows manipulation of this location object. Can throw an
+	 * {@link UnsupportedOperationException}, if not permitted.
+	 * 
+	 * @param latitude
+	 *            (or x)
+	 */
+	default public void setLongitude(double longitude) throws UnsupportedOperationException {
+		throw new UnsupportedOperationException();
+	}
+
 	/**
 	 * Returns the elapsed time since this location was retrieved (measured)
 	 * 
@@ -69,6 +101,37 @@ public interface Location extends Transmitable, Cloneable {
 	 */
 	public long getAgeOfLocation();
 
+	/**
+	 * Accuracy of this location estimate in meters (0 meaning perfect
+	 * accuracy).
+	 * 
+	 * @return accuracy in meters (undefined, if hasAccuracy is false!)
+	 */
+	default public double getAccuracy() {
+		return 0;
+	}
+
+	/**
+	 * True, if the location object has an accuracy associated to it.
+	 * 
+	 * @return
+	 */
+	default public boolean hasAccuracy() {
+		return false;
+	}
+
+	/**
+	 * Sets the accuracy of this location estimate in meters (basically the
+	 * upper error margin for this estimation). Throws an
+	 * {@link UnsupportedOperationException} if this method is not supported by
+	 * the implementation.
+	 * 
+	 * @param accuracy
+	 */
+	default public void setAccuracy(double accuracy) throws UnsupportedOperationException {
+		throw new UnsupportedOperationException();
+	}
+
 	/**
 	 * 
 	 * Distance to the destination in meters
@@ -89,7 +152,9 @@ public interface Location extends Transmitable, Cloneable {
 	public float bearingTo(Location dest);
 
 	/**
-	 * Copy of the current location
+	 * Copy of the current location (use this to retrieve a valid
+	 * {@link Location} object). Usually, the object can then be manipulated via
+	 * the setters.
 	 * 
 	 * @return
 	 */

src/de/tudarmstadt/maki/simonstrator/api/component/sensor/location/LocationActuator.java

@@ -20,6 +20,8 @@
 
 package de.tudarmstadt.maki.simonstrator.api.component.sensor.location;
 
+import java.util.Set;
+
 /**
  * Actuator for location information, allowing "someone" to change a host's
  * current location. While this might not be relevant on prototypical
@@ -32,27 +34,47 @@ package de.tudarmstadt.maki.simonstrator.api.component.sensor.location;
 public interface LocationActuator extends LocationSensor {
 
 	/**
-	 * Updates the node's current location with these coordinates. There is no
+	 * Updates the node's current location with the new location. There is no
 	 * guarantee that this operation will succeed. IF the current location
 	 * changed, the {@link LocationSensor} will accurately reflect this.
 	 * 
-	 * @param longitude
-	 *            (or x)
-	 * @param latitude
-	 *            (or y)
+	 * @param newLocation
 	 * 
 	 */
-	public void updateCurrentLocation(double longitude, double latitude);
+	public void updateCurrentLocation(Location newLocation);
+
+	/**
+	 * Returns the current target {@link AttractionPoint} a node is approaching.
+	 * 
+	 * @return
+	 */
+	public AttractionPoint getCurrentTargetAttractionPoint();
 
 	/**
 	 * A way to interact with node movement from within applications and the
 	 * like. This is an optional operation - it is expected to throw an
 	 * {@link UnsupportedOperationException} if it is not supported.
 	 * 
-	 * @param longitude
-	 * @param latitude
+	 * @param targetAttractionPoint
+	 *            {@link AttractionPoint} the node should move to.
+	 */
+	public void setTargetAttractionPoint(AttractionPoint targetAttractionPoint) throws UnsupportedOperationException;
+
+	/**
+	 * Returns all currently known (to this node) attraction points. These can
+	 * be used for example to update the target location.
+	 * 
+	 * @return
+	 */
+	public Set<AttractionPoint> getAllAttractionPoints();
+
+	/**
+	 * Programmatically add a new attraction point. Currently not supported.
+	 * 
+	 * @param attractionPoint
 	 */
-	public void setNewTargetLocation(double longitude, double latitude)
-			throws UnsupportedOperationException;
+	default public void addAttractionPoint(AttractionPoint attractionPoint) {
+		throw new UnsupportedOperationException();
+	}
 
 }

src/de/tudarmstadt/maki/simonstrator/api/component/sis/SiSProviderErrorModel.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.sis;
+
+import de.tudarmstadt.maki.simonstrator.api.Host;
+import de.tudarmstadt.maki.simonstrator.api.component.sis.type.SiSType;
+
+/**
+ * Intercepts {@link SiSInformationProvider} with a custom error model.
+ * 
+ * @author Nils Richerzhagen
+ *
+ */
+public interface SiSProviderErrorModel<T> {
+
+	/**
+	 * The Type this model operates on.
+	 * 
+	 * @return
+	 */
+	public SiSType<T> getSiSType();
+
+	/**
+	 * 
+	 * @param localHost
+	 * @param type
+	 * @param originalDataSource
+	 * @return
+	 */
+	public SiSDataCallback<T> createErrorModelCallback(Host localHost, SiSType<T> type,
+			SiSDataCallback<T> originalDataSource);
+
+}