Refactored part of the RouteSensor-API

src/de/tudarmstadt/maki/simonstrator/api/component/sensor/future_location/FutureLocationSensor.java

@@ -24,20 +24,17 @@ import de.tudarmstadt.maki.simonstrator.api.Host;
 import de.tudarmstadt.maki.simonstrator.api.component.sensor.location.Location;
 
 /**
- * Based on the Google Location Service (LocationClient) provided for the
- * Android Platform. Provides access to the last known location (energy
- * efficient) or QoS-Specifications for regular location updates.
+ * TODO documentation
  * 
- * @see http 
- *      ://developer.android.com/reference/com/google/android/gms/location/package
- *      -summary.html
- * @author Bjoern Richerzhagen
+ * @deprecated Should this really be part of the API? Currently, I do not get
+ *             its intention. (BR)
  * 
  */
+@Deprecated
 public interface FutureLocationSensor {
 
 	/**
-	 * Retrieve the last known location
+	 * TODO documentation
 	 * 
 	 * @return
 	 */

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

@@ -23,8 +23,10 @@ package de.tudarmstadt.maki.simonstrator.api.component.sensor.location;
 import de.tudarmstadt.maki.simonstrator.api.common.Transmitable;
 
 /**
- * Again, based on Android.Location. Does not support direction and speed at the
- * moment.
+ * Again, based on Android.Location.
+ * 
+ * Updated August 2017 (Bjoern Richerzhagen): added optional methods for bearing
+ * and speed. This should at some time deprecate the SpeedSensor.
  * 
  * @see http://developer.android.com/reference/android/location/Location.html
  * 
@@ -101,6 +103,36 @@ public interface Location extends Transmitable, Cloneable {
 	 */
 	public long getAgeOfLocation();
 
+	/**
+	 * Bearing (or heading) of the current movement vector in degrees between 0
+	 * (exclusive) and 360 (inclusive). If the location does not have a bearing,
+	 * 0 is returned.
+	 * 
+	 * @return
+	 */
+	default public double getBearing() {
+		return 0;
+	}
+
+	/**
+	 * Current movement speed. This value is only meaningful, if hasSpeed()
+	 * returns true.
+	 * 
+	 * @return
+	 */
+	default public double getSpeed() {
+		return 0;
+	}
+
+	/**
+	 * True, if the location object has associated speed information.
+	 * 
+	 * @return
+	 */
+	default public boolean hasSpeed() {
+		return false;
+	}
+
 	/**
 	 * Accuracy of this location estimate in meters (0 meaning perfect
 	 * accuracy).

src/de/tudarmstadt/maki/simonstrator/api/component/sensor/route/Route.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.route;
+
+import java.util.List;
+
+import de.tudarmstadt.maki.simonstrator.api.component.sensor.location.Location;
+
+/**
+ * Basic interface for a route object (unifying SUMO and OSM-based models).
+ * 
+ * @author Bjoern Richerzhagen
+ *
+ */
+public interface Route {
+
+	/**
+	 * Target location of this route.
+	 * 
+	 * @return
+	 */
+	public Location getTargetLocation();
+
+	/**
+	 * True, if the Route contains segment information.
+	 * 
+	 * @return
+	 */
+	public boolean hasSegmentInformation();
+
+	/**
+	 * Segment we are currently on.
+	 * 
+	 * @return
+	 */
+	public RouteSegment getCurrentSegment();
+
+	/**
+	 * List of segments that are still ahead of us (this list INCLUDES the
+	 * current segment!)
+	 * 
+	 * @return segments ahead, in order (the next segment is the first entry in
+	 *         the list).
+	 */
+	public List<RouteSegment> getSegmentsAhead();
+
+	/**
+	 * List of segments we already left behind (this list does NOT include the
+	 * current segment).
+	 * 
+	 * @return segments left behind, in order (the segment we just left behind
+	 *         is the LAST entry in the list).
+	 */
+	public List<RouteSegment> getSegmentsBehind();
+
+	/**
+	 * A route segment (path segment), basically (part of) a road. This is
+	 * assumed to have a unique string ID.
+	 * 
+	 * @author Bjoern Richerzhagen
+	 *
+	 */
+	public interface RouteSegment {
+
+		/**
+		 * Unique ID of this route segment
+		 * 
+		 * @return
+		 */
+		public String getSegmentId();
+
+		/**
+		 * Route points of this segment (at least the START and END location,
+		 * but may provide additional intermediate points).
+		 * 
+		 * @return
+		 */
+		public List<Location> getSegmentLocations();
+
+	}
+
+}

src/de/tudarmstadt/maki/simonstrator/api/component/sensor/route/RouteSensor.java

@@ -21,15 +21,106 @@
 package de.tudarmstadt.maki.simonstrator.api.component.sensor.route;
 
 import de.tudarmstadt.maki.simonstrator.api.component.sensor.SensorComponent;
-import de.tudarmstadt.maki.simonstrator.api.component.vehicular.roadnetwork.RoadNetworkRoute;
+import de.tudarmstadt.maki.simonstrator.api.component.sensor.route.Route.RouteSegment;
 
 /**
+ * A sensor that provides access to the chosen route of a component. This is
+ * only useful within mobility models that define routing to some extend (e.g.,
+ * SUMO or OSM-based mobility models).
  * 
- * @author Tobias Meuser
+ * 
+ * @author Tobias Meuser, Bjoern Richerzhagen
  *
  */
 public interface RouteSensor extends SensorComponent {
 
-	public RoadNetworkRoute getCurrentRoute();
+	/**
+	 * Returns the current route of the component.
+	 * 
+	 * @return
+	 */
+	public Route getRoute();
+
+	/**
+	 * Adds a listener for route updates
+	 * 
+	 * @param listener
+	 */
+	public void addRouteListener(RouteListener listener);
+
+	/**
+	 * Removes a listener for route updates
+	 * 
+	 * @param listener
+	 */
+	public void removeRouteListener(RouteListener listener);
+
+	/**
+	 * Adds a listener for segment updates along routes
+	 * 
+	 * @param listener
+	 */
+	public void addRouteSegmentListener(RouteSegmentListener listener);
+
+	/**
+	 * Removes a listener for segment updates along routes
+	 * 
+	 * @param listener
+	 */
+	public void removeRouteSegmentListener(RouteSegmentListener listener);
+
+	/**
+	 * A listener to be informed of each segment change along a route. This is
+	 * realized as a separate listener, as the required computations should only
+	 * be performed in case anyone is interested at all :)
+	 * 
+	 * @author Bjoern Richerzhagen
+	 *
+	 */
+	public interface RouteSegmentListener {
+
+		/**
+		 * A route consists of several segments (basically street segments)
+		 * along which the component moves towards the target. Whenever a
+		 * component updates its current segment, this method is invoked.
+		 * 
+		 * @param route
+		 * @param leftSegment
+		 * @param enteredSegment
+		 */
+		public void onChangedRouteSegment(RouteSensor sensor, Route route, RouteSegment leftSegment,
+				RouteSegment enteredSegment);
+
+	}
+
+	/**
+	 * A listener for route updates and movement along the route.
+	 * 
+	 * @author Bjoern Richerzhagen
+	 *
+	 */
+	public interface RouteListener {
+
+		/**
+		 * Triggered whenever the component reached the end of the current
+		 * route.
+		 * 
+		 * @param sensor
+		 * @param route
+		 */
+		public void onReachedDestination(RouteSensor sensor, Route route);
+
+		/**
+		 * Triggered whenever the route of the current component changes (either
+		 * due to a new target being chosen or due to updates along the route).
+		 * 
+		 * @param sensor
+		 * @param oldRoute
+		 *            (may be null!)
+		 * @param newRoute
+		 */
+		public void onChangedRoute(RouteSensor sensor, Route oldRoute, Route newRoute);
+
+	}
 
 }

src/de/tudarmstadt/maki/simonstrator/api/component/sensor/route/VehicularRouteSensor.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.route;
+
+import de.tudarmstadt.maki.simonstrator.api.component.vehicular.roadnetwork.RoadNetworkRoute;
+
+/**
+ * Masks the dependency on the RoadNetwork behind another sensor class.
+ * 
+ * @author Bjoern Richerzhagen, based on Tobias Meuser
+ *
+ */
+public interface VehicularRouteSensor extends RouteSensor {
+
+	/**
+	 * Representation of the current route as a road network.
+	 * 
+	 * @return
+	 */
+	public RoadNetworkRoute getCurrentRoute();
+
+}

src/de/tudarmstadt/maki/simonstrator/api/component/sensor/speed/SpeedSensor.java

@@ -21,12 +21,19 @@
 package de.tudarmstadt.maki.simonstrator.api.component.sensor.speed;
 
 import de.tudarmstadt.maki.simonstrator.api.component.sensor.SensorComponent;
+import de.tudarmstadt.maki.simonstrator.api.component.sensor.location.Location;
+import de.tudarmstadt.maki.simonstrator.api.component.sensor.location.LocationSensor;
 
 /**
  * 
  * @author Tobias Meuser
  *
+ * @deprecated this should (at some time) be replaced by the respective
+ *             information in {@link Location}, available via the
+ *             {@link LocationSensor} (BR)
+ *
  */
+@Deprecated
 public interface SpeedSensor extends SensorComponent {
 	double getCurrentSpeed();
 }

src/de/tudarmstadt/maki/simonstrator/api/component/vehicular/api/information/Position.java

@@ -2,6 +2,12 @@ package de.tudarmstadt.maki.simonstrator.api.component.vehicular.api.information
 
 import java.io.Serializable;
 
+/**
+ * @deprecated We should not have a second representation of locations within
+ *             the API. Try to mask the functionality behind Location (which now
+ *             provides speed and heading)
+ */
+@Deprecated
 public class Position implements Serializable, Comparable<Position> {
     /**
      *

src/de/tudarmstadt/maki/simonstrator/api/component/vehicular/api/information/Route.java

@@ -3,6 +3,10 @@ package de.tudarmstadt.maki.simonstrator.api.component.vehicular.api.information
 import java.util.ArrayList;
 import java.util.List;
 
+/**
+ * @deprecated unused?
+ */
+@Deprecated
 public class Route {
     private List<Street> _waypoints;
 

src/de/tudarmstadt/maki/simonstrator/api/component/vehicular/api/information/Street.java

 package de.tudarmstadt.maki.simonstrator.api.component.vehicular.api.information;
 
+/**
+ * @deprecated unused?
+ */
+@Deprecated
 public class Street {
     private String _edgeID;