de.monarchy.guideme.data
Class PersonalLocation

java.lang.Object
  de.monarchy.guideme.data.PersonalLocation

All Implemented Interfaces:

RoutingListener, java.lang.Runnable

public class PersonalLocation
extends java.lang.Object
implements java.lang.Runnable, RoutingListener

PersonalLocation is the main service of the program, providing information about position and orientation of the mobile device. After binding to this class, any other component can be notified about changes in position, orientation and routing via handlers. PersonalLocation therefore provides two lists. MovementHandlers are getting updates about orientation and position changes, respectively indicated by the constants POSITION_CHANGED and ORIENTATION_CHANGED as described below. RoutingHandlers receive information when routing calls succeed or fail. Those, too, are indicated by constants ROUTING_FAILED and ROUTING_DONE. POSITION_CHANGED will provide a GeoCoordinate as m.obj. ORIENTATION_CHANGED provides a float[] as m.obj as described in SensorEvent. ROUTING_DONE delivers a RoutingPoint[] as m.obj. ROUTING_FAILED is only a notice and does not carry any additional data. Every given data should not be manipulated directly. If a Handler needs to do so, it should build a deep copy of the object to avoid side effects.

Author:

dstuerze

Field Summary

static int	CALCULATE_ROUTE_FROM_TO status asking for routing service from a given point
static int	CALCULATE_ROUTE_TO status asking for routing service from actual position
Context	context context, needed for service connections
Handler	handler handler for message queue
static int	KILL_COMMAND kills the thread
static int	ORIENTATION_CHANGED status telling that the orientation of the device changed
static int	POSITION_CHANGED status telling that the position of the device changed
static java.lang.String	preferred_language variable expressing the user's preferred language for pois
static int	ROUTING_DONE status telling that a new route was calculated
static int	ROUTING_FAILED status telling that a routing call was unsuccessful

Constructor Summary

PersonalLocation(Context c)
Creates a new data provider.

Method Summary

boolean	addMovementHandler(Handler m) Adds a Handler to this service, so external objects can retain information about the position of the device.
boolean	addRoutingHandler(Handler m) Adds a Handler to this service, so external objects can retain information about changing routing information.
void	calculateRoute(GeoCoordinate to) Convenience method for finding a route between the actual position and the given destination point.
void	calculateRoute(GeoCoordinate from, GeoCoordinate to) Calculates a route between the given points.
void	clearRoute() Removes the calculated route.
float[]	getOrientation() Returns the orientation of the device in an float array.
POI[]	getPOIs() Returns an array of all known POIs.
GeoCoordinate	getPosition() Returns the current position of the device as an GeoCoordinate.
RoutePoint[]	getRoute() Returns the last route calculated by the service.
void	onError(int code) This method is called if an error occured while calculating the route.
void	onRouteCalculated(RoutePoint[] points) Delivers a route to the Listener.
void	onStart() Registers the position listener at system services so the thread is able to maintain information.
void	onStop() Cuts the location service off the system services, so that it will no longer get informations about position or orientation updates.
void	registerPositionListener() Registers the service's listener to the best location service available.
boolean	removeMovementHandler(Handler m) Removes a handler from this service.
boolean	removeRoutingHandler(Handler m) Removes a handler from this service.
void	run()
void	setOrientation(float[] orientation) Sets the orientation of the device.
void	setPosition(GeoCoordinate position) Sets the position of the device.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

KILL_COMMAND

public static final int KILL_COMMAND

kills the thread

See Also:

Constant Field Values

ORIENTATION_CHANGED

public static final int ORIENTATION_CHANGED

status telling that the orientation of the device changed

See Also:

Constant Field Values

POSITION_CHANGED

public static final int POSITION_CHANGED

status telling that the position of the device changed

See Also:

Constant Field Values

ROUTING_DONE

public static final int ROUTING_DONE

status telling that a new route was calculated

See Also:

Constant Field Values

ROUTING_FAILED

public static final int ROUTING_FAILED

status telling that a routing call was unsuccessful

See Also:

Constant Field Values

CALCULATE_ROUTE_TO

public static final int CALCULATE_ROUTE_TO

status asking for routing service from actual position

See Also:

Constant Field Values

CALCULATE_ROUTE_FROM_TO

public static final int CALCULATE_ROUTE_FROM_TO

status asking for routing service from a given point

See Also:

Constant Field Values

preferred_language

public static java.lang.String preferred_language

variable expressing the user's preferred language for pois

context

public Context context

context, needed for service connections

handler

public Handler handler

handler for message queue

Constructor Detail

PersonalLocation

public PersonalLocation(Context c)

Creates a new data provider.

Parameters:

c - context the object is living in

Method Detail

getOrientation

public float[] getOrientation()

Returns the orientation of the device in an float array. This array is similar to the one returned by SensorEvents, so for additional information you should look up there.

Returns:

orientation of the device

setOrientation

public void setOrientation(float[] orientation)

Sets the orientation of the device. This method is only to be calles by a suitable listener. It is thread safe, so multiple calls to this method will be processed in a correct order.

Parameters:

orientation - new orientation as described in SensorEvent

getRoute

public RoutePoint[] getRoute()

Returns the last route calculated by the service.

Returns:

last known route

clearRoute

public void clearRoute()

Removes the calculated route. Will not inform listeners.

getPosition

public GeoCoordinate getPosition()

Returns the current position of the device as an GeoCoordinate.

Returns:

position

setPosition

public void setPosition(GeoCoordinate position)

Sets the position of the device. This method is only to be calles by a suitable listener. It is thread safe, so multiple calls to this method will be processed in a correct order.

Parameters:

position - new position of the device

calculateRoute

public void calculateRoute(GeoCoordinate from,
                           GeoCoordinate to)

Calculates a route between the given points. The method just calls the registered routing service and lies still while waiting for a result.

Parameters:

from - starting point

to - destination point

calculateRoute

public void calculateRoute(GeoCoordinate to)

Convenience method for finding a route between the actual position and the given destination point. Similar call as calculateRoute(getPosition(), to).

Parameters:

to - destination point.

addMovementHandler

public boolean addMovementHandler(Handler m)

Adds a Handler to this service, so external objects can retain information about the position of the device. The method is thread safe, so multiple calls will not corrupt the list of handlers. New handlers go in last position of the handler list. Every handler can only be added once to the service.

Parameters:

m - new handler

Returns:

true if the handler could be added

removeMovementHandler

public boolean removeMovementHandler(Handler m)

Removes a handler from this service.

Parameters:

m - handler to be removed

Returns:

true if removal was successful

addRoutingHandler

public boolean addRoutingHandler(Handler m)

Adds a Handler to this service, so external objects can retain information about changing routing information. The method is thread safe, so multiple calls will not corrupt the list of handlers. New handlers go in last position of the handler list. Every handler can only be added once to the service.

Parameters:

m - new handler

Returns:

true if the handler could be added

removeRoutingHandler

public boolean removeRoutingHandler(Handler m)

Removes a handler from this service.

Parameters:

m - handler to be removed

Returns:

true if removal was successful

registerPositionListener

public void registerPositionListener()

Registers the service's listener to the best location service available. To avoid multiple calls, the listener will first be removed from all location services and then added to the one matching the following criteria the best: - high accuracy - no additional costs - low power consumption

onError

public void onError(int code)

Description copied from interface: RoutingListener

This method is called if an error occured while calculating the route.

Specified by:

onError in interface RoutingListener

Parameters:

code - a constant value from RoutingComponent indicating the type of error

onRouteCalculated

public void onRouteCalculated(RoutePoint[] points)

Description copied from interface: RoutingListener

Delivers a route to the Listener.

Specified by:

onRouteCalculated in interface RoutingListener

Parameters:

points - RoutePoint[] with turning points

getPOIs

public POI[] getPOIs()

Returns an array of all known POIs.

Returns:

pois in an array

run

public void run()

Specified by:

run in interface java.lang.Runnable

onStop

public void onStop()

Cuts the location service off the system services, so that it will no longer get informations about position or orientation updates.

onStart

public void onStart()

Registers the position listener at system services so the thread is able to maintain information.