diff --git a/cordova-js-src/plugin/android/app.js b/cordova-js-src/plugin/android/app.js index 027ce31b..c783ab1e 100644 --- a/cordova-js-src/plugin/android/app.js +++ b/cordova-js-src/plugin/android/app.js @@ -31,14 +31,14 @@ module.exports = { }, /** - * Load the url into the webview or into new browser instance. + * Load the url into the WebView or into new browser instance. * * @param url The URL to load * @param props Properties that can be passed in to the activity: * wait: int => wait msec before loading URL * loadingDialog: "Title,Message" => display a native loading dialog * loadUrlTimeoutValue: int => time in msec to wait before triggering a timeout error - * clearHistory: boolean => clear webview history (default=false) + * clearHistory: boolean => clear WebView history (default=false) * openExternal: boolean => open in a new browser (default=false) * * Example: diff --git a/framework/cordova.gradle b/framework/cordova.gradle index 9b978398..abb5b411 100644 --- a/framework/cordova.gradle +++ b/framework/cordova.gradle @@ -150,7 +150,7 @@ def doGetConfigPreference(name, defaultValue) { } def doApplyCordovaConfigCustomization() { - // Apply user overide properties that comes from the "--gradleArg=-P" parameters + // Apply user override properties that comes from the "--gradleArg=-P" parameters if (project.hasProperty('cdvMinSdkVersion')) { cordovaConfig.MIN_SDK_VERSION = Integer.parseInt('' + cdvMinSdkVersion) } diff --git a/framework/src/org/apache/cordova/AllowListPlugin.java b/framework/src/org/apache/cordova/AllowListPlugin.java index 63dd5a19..e85f8ecd 100644 --- a/framework/src/org/apache/cordova/AllowListPlugin.java +++ b/framework/src/org/apache/cordova/AllowListPlugin.java @@ -39,7 +39,7 @@ public class AllowListPlugin extends CordovaPlugin { // Used when instantiated via reflection by PluginManager public AllowListPlugin() { } - // These can be used by embedders to allow Java-configuration of an allow list. + // These can be used by plugin developers to allow Java-configuration of an allow list. public AllowListPlugin(Context context) { this(new AllowList(), new AllowList(), null); new CustomConfigXmlParser().parse(context); diff --git a/framework/src/org/apache/cordova/AuthenticationToken.java b/framework/src/org/apache/cordova/AuthenticationToken.java index d3a231a0..38451c56 100644 --- a/framework/src/org/apache/cordova/AuthenticationToken.java +++ b/framework/src/org/apache/cordova/AuthenticationToken.java @@ -37,8 +37,7 @@ public class AuthenticationToken { /** * Sets the user name. * - * @param userName - * the new user name + * @param userName the new user name */ public void setUserName(String userName) { this.userName = userName; @@ -56,8 +55,7 @@ public class AuthenticationToken { /** * Sets the password. * - * @param password - * the new password + * @param password the new password */ public void setPassword(String password) { this.password = password; diff --git a/framework/src/org/apache/cordova/CallbackMap.java b/framework/src/org/apache/cordova/CallbackMap.java index 050daa01..b825610c 100644 --- a/framework/src/org/apache/cordova/CallbackMap.java +++ b/framework/src/org/apache/cordova/CallbackMap.java @@ -54,7 +54,7 @@ public class CallbackMap { * obtained from registerCallback() * * @param mappedId The request code obtained from registerCallback() - * @return The CordovaPlugin and orignal request code that correspond to the + * @return The CordovaPlugin and original request code that correspond to the * given mappedCode */ public synchronized Pair getAndRemoveCallback(int mappedId) { diff --git a/framework/src/org/apache/cordova/Config.java b/framework/src/org/apache/cordova/Config.java index 238cd5e3..2082f251 100644 --- a/framework/src/org/apache/cordova/Config.java +++ b/framework/src/org/apache/cordova/Config.java @@ -23,7 +23,7 @@ import java.util.List; import android.app.Activity; -@Deprecated // Use AllowList, CordovaPrefences, etc. directly. +@Deprecated // Use AllowList, CordovaPreferences, etc. directly. public class Config { private static final String TAG = "Config"; diff --git a/framework/src/org/apache/cordova/CordovaActivity.java b/framework/src/org/apache/cordova/CordovaActivity.java index 325e9e9d..50d6b323 100755 --- a/framework/src/org/apache/cordova/CordovaActivity.java +++ b/framework/src/org/apache/cordova/CordovaActivity.java @@ -49,7 +49,7 @@ import androidx.core.splashscreen.SplashScreen; * application. It should be extended by the user to load the specific * html file that contains the application. * - * As an example: + *

As an example:

* * 
  *     package org.apache.cordova.examples;
@@ -68,17 +68,16 @@ import androidx.core.splashscreen.SplashScreen;
  *     }
  *
* - * Cordova xml configuration: Cordova uses a configuration file at - * res/xml/config.xml to specify its settings. See "The config.xml File" - * guide in cordova-docs at http://cordova.apache.org/docs for the documentation - * for the configuration. The use of the set*Property() methods is - * deprecated in favor of the config.xml file. + *

Cordova xml configuration: Cordova uses a configuration file at + * res/xml/config.xml to specify its settings. See the "Config.xml API" documentation for + * configuration details at Apache Cordova Docs.

* + *

The use of the set*Property() methods is deprecated in favor of the config.xml file.

*/ public class CordovaActivity extends AppCompatActivity { public static String TAG = "CordovaActivity"; - // The webview for our app + // The WebView for our app protected CordovaWebView appView; private static int ACTIVITY_STARTING = 0; @@ -206,7 +205,7 @@ public class CordovaActivity extends AppCompatActivity { /** * Construct the default web view object. *

- * Override this to customize the webview that is used. + * Override this to customize the WebView that is used. */ protected CordovaWebView makeWebView() { return new CordovaWebViewImpl(makeWebViewEngine()); @@ -227,7 +226,7 @@ public class CordovaActivity extends AppCompatActivity { } /** - * Load the url into the webview. + * Load the url into the WebView. */ public void loadUrl(String url) { if (appView == null) { @@ -250,7 +249,7 @@ public class CordovaActivity extends AppCompatActivity { if (this.appView != null) { // CB-9382 If there is an activity that started for result and main activity is waiting for callback - // result, we shoudn't stop WebView Javascript timers, as activity for result might be using them + // result, we shouldn't stop WebView Javascript timers, as activity for result might be using them boolean keepRunning = this.keepRunning || this.cordovaInterface.activityResultCallback != null; this.appView.handlePause(keepRunning); } diff --git a/framework/src/org/apache/cordova/CordovaClientCertRequest.java b/framework/src/org/apache/cordova/CordovaClientCertRequest.java index a7889341..af88392f 100644 --- a/framework/src/org/apache/cordova/CordovaClientCertRequest.java +++ b/framework/src/org/apache/cordova/CordovaClientCertRequest.java @@ -47,8 +47,8 @@ public class CordovaClientCertRequest implements ICordovaClientCertRequest { request.cancel(); } - /* - * Returns the host name of the server requesting the certificate. + /** + * @return the host name of the server requesting the certificate. */ @SuppressLint("NewApi") @Override @@ -57,8 +57,8 @@ public class CordovaClientCertRequest implements ICordovaClientCertRequest { return request.getHost(); } - /* - * Returns the acceptable types of asymmetric keys (can be null). + /** + * @return the acceptable types of asymmetric keys (can be null). */ @SuppressLint("NewApi") @Override @@ -67,8 +67,8 @@ public class CordovaClientCertRequest implements ICordovaClientCertRequest { return request.getKeyTypes(); } - /* - * Returns the port number of the server requesting the certificate. + /** + * @return the port number of the server requesting the certificate. */ @SuppressLint("NewApi") @Override @@ -77,8 +77,8 @@ public class CordovaClientCertRequest implements ICordovaClientCertRequest { return request.getPort(); } - /* - * Returns the acceptable certificate issuers for the certificate matching the private key (can be null). + /** + * @return the acceptable certificate issuers for the certificate matching the private key (can be null). */ @SuppressLint("NewApi") @Override @@ -87,7 +87,7 @@ public class CordovaClientCertRequest implements ICordovaClientCertRequest { return request.getPrincipals(); } - /* + /** * Ignore the request for now. Do not remember user's choice. */ @SuppressLint("NewApi") @@ -97,7 +97,7 @@ public class CordovaClientCertRequest implements ICordovaClientCertRequest { request.ignore(); } - /* + /** * Proceed with the specified private key and client certificate chain. Remember the user's positive choice and use it for future requests. * * @param privateKey The privateKey diff --git a/framework/src/org/apache/cordova/CordovaDialogsHelper.java b/framework/src/org/apache/cordova/CordovaDialogsHelper.java index a4c7ceb7..f74ad8e7 100644 --- a/framework/src/org/apache/cordova/CordovaDialogsHelper.java +++ b/framework/src/org/apache/cordova/CordovaDialogsHelper.java @@ -118,8 +118,8 @@ public class CordovaDialogsHelper { * If the client returns true, WebView will assume that the client will * handle the prompt dialog and call the appropriate JsPromptResult method. * - * Since we are hacking prompts for our own purposes, we should not be using them for - * this purpose, perhaps we should hack console.log to do this instead! + *

Since we are hacking prompts for our own purposes, we should not be using them for + * this purpose, perhaps we should hack console.log to do this instead!

*/ public void showPrompt(String message, String defaultValue, final Result result) { // Returning false would also show a dialog, but the default one shows the origin (ugly). diff --git a/framework/src/org/apache/cordova/CordovaInterface.java b/framework/src/org/apache/cordova/CordovaInterface.java index 53d03a5c..86779722 100755 --- a/framework/src/org/apache/cordova/CordovaInterface.java +++ b/framework/src/org/apache/cordova/CordovaInterface.java @@ -51,7 +51,8 @@ public interface CordovaInterface { /** * Get the Android activity. * - * If a custom engine lives outside of the Activity's lifecycle the return value may be null. + *

If a custom engine lives outside of the Activity's lifecycle the return value + * may be null.

* * @return the Activity */ @@ -74,7 +75,7 @@ public interface CordovaInterface { public Object onMessage(String id, Object data); /** - * Returns a shared thread pool that can be used for background tasks. + * @return a shared thread pool that can be used for background tasks. */ public ExecutorService getThreadPool(); @@ -89,7 +90,9 @@ public interface CordovaInterface { public void requestPermissions(CordovaPlugin plugin, int requestCode, String [] permissions); /** - * Check for a permission. Returns true if the permission is granted, false otherwise. + * Check for a permission. + * + * @return true if the permission is granted, false otherwise. */ public boolean hasPermission(String permission); diff --git a/framework/src/org/apache/cordova/CordovaInterfaceImpl.java b/framework/src/org/apache/cordova/CordovaInterfaceImpl.java index 649dd573..068c4369 100644 --- a/framework/src/org/apache/cordova/CordovaInterfaceImpl.java +++ b/framework/src/org/apache/cordova/CordovaInterfaceImpl.java @@ -135,7 +135,9 @@ public class CordovaInterfaceImpl implements CordovaInterface { } /** - * Routes the result to the awaiting plugin. Returns false if no plugin was waiting. + * Routes the result to the awaiting plugin. + * + * @return false if no plugin was waiting. */ public boolean onActivityResult(int requestCode, int resultCode, Intent intent) { CordovaPlugin callback = activityResultCallback; diff --git a/framework/src/org/apache/cordova/CordovaPlugin.java b/framework/src/org/apache/cordova/CordovaPlugin.java index 8adeb7a1..90a12c1a 100644 --- a/framework/src/org/apache/cordova/CordovaPlugin.java +++ b/framework/src/org/apache/cordova/CordovaPlugin.java @@ -79,7 +79,7 @@ public class CordovaPlugin { } /** - * Returns the plugin's service name (what you'd use when calling pluginManger.getPlugin()) + * @return the plugin's service name (what you'd use when calling pluginManger.getPlugin()) */ public String getServiceName() { return serviceName; @@ -88,11 +88,14 @@ public class CordovaPlugin { /** * Executes the request. * - * This method is called from the WebView thread. To do a non-trivial amount of work, use: - * cordova.getThreadPool().execute(runnable); + *

This method is called from the WebView thread. To do a non-trivial + * amount of work, use:

* - * To run on the UI thread, use: - * cordova.getActivity().runOnUiThread(runnable); + * 
cordova.getThreadPool().execute(runnable);
+ * + *

To run on the UI thread, use:

+ * + * 
cordova.getActivity().runOnUiThread(runnable);
* * @param action The action to execute. * @param rawArgs The exec() arguments in JSON form. @@ -107,11 +110,13 @@ public class CordovaPlugin { /** * Executes the request. * - * This method is called from the WebView thread. To do a non-trivial amount of work, use: - * cordova.getThreadPool().execute(runnable); + *

This method is called from the WebView thread. To do a non-trivial amount of work, use:

* - * To run on the UI thread, use: - * cordova.getActivity().runOnUiThread(runnable); + * 
cordova.getThreadPool().execute(runnable);
+ * + *

To run on the UI thread, use:

+ * + * 
cordova.getActivity().runOnUiThread(runnable);
* * @param action The action to execute. * @param args The exec() arguments. @@ -126,10 +131,10 @@ public class CordovaPlugin { /** * Executes the request. * - * This method is called from the WebView thread. To do a non-trivial amount of work, use: + *

This method is called from the WebView thread. To do a non-trivial amount of work, use:

* cordova.getThreadPool().execute(runnable); * - * To run on the UI thread, use: + *

To run on the UI thread, use:

* cordova.getActivity().runOnUiThread(runnable); * * @param action The action to execute. @@ -231,18 +236,18 @@ public class CordovaPlugin { /** * Hook for blocking the loading of external resources. * - * This will be called when the WebView's shouldInterceptRequest wants to + *

This will be called when the WebView's shouldInterceptRequest wants to * know whether to open a connection to an external resource. Return false * to block the request: if any plugin returns false, Cordova will block * the request. If all plugins return null, the default policy will be * enforced. If at least one plugin returns true, and no plugins return - * false, then the request will proceed. + * false, then the request will proceed.

* - * Note that this only affects resource requests which are routed through + *

Note that this only affects resource requests which are routed through * WebViewClient.shouldInterceptRequest, such as XMLHttpRequest requests and * img tag loads. WebSockets and media requests (such as

*/ public Boolean shouldAllowRequest(String url) { return null; @@ -250,13 +255,13 @@ public class CordovaPlugin { /** * Hook for blocking navigation by the Cordova WebView. This applies both to top-level and - * iframe navigations. + * iframe navigation. * - * This will be called when the WebView's needs to know whether to navigate + *

This will be called when the WebView's needs to know whether to navigate * to a new page. Return false to block the navigation: if any plugin * returns false, Cordova will block the navigation. If all plugins return * null, the default policy will be enforced. It at least one plugin returns - * true, and no plugins return false, then the navigation will proceed. + * true, and no plugins return false, then the navigation will proceed.

*/ public Boolean shouldAllowNavigation(String url) { return null; @@ -274,12 +279,12 @@ public class CordovaPlugin { /** * Hook for blocking the launching of Intents by the Cordova application. * - * This will be called when the WebView will not navigate to a page, but + *

This will be called when the WebView will not navigate to a page, but * could launch an intent to handle the URL. Return false to block this: if * any plugin returns false, Cordova will block the navigation. If all * plugins return null, the default policy will be enforced. If at least one * plugin returns true, and no plugins return false, then the URL will be - * opened. + * opened.

*/ public Boolean shouldOpenExternalUrl(String url) { return null; @@ -288,8 +293,8 @@ public class CordovaPlugin { /** * Allows plugins to handle a link being clicked. Return true here to cancel the navigation. * - * @param url The URL that is trying to be loaded in the Cordova webview. - * @return Return true to prevent the URL from loading. Default is false. + * @param url The URL that is trying to be loaded in the Cordova WebView. + * @return true to prevent the URL from loading. Default is false. */ public boolean onOverrideUrlLoading(String url) { return false; @@ -299,17 +304,20 @@ public class CordovaPlugin { * Hook for redirecting requests. Applies to WebView requests as well as requests made by plugins. * To handle the request directly, return a URI in the form: * - * cdvplugin://pluginId/... + * 
cdvplugin://pluginId/...
* - * And implement handleOpenForRead(). - * To make this easier, use the toPluginUri() and fromPluginUri() helpers: + *

And implement handleOpenForRead().

* + *

To make this easier, use the toPluginUri() and fromPluginUri() helpers:

+ * + * 
      *     public Uri remapUri(Uri uri) { return toPluginUri(uri); }
      *
      *     public CordovaResourceApi.OpenForReadResult handleOpenForRead(Uri uri) throws IOException {
      *         Uri origUri = fromPluginUri(uri);
      *         ...
      *     }
+     *
*/ public Uri remapUri(Uri uri) { return null; @@ -347,9 +355,9 @@ public class CordovaPlugin { /** * Called when the WebView does a top-level navigation or refreshes. * - * Plugins should stop any long-running processes and clean up internal state. + *

Plugins should stop any long-running processes and clean up internal state.

* - * Does nothing by default. + *

Does nothing by default.

*/ public void onReset() { } @@ -362,9 +370,7 @@ public class CordovaPlugin { * @param handler The HttpAuthHandler used to set the WebView's response * @param host The host requiring authentication * @param realm The realm for which authentication is required - * - * @return Returns True if plugin will resolve this auth challenge, otherwise False - * + * @return true if the plugin will resolve this auth challenge, else false */ public boolean onReceivedHttpAuthRequest(CordovaWebView view, ICordovaHttpAuthHandler handler, String host, String realm) { return false; @@ -376,9 +382,7 @@ public class CordovaPlugin { * * @param view The WebView that is initiating the callback * @param request The client certificate request - * - * @return Returns True if plugin will resolve this auth challenge, otherwise False - * + * @return True if plugin will resolve this auth challenge, otherwise False */ public boolean onReceivedClientCertRequest(CordovaWebView view, ICordovaClientCertRequest request) { return false; @@ -396,20 +400,17 @@ public class CordovaPlugin { * Called by the Plugin Manager when we need to actually request permissions * * @param requestCode Passed to the activity to track the request - * - * @return Returns the permission that was stored in the plugin + * @return The permission that was stored in the plugin */ - public void requestPermissions(int requestCode) { } - /* + /** * Called by the WebView implementation to check for geolocation permissions, can be used * by other Java methods in the event that a plugin is using this as a dependency. * - * @return Returns true if the plugin has all the permissions it needs to operate. + * @return True if the plugin has all the permissions it needs to operate. */ - public boolean hasPermisssion() { return true; } @@ -420,7 +421,6 @@ public class CordovaPlugin { * @param requestCode * @param permissions * @param grantResults - * * @deprecated Use {@link #onRequestPermissionsResult} instead. */ @Deprecated @@ -443,6 +443,7 @@ public class CordovaPlugin { /** * Allow plugins to supply a PathHandler for the WebViewAssetHandler + * * @return a CordovaPluginPathHandler which listen for paths and returns a response */ public CordovaPluginPathHandler getPathHandler() { @@ -450,11 +451,13 @@ public class CordovaPlugin { } /** - * Called when the WebView's render process has exited. Can be used to collect information regarding the crash for crashlytics or optionally attempt to gracefully handle/recover the crashed webview by recreating it. + * Called when the WebView's render process has exited. Can be used to collect information + * regarding the crash for crashlytics or optionally attempt to gracefully handle/recover the + * crashed WebView by recreating it. * - * See WebViewClient#onRenderProcessGone + *

See WebViewClient#onRenderProcessGone

* - * Note: A plugin must not attempt to recover a webview that it does not own/manage. + *

Note: A plugin must not attempt to recover a WebView that it does not own/manage.

* * @return true if the host application handled the situation that process has exited, * otherwise, application will crash if render process crashed, or be killed diff --git a/framework/src/org/apache/cordova/CordovaResourceApi.java b/framework/src/org/apache/cordova/CordovaResourceApi.java index a9f3453c..1d6fd6f2 100644 --- a/framework/src/org/apache/cordova/CordovaResourceApi.java +++ b/framework/src/org/apache/cordova/CordovaResourceApi.java @@ -45,21 +45,36 @@ import java.util.zip.GZIPInputStream; /** * 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. + *
    + *
  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. + *
  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. + *
* - * 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/foo", which CordovaResourceApi - * would then delegate to pluginManager.getPlugin(plugin-name).openForRead(url) - * - Currently, plugins *can* do this by remapping to a data: URL, but it's inefficient - * for large payloads. + *

Future Work:

+ * */ public class CordovaResourceApi { @SuppressWarnings("unused") @@ -143,8 +158,7 @@ public class CordovaResourceApi { } /** - * Returns a File that points to the resource, or null if the resource - * is not on the local filesystem. + * @return A file that points to the resource, or null if the resource is not on the local filesystem. */ public File mapUriToFile(Uri uri) { assertBackgroundThread(); @@ -223,11 +237,12 @@ public class CordovaResourceApi { /** * Opens a stream to the given URI, also providing the MIME type & length. + * * @return Never returns null. - * @throws Throws an InvalidArgumentException for relative URIs. Relative URIs should be - * resolved before being passed into this function. - * @throws Throws an IOException if the URI cannot be opened. - * @throws Throws an IllegalStateException if called on a foreground thread. + * @throws IllegalArgumentException For relative URIs. Relative URIs should be resolved before + * being passed into this function. + * @throws IOException If the URI cannot be opened. + * @throws IllegalStateException If called on a foreground thread. */ public OpenForReadResult openForRead(Uri uri) throws IOException { return openForRead(uri, false); @@ -235,11 +250,12 @@ public class CordovaResourceApi { /** * Opens a stream to the given URI, also providing the MIME type & length. + * * @return Never returns null. - * @throws Throws an InvalidArgumentException for relative URIs. Relative URIs should be - * resolved before being passed into this function. - * @throws Throws an IOException if the URI cannot be opened. - * @throws Throws an IllegalStateException if called on a foreground thread and skipThreadCheck is false. + * @throws IllegalArgumentException For relative URIs. Relative URIs should be resolved before + * being passed into this function. + * @throws IOException If the URI cannot be opened. + * @throws IllegalStateException If called on a foreground thread and skipThreadCheck is false. */ public OpenForReadResult openForRead(Uri uri, boolean skipThreadCheck) throws IOException { if (!skipThreadCheck) { @@ -320,10 +336,11 @@ public class CordovaResourceApi { /** * Opens a stream to the given URI. + * * @return Never returns null. - * @throws Throws an InvalidArgumentException for relative URIs. Relative URIs should be - * resolved before being passed into this function. - * @throws Throws an IOException if the URI cannot be opened. + * @throws IllegalArgumentException For relative URIs. Relative URIs should be resolved before + * being passed into this function. + * @throws IOException If the URI cannot be opened. */ public OutputStream openOutputStream(Uri uri, boolean append) throws IOException { assertBackgroundThread(); diff --git a/framework/src/org/apache/cordova/CordovaWebView.java b/framework/src/org/apache/cordova/CordovaWebView.java index 47247f79..e4c7bd04 100644 --- a/framework/src/org/apache/cordova/CordovaWebView.java +++ b/framework/src/org/apache/cordova/CordovaWebView.java @@ -25,9 +25,9 @@ import android.view.View; import android.webkit.WebChromeClient.CustomViewCallback; /** - * Main interface for interacting with a Cordova webview - implemented by CordovaWebViewImpl. + * Main interface for interacting with a Cordova WebView - implemented by CordovaWebViewImpl. * This is an interface so that it can be easily mocked in tests. - * Methods may be added to this interface without a major version bump, as plugins & embedders + * Methods may be added to this interface without a major version bump, as plugins/developer * are not expected to implement it. */ public interface CordovaWebView { @@ -70,34 +70,47 @@ public interface CordovaWebView { /** * Send JavaScript statement back to JavaScript. * - * Deprecated (https://issues.apache.org/jira/browse/CB-6851) + *

Deprecated (CB-6851) * Instead of executing snippets of JS, you should use the exec bridge - * to create a Java->JS communication channel. - * To do this: - * 1. Within plugin.xml (to have your JS run before deviceready): - * - * 2. Within your .js (call exec on start-up): + * to create a Java->JS communication channel.

+ * + *

To do this:

+ * + *

1. Within plugin.xml (to have your JS run before deviceready):

+ * + * 
+     * 
+     *
+ * + *

2. Within your .js (call exec on start-up):

+ * + * 
      *    require('cordova/channel').onCordovaReady.subscribe(function() {
      *      require('cordova/exec')(win, null, 'Plugin', 'method', []);
      *      function win(message) {
      *        ... process message from java here ...
      *      }
      *    });
-     * 3. Within your .java:
+     *
+ * + *

3. Within your .java:

+ * + * 
      *    PluginResult dataResult = new PluginResult(PluginResult.Status.OK, CODE);
      *    dataResult.setKeepCallback(true);
      *    savedCallbackContext.sendPluginResult(dataResult);
+     *
*/ @Deprecated void sendJavascript(String statememt); /** - * Load the specified URL in the Cordova webview or a new browser instance. + * Load the specified URL in the Cordova WebView or a new browser instance. * - * NOTE: If openExternal is false, only allow listed URLs can be loaded. + *

NOTE: If openExternal is false, only allow listed URLs can be loaded.

* * @param url The url to load. - * @param openExternal Load url in browser instead of Cordova webview. + * @param openExternal Load url in browser instead of Cordova WebView. * @param clearHistory Clear the history stack, so new page becomes top of history * @param params Parameters for new app */ diff --git a/framework/src/org/apache/cordova/CordovaWebViewEngine.java b/framework/src/org/apache/cordova/CordovaWebViewEngine.java index c8e5a55d..e2a45374 100644 --- a/framework/src/org/apache/cordova/CordovaWebViewEngine.java +++ b/framework/src/org/apache/cordova/CordovaWebViewEngine.java @@ -59,7 +59,7 @@ public interface CordovaWebViewEngine { /** Clean up all resources associated with the WebView. */ void destroy(); - /** Add the evaulate Javascript method **/ + /** Add the evaluate Javascript method **/ void evaluateJavascript(String js, ValueCallback callback); /** diff --git a/framework/src/org/apache/cordova/CordovaWebViewImpl.java b/framework/src/org/apache/cordova/CordovaWebViewImpl.java index 4d5221e2..087ed374 100644 --- a/framework/src/org/apache/cordova/CordovaWebViewImpl.java +++ b/framework/src/org/apache/cordova/CordovaWebViewImpl.java @@ -43,7 +43,7 @@ import java.util.Map; import java.util.Set; /** - * Main class for interacting with a Cordova webview. Manages plugins, events, and a CordovaWebViewEngine. + * Main class for interacting with a Cordova WebView. Manages plugins, events, and a CordovaWebViewEngine. * Class uses two-phase initialization. You must call init() before calling any other methods. */ public class CordovaWebViewImpl implements CordovaWebView { @@ -154,7 +154,7 @@ public class CordovaWebViewImpl implements CordovaWebView { stopLoading(); LOG.e(TAG, "CordovaWebView: TIMEOUT ERROR!"); - // Handle other errors by passing them to the webview in JS + // Handle other errors by passing them to the WebView in JS JSONObject data = new JSONObject(); try { data.put("errorCode", -6); @@ -219,7 +219,7 @@ public class CordovaWebViewImpl implements CordovaWebView { engine.clearHistory(); } - // If loading into our webview + // If loading into our WebView if (!openExternal) { // Make sure url is in allow list if (pluginManager.shouldAllowNavigation(url)) { @@ -487,7 +487,7 @@ public class CordovaWebViewImpl implements CordovaWebView { // If app doesn't want to run in background if (!keepRunning) { - // Pause JavaScript timers. This affects all webviews within the app! + // Pause JavaScript timers. This affects all WebViews within the app! engine.setPaused(true); } } @@ -497,7 +497,7 @@ public class CordovaWebViewImpl implements CordovaWebView { return; } - // Resume JavaScript timers. This affects all webviews within the app! + // Resume JavaScript timers. This affects all WebViews within the app! engine.setPaused(false); this.pluginManager.onResume(keepRunning); @@ -537,7 +537,7 @@ public class CordovaWebViewImpl implements CordovaWebView { // We should use a blank data: url instead so it's more obvious this.loadUrl("about:blank"); - // TODO: Should not destroy webview until after about:blank is done loading. + // TODO: Should not destroy WebView until after about:blank is done loading. engine.destroy(); hideCustomView(); } diff --git a/framework/src/org/apache/cordova/CoreAndroid.java b/framework/src/org/apache/cordova/CoreAndroid.java index 36b28b2d..158e46db 100755 --- a/framework/src/org/apache/cordova/CoreAndroid.java +++ b/framework/src/org/apache/cordova/CoreAndroid.java @@ -69,8 +69,9 @@ public class CoreAndroid extends CordovaPlugin { * Executes the request and returns PluginResult. * * @param action The action to execute. - * @param args JSONArry of arguments for the plugin. + * @param args JSONArray of arguments for the plugin. * @param callbackContext The callback context from which we were invoked. + * * @return A PluginResult object with a status and message. */ @Override @@ -83,9 +84,9 @@ public class CoreAndroid extends CordovaPlugin { this.clearCache(); } else if (action.equals("show")) { - // This gets called from JavaScript onCordovaReady to show the webview. + // This gets called from JavaScript onCordovaReady to show the WebView. // I recommend we change the name of the Message as spinner/stop is not - // indicative of what this actually does (shows the webview). + // indicative of what this actually does (shows the WebView). cordova.getActivity().runOnUiThread(new Runnable() { @Override public void run() { @@ -154,7 +155,7 @@ public class CoreAndroid extends CordovaPlugin { } /** - * Load the url into the webview. + * Load the url into the WebView. * * @param url * @param props Properties that can be passed in to the Cordova activity (i.e. loadingDialog, wait, ...) @@ -354,9 +355,8 @@ public class CoreAndroid extends CordovaPlugin { } } - /* + /** * Unregister the receiver - * */ @Override public void onDestroy() diff --git a/framework/src/org/apache/cordova/ICordovaClientCertRequest.java b/framework/src/org/apache/cordova/ICordovaClientCertRequest.java index 1417a156..601be9b9 100644 --- a/framework/src/org/apache/cordova/ICordovaClientCertRequest.java +++ b/framework/src/org/apache/cordova/ICordovaClientCertRequest.java @@ -31,32 +31,32 @@ public interface ICordovaClientCertRequest { */ public void cancel(); - /* - * Returns the host name of the server requesting the certificate. + /** + * @return the host name of the server requesting the certificate. */ public String getHost(); - /* - * Returns the acceptable types of asymmetric keys (can be null). + /** + * @return the acceptable types of asymmetric keys (can be null). */ public String[] getKeyTypes(); - /* - * Returns the port number of the server requesting the certificate. + /** + * @return the port number of the server requesting the certificate. */ public int getPort(); - /* - * Returns the acceptable certificate issuers for the certificate matching the private key (can be null). + /** + * @return the acceptable certificate issuers for the certificate matching the private key (can be null). */ public Principal[] getPrincipals(); - /* + /** * Ignore the request for now. Do not remember user's choice. */ public void ignore(); - /* + /** * Proceed with the specified private key and client certificate chain. Remember the user's positive choice and use it for future requests. * * @param privateKey The privateKey diff --git a/framework/src/org/apache/cordova/LOG.java b/framework/src/org/apache/cordova/LOG.java index 9fe7a7df..758eaba0 100755 --- a/framework/src/org/apache/cordova/LOG.java +++ b/framework/src/org/apache/cordova/LOG.java @@ -23,8 +23,8 @@ import android.util.Log; /** * Log to Android logging system. * - * Log message can be a string or a printf formatted string with arguments. - * See http://developer.android.com/reference/java/util/Formatter.html + *

Log message can be a string or a printf formatted string with arguments. + * See Formatter

*/ public class LOG { diff --git a/framework/src/org/apache/cordova/NativeToJsMessageQueue.java b/framework/src/org/apache/cordova/NativeToJsMessageQueue.java index 6e6f2a73..60a1acb4 100755 --- a/framework/src/org/apache/cordova/NativeToJsMessageQueue.java +++ b/framework/src/org/apache/cordova/NativeToJsMessageQueue.java @@ -124,12 +124,10 @@ public class NativeToJsMessageQueue { } /** - * Combines and returns queued messages combined into a single string. - * * Combines as many messages as possible, without exceeding * COMBINED_RESPONSE_CUTOFF in case of multiple response messages. * - * Returns null if the queue is empty. + * @return a string of queued messages combined or null if the queue is empty. */ public String popAndEncode(boolean fromOnlineEvent) { synchronized (this) { diff --git a/framework/src/org/apache/cordova/PermissionHelper.java b/framework/src/org/apache/cordova/PermissionHelper.java index b2e4023c..bac8b8fe 100644 --- a/framework/src/org/apache/cordova/PermissionHelper.java +++ b/framework/src/org/apache/cordova/PermissionHelper.java @@ -66,7 +66,6 @@ public class PermissionHelper { * * @param plugin The plugin the permission is being checked against * @param permission The permission to be checked - * * @return True if the permission has already been granted and false otherwise */ public static boolean hasPermission(CordovaPlugin plugin, String permission) { diff --git a/framework/src/org/apache/cordova/PluginEntry.java b/framework/src/org/apache/cordova/PluginEntry.java index 389cc249..1b519959 100755 --- a/framework/src/org/apache/cordova/PluginEntry.java +++ b/framework/src/org/apache/cordova/PluginEntry.java @@ -48,36 +48,36 @@ public final class PluginEntry { /** * Constructs with a CordovaPlugin already instantiated. * - * @param service The name of the service - * @param pluginClass The plugin class name + * @param service The name of the service + * @param plugin The plugin class name */ public PluginEntry(String service, CordovaPlugin plugin) { this(service, plugin.getClass().getName(), true, plugin); } /** - * @param service The name of the service - * @param plugin The CordovaPlugin already instantiated - * @param onload Create plugin object when HTML page is loaded + * @param service The name of the service + * @param plugin The CordovaPlugin already instantiated + * @param onload Create plugin object when HTML page is loaded */ public PluginEntry(String service, CordovaPlugin plugin, boolean onload) { this(service, plugin.getClass().getName(), onload, plugin); } /** - * @param service The name of the service - * @param pluginClass The plugin class name - * @param onload Create plugin object when HTML page is loaded + * @param service The name of the service + * @param pluginClass The plugin class name + * @param onload Create plugin object when HTML page is loaded */ public PluginEntry(String service, String pluginClass, boolean onload) { this(service, pluginClass, onload, null); } /** - * @param service The name of the service - * @param pluginClass The plugin class name - * @param onload Create plugin object when HTML page is loaded - * @param plugin The CordovaPlugin already instantiated + * @param service The name of the service + * @param pluginClass The plugin class name + * @param onload Create plugin object when HTML page is loaded + * @param plugin The CordovaPlugin already instantiated */ private PluginEntry(String service, String pluginClass, boolean onload, CordovaPlugin plugin) { this.service = service; diff --git a/framework/src/org/apache/cordova/PluginManager.java b/framework/src/org/apache/cordova/PluginManager.java index 255eacd0..24560c2f 100755 --- a/framework/src/org/apache/cordova/PluginManager.java +++ b/framework/src/org/apache/cordova/PluginManager.java @@ -38,8 +38,8 @@ import android.webkit.WebView; /** * PluginManager is exposed to JavaScript in the Cordova WebView. * - * Calling native plugin code can be done by calling PluginManager.exec(...) - * from JavaScript. + *

Calling native plugin code can be done by calling PluginManager.exec(...) + * from JavaScript.

*/ public class PluginManager { private static String TAG = "PluginManager"; @@ -87,7 +87,7 @@ public class PluginManager { } /** - * Init when loading a new HTML page into webview. + * Init when loading a new HTML page into WebView. */ public void init() { LOG.d(TAG, "init()"); @@ -121,9 +121,9 @@ public class PluginManager { * Receives a request for execution and fulfills it by finding the appropriate * Java class and calling it's execute method. * - * PluginManager.exec can be used either synchronously or async. In either case, a JSON encoded + *

PluginManager.exec can be used either synchronously or async. In either case, a JSON encoded * string is returned that will indicate if any errors have occurred when trying to find - * or execute the class denoted by the clazz argument. + * or execute the class denoted by the clazz argument.

* * @param service String containing the service to run * @param action String containing the action that the class is supposed to perform. This is @@ -252,9 +252,7 @@ public class PluginManager { * @param handler The HttpAuthHandler used to set the WebView's response * @param host The host requiring authentication * @param realm The realm for which authentication is required - * - * @return Returns True if there is a plugin which will resolve this auth challenge, otherwise False - * + * @return True if there is a plugin which will resolve this auth challenge, otherwise False */ public boolean onReceivedHttpAuthRequest(CordovaWebView view, ICordovaHttpAuthHandler handler, String host, String realm) { synchronized (this.pluginMap) { @@ -273,9 +271,7 @@ public class PluginManager { * * @param view The WebView that is initiating the callback * @param request The client certificate request - * - * @return Returns True if plugin will resolve this auth challenge, otherwise False - * + * @return True if plugin will resolve this auth challenge, otherwise False */ public boolean onReceivedClientCertRequest(CordovaWebView view, ICordovaClientCertRequest request) { synchronized (this.pluginMap) { @@ -375,12 +371,14 @@ public class PluginManager { } /** - * @todo should we move this somewhere public and accessible by all plugins? - * For now, it is placed where it is used and kept private so we can decide later and move without causing a breaking change. - * An ideal location might be in the "ConfigXmlParser" at the time it generates the "launchUrl". + * TODO: should we move this somewhere public and accessible by all plugins? * - * @todo should we be restrictive on the "file://" return? e.g. "file:///android_asset/www/" - * Would be considered as a breaking change if we apply a more granular check. + *

For now, it is placed where it is used and kept private so we can decide later and move without causing a breaking change. + * An ideal location might be in the "ConfigXmlParser" at the time it generates the "launchUrl".

+ * + * TODO: should we be restrictive on the "file://" return? e.g. "file:///android_asset/www/" + * + *

Would be considered as a breaking change if we apply a more granular check.

*/ private String getLaunchUrlPrefix() { if (!app.getPreferences().getBoolean("AndroidInsecureFileModeEnabled", false)) { @@ -393,14 +391,14 @@ public class PluginManager { } /** - * Called when the webview is going to request an external resource. + * Called when the WebView is going to request an external resource. * - * This delegates to the installed plugins, and returns true/false for the + *

This delegates to the installed plugins, and returns true/false for the * first plugin to provide a non-null result. If no plugins respond, then - * the default policy is applied. + * the default policy is applied.

* * @param url The URL that is being requested. - * @return Returns true to allow the resource to load, + * @return true to allow the resource to load, * false to block the resource. */ public boolean shouldAllowRequest(String url) { @@ -425,7 +423,7 @@ public class PluginManager { return true; } if (url.startsWith("file://")) { - //This directory on WebKit/Blink based webviews contains SQLite databases! + //This directory on WebKit/Blink based WebViews contains SQLite databases! //DON'T CHANGE THIS UNLESS YOU KNOW WHAT YOU'RE DOING! return !url.contains("/app_webview/"); } @@ -433,14 +431,14 @@ public class PluginManager { } /** - * Called when the webview is going to change the URL of the loaded content. + * Called when the WebView is going to change the URL of the loaded content. * - * This delegates to the installed plugins, and returns true/false for the + *

This delegates to the installed plugins, and returns true/false for the * first plugin to provide a non-null result. If no plugins respond, then - * the default policy is applied. + * the default policy is applied.

* * @param url The URL that is being requested. - * @return Returns true to allow the navigation, + * @return true to allow the navigation, * false to block the navigation. */ public boolean shouldAllowNavigation(String url) { @@ -462,7 +460,7 @@ public class PluginManager { /** - * Called when the webview is requesting the exec() bridge be enabled. + * Called when the WebView is requesting the exec() bridge be enabled. */ public boolean shouldAllowBridgeAccess(String url) { synchronized (this.entryMap) { @@ -482,15 +480,15 @@ public class PluginManager { } /** - * Called when the webview is going not going to navigate, but may launch + * Called when the WebView is going not going to navigate, but may launch * an Intent for an URL. * - * This delegates to the installed plugins, and returns true/false for the + *

This delegates to the installed plugins, and returns true/false for the * first plugin to provide a non-null result. If no plugins respond, then - * the default policy is applied. + * the default policy is applied.

* * @param url The URL that is being requested. - * @return Returns true to allow the URL to launch an intent, + * @return true to allow the URL to launch an intent, * false to block the intent. */ public Boolean shouldOpenExternalUrl(String url) { @@ -511,7 +509,7 @@ public class PluginManager { } /** - * Called when the URL of the webview changes. + * Called when the URL of the WebView changes. * * @param url The URL that is being changed to. * @return Return false to allow the URL to load, return true to prevent the URL from loading. @@ -623,9 +621,9 @@ public class PluginManager { /** * Called when the WebView's render process has exited. * - * See https://developer.android.com/reference/android/webkit/WebViewClient#onRenderProcessGone(android.webkit.WebView,%20android.webkit.RenderProcessGoneDetail) + *

See WebViewClient#onRenderProcessGone

* - * @return true if the host application handled the situation that process has exited, + * @return true if the host application handled the situation that process has exited, * otherwise, application will crash if render process crashed, or be killed * if render process was killed by the system. */ diff --git a/framework/src/org/apache/cordova/PluginResult.java b/framework/src/org/apache/cordova/PluginResult.java index 5db60b3b..a9696fb4 100644 --- a/framework/src/org/apache/cordova/PluginResult.java +++ b/framework/src/org/apache/cordova/PluginResult.java @@ -118,8 +118,7 @@ public class PluginResult { } /** - * If messageType == MESSAGE_TYPE_STRING, then returns the message string. - * Otherwise, returns null. + * @return message string when messageType is MESSAGE_TYPE_STRING otherwise null. */ public String getStrMessage() { return strMessage; diff --git a/framework/src/org/apache/cordova/SplashScreenPlugin.java b/framework/src/org/apache/cordova/SplashScreenPlugin.java index 425b13f9..8f02d521 100644 --- a/framework/src/org/apache/cordova/SplashScreenPlugin.java +++ b/framework/src/org/apache/cordova/SplashScreenPlugin.java @@ -45,25 +45,25 @@ public class SplashScreenPlugin extends CordovaPlugin { // Config preference values /** - * @param boolean autoHide to auto splash screen (default=true) + * Boolean flag to auto hide splash screen (default=true) */ private boolean autoHide; /** - * @param int delayTime in milliseconds (default=-1) + * Integer value of how long to delay in milliseconds (default=-1) */ private int delayTime; /** - * @param int fade to fade out splash screen (default=true) + * Boolean flag if to fade to fade out splash screen (default=true) */ private boolean isFadeEnabled; /** - * @param int fadeDuration fade out duration in milliseconds (default=500) + * Integer value of the fade duration in milliseconds (default=500) */ private int fadeDuration; // Internal variables /** - * @param boolean keepOnScreen flag to determine if the splash screen remains visible. + * Boolean flag to determine if the splash screen remains visible. */ private boolean keepOnScreen = true; diff --git a/framework/src/org/apache/cordova/engine/SystemWebChromeClient.java b/framework/src/org/apache/cordova/engine/SystemWebChromeClient.java index 8a48e351..6ed2bdaa 100755 --- a/framework/src/org/apache/cordova/engine/SystemWebChromeClient.java +++ b/framework/src/org/apache/cordova/engine/SystemWebChromeClient.java @@ -119,8 +119,8 @@ public class SystemWebChromeClient extends WebChromeClient { * If the client returns true, WebView will assume that the client will * handle the prompt dialog and call the appropriate JsPromptResult method. * - * Since we are hacking prompts for our own purposes, we should not be using them for - * this purpose, perhaps we should hack console.log to do this instead! + *

Since we are hacking prompts for our own purposes, we should not be using them for + * this purpose, perhaps we should hack console.log to do this instead!

*/ @Override public boolean onJsPrompt(WebView view, String origin, String message, String defaultValue, final JsPromptResult result) { @@ -155,15 +155,15 @@ public class SystemWebChromeClient extends WebChromeClient { quotaUpdater.updateQuota(MAX_QUOTA); } - @Override /** * Instructs the client to show a prompt to ask the user to set the Geolocation permission state for the specified origin. * - * This also checks for the Geolocation Plugin and requests permission from the application to use Geolocation. + *

This also checks for the Geolocation Plugin and requests permission from the application to use Geolocation.

* * @param origin * @param callback */ + @Override public void onGeolocationPermissionsShowPrompt(String origin, Callback callback) { super.onGeolocationPermissionsShowPrompt(origin, callback); callback.invoke(origin, true, false); @@ -188,12 +188,13 @@ public class SystemWebChromeClient extends WebChromeClient { parentEngine.getCordovaWebView().hideCustomView(); } - @Override /** * Ask the host application for a custom progress view to show while * a