Better Override APN javadoc.

Add explanation for the possible failure reasons of
addOverrideApn, updateOverrideApn and removeOverrideApn.

Bug: 73750993
Test: test not required

Change-Id: Ic3493043fe6e5fedea006118bfc8dab7219d03ab

1 files changed, 14 insertions, 0 deletions

diff --git a/core/java/android/app/admin/DevicePolicyManager.java b/core/java/android/app/admin/DevicePolicyManager.java
index 7b6a28810f3b..2c4bf8260fe6 100644
--- a/core/java/android/app/admin/DevicePolicyManager.java
+++ b/core/java/android/app/admin/DevicePolicyManager.java
@@ -9392,6 +9392,11 @@ public class DevicePolicyManager {
     /**
      * Called by device owner to add an override APN.
      *
+     * <p>This method may returns {@code -1} if {@code apnSetting} conflicts with an existing
+     * override APN. Update the existing conflicted APN with
+     * {@link #updateOverrideApn(ComponentName, int, ApnSetting)} instead of adding a new entry.
+     * <p>See {@link ApnSetting} for the definition of conflict.
+     *
      * @param admin which {@link DeviceAdminReceiver} this request is associated with
      * @param apnSetting the override APN to insert
      * @return The {@code id} of inserted override APN. Or {@code -1} when failed to insert into
@@ -9415,6 +9420,12 @@ public class DevicePolicyManager {
     /**
      * Called by device owner to update an override APN.
      *
+     * <p>This method may returns {@code false} if there is no override APN with the given
+     * {@code apnId}.
+     * <p>This method may also returns {@code false} if {@code apnSetting} conflicts with an
+     * existing override APN. Update the existing conflicted APN instead.
+     * <p>See {@link ApnSetting} for the definition of conflict.
+     *
      * @param admin which {@link DeviceAdminReceiver} this request is associated with
      * @param apnId the {@code id} of the override APN to update
      * @param apnSetting the override APN to update
@@ -9440,6 +9451,9 @@ public class DevicePolicyManager {
     /**
      * Called by device owner to remove an override APN.
      *
+     * <p>This method may returns {@code false} if there is no override APN with the given
+     * {@code apnId}.
+     *
      * @param admin which {@link DeviceAdminReceiver} this request is associated with
      * @param apnId the {@code id} of the override APN to remove
      * @return {@code true} if the required override APN is successfully removed, {@code false}