Generalize guidance for AIDL-generated code
It's not just for Binders!
PiperOrigin-RevId: 491734109
Change-Id: I195b60ed6b1bb690904aaabde854f3aad53d34ea
diff --git a/api-guidelines/classes.md b/api-guidelines/classes.md
index 09a12f4..878454f 100644
--- a/api-guidelines/classes.md
+++ b/api-guidelines/classes.md
@@ -85,6 +85,88 @@
`View` and calling several methods on the `View` to install the backport,
`TooltipHelper` would be an acceptable class name.
+### Do not expose AIDL-generated code as public APIs directly <a name="no-aidl-generated"></a>
+
+Keep AIDL-generated code as implementation details. Generated AIDL classes do
+not meet the API style guide requirements (for example, they cannot use
+overloading) and are not guaranteed to maintain language API compatibility, so
+we can't embed them in a public API.
+
+Instead, add a public API layer on top of the AIDL interface, even if it
+initially is a shallow wrapper.
+
+#### `Binder` interfaces
+
+If the `Binder` interface is an implementation detail, it can be changed freely
+in the future, with the public layer allowing for the required backward
+compatibility to be maintained. For example, you may find you need to add new
+arguments to the internal calls, or optimize IPC traffic via batching/streaming,
+using shared memory, or similar. None of these can currently be done if your
+AIDL interface is also the public API.
+
+For example, instead of exposing `FooService` as a public API directly:
+
+```java {.bad}
+// BAD: Public API generated from IFooService.aidl
+public class IFooService {
+ public void doFoo(String foo);
+}
+```
+
+instead wrap the `Binder` interface inside a manager or other class:
+
+```java {.good}
+/**
+ * @hide
+ */
+public class IFooService {
+ public void doFoo(String foo);
+}
+
+public IFooManager {
+ public void doFoo(String foo) {
+ mFooService.doFoo(foo);
+ }
+}
+```
+
+and if later a new argument is needed for this call, the internal interface can
+be kept simple and convenient overloads added to the public API. And the
+wrapping layer can be used to handle other backwards-compatibility concerns as
+the implementation evolves, as well:
+
+```java {.good}
+/**
+ * @hide
+ */
+public class IFooService {
+ public void doFoo(String foo, int flags);
+}
+
+public IFooManager {
+ public void doFoo(String foo) {
+ if (mAppTargetSdkLevel < 26) {
+ useOldFooLogic(); // Apps targeting API before 26 are broken otherwise
+ mFooService.doFoo(foo, FLAG_THAT_ONE_WEIRD_HACK);
+ } else {
+ mFooService.doFoo(foo, 0);
+ }
+ }
+
+ public void doFoo(String foo, int flags) {
+ mFooService.doFoo(foo, flags);
+ }
+}
+```
+
+For `Binder` interfaces that are not part of the Android platform (for example,
+a service interface exported by Google Play Services for applications to use),
+the requirement for a stable, published, and versioned IPC interface means that
+it is much harder to evolve the interface itself. However, it is still
+worthwhile to have a wrapper layer around it, to match other API guidelines and
+to make it easier to use the same public API for a new version of the IPC
+interface, if that ever becomes necessary.
+
### Do not use `CompletableFuture` or `Future` <a name="bad-future"></a>
`java.util.concurrent.CompletableFuture` has a large API surface that permits
diff --git a/api-guidelines/framework.md b/api-guidelines/framework.md
index 414f86d..a163be4 100644
--- a/api-guidelines/framework.md
+++ b/api-guidelines/framework.md
@@ -183,85 +183,6 @@
This guideline is enforced by Metalava in both the platform and AndroidX builds.
-### Do not expose Binder interfaces as public APIs directly <a name="no-public-binder"></a>
-
-Keep AIDL-generated-code as implementation details. Generated AIDL classes do
-not meet the API style guide requirements (for example, they cannot use
-overloading) and may change at any time, so we can't embed them in an API.
-
-Instead, add a public API layer on top of the AIDL interface, even if it
-initially is a shallow wrapper.
-
-If the Binder interface is an implementation detail, it can be changed freely in
-the future, with the public layer allowing for the required backward
-compatibility to be maintained. For example, you may find you need to add new
-arguments to the internal calls, or optimize IPC traffic via batching/streaming,
-using shared memory, or similar. None of these can currently be done if your
-AIDL interface is also the public API.
-
-For example, instead of exposing FooService as a public API directly:
-
-```java {.bad}
-// BAD: Public API generated from IFooService.aidl
-public class IFooService {
- public void doFoo(String foo);
-}
-```
-
-instead wrap the Binder interface inside a manager or other class:
-
-```java {.good}
-/**
- * @hide
- */
-public class IFooService {
- public void doFoo(String foo);
-}
-
-public IFooManager {
- public void doFoo(String foo) {
- mFooService.doFoo(foo);
- }
-}
-```
-
-and if later a new argument is needed for this call, the internal interface can
-be kept simple and convenient overloads added to the public API. And the
-wrapping layer can be used to handle other backwards-compatibility concerns as
-the implementation evolves, as well:
-
-```java {.good}
-/**
- * @hide
- */
-public class IFooService {
- public void doFoo(String foo, int flags);
-}
-
-public IFooManager {
- public void doFoo(String foo) {
- if (mAppTargetSdkLevel < 26) {
- useOldFooLogic(); // Apps targeting API before 26 are broken otherwise
- mFooService.doFoo(foo, FLAG_THAT_ONE_WEIRD_HACK);
- } else {
- mFooService.doFoo(foo, 0);
- }
- }
-
- public void doFoo(String foo, int flags) {
- mFooService.doFoo(foo, flags);
- }
-}
-```
-
-For Binder interfaces that are not part of the Android platform (for example, a
-service interface exported by Google Play Services for applications to use), the
-requirement for a stable, published, and versioned IPC interface means that it
-is much harder to evolve the interface itself. However, it is still worthwhile
-to have a wrapper layer around it, to match other API guidelines and to make it
-easier to use the same public API for a new version of the IPC interface, if
-that ever becomes necessary.
-
### Do not add new setting provider keys <a name="no-settings-provider"></a>
Do not expose new keys from
