diff options
| -rw-r--r-- | api-guidelines/classes.md | 31 |
1 files changed, 31 insertions, 0 deletions
diff --git a/api-guidelines/classes.md b/api-guidelines/classes.md index 2c21ab8..e3a4777 100644 --- a/api-guidelines/classes.md +++ b/api-guidelines/classes.md @@ -167,6 +167,37 @@ 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 raw `Binder` objects in public API <a name="classes-wrap-binder"></a> + +A `Binder` object does not have any meaning on its own and thus should not be +used in public API. One common use-case is to use a `Binder` or `IBinder` as a +token because it has identity semantics. Instead of using a raw `Binder` object +use a wrapper token class instead. + +```java{.bad} +public final class IdentifiableObject { + public Binder getToken() {...} +} +``` + +```java{.good} +public final class IdentifiableObjectToken { + /** + * @hide + */ + public Binder getRawValue() {...} + + /** + * @hide + */ + public static IdentifiableObjectToken wrapToken(Binder rawValue) {...} +} + +public final class IdentifiableObject { + public IdentifiableObjectToken getToken() {...} +} +``` + ### `Manager` classes must be `final`. Manager classes should be declared as `final`. Manager classes talk to system |