org.placelab.spotter
Interface Spotter

All Known Implementing Classes:

AbstractSpotter, SpotterExtension

public interface Spotter

A spotter is a java object that generalizes the function of an environmental sensor like a GPS unit or a WiFi card. A spotter produces Measurement objects. The types of the measurements produced depend on the type of spotter.

Regardless of the underlying implementation of the Spotter, all Spotters support the following three modes of operation:

• Synchronous: Call getMeasurement() at application defined intervals and get back a single Measurement for each call. This mode of operation is simple, but may result in excessive wait times while the method blocks to collect measurements or it may result in missed Measurements if it is not called often enough.
• Continous Scan: Call startScanning() to have the Spotter begin scanning for Measurements in the background, notifying its registered SpotterListener objects when new Measurements are available. The continous scan will continue providing Measurements until stopScanning() is called.
• Single Background Scan: Call scanOnce() to have the Spotter do a single background scan and return a Measurement to the registered SpotterListeners.

Method Summary

void	addListener(SpotterListener listener) Adds a SpotterListener to be called back whenever new Measurements are generated by the Spotter.
void	close() Unloads resources used by the spotter.
Measurement	getMeasurement() A blocking call to get a new Measurement.
void	open() Load resources used by the spotter.
void	removeListener(SpotterListener listener)
void	scanOnce() Performs a single background scan for Measurements and returns the result to registered SpotterListeners' SpotterListener.gotMeasurement(Spotter, Measurement) method.
void	scanOnce(EventSystem evs) Like scanOnce() but instead uses the given EventSystem to deliver the callback to hide the background thread from the application.
void	startScanning() Start scanning for Measurements in the background and return the Measurements by notifying SpotterListeners with the SpotterListener.gotMeasurement(Spotter, Measurement) method.
void	startScanning(EventSystem evs) Start scanning for Measurements.
void	stopScanning() Stops a currently running background scan started from either scanOnce or startScanning.

Method Detail

open

public void open()
          throws SpotterException

Load resources used by the spotter. Applications should be able to invoke this methods multiple times in sequence and have the "right" things happen. All Spotters should be opened before being used.

Throws:

SpotterException - if the necessary hardware or software for this spotter is not present

close

public void close()
           throws SpotterException

Unloads resources used by the spotter. Multiple calls to close are ok.

Throws:

SpotterException

getMeasurement

public Measurement getMeasurement()
                           throws SpotterException

A blocking call to get a new Measurement. A spotter implementation may choose to just return the last cached Measurement, or go ahead and do a new scan and return the results of that scan. Note that the accuracy of timestamps returned by this usage model depends on the spotter implementation. You should not call this method while this Spotter is performing a continous scan. Doing so will result in a SpotterException being thrown.

Throws:

SpotterException

startScanning

public void startScanning()

Start scanning for Measurements in the background and return the Measurements by notifying SpotterListeners with the SpotterListener.gotMeasurement(Spotter, Measurement) method. Depending on the Spotter implementation this may start up a new background thread. Callbacks to the SpotterListener are not guaranteed to (and probably won't) be in the the same thread as startScanning was called in.

See Also:

startScanning(EventSystem)

startScanning

public void startScanning(EventSystem evs)

Start scanning for Measurements. This method may or may not create a new thread internally, but should never expose that thread to the application. Instead callbacks to SpotterListeners should be invoked via the Eventsystem.notifyTransientEvent() method, so that the callbacks get run through the EventSystem thread.

See Also:

startScanning()

stopScanning

public void stopScanning()

Stops a currently running background scan started from either scanOnce or startScanning.

scanOnce

public void scanOnce()

Performs a single background scan for Measurements and returns the result to registered SpotterListeners' SpotterListener.gotMeasurement(Spotter, Measurement) method. This may start a new thread and deliver the callback in that new thread.

Registered SpotterListeners that also implement the ScanOnceListener interface will also receive ScanOnceListener.endOfScan(Spotter) notifications.

See Also:

scanOnce(EventSystem)

scanOnce

public void scanOnce(EventSystem evs)

Like scanOnce() but instead uses the given EventSystem to deliver the callback to hide the background thread from the application.

addListener

public void addListener(SpotterListener listener)

Adds a SpotterListener to be called back whenever new Measurements are generated by the Spotter.

removeListener

public void removeListener(SpotterListener listener)