From 4e01ff666e61f4adb129002e4f2bbc8163806983 Mon Sep 17 00:00:00 2001 From: Bradlee Speice Date: Sat, 10 May 2014 20:20:16 -0400 Subject: [PATCH] Big documentation (no functionality) update --- .../bspeice/minimalbible/MinimalBible.java | 40 ++++++++++--- .../minimalbible/MinimalBibleModules.java | 2 +- .../minimalbible/activities/BaseActivity.java | 6 +- .../minimalbible/activities/BaseFragment.java | 26 ++++++++ .../downloader/ActivityDownloaderModule.java | 2 +- .../downloader/BookListFragment.java | 40 ++++++------- .../downloader/DownloadActivity.java | 1 + .../activities/downloader/DownloadPrefs_.java | 2 +- .../downloader/manager/BookRefreshTask.java | 14 +---- .../downloader/manager/DownloadManager.java | 59 +++++++++++++++++-- .../downloader/manager/EventBookList.java | 4 ++ 11 files changed, 146 insertions(+), 50 deletions(-) create mode 100644 MinimalBible/src/org/bspeice/minimalbible/activities/BaseFragment.java diff --git a/MinimalBible/src/org/bspeice/minimalbible/MinimalBible.java b/MinimalBible/src/org/bspeice/minimalbible/MinimalBible.java index 82ad26a..c61a6c2 100644 --- a/MinimalBible/src/org/bspeice/minimalbible/MinimalBible.java +++ b/MinimalBible/src/org/bspeice/minimalbible/MinimalBible.java @@ -7,32 +7,56 @@ import dagger.ObjectGraph; public class MinimalBible extends Application { + /** + * The graph used by Dagger to track dependencies + */ private ObjectGraph graph; - + + /** + * A singleton reference to the Application currently being run. + * Used mostly so we have a fixed point to get the App Context from + */ private static MinimalBible instance; - + + /** + * Create the application, and persist the application Context + */ public MinimalBible() { instance = this; } - - public static Context getAppContext() { - return instance; - } - public static MinimalBible getApplication(Context ctx) { - return (MinimalBible)ctx.getApplicationContext(); + /** + * Get the Application Context. Please note, all attempts to get the App Context should come + * through here, and please be sure that the Application won't satisfy what you need. + * @return The Application Context + */ + public static Context getAppContext() { + return instance; } + /** + * Get the Application, rather than just the Application Context. You likely should be using + * this, rather than {@link #getAppContext()} + * @return The MinimalBible {@link android.app.Application} object + */ public static MinimalBible getApplication() { return (MinimalBible)getAppContext(); } + /** + * Create the {@link android.app.Application}. Responsible for building and + * holding on to the master ObjectGraph. + */ @Override public void onCreate() { graph = ObjectGraph.create(new MinimalBibleModules()); graph.inject(this); } + /** + * Inject a Dagger object + * @param o The object to be injected + */ public void inject(Object o) { graph.inject(o); } diff --git a/MinimalBible/src/org/bspeice/minimalbible/MinimalBibleModules.java b/MinimalBible/src/org/bspeice/minimalbible/MinimalBibleModules.java index e23674a..346a598 100644 --- a/MinimalBible/src/org/bspeice/minimalbible/MinimalBibleModules.java +++ b/MinimalBible/src/org/bspeice/minimalbible/MinimalBibleModules.java @@ -5,7 +5,7 @@ import org.bspeice.minimalbible.activities.ActivityModules; import dagger.Module; /** - * Modules for the global application + * Master module for MinimalBible */ @Module( injects = { diff --git a/MinimalBible/src/org/bspeice/minimalbible/activities/BaseActivity.java b/MinimalBible/src/org/bspeice/minimalbible/activities/BaseActivity.java index f2ca95c..de85f3d 100644 --- a/MinimalBible/src/org/bspeice/minimalbible/activities/BaseActivity.java +++ b/MinimalBible/src/org/bspeice/minimalbible/activities/BaseActivity.java @@ -8,10 +8,12 @@ import android.os.Build; import android.os.Bundle; import android.support.v7.app.ActionBarActivity; +/** + * Wrapper for activities in MinimalBible to make sure we can support + * common functionality between them all. + */ public class BaseActivity extends ActionBarActivity { - // BaseActivity to take care of some stuff like setting the action bar color - @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); diff --git a/MinimalBible/src/org/bspeice/minimalbible/activities/BaseFragment.java b/MinimalBible/src/org/bspeice/minimalbible/activities/BaseFragment.java new file mode 100644 index 0000000..85f341d --- /dev/null +++ b/MinimalBible/src/org/bspeice/minimalbible/activities/BaseFragment.java @@ -0,0 +1,26 @@ +package org.bspeice.minimalbible.activities; + +import android.app.Activity; +import android.os.Build; +import android.support.v4.app.Fragment; +import android.view.View; + +import com.readystatesoftware.systembartint.SystemBarTintManager; + +/** + * Base class that defines all behavior common to Fragments in MinimalBible + */ +public class BaseFragment extends Fragment { + + /** + * Calculate the offset we need to display properly if the System bar is translucent + * @param context The {@link android.app.Activity} we are displaying in + * @param view The {@link android.view.View} we need to calculate the offset for. + */ + public static void setInsets(Activity context, View view) { + if (Build.VERSION.SDK_INT < Build.VERSION_CODES.KITKAT) return; + SystemBarTintManager tintManager = new SystemBarTintManager(context); + SystemBarTintManager.SystemBarConfig config = tintManager.getConfig(); + view.setPadding(0, config.getPixelInsetTop(true), config.getPixelInsetRight(), config.getPixelInsetBottom()); + } +} diff --git a/MinimalBible/src/org/bspeice/minimalbible/activities/downloader/ActivityDownloaderModule.java b/MinimalBible/src/org/bspeice/minimalbible/activities/downloader/ActivityDownloaderModule.java index c7dd3c7..9cd1e3d 100644 --- a/MinimalBible/src/org/bspeice/minimalbible/activities/downloader/ActivityDownloaderModule.java +++ b/MinimalBible/src/org/bspeice/minimalbible/activities/downloader/ActivityDownloaderModule.java @@ -26,7 +26,7 @@ public class ActivityDownloaderModule { * Provide a Singleton DownloadManager for injection * Note that we need to annotate Singleton here, only annotating on the * DownloadManager itself is not enough. - * @return global DownloadManager instance + * @return Global DownloadManager instance */ @Provides @Singleton DownloadManager provideDownloadManager() { diff --git a/MinimalBible/src/org/bspeice/minimalbible/activities/downloader/BookListFragment.java b/MinimalBible/src/org/bspeice/minimalbible/activities/downloader/BookListFragment.java index 306f24f..e3b847b 100644 --- a/MinimalBible/src/org/bspeice/minimalbible/activities/downloader/BookListFragment.java +++ b/MinimalBible/src/org/bspeice/minimalbible/activities/downloader/BookListFragment.java @@ -4,9 +4,7 @@ import android.app.Activity; import android.app.AlertDialog; import android.app.ProgressDialog; import android.content.DialogInterface; -import android.os.Build; import android.os.Bundle; -import android.support.v4.app.Fragment; import android.util.Log; import android.view.LayoutInflater; import android.view.View; @@ -14,11 +12,9 @@ import android.view.ViewGroup; import android.widget.ListView; import android.widget.Toast; -import com.readystatesoftware.systembartint.SystemBarTintManager; - -import org.androidannotations.annotations.sharedpreferences.Pref; import org.bspeice.minimalbible.MinimalBible; import org.bspeice.minimalbible.R; +import org.bspeice.minimalbible.activities.BaseFragment; import org.bspeice.minimalbible.activities.downloader.manager.DownloadManager; import org.bspeice.minimalbible.activities.downloader.manager.EventBookList; import org.crosswire.jsword.book.Book; @@ -27,7 +23,6 @@ import org.crosswire.jsword.book.BookComparators; import org.crosswire.jsword.book.BookFilter; import org.crosswire.jsword.book.FilterUtil; -import java.util.Collection; import java.util.Collections; import java.util.List; @@ -40,7 +35,7 @@ import butterknife.InjectView; * A placeholder fragment containing a simple view. */ -public class BookListFragment extends Fragment { +public class BookListFragment extends BaseFragment { /** * The fragment argument representing the section number for this fragment. */ @@ -72,7 +67,7 @@ public class BookListFragment extends Fragment { @Override public void onCreate(Bundle state) { super.onCreate(state); - MinimalBible.getApplication().inject(this); + MinimalBible.getApplication().inject(this); // Injection for Dagger goes here, not ctor } @Override @@ -92,6 +87,10 @@ public class BookListFragment extends Fragment { .getString(ARG_BOOK_CATEGORY)); } + /** + * Trigger the functionality to display a list of modules. Prompts user if downloading + * from the internet is allowable. + */ public void displayModules() { boolean dialogDisplayed = downloadPrefs.showedDownloadDialog().get(); @@ -108,16 +107,22 @@ public class BookListFragment extends Fragment { } } + /** + * Do the work of refreshing modules (download manager handles using cached copy vs. actual + * refresh), and then displaying them when ready. + */ private void refreshModules() { - EventBookList bookList = downloadManager.getDownloadBus().getStickyEvent(EventBookList.class); + // Check if the downloadManager has already refreshed everything + List bookList = downloadManager.getBookList(); if (bookList == null) { - downloadManager.getDownloadBus().registerSticky(this); + // downloadManager is in progress of refreshing + downloadManager.getDownloadBus().register(this); refreshDialog = new ProgressDialog(getActivity()); refreshDialog.setMessage("Refreshing available modules..."); refreshDialog.setCancelable(false); refreshDialog.show(); } else { - displayBooks(bookList.getBookList()); + displayBooks(bookList); } } @@ -132,17 +137,13 @@ public class BookListFragment extends Fragment { displayBooks(event.getBookList()); } - public static void setInsets(Activity context, View view) { - if (Build.VERSION.SDK_INT < Build.VERSION_CODES.KITKAT) return; - SystemBarTintManager tintManager = new SystemBarTintManager(context); - SystemBarTintManager.SystemBarConfig config = tintManager.getConfig(); - view.setPadding(0, config.getPixelInsetTop(true), config.getPixelInsetRight(), config.getPixelInsetBottom()); - } - + /** + * Do the hard work of creating the Adapter and displaying books. + * @param bookList The (unfiltered) list of {link org.crosswire.jsword.Book}s to display + */ public void displayBooks(List bookList) { try { // TODO: Should the filter be applied earlier in the process? - // TODO: Sort books by name? List displayList; BookCategory c = BookCategory.fromString(getArguments().getString(ARG_BOOK_CATEGORY)); @@ -156,7 +157,6 @@ public class BookListFragment extends Fragment { // To be honest, there should be no reason you end up here. Log.e(TAG, e.getMessage()); } - } private class DownloadDialogListener implements diff --git a/MinimalBible/src/org/bspeice/minimalbible/activities/downloader/DownloadActivity.java b/MinimalBible/src/org/bspeice/minimalbible/activities/downloader/DownloadActivity.java index c9ad587..765854f 100644 --- a/MinimalBible/src/org/bspeice/minimalbible/activities/downloader/DownloadActivity.java +++ b/MinimalBible/src/org/bspeice/minimalbible/activities/downloader/DownloadActivity.java @@ -44,6 +44,7 @@ public class DownloadActivity extends BaseActivity implements @Override public void onNavigationDrawerItemSelected(int position) { // update the main content by replacing fragments + //TODO: Switch to AutoFactory pattern, rather than newInstance() FragmentManager fragmentManager = getSupportFragmentManager(); fragmentManager .beginTransaction() diff --git a/MinimalBible/src/org/bspeice/minimalbible/activities/downloader/DownloadPrefs_.java b/MinimalBible/src/org/bspeice/minimalbible/activities/downloader/DownloadPrefs_.java index 4c8c71d..c1f9ca0 100644 --- a/MinimalBible/src/org/bspeice/minimalbible/activities/downloader/DownloadPrefs_.java +++ b/MinimalBible/src/org/bspeice/minimalbible/activities/downloader/DownloadPrefs_.java @@ -1,6 +1,6 @@ /* This is brutally ugly, but until https://github.com/square/dagger/issues/410 is resolved, -this is the best I can do while making sure that I can refactor the API later. +this is the best I can do while making sure that I can easily switch the API later */ // // DO NOT EDIT THIS FILE, IT HAS BEEN GENERATED USING AndroidAnnotations 3.0.1. diff --git a/MinimalBible/src/org/bspeice/minimalbible/activities/downloader/manager/BookRefreshTask.java b/MinimalBible/src/org/bspeice/minimalbible/activities/downloader/manager/BookRefreshTask.java index 8c60678..b1ab7d7 100644 --- a/MinimalBible/src/org/bspeice/minimalbible/activities/downloader/manager/BookRefreshTask.java +++ b/MinimalBible/src/org/bspeice/minimalbible/activities/downloader/manager/BookRefreshTask.java @@ -9,7 +9,6 @@ import android.util.Log; import org.bspeice.minimalbible.MinimalBible; import org.bspeice.minimalbible.activities.downloader.DownloadPrefs_; import org.crosswire.jsword.book.Book; -import org.crosswire.jsword.book.BookFilter; import org.crosswire.jsword.book.install.InstallException; import org.crosswire.jsword.book.install.Installer; @@ -30,19 +29,12 @@ public class BookRefreshTask extends AsyncTask> { DownloadPrefs_ downloadPrefs; private EventBus downloadBus; - private BookFilter filter; public BookRefreshTask(EventBus downloadBus) { this.downloadBus = downloadBus; MinimalBible.getApplication().inject(this); } - public BookRefreshTask(EventBus downloadBus, BookFilter f) { - this.downloadBus = downloadBus; - this.filter = f; - MinimalBible.getApplication().inject(this); - } - @Override protected List doInBackground(Installer... params) { List books = new LinkedList(); @@ -60,11 +52,7 @@ public class BookRefreshTask extends AsyncTask> { } } - if (filter != null) { - books.addAll(i.getBooks(filter)); - } else { - books.addAll(i.getBooks()); - } + books.addAll(i.getBooks()); publishProgress(++index, params.length); } diff --git a/MinimalBible/src/org/bspeice/minimalbible/activities/downloader/manager/DownloadManager.java b/MinimalBible/src/org/bspeice/minimalbible/activities/downloader/manager/DownloadManager.java index ed6a881..ba73abb 100644 --- a/MinimalBible/src/org/bspeice/minimalbible/activities/downloader/manager/DownloadManager.java +++ b/MinimalBible/src/org/bspeice/minimalbible/activities/downloader/manager/DownloadManager.java @@ -3,10 +3,12 @@ package org.bspeice.minimalbible.activities.downloader.manager; import android.util.Log; import org.bspeice.minimalbible.MinimalBible; +import org.crosswire.jsword.book.Book; import org.crosswire.jsword.book.BookCategory; import org.crosswire.jsword.book.install.InstallManager; import org.crosswire.jsword.book.install.Installer; +import java.util.List; import java.util.Map; import javax.inject.Inject; @@ -19,6 +21,11 @@ public class DownloadManager { private final String TAG = "DownloadManager"; + /** + * Cached copy of modules that are available so we don't refresh for everyone who requests it. + */ + private List availableModules = null; + @Inject protected EventBus downloadBus; @@ -26,21 +33,37 @@ public class DownloadManager { BookCategory.COMMENTARY, BookCategory.DICTIONARY, BookCategory.MAPS }; + /** + * Set up the DownloadManager, and notify jSword of where it should store files at + */ public DownloadManager() { MinimalBible.getApplication().inject(this); setDownloadDir(); - downloadEvents(); + refreshModules(); } + /** + * Get the installers available to jSword - this is how we get access to the actual modules + * @return All available {@link org.crosswire.jsword.book.install.Installer}s + */ public Map getInstallers() { return new InstallManager().getInstallers(); } - + + /** + * Helper method to transform the installers map to an array + * @return Array with all available {@link org.crosswire.jsword.book.install.Installer} objects + */ public Installer[] getInstallersArray() { Map installers = getInstallers(); return installers.values().toArray(new Installer[installers.size()]); } + /** + * Notify jSword that it needs to store files in the Android internal directory + * NOTE: Android will uninstall these files if you uninstall MinimalBible. + */ + @SuppressWarnings("null") private void setDownloadDir() { // We need to set the download directory for jSword to stick with // Android. @@ -49,10 +72,38 @@ public class DownloadManager { System.setProperty("jsword.home", home); } - private void downloadEvents() { + /** + * Do the work of kicking off the AsyncTask to refresh books, and make sure we know + * when it's done. + */ + private void refreshModules() { + downloadBus.register(this); new BookRefreshTask(downloadBus).execute(getInstallersArray()); } - + + /** + * When book refresh is done, cache the list so we can give that to someone else + * @param event A POJO wrapper around the Book list + */ + @SuppressWarnings("unused") + public void onEvent(EventBookList event) { + this.availableModules = event.getBookList(); + } + + /** + * Get the cached book list + * @return The cached book list, or null + */ + public List getBookList() { + return availableModules; + } + + /** + * Get the current download bus if you want to know when refresh is done. + * Please note that you will not be notified if the book refresh has already + * been completed, make sure to check {@link #getBookList()} first. + * @return The EventBus the DownloadManager is using + */ public EventBus getDownloadBus() { return this.downloadBus; } diff --git a/MinimalBible/src/org/bspeice/minimalbible/activities/downloader/manager/EventBookList.java b/MinimalBible/src/org/bspeice/minimalbible/activities/downloader/manager/EventBookList.java index a2b561b..1b4d0da 100644 --- a/MinimalBible/src/org/bspeice/minimalbible/activities/downloader/manager/EventBookList.java +++ b/MinimalBible/src/org/bspeice/minimalbible/activities/downloader/manager/EventBookList.java @@ -4,6 +4,10 @@ import java.util.List; import org.crosswire.jsword.book.Book; +/** + * POJO class for {@link de.greenrobot.event.EventBus} to broadcast whenever + * we've finished updating the book list. + */ public class EventBookList { private List bookList;