de.monarchy.guideme.data
Class PersonalLocation

java.lang.Object
  extended by 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.