Merge "Add example to PermissionEnforcer javadoc"

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