From 57a8bcf130108f643a8fa3941f7e5d38f9cded2f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Thi=C3=A9baud=20Weksteen?= <tweek@google.com>
Date: Mon, 8 May 2023 19:10:33 +1000
Subject: [PATCH] Add example to PermissionEnforcer javadoc

Include an example on how to mock the enforcer when using Mockito.

Test: n/a
Change-Id: Ib7572dd8b4778f752f7e642c5229230ce4254c1a
---
 core/java/android/os/PermissionEnforcer.java | 32 ++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/core/java/android/os/PermissionEnforcer.java b/core/java/android/os/PermissionEnforcer.java
index d772fe3bd037b..91d22698d7df7 100644
--- a/core/java/android/os/PermissionEnforcer.java
+++ b/core/java/android/os/PermissionEnforcer.java
@@ -34,6 +34,38 @@ import android.permission.PermissionCheckerManager;
  * PermissionEnforcer to validate the permissions. The methods available are
  * purposely similar to the AIDL annotation syntax.
  *
+ * <p>The constructor of the Stub generated by AIDL expects a
+ * PermissionEnforcer. It can be based on the current Context. For example:
+ *
+ * <pre>{@code
+ * class MyFoo extends Foo.Stub {
+ *     MyFoo(Context context) {
+ *         super(PermissionEnforcer.fromContext(context));
+ *     }
+ *
+ *     @Override
+ *     @EnforcePermission(android.Manifest.permission.INTERNET)
+ *     public MyMethod() {
+ *         MyMethod_enforcePermission();
+ *     }
+ * }
+ * }</pre>
+ *
+ * <p>A {@link android.os.test.FakePermissionEnforcer} is available for unit
+ * testing. It can be attached to a mocked Context using:
+ * <pre>{@code
+ * @Mock private Context mContext;
+ *
+ * @Before
+ * public setUp() {
+ *   fakeEnforcer = new FakePermissionEnforcer();
+ *   fakeEnforcer.grant(android.Manifest.permission.INTERNET);
+ *
+ *   doReturn(fakeEnforcer).when(mContext).getSystemService(
+                eq(Context.PERMISSION_ENFORCER_SERVICE));
+ * }
+ * }</pre>
+ *
  * @see android.permission.PermissionManager
  *
  * @hide