Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit aa68ab82 authored by Torne (Richard Coles)'s avatar Torne (Richard Coles)
Browse files

Clarify problems with Linkify.MAP_ADDRESSES. 

Update the documentation for WebView.findAddress, as well as the related
functionality in Linkify and TextView, to clarify why the method is
deprecated, why it should not be used, and that it can cause unexpected
exceptions to be thrown from several places on older OS versions.

Fixes: 24676033
Test: m offline-sdk-docs
Change-Id: I45d82b9a4c9cf62d9566898dd21cd2139ad98f37
parent d1ca4823

core/java/android/text/util/Linkify.java

+13 −4
Original line number Diff line number Diff line
@@ -67,6 +67,14 @@ import java.util.regex.Pattern; 
 *  create <code>http://example.com</code> when the clickable URL link is

 *  created.

 *

 *  <p class="note"><b>Note:</b> When using {@link #MAP_ADDRESSES} or {@link #ALL}

 *  to match street addresses on API level {@link android.os.Build.VERSION_CODES#O_MR1}

 *  and earlier, methods in this class may throw

 *  {@link android.util.AndroidRuntimeException} or other exceptions if the

 *  device's WebView implementation is currently being updated, because

 *  {@link android.webkit.WebView#findAddress} is required to match street

 *  addresses.

 *

 * @see MatchFilter

 * @see TransformFilter

 */
@@ -95,10 +103,11 @@ public class Linkify { 


    /**

     *  Bit field indicating that street addresses should be matched in methods that

     *  take an options mask. Note that this uses the

     *  {@link android.webkit.WebView#findAddress(String) findAddress()} method in

     *  {@link android.webkit.WebView} for finding addresses, which has various

     *  limitations and has been deprecated.

     *  take an options mask. Note that this should be avoided, as it uses the

     *  {@link android.webkit.WebView#findAddress(String)} method, which has various

     *  limitations and has been deprecated: see the documentation for

     *  {@link android.webkit.WebView#findAddress(String)} for more information.

     *

     *  @deprecated use {@link android.view.textclassifier.TextClassifier#generateLinks(

     *  TextLinks.Request)} instead and avoid it even when targeting API levels where no alternative

     *  is available.

core/java/android/webkit/WebView.java

+12 −4
Original line number Diff line number Diff line
@@ -1603,9 +1603,9 @@ public class WebView extends AbsoluteLayout 
    }



    /**

     * Gets the first substring consisting of the address of a physical

     * location. Currently, only addresses in the United States are detected,

     * and consist of:

     * Gets the first substring which appears to be the address of a physical

     * location. Only addresses in the United States can be detected, which

     * must consist of:

     * <ul>

     *   <li>a house number</li>

     *   <li>a street name</li>
@@ -1621,9 +1621,17 @@ public class WebView extends AbsoluteLayout 
     * or abbreviated using USPS standards. The house number may not exceed

     * five digits.

     *

     * <p class="note"><b>Note:</b> This function is deprecated and should be

     * avoided on all API levels, as it cannot detect addresses outside of the

     * United States and has a high rate of false positives. On API level

     * {@link android.os.Build.VERSION_CODES#O_MR1} and earlier, it also causes

     * the entire WebView implementation to be loaded and initialized, which

     * can throw {@link android.util.AndroidRuntimeException} or other exceptions

     * if the WebView implementation is currently being updated.

     *

     * @param addr the string to search for addresses

     * @return the address, or if no address is found, {@code null}

     * @deprecated this method is superseded by {@link TextClassifier#generateLinks(

     * @deprecated This method is superseded by {@link TextClassifier#generateLinks(

     * android.view.textclassifier.TextLinks.Request)}. Avoid using this method even when targeting

     * API levels where no alternative is available.

     */

core/java/android/widget/TextView.java

+4 −0
Original line number Diff line number Diff line
@@ -4960,6 +4960,10 @@ public class TextView extends View implements ViewTreeObserver.OnPreDrawListener 
     * android.text.util.Linkify#ALL Linkify.ALL} and peers for

     * possible values.

     *

     * <p class="note"><b>Note:</b>

     * {@link android.text.util.Linkify#MAP_ADDRESSES Linkify.MAP_ADDRESSES}

     * is deprecated and should be avoided; see its documentation.

     *

     * @attr ref android.R.styleable#TextView_autoLink

     */

    @android.view.RemotableViewMethod

core/res/res/values/attrs.xml

+2 −1
Original line number Diff line number Diff line
@@ -1560,7 +1560,8 @@ 
        <flag name="email" value="0x02" />

        <!-- Match phone numbers. -->

        <flag name="phone" value="0x04" />

        <!-- Match map addresses. -->

        <!-- Match map addresses.

             Deprecated: see {@link android.text.util.Linkify#MAP_ADDRESSES}. -->

        <flag name="map" value="0x08" />

        <!-- Match all patterns (equivalent to web|email|phone|map). -->

        <flag name="all" value="0x0f" />