Export package: Documentation and make activity optional

5 files changed, 110 insertions, 22 deletions

diff --git a/main/src/cgeo/geocaching/export/AbstractExport.java b/main/src/cgeo/geocaching/export/AbstractExport.java
index e88b1e6..c5bf3c0 100644
--- a/main/src/cgeo/geocaching/export/AbstractExport.java
+++ b/main/src/cgeo/geocaching/export/AbstractExport.java
@@ -13,6 +13,13 @@ public abstract class AbstractExport implements Export {
         return name;
     }
 
+    /**
+     * Generates a localized string from a ressource id.
+     *
+     * @param ressourceId
+     *            the ressource id of the string
+     * @return localized string
+     */
     protected static String getString(int ressourceId) {
         return cgeoapplication.getInstance().getString(ressourceId);
     }
diff --git a/main/src/cgeo/geocaching/export/Export.java b/main/src/cgeo/geocaching/export/Export.java
index 257238c..700c752 100644
--- a/main/src/cgeo/geocaching/export/Export.java
+++ b/main/src/cgeo/geocaching/export/Export.java
@@ -6,8 +6,24 @@ import android.app.Activity;
 
 import java.util.List;
 
+/**
+ * Represent an exporter to export a {@link List} of {@link cgCache} to various formats.
+ */
 public interface Export {
+    /**
+     * Export a {@link List} of {@link cgCache} to various formats.
+     * 
+     * @param caches
+     *            The {@link List} of {@link cgCache} to be exported
+     * @param activity
+     *            optional: Some exporters might have an UI which requires an {@link Activity}
+     */
     public void export(List<cgCache> caches, Activity activity);
 
+    /**
+     * Get the localized name of this exporter.
+     *
+     * @return localized name
+     */
     public String getName();
 }
diff --git a/main/src/cgeo/geocaching/export/ExportFactory.java b/main/src/cgeo/geocaching/export/ExportFactory.java
index 01343c3..dd3a6f4 100644
--- a/main/src/cgeo/geocaching/export/ExportFactory.java
+++ b/main/src/cgeo/geocaching/export/ExportFactory.java
@@ -13,7 +13,13 @@ import android.widget.TextView;
 
 import java.util.List;
 
+/**
+ * Factory to create a dialog with all available exporters.
+ */
 public class ExportFactory {
+    /**
+     * Contains instances of all available exporters.
+     */
     public enum Exporters {
         FIELDNOTES(new FieldnoteExport()),
         GPX(new GpxExport());
@@ -25,6 +31,14 @@ public class ExportFactory {
         public final Export exporter;
     }
 
+    /**
+     * Creates a dialog so that the user can select an exporter.
+     *
+     * @param caches
+     *            The {@link List} of {@link cgCache} to be exported
+     * @param activity
+     *            The {@link Activity} in whose context the dialog should be shown
+     */
     public static void showExportMenu(final List<cgCache> caches, final Activity activity) {
         final AlertDialog.Builder builder = new AlertDialog.Builder(activity);
         builder.setTitle(R.string.export).setIcon(android.R.drawable.ic_menu_share);
diff --git a/main/src/cgeo/geocaching/export/FieldnoteExport.java b/main/src/cgeo/geocaching/export/FieldnoteExport.java
index e00a8b0..7677569 100644
--- a/main/src/cgeo/geocaching/export/FieldnoteExport.java
+++ b/main/src/cgeo/geocaching/export/FieldnoteExport.java
@@ -33,6 +33,13 @@ import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 
+/**
+ * Exports offline-logs in the Groundspeak Field Note format.<br>
+ * <br>
+ *
+ * Field Notes are simple plain text files, but poorly documented. Syntax:<br>
+ * <code>GCxxxxx,yyyy-mm-ddThh:mm:ssZ,Found it,"logtext"</code>
+ */
 public class FieldnoteExport extends AbstractExport {
     private static final File exportLocation = new File(Environment.getExternalStorageDirectory().getAbsolutePath() + "/field-notes");
     private static final SimpleDateFormat fieldNoteDateFormat = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z'");
@@ -41,6 +48,11 @@ public class FieldnoteExport extends AbstractExport {
         super(getString(R.string.export_fieldnotes));
     }
 
+    /**
+     * A dialog to allow the user to set options for the export.
+     *
+     * Currently available options are: upload field notes, only new logs since last export/upload
+     */
     private class ExportOptionsDialog extends AlertDialog {
         public ExportOptionsDialog(final List<cgCache> caches, final Activity activity) {
             super(activity);
@@ -65,7 +77,14 @@ public class FieldnoteExport extends AbstractExport {
 
     @Override
     public void export(final List<cgCache> caches, final Activity activity) {
-        new ExportOptionsDialog(caches, activity).show();
+        if (null == activity) {
+            // No activity given, so no user interaction possible.
+            // Start export with default parameters.
+            new ExportTask(caches, null, false, false).execute((Void) null);
+        } else {
+            // Show configuration dialog
+            new ExportOptionsDialog(caches, activity).show();
+        }
     }
 
     private class ExportTask extends AsyncTask<Void, Integer, Boolean> {
@@ -78,6 +97,18 @@ public class FieldnoteExport extends AbstractExport {
 
         private static final int STATUS_UPLOAD = -1;
 
+        /**
+         * Instantiates and configurates the task for exporting field notes.
+         *
+         * @param caches
+         *            The {@link List} of {@link cgCache} to be exported
+         * @param activity
+         *            optional: Show a progress bar and toasts
+         * @param upload
+         *            Upload the Field Note to geocaching.com
+         * @param onlyNew
+         *            Upload/export only new logs since last export
+         */
         public ExportTask(final List<cgCache> caches, final Activity activity, final boolean upload, final boolean onlyNew) {
             this.caches = caches;
             this.activity = activity;
@@ -87,8 +118,10 @@ public class FieldnoteExport extends AbstractExport {
 
         @Override
         protected void onPreExecute() {
-            progress.show(activity, null, getString(R.string.export) + ": " + getName(), ProgressDialog.STYLE_HORIZONTAL, null);
-            progress.setMaxProgressAndReset(caches.size());
+            if (null != activity) {
+                progress.show(activity, null, getString(R.string.export) + ": " + getName(), ProgressDialog.STYLE_HORIZONTAL, null);
+                progress.setMaxProgressAndReset(caches.size());
+            }
         }
 
         @Override
@@ -199,24 +232,28 @@ public class FieldnoteExport extends AbstractExport {
 
         @Override
         protected void onPostExecute(Boolean result) {
-            progress.dismiss();
+            if (null != activity) {
+                progress.dismiss();
 
-            if (result) {
-                if (onlyNew) {
-                    // update last export time in settings
+                if (result) {
+                    if (onlyNew) {
+                        // update last export time in settings
+                    }
+                    ActivityMixin.showToast(activity, getName() + " " + getString(R.string.export_exportedto) + ": " + exportFile.toString());
+                } else {
+                    ActivityMixin.showToast(activity, getString(R.string.export_failed));
                 }
-                ActivityMixin.showToast(activity, getName() + " " + getString(R.string.export_exportedto) + ": " + exportFile.toString());
-            } else {
-                ActivityMixin.showToast(activity, getString(R.string.export_failed));
             }
         }
 
         @Override
         protected void onProgressUpdate(Integer... status) {
-            if (STATUS_UPLOAD == status[0]) {
-                progress.setMessage(getString(R.string.export_fieldnotes_uploading));
-            } else {
-                progress.setProgress(status[0]);
+            if (null != activity) {
+                if (STATUS_UPLOAD == status[0]) {
+                    progress.setMessage(getString(R.string.export_fieldnotes_uploading));
+                } else {
+                    progress.setProgress(status[0]);
+                }
             }
         }
     }
diff --git a/main/src/cgeo/geocaching/export/GpxExport.java b/main/src/cgeo/geocaching/export/GpxExport.java
index 1e7d973..562f5fa 100644
--- a/main/src/cgeo/geocaching/export/GpxExport.java
+++ b/main/src/cgeo/geocaching/export/GpxExport.java
@@ -45,6 +45,14 @@ public class GpxExport extends AbstractExport {
         private final Progress progress = new Progress();
         private File exportFile;
 
+        /**
+         * Instantiates and configurates the task for exporting field notes.
+         * 
+         * @param caches
+         *            The {@link List} of {@link cgCache} to be exported
+         * @param activity
+         *            optional: Show a progress bar and toasts
+         */
         public ExportTask(final List<cgCache> caches, final Activity activity) {
             this.caches = caches;
             this.activity = activity;
@@ -52,8 +60,10 @@ public class GpxExport extends AbstractExport {
 
         @Override
         protected void onPreExecute() {
-            progress.show(activity, null, getString(R.string.export) + ": " + getName(), ProgressDialog.STYLE_HORIZONTAL, null);
-            progress.setMaxProgressAndReset(caches.size());
+            if (null != activity) {
+                progress.show(activity, null, getString(R.string.export) + ": " + getName(), ProgressDialog.STYLE_HORIZONTAL, null);
+                progress.setMaxProgressAndReset(caches.size());
+            }
         }
 
         @Override
@@ -200,17 +210,21 @@ public class GpxExport extends AbstractExport {
 
         @Override
         protected void onPostExecute(Boolean result) {
-            progress.dismiss();
-            if (result) {
-                ActivityMixin.showToast(activity, getName() + " " + getString(R.string.export_exportedto) + ": " + exportFile.toString());
-            } else {
-                ActivityMixin.showToast(activity, getString(R.string.export_failed));
+            if (null != activity) {
+                progress.dismiss();
+                if (result) {
+                    ActivityMixin.showToast(activity, getName() + " " + getString(R.string.export_exportedto) + ": " + exportFile.toString());
+                } else {
+                    ActivityMixin.showToast(activity, getString(R.string.export_failed));
+                }
             }
         }
 
         @Override
         protected void onProgressUpdate(Integer... status) {
-            progress.setProgress(status[0]);
+            if (null != activity) {
+                progress.setProgress(status[0]);
+            }
         }
     }
 }