Expose APIs to configure underlying network priority

This commit expose VcnUnderlyingNetworkTemplate classes
and methods to configure those objects in VcnGatewayConnectionConfig.

Those APIs allow callers to configure the underlying network priority
for VCN gateway when VCN is doing route selection. Callers can
construct VcnUnderlyingNeworkTemplate with network requirements and
then set VcnUnderlyingNeworkTemplate list from most preffered to least
preffered in VcnGatewayConnectionConfig.

Bug: 205343355
CTS-Coverage-Bug: 209498272
Test: atest FrameworksVcnTests, CtsVcnTestCases
Test: make update-api
Change-Id: Ib7d51cf1ce562a1acbcb767ec569d7e11c861a1d

7 files changed, 93 insertions, 47 deletions

diff --git a/core/api/current.txt b/core/api/current.txt
index 230689dda0c9..917d89cd8e7d 100644
--- a/core/api/current.txt
+++ b/core/api/current.txt
@@ -27276,6 +27276,23 @@ package android.net.sip {
 
 package android.net.vcn {
 
+  public final class VcnCellUnderlyingNetworkTemplate extends android.net.vcn.VcnUnderlyingNetworkTemplate {
+    method @NonNull public java.util.Set<java.lang.String> getOperatorPlmnIds();
+    method public int getOpportunistic();
+    method public int getRoaming();
+    method @NonNull public java.util.Set<java.lang.Integer> getSimSpecificCarrierIds();
+  }
+
+  public static final class VcnCellUnderlyingNetworkTemplate.Builder {
+    ctor public VcnCellUnderlyingNetworkTemplate.Builder();
+    method @NonNull public android.net.vcn.VcnCellUnderlyingNetworkTemplate build();
+    method @NonNull public android.net.vcn.VcnCellUnderlyingNetworkTemplate.Builder setMetered(int);
+    method @NonNull public android.net.vcn.VcnCellUnderlyingNetworkTemplate.Builder setOperatorPlmnIds(@NonNull java.util.Set<java.lang.String>);
+    method @NonNull public android.net.vcn.VcnCellUnderlyingNetworkTemplate.Builder setOpportunistic(int);
+    method @NonNull public android.net.vcn.VcnCellUnderlyingNetworkTemplate.Builder setRoaming(int);
+    method @NonNull public android.net.vcn.VcnCellUnderlyingNetworkTemplate.Builder setSimSpecificCarrierIds(@NonNull java.util.Set<java.lang.Integer>);
+  }
+
   public final class VcnConfig implements android.os.Parcelable {
     method public int describeContents();
     method @NonNull public java.util.Set<android.net.vcn.VcnGatewayConnectionConfig> getGatewayConnectionConfigs();
@@ -27294,6 +27311,7 @@ package android.net.vcn {
     method @NonNull public String getGatewayConnectionName();
     method @IntRange(from=0x500) public int getMaxMtu();
     method @NonNull public long[] getRetryIntervalsMillis();
+    method @NonNull public java.util.List<android.net.vcn.VcnUnderlyingNetworkTemplate> getVcnUnderlyingNetworkPriorities();
   }
 
   public static final class VcnGatewayConnectionConfig.Builder {
@@ -27303,6 +27321,7 @@ package android.net.vcn {
     method @NonNull public android.net.vcn.VcnGatewayConnectionConfig.Builder removeExposedCapability(int);
     method @NonNull public android.net.vcn.VcnGatewayConnectionConfig.Builder setMaxMtu(@IntRange(from=0x500) int);
     method @NonNull public android.net.vcn.VcnGatewayConnectionConfig.Builder setRetryIntervalsMillis(@NonNull long[]);
+    method @NonNull public android.net.vcn.VcnGatewayConnectionConfig.Builder setVcnUnderlyingNetworkPriorities(@NonNull java.util.List<android.net.vcn.VcnUnderlyingNetworkTemplate>);
   }
 
   public class VcnManager {
@@ -27326,6 +27345,24 @@ package android.net.vcn {
     method public abstract void onStatusChanged(int);
   }
 
+  public abstract class VcnUnderlyingNetworkTemplate {
+    method public int getMetered();
+    field public static final int MATCH_ANY = 0; // 0x0
+    field public static final int MATCH_FORBIDDEN = 2; // 0x2
+    field public static final int MATCH_REQUIRED = 1; // 0x1
+  }
+
+  public final class VcnWifiUnderlyingNetworkTemplate extends android.net.vcn.VcnUnderlyingNetworkTemplate {
+    method @NonNull public java.util.Set<java.lang.String> getSsids();
+  }
+
+  public static final class VcnWifiUnderlyingNetworkTemplate.Builder {
+    ctor public VcnWifiUnderlyingNetworkTemplate.Builder();
+    method @NonNull public android.net.vcn.VcnWifiUnderlyingNetworkTemplate build();
+    method @NonNull public android.net.vcn.VcnWifiUnderlyingNetworkTemplate.Builder setMetered(int);
+    method @NonNull public android.net.vcn.VcnWifiUnderlyingNetworkTemplate.Builder setSsids(@NonNull java.util.Set<java.lang.String>);
+  }
+
 }
 
 package android.nfc {
diff --git a/core/java/android/net/vcn/VcnCellUnderlyingNetworkTemplate.java b/core/java/android/net/vcn/VcnCellUnderlyingNetworkTemplate.java
index 2dcb6872d63b..125b5730b2ed 100644
--- a/core/java/android/net/vcn/VcnCellUnderlyingNetworkTemplate.java
+++ b/core/java/android/net/vcn/VcnCellUnderlyingNetworkTemplate.java
@@ -49,8 +49,6 @@ import java.util.Set;
  * networks.
  *
  * <p>See {@link VcnUnderlyingNetworkTemplate}
- *
- * @hide
  */
 public final class VcnCellUnderlyingNetworkTemplate extends VcnUnderlyingNetworkTemplate {
     private static final String ALLOWED_NETWORK_PLMN_IDS_KEY = "mAllowedNetworkPlmnIds";
@@ -279,8 +277,13 @@ public final class VcnCellUnderlyingNetworkTemplate extends VcnUnderlyingNetwork
         /**
          * Set the matching criteria for metered networks.
          *
+         * <p>A template where setMetered(MATCH_REQUIRED) will only match metered networks (one
+         * without NET_CAPABILITY_NOT_METERED). A template where setMetered(MATCH_FORBIDDEN) will
+         * only match a network that is not metered (one with NET_CAPABILITY_NOT_METERED).
+         *
          * @param matchCriteria the matching criteria for metered networks. Defaults to {@link
-         *     #MATCH_ANY}. See {@link NetworkCapabilities#NET_CAPABILITY_NOT_METERED}
+         *     #MATCH_ANY}.
+         * @see NetworkCapabilities#NET_CAPABILITY_NOT_METERED
          */
         // The matching getter is defined in the super class. Please see {@link
         // VcnUnderlyingNetworkTemplate#getMetered()}
@@ -300,10 +303,11 @@ public final class VcnCellUnderlyingNetworkTemplate extends VcnUnderlyingNetwork
          * priority from a partner's networks.
          *
          * @param operatorPlmnIds the matching operator PLMN IDs in String. Network with one of the
-         *     matching PLMN IDs can match this template. Defaults to an empty set, allowing ANY
-         *     PLMN ID. A valid PLMN is a concatenation of MNC and MCC, and thus consists of 5 or 6
-         *     decimal digits. See {@link SubscriptionInfo#getMccString()} and {@link
-         *     SubscriptionInfo#getMncString()}.
+         *     matching PLMN IDs can match this template. If the set is empty, any PLMN ID will
+         *     match. The default is an empty set. A valid PLMN is a concatenation of MNC and MCC,
+         *     and thus consists of 5 or 6 decimal digits.
+         * @see SubscriptionInfo#getMccString()
+         * @see SubscriptionInfo#getMncString()
          */
         @NonNull
         public Builder setOperatorPlmnIds(@NonNull Set<String> operatorPlmnIds) {
@@ -318,8 +322,9 @@ public final class VcnCellUnderlyingNetworkTemplate extends VcnUnderlyingNetwork
          * Set sim specific carrier IDs with which a network can match this template.
          *
          * @param simSpecificCarrierIds the matching sim specific carrier IDs. Network with one of
-         *     the sim specific carrier IDs can match this template. Defaults to an empty set,
-         *     allowing ANY carrier ID. See {@link TelephonyManager#getSimSpecificCarrierId()}.
+         *     the sim specific carrier IDs can match this template. If the set is empty, any
+         *     carrier ID will match. The default is an empty set.
+         * @see TelephonyManager#getSimSpecificCarrierId()
          */
         @NonNull
         public Builder setSimSpecificCarrierIds(@NonNull Set<Integer> simSpecificCarrierIds) {
@@ -333,8 +338,13 @@ public final class VcnCellUnderlyingNetworkTemplate extends VcnUnderlyingNetwork
         /**
          * Set the matching criteria for roaming networks.
          *
+         * <p>A template where setRoaming(MATCH_REQUIRED) will only match roaming networks (one
+         * without NET_CAPABILITY_NOT_ROAMING). A template where setRoaming(MATCH_FORBIDDEN) will
+         * only match a network that is not roaming (one with NET_CAPABILITY_NOT_ROAMING).
+         *
          * @param matchCriteria the matching criteria for roaming networks. Defaults to {@link
-         *     #MATCH_ANY}. See {@link NetworkCapabilities#NET_CAPABILITY_NOT_ROAMING}.
+         *     #MATCH_ANY}.
+         * @see NetworkCapabilities#NET_CAPABILITY_NOT_ROAMING
          */
         @NonNull
         public Builder setRoaming(@MatchCriteria int matchCriteria) {
@@ -348,8 +358,8 @@ public final class VcnCellUnderlyingNetworkTemplate extends VcnUnderlyingNetwork
          * Set the matching criteria for opportunistic cellular subscriptions.
          *
          * @param matchCriteria the matching criteria for opportunistic cellular subscriptions.
-         *     Defaults to {@link #MATCH_ANY}. See {@link
-         *     SubscriptionManager#setOpportunistic(boolean, int)}
+         *     Defaults to {@link #MATCH_ANY}.
+         * @see SubscriptionManager#setOpportunistic(boolean, int)
          */
         @NonNull
         public Builder setOpportunistic(@MatchCriteria int matchCriteria) {
diff --git a/core/java/android/net/vcn/VcnGatewayConnectionConfig.java b/core/java/android/net/vcn/VcnGatewayConnectionConfig.java
index f17f30a0d1d8..92956e859fc7 100644
--- a/core/java/android/net/vcn/VcnGatewayConnectionConfig.java
+++ b/core/java/android/net/vcn/VcnGatewayConnectionConfig.java
@@ -375,11 +375,10 @@ public final class VcnGatewayConnectionConfig {
     /**
      * Retrieve the VcnUnderlyingNetworkTemplate list, or a default list if it is not configured.
      *
-     * @see Builder#setVcnUnderlyingNetworkTemplates(List)
-     * @hide
+     * @see Builder#setVcnUnderlyingNetworkPriorities(List)
      */
     @NonNull
-    public List<VcnUnderlyingNetworkTemplate> getVcnUnderlyingNetworkTemplates() {
+    public List<VcnUnderlyingNetworkTemplate> getVcnUnderlyingNetworkPriorities() {
         return new ArrayList<>(mUnderlyingNetworkTemplates);
     }
 
@@ -543,29 +542,28 @@ public final class VcnGatewayConnectionConfig {
         }
 
         /**
-         * Set the list of templates to match underlying networks against, in priority order.
+         * Set the list of templates to match underlying networks against, in high-to-low priority
+         * order.
          *
-         * <p>To select the VCN underlying network, the VCN gateway will go through all the network
-         * candidates and return a network matching the highest priority rule.
+         * <p>To select the VCN underlying network, the VCN connection will go through all the
+         * network candidates and return a network matching the highest priority rule.
          *
          * <p>If multiple networks match the same rule, the VCN will prefer an already-selected
          * network as opposed to a new/unselected network. However, if both are new/unselected
          * networks, a network will be chosen arbitrarily amongst the networks matching the highest
          * priority rule.
          *
-         * <p>A rule that matches all carrier-owned networks is implicitly added at the end of the
-         * priority list, ensuring that if all networks fail to match the rules provided, an
-         * underlying network will still be selected (at random if necessary).
+         * <p>If all networks fail to match the rules provided, an underlying network will still be
+         * selected (at random if necessary).
          *
          * @param underlyingNetworkTemplates a list of unique VcnUnderlyingNetworkTemplates that are
          *     ordered from most to least preferred, or an empty list to use the default
          *     prioritization. The default network prioritization order is Opportunistic cellular,
          *     Carrier WiFi and then Macro cellular.
          * @return this {@link Builder} instance, for chaining
-         * @hide
          */
         @NonNull
-        public Builder setVcnUnderlyingNetworkTemplates(
+        public Builder setVcnUnderlyingNetworkPriorities(
                 @NonNull List<VcnUnderlyingNetworkTemplate> underlyingNetworkTemplates) {
             validateNetworkTemplateList(underlyingNetworkTemplates);
 
diff --git a/core/java/android/net/vcn/VcnUnderlyingNetworkTemplate.java b/core/java/android/net/vcn/VcnUnderlyingNetworkTemplate.java
index 33b02e8f10e6..60fc936072fb 100644
--- a/core/java/android/net/vcn/VcnUnderlyingNetworkTemplate.java
+++ b/core/java/android/net/vcn/VcnUnderlyingNetworkTemplate.java
@@ -22,7 +22,6 @@ import static com.android.internal.annotations.VisibleForTesting.Visibility;
 import android.annotation.IntDef;
 import android.annotation.NonNull;
 import android.annotation.Nullable;
-import android.net.NetworkCapabilities;
 import android.os.PersistableBundle;
 import android.util.SparseArray;
 
@@ -41,9 +40,7 @@ import java.util.Objects;
  * <p>Apps provisioning a VCN can configure the underlying network priority for each Gateway
  * Connection by setting a list (in priority order, most to least preferred) of the appropriate
  * subclasses in the VcnGatewayConnectionConfig. See {@link
- * VcnGatewayConnectionConfig.Builder#setVcnUnderlyingNetworkTemplates}
- *
- * @hide
+ * VcnGatewayConnectionConfig.Builder#setVcnUnderlyingNetworkPriorities}
  */
 public abstract class VcnUnderlyingNetworkTemplate {
     /** @hide */
@@ -69,22 +66,23 @@ public abstract class VcnUnderlyingNetworkTemplate {
     public @interface NetworkQuality {}
 
     /**
-     * Used to configure the matching criteria of a network capability (See {@link
-     * NetworkCapabilities}). Denotes that networks with or without the capability are both
-     * acceptable to match the template.
+     * Used to configure the matching criteria of a network characteristic. This may include network
+     * capabilities, or cellular subscription information. Denotes that networks with or without the
+     * characteristic are both acceptable to match this template.
      */
     public static final int MATCH_ANY = 0;
 
     /**
-     * Used to configure the matching criteria of a network capability (See {@link
-     * NetworkCapabilities}). Denotes that only network with the capability can match the template.
+     * Used to configure the matching criteria of a network characteristic. This may include network
+     * capabilities, or cellular subscription information. Denotes that a network MUST have the
+     * capability in order to match this template.
      */
     public static final int MATCH_REQUIRED = 1;
 
     /**
-     * Used to configure the matching criteria of a network capability (See {@link
-     * NetworkCapabilities}). Denotes that only network without the capability can match the
-     * template.
+     * Used to configure the matching criteria of a network characteristic. This may include network
+     * capabilities, or cellular subscription information. Denotes that a network MUST NOT have the
+     * capability in order to match this template.
      */
     public static final int MATCH_FORBIDDEN = 2;
 
diff --git a/core/java/android/net/vcn/VcnWifiUnderlyingNetworkTemplate.java b/core/java/android/net/vcn/VcnWifiUnderlyingNetworkTemplate.java
index fcf5b0943053..272ca9dd7583 100644
--- a/core/java/android/net/vcn/VcnWifiUnderlyingNetworkTemplate.java
+++ b/core/java/android/net/vcn/VcnWifiUnderlyingNetworkTemplate.java
@@ -40,8 +40,6 @@ import java.util.Set;
  * networks.
  *
  * <p>See {@link VcnUnderlyingNetworkTemplate}
- *
- * @hide
  */
 public final class VcnWifiUnderlyingNetworkTemplate extends VcnUnderlyingNetworkTemplate {
     private static final String SSIDS_KEY = "mSsids";
@@ -168,8 +166,13 @@ public final class VcnWifiUnderlyingNetworkTemplate extends VcnUnderlyingNetwork
         /**
          * Set the matching criteria for metered networks.
          *
+         * <p>A template where setMetered(MATCH_REQUIRED) will only match metered networks (one
+         * without NET_CAPABILITY_NOT_METERED). A template where setMetered(MATCH_FORBIDDEN) will
+         * only match a network that is not metered (one with NET_CAPABILITY_NOT_METERED).
+         *
          * @param matchCriteria the matching criteria for metered networks. Defaults to {@link
-         *     #MATCH_ANY}. See {@link NetworkCapabilities#NET_CAPABILITY_NOT_METERED}
+         *     #MATCH_ANY}.
+         * @see NetworkCapabilities#NET_CAPABILITY_NOT_METERED
          */
         // The matching getter is defined in the super class. Please see {@link
         // VcnUnderlyingNetworkTemplate#getMetered()}
@@ -186,7 +189,7 @@ public final class VcnWifiUnderlyingNetworkTemplate extends VcnUnderlyingNetwork
          * Set the SSIDs with which a network can match this priority rule.
          *
          * @param ssids the matching SSIDs. Network with one of the matching SSIDs can match this
-         *     priority rule. Defaults to an empty set, allowing ANY SSID.
+         *     priority rule. If the set is empty, any SSID will match. The default is an empty set.
          */
         @NonNull
         public Builder setSsids(@NonNull Set<String> ssids) {
diff --git a/services/core/java/com/android/server/vcn/routeselection/UnderlyingNetworkController.java b/services/core/java/com/android/server/vcn/routeselection/UnderlyingNetworkController.java
index 6933e6641d29..ca2e449ffc25 100644
--- a/services/core/java/com/android/server/vcn/routeselection/UnderlyingNetworkController.java
+++ b/services/core/java/com/android/server/vcn/routeselection/UnderlyingNetworkController.java
@@ -401,7 +401,7 @@ public class UnderlyingNetworkController {
                     new TreeSet<>(
                             UnderlyingNetworkRecord.getComparator(
                                     mVcnContext,
-                                    mConnectionConfig.getVcnUnderlyingNetworkTemplates(),
+                                    mConnectionConfig.getVcnUnderlyingNetworkPriorities(),
                                     mSubscriptionGroup,
                                     mLastSnapshot,
                                     mCurrentRecord,
@@ -502,7 +502,7 @@ public class UnderlyingNetworkController {
         pw.increaseIndent();
         int index = 0;
         for (VcnUnderlyingNetworkTemplate priority :
-                mConnectionConfig.getVcnUnderlyingNetworkTemplates()) {
+                mConnectionConfig.getVcnUnderlyingNetworkPriorities()) {
             pw.println("Priority index: " + index);
             priority.dump(pw);
             index++;
@@ -518,7 +518,7 @@ public class UnderlyingNetworkController {
                 record.dump(
                         mVcnContext,
                         pw,
-                        mConnectionConfig.getVcnUnderlyingNetworkTemplates(),
+                        mConnectionConfig.getVcnUnderlyingNetworkPriorities(),
                         mSubscriptionGroup,
                         mLastSnapshot,
                         mCurrentRecord,
diff --git a/tests/vcn/java/android/net/vcn/VcnGatewayConnectionConfigTest.java b/tests/vcn/java/android/net/vcn/VcnGatewayConnectionConfigTest.java
index d7884e40b429..2aef9ae7ca32 100644
--- a/tests/vcn/java/android/net/vcn/VcnGatewayConnectionConfigTest.java
+++ b/tests/vcn/java/android/net/vcn/VcnGatewayConnectionConfigTest.java
@@ -96,7 +96,7 @@ public class VcnGatewayConnectionConfigTest {
     // Public for use in VcnGatewayConnectionTest
     public static VcnGatewayConnectionConfig buildTestConfig() {
         final VcnGatewayConnectionConfig.Builder builder =
-                newBuilder().setVcnUnderlyingNetworkTemplates(UNDERLYING_NETWORK_TEMPLATES);
+                newBuilder().setVcnUnderlyingNetworkPriorities(UNDERLYING_NETWORK_TEMPLATES);
 
         return buildTestConfigWithExposedCaps(builder, EXPOSED_CAPS);
     }
@@ -177,7 +177,7 @@ public class VcnGatewayConnectionConfigTest {
     @Test
     public void testBuilderRequiresNonNullNetworkTemplates() {
         try {
-            newBuilder().setVcnUnderlyingNetworkTemplates(null);
+            newBuilder().setVcnUnderlyingNetworkPriorities(null);
             fail("Expected exception due to invalid underlyingNetworkTemplates");
         } catch (NullPointerException e) {
         }
@@ -220,7 +220,7 @@ public class VcnGatewayConnectionConfigTest {
         Arrays.sort(exposedCaps);
         assertArrayEquals(EXPOSED_CAPS, exposedCaps);
 
-        assertEquals(UNDERLYING_NETWORK_TEMPLATES, config.getVcnUnderlyingNetworkTemplates());
+        assertEquals(UNDERLYING_NETWORK_TEMPLATES, config.getVcnUnderlyingNetworkPriorities());
         assertEquals(TUNNEL_CONNECTION_PARAMS, config.getTunnelConnectionParams());
 
         assertArrayEquals(RETRY_INTERVALS_MS, config.getRetryIntervalsMillis());
@@ -241,7 +241,7 @@ public class VcnGatewayConnectionConfigTest {
 
         final VcnGatewayConnectionConfig config = new VcnGatewayConnectionConfig(configBundle);
         assertEquals(
-                DEFAULT_UNDERLYING_NETWORK_TEMPLATES, config.getVcnUnderlyingNetworkTemplates());
+                DEFAULT_UNDERLYING_NETWORK_TEMPLATES, config.getVcnUnderlyingNetworkPriorities());
     }
 
     private static IkeTunnelConnectionParams buildTunnelConnectionParams(String ikePsk) {
@@ -292,7 +292,7 @@ public class VcnGatewayConnectionConfigTest {
                 new VcnGatewayConnectionConfig.Builder(
                                 "buildTestConfigWithVcnUnderlyingNetworkTemplates",
                                 TUNNEL_CONNECTION_PARAMS)
-                        .setVcnUnderlyingNetworkTemplates(networkTemplates),
+                        .setVcnUnderlyingNetworkPriorities(networkTemplates),
                 EXPOSED_CAPS);
     }