Class SimulatedLocationDataSource


  • public final class SimulatedLocationDataSource
    extends LocationDataSource
    A location data source that provides simulated device locations for testing.

    Use this data source to simulate location updates for a device. It uses a collection of LocationDataSource.Location that are sequentially passed to LocationDataSource.updateLocation(Location). The location collection can be derived from vertices in a provided polyline, generated evenly along a polyline based on a travel velocity, or assigned to the collection directly.

    Since:
    100.8.0 for Android and 100.9.0 for Java SE
    • Constructor Detail

      • SimulatedLocationDataSource

        public SimulatedLocationDataSource()
        Creates a simulated location data source.
        Since:
        100.8.0 for Android and 100.9.0 for Java SE
    • Method Detail

      • setLocations

        public void setLocations​(java.lang.Iterable<LocationDataSource.Location> locations)
        Sets a list of locations that are iterated sequentially.

        As the list of locations is iterated, the LocationDataSource.LocationChangedEvent is fired for each location. The frequency at which this data source iterates over the provided locations is determined by getIterationRate(). Populate the location list by calling setLocations(Polyline) or directly assigning a list of locations by this method.

        Note - the provided locations are copied from the Iterable, thus any subsequent changes to the Iterable won't have any affect on the list of locations returned by getLocations().

        Parameters:
        locations - a list of locations
        Throws:
        java.lang.IllegalArgumentException - if locations is null or empty
        Since:
        100.8.0 for Android and 100.9.0 for Java SE
      • getCurrentLocationIndex

        public int getCurrentLocationIndex()
        Gets the index of the item in the location list that provides the current location.

        This represents the index of the location that is currently used by this location data source to represent the current location. This can be used to either find which location in the getLocations() list is being used, or it can be used to forward/rewind/loop to a different location in the getLocations list using setCurrentLocationIndex(int).

        Returns:
        the index of the current location in the location list
        Since:
        100.8.0 for Android and 100.9.0 for Java SE
      • setCurrentLocationIndex

        public void setCurrentLocationIndex​(int index)
        Sets the index of the item in the location list that provides the current location.

        Sets the index of the item in the location list that will be used by this location data source to represent the current location. The index can be used to forward/rewind/loop to a different location in the list returned by getLocations().

        Parameters:
        index - the index of the current location in the location list
        Throws:
        java.lang.IllegalArgumentException - if index is negative
        Since:
        100.8.0 for Android and 100.9.0 for Java SE
      • getIterationRate

        public double getIterationRate()
        Gets the rate over which the getLocations() list is iterated, default is 1.0.

        The rate at which the locations are iterated over, controlling the time between location updates. The default value is 1.0, which updates the location once a second. To increase the frequency, set this property to a higher value, e.g. 2.0 = 2x speedup. To decrease frequency, set this property to a lower value, e.g. 0.5 = 2x slowdown. This property does not affect the time property of the items in the getLocations (they are always 1 second apart).

        Returns:
        the iteration rate over the location list
        Since:
        100.8.0 for Android and 100.9.0 for Java SE
      • setIterationRate

        public void setIterationRate​(double iterationRate)
        Sets the rate over which the getLocations() list is iterated, default is 1.0.

        The rate at which the locations are iterated over, controlling the time between location updates. The default value is 1.0, which updates the location once a second. To increase the frequency, set this property to a higher value, e.g. 2.0 = 2x speedup. To decrease frequency, set this property to a lower value, e.g. 0.5 = 2x slowdown. This property does not affect the time property of the items in the getLocations (they are always 1 second apart).

        Parameters:
        iterationRate - the iteration rate over the location list
        Throws:
        java.lang.IllegalArgumentException - if iterationRate is zero or negative
        Since:
        100.8.0 for Android and 100.9.0 for Java SE
      • setLocations

        public void setLocations​(Polyline polyline)
        Creates a list of locations using vertices from an input polyline.

        The generated locations are available from the getLocations() method.

        Based on the inputs, these location properties are set:

        • time stamp
        • position
        • velocity
        These location properties are not set:
        • horizontal accuracy
        • vertical accuracy
        • last known
        This location property is calculated:
        • course
        Parameters:
        polyline - a polyline that defines a simulated route of travel
        Throws:
        java.lang.IllegalArgumentException - if polyline is null or empty
        Since:
        100.8.0 for Android and 100.9.0 for Java SE
      • setLocations

        public void setLocations​(Polyline polyline,
                                 SimulationParameters parameters)
        Creates a list of locations along an input polyline based on simulation parameters.

        The generated locations are available from the getLocations() method. Distance between each location on the polyline depends on velocity. For example if velocity is 10 meters per second then distance between 2 locations will be 10 meters. The LocationDataSource.Location.getTimeStamp() values will always be one second apart.

        Based on the inputs, these location properties are set:

        • time stamp
        • position
        • velocity
        • horizontal accuracy
        • vertical accuracy
        This location property is not set:
        • last known
        This location property is calculated:
        • course
        Parameters:
        polyline - a polyline that defines a simulated travel path
        parameters - a SimulationParameters used in creating the locations from the polyline. If it is null, it is equivalent to call setLocations(Polyline)
        Throws:
        java.lang.IllegalArgumentException - if polyline is null or empty
        Since:
        100.8.0 for Android and 100.9.0 for Java SE