Mark older CapabilitiesCallback APIs as default

- Mark the existing RcsUceAdapter.CapabilitiesCallback APIs as
default. Otherwise, there is no way for apps to stop implementing
the existing APIs in favor of new APIs that include SipDetails.

- Not all apps actually require SipDetails, so we can keep the old
versions of the methods without deprecation

Bug: b/265170620
Test: atest CtsTelephonyTestCases:RcsUceAdapterTest
Change-Id: I8783f54f9e92d0484e6064f4cb16473a8edd41fe

2 files changed, 43 insertions, 22 deletions

diff --git a/core/api/system-current.txt b/core/api/system-current.txt
index dd962cd11660..1b4d14410bf0 100644
--- a/core/api/system-current.txt
+++ b/core/api/system-current.txt
@@ -15712,9 +15712,9 @@ package android.telephony.ims {
 
   public static interface RcsUceAdapter.CapabilitiesCallback {
     method public void onCapabilitiesReceived(@NonNull java.util.List<android.telephony.ims.RcsContactUceCapability>);
-    method @Deprecated public void onComplete();
+    method public default void onComplete();
     method public default void onComplete(@Nullable android.telephony.ims.SipDetails);
-    method @Deprecated public void onError(int, long);
+    method public default void onError(int, long);
     method public default void onError(int, long, @Nullable android.telephony.ims.SipDetails);
   }
 
diff --git a/telephony/java/android/telephony/ims/RcsUceAdapter.java b/telephony/java/android/telephony/ims/RcsUceAdapter.java
index b49181e7367b..3bb9be0252cd 100644
--- a/telephony/java/android/telephony/ims/RcsUceAdapter.java
+++ b/telephony/java/android/telephony/ims/RcsUceAdapter.java
@@ -447,12 +447,12 @@ public class RcsUceAdapter {
     /**
      * A callback for the response to a UCE request. The method
      * {@link CapabilitiesCallback#onCapabilitiesReceived} will be called zero or more times as the
-     * capabilities are received for each requested contact.
+     * capabilities are fetched from multiple sources, both cached on the device and on the network.
      * <p>
      * This request will take a varying amount of time depending on if the contacts requested are
      * cached or if it requires a network query. The timeout time of these requests can vary
      * depending on the network, however in poor cases it could take up to a minute for a request
-     * to timeout. In that time only a subset of capabilities may have been retrieved.
+     * to timeout. In that time, only a subset of capabilities may have been retrieved.
      * <p>
      * After {@link CapabilitiesCallback#onComplete} or {@link CapabilitiesCallback#onError} has
      * been called, the reference to this callback will be discarded on the service side.
@@ -463,22 +463,29 @@ public class RcsUceAdapter {
     public interface CapabilitiesCallback {
 
         /**
-         * Notify this application that the pending capability request has returned successfully
-         * for one or more of the requested contacts.
+         * The pending capability request has completed successfully for one or more of the
+         * requested contacts.
+         * This may be called one or more times before the request is fully completed, as
+         * capabilities may need to be fetched from multiple sources both on device and on the
+         * network. Once the capabilities of all the requested contacts have been received,
+         * {@link #onComplete()} will be called. If there was an error during the capability
+         * exchange process, {@link #onError(int, long)} will be called instead.
          * @param contactCapabilities List of capabilities associated with each contact requested.
          */
         void onCapabilitiesReceived(@NonNull List<RcsContactUceCapability> contactCapabilities);
 
         /**
-         * The pending request has completed successfully due to all requested contacts information
-         * being delivered. The callback {@link #onCapabilitiesReceived(List)}
-         * for each contacts is required to be called before {@link #onComplete} is called.
+         * Called when the pending request has completed successfully due to all requested contacts
+         * information being delivered. The callback {@link #onCapabilitiesReceived(List)} will be
+         * called one or more times and will contain the contacts in the request that the device has
+         * received capabilities for.
          *
-         * @deprecated Replaced by {@link #onComplete(SipDetails)}, deprecated for
-         * SIP information.
+         * @see #onComplete(SipDetails) onComplete(SipDetails) provides more information related to
+         * the underlying SIP transaction used to perform the capabilities exchange. Either this
+         * method or the alternate method should be implemented to determine when the request has
+         * completed successfully.
          */
-        @Deprecated
-        void onComplete();
+        default void onComplete() {}
 
         /**
          * The pending request has resulted in an error and may need to be retried, depending on the
@@ -487,18 +494,26 @@ public class RcsUceAdapter {
          * @param retryIntervalMillis The time in milliseconds the requesting application should
          * wait before retrying, if non-zero.
          *
-         * @deprecated Replaced by {@link #onError(int, long, SipDetails)}, deprecated for
-         * SIP information.
+         * @see #onError(int, long, SipDetails) onError(int, long, SipDetails) provides more
+         * information related to the underlying SIP transaction that resulted in an error. Either
+         * this method or the alternative method should be implemented to determine when the
+         * request has completed with an error.
          */
-        @Deprecated
-        void onError(@ErrorCode int errorCode, long retryIntervalMillis);
+        default void onError(@ErrorCode int errorCode, long retryIntervalMillis) {}
 
         /**
-         * The pending request has completed successfully due to all requested contacts information
-         * being delivered. The callback {@link #onCapabilitiesReceived(List)}
-         * for each contacts is required to be called before {@link #onComplete} is called.
+         * Called when the pending request has completed successfully due to all requested contacts
+         * information being delivered. The callback {@link #onCapabilitiesReceived(List)} will be
+         * called one or more times and will contain the contacts in the request that the device has
+         * received capabilities for.
          *
-         * @param details The SIP information related to this request.
+         * This method contains more information about the underlying SIP transaction if it exists.
+         * If this information is not needed, {@link #onComplete()} can be implemented
+         * instead.
+         *
+         * @param details The SIP information related to this request if the device supports
+         *                supplying this information. This parameter will be {@code null} if this
+         *                information is not available.
          */
         default void onComplete(@Nullable SipDetails details) {
             onComplete();
@@ -507,10 +522,16 @@ public class RcsUceAdapter {
         /**
          * The pending request has resulted in an error and may need to be retried, depending on the
          * error code.
+         *
+         * This method contains more information about the underlying SIP transaction if it exists.
+         * If this information is not needed, {@link #onError(int, long)} can be implemented
+         * instead.
          * @param errorCode The reason for the framework being unable to process the request.
          * @param retryIntervalMillis The time in milliseconds the requesting application should
          * wait before retrying, if non-zero.
-         * @param details The SIP information related to this request.
+         * @param details The SIP information related to this request if the device supports
+         *                supplying this information. This parameter will be {@code null} if this
+         *                information is not available.
          */
         default void onError(@ErrorCode int errorCode, long retryIntervalMillis,
                 @Nullable SipDetails details) {