github/cordova-android
github/cordova-android
3
0
Fork 1
mirror of https://github.com/apache/cordova-android.git synced 2025-02-22 00:32:55 +08:00
Code Issues Packages Projects Releases Wiki Activity

style: update & resolve doc block warnings (#1774)

Browse Source 
* style: resolve throw symbols (except InvalidArgumentException)
* style: resolve unknown symbol & reduce indention for PluginEntry
* fix: define IllegalArgumentException not InvalidArgumentException
This commit is contained in:
エリス 2025-01-30 18:17:22 +09:00 committed by GitHub
parent e012478537
commit eb0f002112
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
30 changed files with 252 additions and 222 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
cordova-js-src/plugin/android/app.js vendored
View File

@ -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:

2
framework/cordova.gradle
View File

@ -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)
}

2
framework/src/org/apache/cordova/AllowListPlugin.java
View File

@ -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);

6
framework/src/org/apache/cordova/AuthenticationToken.java
View File

@ -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;

2
framework/src/org/apache/cordova/CallbackMap.java
View File

@ -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<CordovaPlugin, Integer> getAndRemoveCallback(int mappedId) {

2
framework/src/org/apache/cordova/Config.java
View File

@ -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";

19
framework/src/org/apache/cordova/CordovaActivity.java
View File

@ -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:
* <p>As an example:</p>
*
* <pre>
* package org.apache.cordova.examples;
@ -68,17 +68,16 @@ import androidx.core.splashscreen.SplashScreen;
* }
* </pre>
*
* 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.
* <p>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 <a href="https://cordova.apache.org/docs">Apache Cordova Docs</a>.</p>
*
* <p>The use of the set*Property() methods is deprecated in favor of the config.xml file.</p>
*/
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.
* <p/>
* 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);
}

20
framework/src/org/apache/cordova/CordovaClientCertRequest.java
View File

@ -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

4
framework/src/org/apache/cordova/CordovaDialogsHelper.java
View File

@ -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!
* <p>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!</p>
*/
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).

9
framework/src/org/apache/cordova/CordovaInterface.java
View File

@ -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.
* <p>If a custom engine lives outside of the Activity's lifecycle the return value
* may be null.</p>
*
* @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);

4
framework/src/org/apache/cordova/CordovaInterfaceImpl.java
View File

@ -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;

89
framework/src/org/apache/cordova/CordovaPlugin.java
View File

@ -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);
* <p>This method is called from the WebView thread. To do a non-trivial
* amount of work, use:</p>
*
* To run on the UI thread, use:
* cordova.getActivity().runOnUiThread(runnable);
* <pre>cordova.getThreadPool().execute(runnable);</pre>
*
* <p>To run on the UI thread, use:</p>
*
* <pre>cordova.getActivity().runOnUiThread(runnable);</pre>
*
* @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);
* <p>This method is called from the WebView thread. To do a non-trivial amount of work, use:</p>
*
* To run on the UI thread, use:
* cordova.getActivity().runOnUiThread(runnable);
* <pre>cordova.getThreadPool().execute(runnable);</pre>
*
* <p>To run on the UI thread, use:</p>
*
* <pre>cordova.getActivity().runOnUiThread(runnable);</pre>
*
* @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:
* <p>This method is called from the WebView thread. To do a non-trivial amount of work, use:</p>
* cordova.getThreadPool().execute(runnable);
*
* To run on the UI thread, use:
* <p>To run on the UI thread, use:</p>
* 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
* <p>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.</p>
*
* Note that this only affects resource requests which are routed through
* <p>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 <video> and <audio>
* tags) are not affected by this method. Use CSP headers to control access
* to such resources.
* to such resources.</p>
*/
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
* <p>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.</p>
*/
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
* <p>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.</p>
*/
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/...
* <pre>cdvplugin://pluginId/...</pre>
*
* And implement handleOpenForRead().
* To make this easier, use the toPluginUri() and fromPluginUri() helpers:
* <p>And implement handleOpenForRead().</p>
*
* <p>To make this easier, use the toPluginUri() and fromPluginUri() helpers:</p>
*
* <pre>
* public Uri remapUri(Uri uri) { return toPluginUri(uri); }
*
* public CordovaResourceApi.OpenForReadResult handleOpenForRead(Uri uri) throws IOException {
* Uri origUri = fromPluginUri(uri);
* ...
* }
* </pre>
*/
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.
* <p>Plugins should stop any long-running processes and clean up internal state.</p>
*
* Does nothing by default.
* <p>Does nothing by default.</p>
*/
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 <a href="https://developer.android.com/reference/android/webkit/WebViewClient#onRenderProcessGone(android.webkit.WebView,%20android.webkit.RenderProcessGoneDetail)">WebViewClient#onRenderProcessGone</a>
* <p>See <a href="https://developer.android.com/reference/android/webkit/WebViewClient#onRenderProcessGone(android.webkit.WebView,%20android.webkit.RenderProcessGoneDetail)">WebViewClient#onRenderProcessGone</a></p>
*
* Note: A plugin must not attempt to recover a webview that it does not own/manage.
* <p>Note: A plugin must not attempt to recover a WebView that it does not own/manage.</p>
*
* @return true if the host application handled the situation that process has exited,
* otherwise, application will crash if render process crashed, or be killed

69
framework/src/org/apache/cordova/CordovaResourceApi.java
View File

@ -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.
* <ol>
* <li>
* Helpers for reading & writing to URLs.
* <ul>
* <li>E.g. handles assets, resources, content providers, files, data URIs, http[s]</li>
* <li>E.g. Can be used to query for mime-type & content length.</p></li>
* </ul>
* </li>
* <li>
* To allow plugins to redirect URLs (via remapUrl).
* <ul>
* <li>
* All plugins should call remapUrl() on URLs they receive from JS *before* passing the URL onto other utility functions in this class.
* </li>
* <li>For an example usage of this, refer to the org.apache.cordova.file plugin.</li>
* </ul>
* </li>
* </ol>
*
* 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.
* <p>Future Work:</p>
* <ul>
* <li>Consider using a Cursor to query content URLs for their size (like the file plugin does).</li>
* <li>
* Allow plugins to remapUri to "cdv-plugin://plugin-name/foo", which CordovaResourceApi would then delegate to pluginManager.getPlugin(plugin-name).openForRead(url)
* <ul>
* <li>Currently, plugins *can* do this by remapping to a data: URL, but it's inefficient for large payloads.</li>
* </ul>
* </li>
* </ul>
*/
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();

37
framework/src/org/apache/cordova/CordovaWebView.java
View File

@ -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)
* <p>Deprecated (<a href="https://issues.apache.org/jira/browse/CB-6851">CB-6851</a>)
* 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):
* <js-module><runs/></js-module>
* 2. Within your .js (call exec on start-up):
* to create a Java->JS communication channel.</p>
*
* <p>To do this:</p>
*
* <p>1. Within plugin.xml (to have your JS run before deviceready):</p>
*
* <pre>
* <js-module><runs/></js-module>
* </pre>
*
* <p>2. Within your .js (call exec on start-up):</p>
*
* <pre>
* 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:
* </pre>
*
* <p>3. Within your .java:</p>
*
* <pre>
* PluginResult dataResult = new PluginResult(PluginResult.Status.OK, CODE);
* dataResult.setKeepCallback(true);
* savedCallbackContext.sendPluginResult(dataResult);
* </pre>
*/
@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.
* <p>NOTE: If openExternal is false, only allow listed URLs can be loaded.</p>
*
* @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
*/

2
framework/src/org/apache/cordova/CordovaWebViewEngine.java
View File

@ -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<String> callback);
/**

12
framework/src/org/apache/cordova/CordovaWebViewImpl.java
View File

@ -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();
}

12
framework/src/org/apache/cordova/CoreAndroid.java
View File

@ -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()

20
framework/src/org/apache/cordova/ICordovaClientCertRequest.java
View File

@ -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

4
framework/src/org/apache/cordova/LOG.java
View File

@ -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
* <p>Log message can be a string or a printf formatted string with arguments.
* See <a href="http://developer.android.com/reference/java/util/Formatter.html">Formatter</a></p>
*/
public class LOG {

4
framework/src/org/apache/cordova/NativeToJsMessageQueue.java
View File

@ -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) {

1
framework/src/org/apache/cordova/PermissionHelper.java
View File

@ -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) {

24
framework/src/org/apache/cordova/PluginEntry.java
View File

@ -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;

64
framework/src/org/apache/cordova/PluginManager.java
View File

@ -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.
* <p>Calling native plugin code can be done by calling PluginManager.exec(...)
* from JavaScript.</p>
*/
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
* <p>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.</p>
*
* @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.
* <p>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".</p>
*
* TODO: should we be restrictive on the "file://" return? e.g. "file:///android_asset/www/"
*
* <p>Would be considered as a breaking change if we apply a more granular check.</p>
*/
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
* <p>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.</p>
*
* @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
* <p>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.</p>
*
* @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
* <p>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.</p>
*
* @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)
* <p>See <a href="https://developer.android.com/reference/android/webkit/WebViewClient#onRenderProcessGone(android.webkit.WebView,%20android.webkit.RenderProcessGoneDetail)">WebViewClient#onRenderProcessGone</a></p>
*
* @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.
*/

3
framework/src/org/apache/cordova/PluginResult.java
View File

@ -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;

10
framework/src/org/apache/cordova/SplashScreenPlugin.java
View File

@ -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;

13
framework/src/org/apache/cordova/engine/SystemWebChromeClient.java
View File

@ -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!
* <p>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!</p>
*/
@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.
* <p>This also checks for the Geolocation Plugin and requests permission from the application to use Geolocation.</p>
*
* @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 <video> is loading.
*
* @return View The progress view.
*/
@Override
public View getVideoLoadingProgressView() {
if (mVideoProgressView == null) {
// Create a new Loading view programmatically.
@ -204,7 +205,7 @@ public class SystemWebChromeClient extends WebChromeClient {
RelativeLayout.LayoutParams layoutParams = new RelativeLayout.LayoutParams(LayoutParams.WRAP_CONTENT, LayoutParams.WRAP_CONTENT);
layoutParams.addRule(RelativeLayout.CENTER_IN_PARENT);
layout.setLayoutParams(layoutParams);
// the proress bar
// the progress bar
ProgressBar bar = new ProgressBar(parentEngine.getView().getContext());
LinearLayout.LayoutParams barLayoutParams = new LinearLayout.LayoutParams(LayoutParams.WRAP_CONTENT, LayoutParams.WRAP_CONTENT);
barLayoutParams.gravity = Gravity.CENTER;

20
framework/src/org/apache/cordova/engine/SystemWebViewClient.java
View File

@ -199,7 +199,7 @@ public class SystemWebViewClient extends WebViewClient {
* one time for the main frame. This also means that onPageStarted will not be called when the contents of an
* embedded frame changes, i.e. clicking a link whose target is an iframe.
*
* @param view The webview initiating the callback.
* @param view The WebView initiating the callback.
* @param url The url of the page.
*/
@Override
@ -216,7 +216,7 @@ public class SystemWebViewClient extends WebViewClient {
* This method is called only for main frame. When onPageFinished() is called, the rendering picture may not be updated yet.
*
*
* @param view The webview initiating the callback.
* @param view The WebView initiating the callback.
* @param url The url of the page.
*/
@Override
@ -228,7 +228,7 @@ public class SystemWebViewClient extends WebViewClient {
}
isCurrentlyLoading = false;
/**
/*
* Because of a timing issue we need to clear this history in onPageFinished as well as
* onPageStarted. However we only want to do this if the doClearHistory boolean is set to
* true. You see when you load a url with a # in it which is common in jQuery applications
@ -332,7 +332,6 @@ public class SystemWebViewClient extends WebViewClient {
*
* @param host
* @param realm
*
* @return the authentication token or null if did not exist
*/
public AuthenticationToken removeAuthenticationToken(String host, String realm) {
@ -342,15 +341,16 @@ public class SystemWebViewClient extends WebViewClient {
/**
* Gets the authentication token.
*
* In order it tries:
* 1- host + realm
* 2- host
* 3- realm
* 4- no host, no realm
* <p>In order it tries:</p>
* <ol>
* <li>host + realm</li>
* <li>host</li>
* <li>realm</li>
* <li>no host, no realm</li>
* </ol>
*
* @param host
* @param realm
*
* @return the authentication token
*/
public AuthenticationToken getAuthenticationToken(String host, String realm) {

12
framework/src/org/apache/cordova/engine/SystemWebViewEngine.java
View File

@ -110,7 +110,7 @@ public class SystemWebViewEngine implements CordovaWebViewEngine {
nativeToJsMessageQueue.addBridgeMode(new NativeToJsMessageQueue.OnlineEventsBridgeMode(new NativeToJsMessageQueue.OnlineEventsBridgeMode.OnlineEventsBridgeModeDelegate() {
@Override
public void setNetworkAvailable(boolean value) {
//sometimes this can be called after calling webview.destroy() on destroy()
//sometimes this can be called after calling webView.destroy() on destroy()
//thus resulting in a NullPointerException
if(webView!=null) {
webView.setNetworkAvailable(value);
@ -175,9 +175,9 @@ public class SystemWebViewEngine implements CordovaWebViewEngine {
String databasePath = webView.getContext().getApplicationContext().getDir("database", Context.MODE_PRIVATE).getPath();
settings.setDatabaseEnabled(true);
// The default is to use the module's debuggable state to decide if the webview inspecter
// should be enabled. However, users can configure InspectableWebview preference to forcefully enable
// or disable the webview inspecter.
// The default is to use the module's debuggable state to decide if the WebView inspector
// should be enabled. However, users can configure InspectableWebView preference to forcefully enable
// or disable the WebView inspector.
String inspectableWebview = preferences.getString("InspectableWebview", null);
boolean shouldEnableInspector = false;
if (inspectableWebview == null) {
@ -249,7 +249,7 @@ public class SystemWebViewEngine implements CordovaWebViewEngine {
/**
* Load the url into the webview.
* Load the url into the WebView.
*/
@Override
public void loadUrl(final String url, boolean clearNavigationStack) {
@ -288,7 +288,7 @@ public class SystemWebViewEngine implements CordovaWebViewEngine {
*/
@Override
public boolean goBack() {
// Check webview first to see if there is a history
// Check WebView first to see if there is a history
// This is needed to support curPage#diffLink, since they are added to parentEngine's history, but not our history url array (JQMobile behavior)
if (webView.canGoBack()) {
webView.goBack();

2
test/androidx/app/src/androidTest/java/org/apache/cordova/unittests/StandardActivityTest.java
View File

@ -66,7 +66,7 @@ public class StandardActivityTest {
@Test
public void webViewCheck() {
StandardActivity activity = (StandardActivity) mActivityRule.getActivity();
//Fish the webview out of the mostly locked down Activity using the Android SDK
// Fish the WebView out of the mostly locked down Activity using the Android SDK
View view = activity.getWindow().getCurrentFocus();
assertEquals(SystemWebView.class, view.getClass());
}

2
test/androidx/app/src/main/java/org/apache/cordova/unittests/EmbeddedWebViewActivity.java
View File

@ -44,7 +44,7 @@ public class EmbeddedWebViewActivity extends AppCompatActivity {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
//Set up the webview
// Set up the WebView
ConfigXmlParser parser = new ConfigXmlParser();
parser.parse(this);