android commit: Add JavaDoc for CordovaResourceApi

[ag...@apache.org]

Repository: cordova-android
Updated Branches:
  refs/heads/master b872df0f3 -> 0ec8f5d28


Add JavaDoc for CordovaResourceApi


Project: http://git-wip-us.apache.org/repos/asf/cordova-android/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-android/commit/0ec8f5d2
Tree: http://git-wip-us.apache.org/repos/asf/cordova-android/tree/0ec8f5d2
Diff: http://git-wip-us.apache.org/repos/asf/cordova-android/diff/0ec8f5d2

Branch: refs/heads/master
Commit: 0ec8f5d283558892d92673903f828b64a53aa3b0
Parents: b872df0
Author: Andrew Grieve <ag...@chromium.org>
Authored: Thu Apr 17 15:47:10 2014 -0400
Committer: Andrew Grieve <ag...@chromium.org>
Committed: Thu Apr 17 15:51:59 2014 -0400

----------------------------------------------------------------------
 .../org/apache/cordova/CordovaResourceApi.java  | 21 ++++++++++++++++++++
 1 file changed, 21 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/cordova-android/blob/0ec8f5d2/framework/src/org/apache/cordova/CordovaResourceApi.java
----------------------------------------------------------------------
diff --git a/framework/src/org/apache/cordova/CordovaResourceApi.java b/framework/src/org/apache/cordova/CordovaResourceApi.java
index ca4c965..f1770fd 100644
--- a/framework/src/org/apache/cordova/CordovaResourceApi.java
+++ b/framework/src/org/apache/cordova/CordovaResourceApi.java
@@ -45,6 +45,27 @@ import java.net.URL;
 import java.nio.channels.FileChannel;
 import java.util.Locale;
 
+/**
+ * What this class provides:
+ * 1. Helpers for reading & writing to URLs.
+ *   - E.g. handles assets, resources, content providers, files, data URIs, http[s]
+ *   - E.g. Can be used to query for mime-type & content length.
+ *
+ * 2. To allow plugins to redirect URLs (via remapUrl).
+ *   - All plugins should call remapUrl() on URLs they receive from JS *before*
+ *     passing the URL onto other utility functions in this class.
+ *   - For an example usage of this, refer to the org.apache.cordova.file plugin.
+ *
+ * 3. It exposes a way to use the OkHttp library that ships with Cordova.
+ *   - Through createHttpConnection().
+ *
+ * Future Work:
+ *   - Consider using a Cursor to query content URLs for their size (like the file plugin does).
+ *   - Allow plugins to remapUri to "cdv-plugin://plugin-name/$ID", which CordovaResourceApi
+ *     would then delegate to pluginManager.getPlugin(plugin-name).openForRead($ID)
+ *     - Currently, plugins *can* do this by remapping to a data: URL, but it's inefficient
+ *       for large payloads.
+ */
 public class CordovaResourceApi {
     @SuppressWarnings("unused")
     private static final String LOG_TAG = "CordovaResourceApi";