From bb2557aa3a03cc09bcad68f96fb61763cec288f9 Mon Sep 17 00:00:00 2001 From: Chalard Jean Date: Mon, 9 Oct 2023 15:44:56 +0900 Subject: [PATCH] Prepare exposing LocalNetworkConfig and its satellites This doesn't actually expose the classes but prepares the files for everything the linter says about it and the API guidelines, as well as add documentation. Test: CSLocalAgentsTest Change-Id: I38c699d627eb91f19ab1628992ae0afde4673e89 --- .../src/android/net/LocalNetworkConfig.java | 18 ++-- .../android/net/MulticastRoutingConfig.java | 84 ++++++++++++------- 2 files changed, 66 insertions(+), 36 deletions(-) diff --git a/framework/src/android/net/LocalNetworkConfig.java b/framework/src/android/net/LocalNetworkConfig.java index e1b33e8989..17b1064f81 100644 --- a/framework/src/android/net/LocalNetworkConfig.java +++ b/framework/src/android/net/LocalNetworkConfig.java @@ -62,11 +62,19 @@ public final class LocalNetworkConfig implements Parcelable { return mUpstreamSelector; } - public @NonNull MulticastRoutingConfig getUpstreamMulticastRoutingConfig() { + /** + * Get the upstream multicast routing config + */ + @NonNull + public MulticastRoutingConfig getUpstreamMulticastRoutingConfig() { return mUpstreamMulticastRoutingConfig; } - public @NonNull MulticastRoutingConfig getDownstreamMulticastRoutingConfig() { + /** + * Get the downstream multicast routing config + */ + @NonNull + public MulticastRoutingConfig getDownstreamMulticastRoutingConfig() { return mDownstreamMulticastRoutingConfig; } @@ -109,13 +117,13 @@ public final class LocalNetworkConfig implements Parcelable { public static final class Builder { @Nullable - NetworkRequest mUpstreamSelector; + private NetworkRequest mUpstreamSelector; @Nullable - MulticastRoutingConfig mUpstreamMulticastRoutingConfig; + private MulticastRoutingConfig mUpstreamMulticastRoutingConfig; @Nullable - MulticastRoutingConfig mDownstreamMulticastRoutingConfig; + private MulticastRoutingConfig mDownstreamMulticastRoutingConfig; /** * Create a Builder diff --git a/framework/src/android/net/MulticastRoutingConfig.java b/framework/src/android/net/MulticastRoutingConfig.java index 6f4ab11dbb..1f4071cd6b 100644 --- a/framework/src/android/net/MulticastRoutingConfig.java +++ b/framework/src/android/net/MulticastRoutingConfig.java @@ -38,8 +38,8 @@ import java.util.Set; * Internal usage to Connectivity * @hide */ -// TODO : @SystemApi -public class MulticastRoutingConfig implements Parcelable { +// @SystemApi(client = MODULE_LIBRARIES) +public final class MulticastRoutingConfig implements Parcelable { private static final String TAG = MulticastRoutingConfig.class.getSimpleName(); /** Do not forward any multicast packets. */ @@ -55,6 +55,7 @@ public class MulticastRoutingConfig implements Parcelable { */ public static final int FORWARD_WITH_MIN_SCOPE = 2; + /** @hide */ @Retention(RetentionPolicy.SOURCE) @IntDef(prefix = { "FORWARD_" }, value = { FORWARD_NONE, @@ -68,6 +69,7 @@ public class MulticastRoutingConfig implements Parcelable { */ public static final int MULTICAST_SCOPE_NONE = -1; + /** @hide */ public static final MulticastRoutingConfig CONFIG_FORWARD_NONE = new MulticastRoutingConfig(FORWARD_NONE, MULTICAST_SCOPE_NONE, null); @@ -102,7 +104,7 @@ public class MulticastRoutingConfig implements Parcelable { * Returns the minimal group address scope that is allowed for forwarding. * If the forwarding mode is not FORWARD_WITH_MIN_SCOPE, will be MULTICAST_SCOPE_NONE. */ - public int getMinScope() { + public int getMinimumScope() { return mMinScope; } @@ -111,7 +113,7 @@ public class MulticastRoutingConfig implements Parcelable { * The list will be empty if the forwarding mode is not FORWARD_SELECTED. */ @NonNull - public Set getMulticastListeningAddresses() { + public Set getListeningAddresses() { return mListeningAddresses; } @@ -133,7 +135,7 @@ public class MulticastRoutingConfig implements Parcelable { } @Override - public void writeToParcel(Parcel dest, int flags) { + public void writeToParcel(@NonNull Parcel dest, int flags) { dest.writeInt(mForwardingMode); dest.writeInt(mMinScope); dest.writeInt(mListeningAddresses.size()); @@ -147,9 +149,10 @@ public class MulticastRoutingConfig implements Parcelable { return 0; } + @NonNull public static final Creator CREATOR = new Creator<>() { @Override - public MulticastRoutingConfig createFromParcel(Parcel in) { + public MulticastRoutingConfig createFromParcel(@NonNull Parcel in) { return new MulticastRoutingConfig(in); } @@ -177,43 +180,58 @@ public class MulticastRoutingConfig implements Parcelable { } } - public static class Builder { + public static final class Builder { @MulticastForwardingMode private final int mForwardingMode; private int mMinScope; private final ArraySet mListeningAddresses; - private Builder(@MulticastForwardingMode final int mode, int scope) { + // The two constructors with runtime checks for the mode and scope are arguably + // less convenient than three static factory methods, but API guidelines mandates + // that Builders are built with a constructor and not factory methods. + /** + * Create a new builder for forwarding mode FORWARD_NONE or FORWARD_SELECTED. + * + *

On a Builder for FORWARD_NONE, no properties can be set. + *

On a Builder for FORWARD_SELECTED, listening addresses can be added and removed + * but the minimum scope can't be set. + * + * @param mode {@link #FORWARD_NONE} or {@link #FORWARD_SELECTED}. Any other + * value will result in IllegalArgumentException. + * @see #Builder(int, int) + */ + public Builder(@MulticastForwardingMode final int mode) { + if (FORWARD_NONE != mode && FORWARD_SELECTED != mode) { + if (FORWARD_WITH_MIN_SCOPE == mode) { + throw new IllegalArgumentException("FORWARD_WITH_MIN_SCOPE requires " + + "passing the scope as a second argument"); + } else { + throw new IllegalArgumentException("Unknown forwarding mode : " + mode); + } + } mForwardingMode = mode; - mMinScope = scope; + mMinScope = MULTICAST_SCOPE_NONE; mListeningAddresses = new ArraySet<>(); } /** - * Create a builder that forwards nothing. - * No properties can be set on such a builder. - */ - public static Builder newBuilderForwardingNone() { - return new Builder(FORWARD_NONE, MULTICAST_SCOPE_NONE); - } - - /** - * Create a builder that forwards packets above a certain scope + * Create a new builder for forwarding mode FORWARD_WITH_MIN_SCOPE. * - * The scope can be changed on this builder, but not the listening addresses. - * @param scope the initial scope - */ - public static Builder newBuilderWithMinScope(final int scope) { - return new Builder(FORWARD_WITH_MIN_SCOPE, scope); - } - - /** - * Create a builder that forwards a specified list of listening addresses. + *

On this Builder the scope can be set with {@link #setMinimumScope}, but + * listening addresses can't be added or removed. * - * Addresses can be added and removed from this builder, but the scope can't be set. + * @param mode Must be {@link #FORWARD_WITH_MIN_SCOPE}. + * @param scope the minimum scope for this multicast routing config. + * @see Builder#Builder(int) */ - public static Builder newBuilderWithListeningAddresses() { - return new Builder(FORWARD_SELECTED, MULTICAST_SCOPE_NONE); + public Builder(@MulticastForwardingMode final int mode, int scope) { + if (FORWARD_WITH_MIN_SCOPE != mode) { + throw new IllegalArgumentException("Forwarding with a min scope must " + + "use forward mode FORWARD_WITH_MIN_SCOPE"); + } + mForwardingMode = mode; + mMinScope = scope; + mListeningAddresses = new ArraySet<>(); } /** @@ -221,6 +239,7 @@ public class MulticastRoutingConfig implements Parcelable { * This is only meaningful (indeed, allowed) for configs in FORWARD_WITH_MIN_SCOPE mode. * @return this builder */ + @NonNull public Builder setMinimumScope(final int scope) { if (FORWARD_WITH_MIN_SCOPE != mForwardingMode) { throw new IllegalArgumentException("Can't set the scope on a builder in mode " @@ -237,6 +256,7 @@ public class MulticastRoutingConfig implements Parcelable { * If this address was already added, this is a no-op. * @return this builder */ + @NonNull public Builder addListeningAddress(@NonNull final Inet6Address address) { if (FORWARD_SELECTED != mForwardingMode) { throw new IllegalArgumentException("Can't add an address on a builder in mode " @@ -254,7 +274,8 @@ public class MulticastRoutingConfig implements Parcelable { * If this address was not added, or was already removed, this is a no-op. * @return this builder */ - public Builder removeListeningAddress(@NonNull final Inet6Address address) { + @NonNull + public Builder clearListeningAddress(@NonNull final Inet6Address address) { if (FORWARD_SELECTED != mForwardingMode) { throw new IllegalArgumentException("Can't remove an address on a builder in mode " + modeToString(mForwardingMode)); @@ -266,6 +287,7 @@ public class MulticastRoutingConfig implements Parcelable { /** * Build the config. */ + @NonNull public MulticastRoutingConfig build() { return new MulticastRoutingConfig(mForwardingMode, mMinScope, mListeningAddresses); }