refactoring: make handler abstract

* needs overridden methods
* add documentation

1 files changed, 16 insertions, 6 deletions

diff --git a/main/src/cgeo/geocaching/utils/GeoDirHandler.java b/main/src/cgeo/geocaching/utils/GeoDirHandler.java
index 21b2562..78455c4 100644
--- a/main/src/cgeo/geocaching/utils/GeoDirHandler.java
+++ b/main/src/cgeo/geocaching/utils/GeoDirHandler.java
@@ -9,10 +9,19 @@ import android.os.Message;
 
 /**
  * GeoData and Direction handler. Manipulating geodata and direction information
- * through a GeoDirHandler ensures that all listeners are registered from a
- * {@link android.os.Looper} thread.
+ * through a GeoDirHandler ensures that all listeners are registered from a {@link android.os.Looper} thread.
+ * <p>
+ * To use this class, override at least one of {@link #updateDirection(float)} or {@link #updateGeoData(IGeoData)}. You
+ * need to start the handler using one of
+ * <ul>
+ * <li>{@link #startDir()}</li>
+ * <li>{@link #startGeo()}</li>
+ * <li>{@link #startGeoAndDir()}</li>
+ * </ul>
+ * A good place might be the {@code onResume} method of the Activity. Stop the Handler accordingly in {@code onPause}.
+ * </p>
  */
-public class GeoDirHandler extends Handler implements IObserver<Object> {
+public abstract class GeoDirHandler extends Handler implements IObserver<Object> {
 
     private static final int OBSERVABLE = 1 << 1;
     private static final int START_GEO = 1 << 2;
@@ -57,7 +66,8 @@ public class GeoDirHandler extends Handler implements IObserver<Object> {
     /**
      * Update method called when new IGeoData is available.
      *
-     * @param data the new data
+     * @param data
+     *            the new data
      */
     protected void updateGeoData(final IGeoData data) {
         // Override this in children
@@ -66,7 +76,8 @@ public class GeoDirHandler extends Handler implements IObserver<Object> {
     /**
      * Update method called when new direction data is available.
      *
-     * @param direction the new direction
+     * @param direction
+     *            the new direction
      */
     protected void updateDirection(final float direction) {
         // Override this in children
@@ -118,4 +129,3 @@ public class GeoDirHandler extends Handler implements IObserver<Object> {
         sendEmptyMessage(STOP_GEO | STOP_DIR);
     }
 }
-