Improve JavaDocs of some API classes

Author: sberyozkin

src/main/java/io/quarkus/security/PermissionChecker.java

@@ -7,7 +7,7 @@
 
 /**
  * Annotation that can be used to annotate a CDI bean method that checks
- * if a {@link io.quarkus.security.identity.SecurityIdentity} holds a permission specified by the {@link #value()}.
+ * if a matching {@link PermissionsAllowed} permission with the {@link #value()} name can be granted.
  * For example:
  * <pre>
  * {@code
@@ -27,7 +27,7 @@
  * }
  * }
  * </pre>
- * The permission checker methods can include any of secured method parameters (matched by name).
+ * The permission checker methods can include any of the secured method parameters, matched by name.
  * Consider the following secured method:
  * <pre>
  * {@code
@@ -37,8 +37,8 @@
  * }
  * }
  * </pre>
- * The permission checker that grants access to the {@code updateString} method can inject
- * any arguments it requires and optionally even {@link io.quarkus.security.identity.SecurityIdentity}:
+ * The permission checker that grants access to the {@code updateString} method can include
+ * any of the {@code updateString} method parameters, {@link io.quarkus.security.identity.SecurityIdentity} can also be included:
  * <pre>
  * {@code
  * &#64;PermissionChecker("update")
@@ -47,8 +47,34 @@
  * }
  * }
  * </pre>
- * The permission checker method parameters are matched with the secured method parameters in exactly same fashion
- * as are constructor parameters of a custom permission. Please see {@link PermissionsAllowed#params()} for more information.
+ * The permission checker method parameters are matched with the secured method parameters exactly the same way as
+ * the constructor parameters of a custom permission are. Please see {@link PermissionsAllowed#params()} for more information.
+ * <pre>
+ * If the {@link PermissionsAllowed} annotation lists several permission names and its {@link PermissionsAllowed#inclusive} property is set to `true` then an equal number of permission checker methods must be available.
+ * Consider the following secured method:
+ * <pre>
+ * {@code
+ * &#64;PermissionsAllowed(value={"read:all", "write"}, inclusive=true)
+ * public String readWriteString(String a) {
+ *     ...
+ * }
+ * }
+ * </pre>
+ * For the access to the {@code readWriteString} method be granted, two permission checkers,
+ * one for the `read:all` permission, and another one for the `write` permission, must be available:
+ * <pre>
+ * {@code
+ * &#64;PermissionChecker("read:all")
+ * public boolean canRead(SecurityIdentity identity) {
+ *     ...
+ * }
+ * &#64;PermissionChecker("write")
+ * public boolean canWrite(SecurityIdentity identity) {
+ *     ...
+ * }
+ * }
+ * </pre>
+ * Note that a permission checker matches one of the {@link PermissionsAllowed} permissions if their String names are equal.
  */
 @Target(ElementType.METHOD)
 @Retention(RetentionPolicy.RUNTIME)

src/main/java/io/quarkus/security/PermissionsAllowed.java

@@ -9,20 +9,7 @@
 import java.security.Permission;
 
 /**
- * Indicates that a resource can only be accessed by a user with one of permissions specified through {@link #value()}.
- * There are some situations where you want to require more than one permission, this can be achieved by repeating
- * annotation. Please see an example below:
- *
- * <pre>
- * &#64;PermissionsAllowed("create")
- * &#64;PermissionsAllowed("update")
- * public Resource createOrUpdate(Long id) {
- *     // business logic
- * }
- * </pre>
- *
- * To put it another way, permissions specified by one annotation instance are disjunctive and the permission check is
- * only true if all annotation instances are evaluated as true.
+ * Lists one or more required permissions that must be granted.
  */
 @Documented
 @Retention(RetentionPolicy.RUNTIME)
@@ -32,7 +19,7 @@
 
     /**
      * Constant value for {@link #params()} indicating that the constructor parameters of the {@link #permission()}
-     * should be autodetected based on formal parameter names. For example, consider following method secured with this
+     * should be autodetected based on formal parameter names. For example, consider the following method secured with this
      * annotation:
      * <pre>
      * {@code
@@ -81,7 +68,7 @@
 
     /**
      * Colon is used to separate a {@link Permission#getName()} and an element of the {@link Permission#getActions()}.
-     * For example, {@link StringPermission} created for method 'getResource':
+     * For example, {@link StringPermission} created for the 'getResource' method:
      *
      * <pre>
      * &#64;PermissionsAllowed("resource:retrieve")
@@ -97,8 +84,9 @@
     String PERMISSION_TO_ACTION_SEPARATOR = ":";
 
     /**
-     * Specifies a list of permissions that grants the access to the resource. It is also possible to define permission's
-     * actions that are permitted for the resource. Yet again, consider method 'getResource':
+     * Specifies a list of permissions that grants access to the resource.
+     * It is also possible to define permission actions that are permitted for the resource.
+     * Consider the `getResource` method:
      *
      * <pre>
      * &#64;PermissionsAllowed({"resource:crud", "resource:retrieve", "system-resource:retrieve"})
@@ -107,15 +95,15 @@
      * }
      * </pre>
      *
-     * Two {@link StringPermission}s will be created:
+     * Two {@link StringPermission} permissions will be created:
      *
      * <pre>
      * var pem1 = new StringPermission("resource", "crud", "retrieve");
      * var pem2 = new StringPermission("system-resource", "retrieve");
      * </pre>
      *
-     * And the permission check will pass if either {@code pem1} or {@code pem2} implies user permissions.
-     * Technically, it is also possible to both define actions and no action for same-named permission like this:
+     * The permission check will pass if either {@code pem1} or {@code pem2} implies user permissions.
+     * It is also possible to combine permissions with and without actions like this:
      *
      * <pre>
      * &#64;PermissionsAllowed({"resource:crud", "resource:retrieve", "natural-resource"})
@@ -130,19 +118,26 @@
      * var pem1 = new StringPermission("resource", "crud", "retrieve");
      * var pem2 = new StringPermission("natural-resource");
      * </pre>
+     * Alternatively, when multiple required permissions must be listed, you can repeat the annotation, for example:
+     * <pre>
+     * &#64;PermissionsAllowed("create")
+     * &#64;PermissionsAllowed("update")
+     * public Resource createOrUpdate(Long id) {
+          // business logic
+     * }
+     * </pre>
      *
-     * To see how the example above is evaluated, please see "implies" method of your {@link #permission()}.
-     *
-     * @see StringPermission#implies(Permission) for more details on how above-mentioned example is evaluated
+     * @see StringPermission#implies(Permission) for more details on how the above example is evaluated.
      *
-     * @return permissions linked to respective actions
+     * @return permissions
      */
     String[] value();
 
     /**
-     * Choose a relation between permissions specified via {@link #value()}. By default, at least one of permissions
-     * is required (please see the example above). You can require all of them by setting `inclusive` to `true`.
-     * Let's re-use same example and make permissions inclusive:
+     * Choose a relation between multiple permissions specified in {@link #value()}.
+     * By default, at least one of permissions must be granted.
+     * You can request that all of the listed  permissions by setting the `inclusive` property to `true`.
+     * For example:
      *
      * <pre>
      * &#64;PermissionsAllowed(value = {"resource:crud", "resource:retrieve", "natural-resource"}, inclusive = true)
@@ -158,23 +153,23 @@
      * var pem2 = new StringPermission("system-resource", "retrieve");
      * </pre>
      *
-     * And the permission check will pass if <b>both</b> {@code pem1} and {@code pem2} implies user permissions.
+     * And the permission check will pass if <b>both</b> {@code pem1} and {@code pem2} imply user permissions.
      *
      * @return `true` if permissions should be inclusive
      */
     boolean inclusive() default false;
 
     /**
      * Mark parameters of the annotated method that should be passed to the constructor of the {@link #permission()}.
-     * First, let's define ourselves three classes:
+     * Consider the following three classes:
      *
      * <pre>
      * class ResourceIdentity { }
      * class User extends ResourceIdentity { }
      * class Admin extends ResourceIdentity { }
      * </pre>
      *
-     * Now that we have defined parameter data types, please consider the secured method 'getResource':
+     * Next, consider the secured 'getResource' method:
      *
      * <pre>
      * &#64;PermissionsAllowed(permission = UserPermission.class, value = "resource", params = {user1, admin1})
@@ -183,7 +178,7 @@
      * }
      * </pre>
      *
-     * In the example above, we marked parameters {@code user1} and {@code admin1} as {@link #permission()} constructor
+     * In the example above, the parameters {@code user1} and {@code admin1} are marked as {@link #permission()} constructor
      * arguments:
      *
      * <pre>
@@ -202,19 +197,13 @@
      * }
      * </pre>
      *
-     * Please mention that:
+     * Please note that:
      * <ul>
-     * <li>constructor parameter names {@code user1} and {@code admin1} must exactly match respective "params",</li>
-     * <li>"ResourceIdentity" could be used as constructor parameter data type, for "User" and "Admin" are assignable
-     * from "ResourceIdentity",</li>
-     * <li>"getResource" parameters {@code user} and {@code admin} are not passed to the "UserPermission" constructor.</li>
+     * <li>The constructor parameter names {@code user1} and {@code admin1} must match respective {@code PermissionsAllowed#params}</li>
+     * <li>`ResourceIdentity` can also be used as a constructor parameter data type</li>
      * </ul>
      *
-     * When this annotation is used as the class-level annotation, same requirements are put on every single secured method.
-     *
-     * <p>
-     * <b>WARNING:</b> "params" attribute is only supported in the scenarios explicitly named in the Quarkus documentation.
-     * </p>
+     * When this annotation is used as the class-level annotation, it applies to every secured method in the class.
      *
      * Method parameter fields or methods can be passed to a Permission constructor as well.
      * Consider the following secured method and its parameters:
@@ -252,8 +241,8 @@
      * }
      * </pre>
      *
-     * Here, the constructor parameter {@code param1} refers to the {@code admin1#param1} secured method parameter
-     * and the constructor parameter {@code param3} to the {@code user1#getParam3} secured method parameter.
+     * The constructor parameter {@code param1} refers to the {@code admin1#param1} secured method parameter
+     * and the constructor parameter {@code param3} refers to the {@code user1#getParam3} secured method parameter.
      *
      * @see #AUTODETECTED
      *
@@ -262,7 +251,7 @@
     String[] params() default AUTODETECTED;
 
     /**
-     * The class that extends the {@link Permission} class, used to create permissions specified via {@link #value()}.
+     * The class that extends the {@link Permission} class to create a permission specified in {@link #value()}.
      *
      * For example:
      *
@@ -287,8 +276,7 @@
     Class<? extends Permission> permission() default StringPermission.class;
 
     /**
-     * The repeatable holder for {@link PermissionsAllowed}. The annotation is not repeatable on class-level as
-     * repeatable interceptor bindings declared on classes are not supported by Quarkus.
+     * The repeatable holder for {@link PermissionsAllowed}. The annotation can only be repeatable on methods.
      */
     @Target(ElementType.METHOD)
     @Retention(RetentionPolicy.RUNTIME)

src/main/java/io/quarkus/security/identity/SecurityIdentity.java

@@ -4,51 +4,49 @@
 import java.security.Principal;
 import java.util.Map;
 import java.util.Set;
-import java.util.concurrent.CompletionStage;
 
 import io.quarkus.security.credential.Credential;
 import io.smallrye.mutiny.Uni;
 
 /**
- * Interface that represents the currently logged in user.
+ * Interface that represents the current security identity such as a logged-in user or other authenticated subject.
  * <p>
- * Instances of this class will always be available for injection even if no user is currently
- * logged in. In this case {@link #isAnonymous()} will return <code>true</code>, and the user
- * will generally not have any roles (although some implementation may assign roles to anonymous users).
+ * Instances of this class will always be available for injection even if no authentication has taken place.
+ * In this case {@link #isAnonymous()} will return <code>true</code>, and the security identity will generally have no roles.
  * <p>
  * Implementations should be immutable.
  */
 public interface SecurityIdentity {
 
     /**
-     * The attribute name that is used to store the underlying user representation.
+     * The attribute name that is used to store the underlying security identity representation.
      */
     String USER_ATTRIBUTE = "quarkus.user";
 
     /**
-     * @return the {@link Principal} representing the current user.
+     * @return the {@link Principal} representing the current security identity.
      */
     Principal getPrincipal();
 
     /**
      * @param clazz {@link Principal} subclass
-     * @return the {@link Principal} subclass representing the current user.
+     * @return the {@link Principal} subclass representing the current security identity.
      */
     default <T extends Principal> T getPrincipal(Class<T> clazz) {
         return clazz.cast(getPrincipal());
     }
 
     /**
-     * @return <code>true</code> if this identity represents an anonymous (i.e. not logged in) user
+     * @return <code>true</code> if this identity is anonymous
      */
     boolean isAnonymous();
 
     /**
-     * Returns the set of all roles held by the user. These roles must be resolvable in advance for every request.
+     * Returns the set of all roles held by the security identity. These roles must be resolvable in advance for every request.
      * <p>
      * Note that roles are returned on a best effort basis. To actually check if
      * a user holds a role {@link #hasRole(String)} should be used instead. Some API's (e.g. JAX-RS) do not allow
-     * for all roles to be returned, so if the underlying user representation does not support retrieving all the roles
+     * for all roles to be returned, so if the underlying identity representation does not support retrieving all the roles
      * this method will not always be reliable. In general all built in Quarkus security extensions should provide this,
      * unless it is documented otherwise.
      *
@@ -61,7 +59,7 @@ default <T extends Principal> T getPrincipal(Class<T> clazz) {
     Set<String> getRoles();
 
     /**
-     * Checks if a user has a given role. These roles must be resolvable in advance for every request.
+     * Checks if a security identity has a given role. These roles must be resolvable in advance for every request.
      * <p>
      * If more advanced authorization support is required than can be provided by a simple role based system
      * then {@link #checkPermission(Permission)} and {@link #checkPermissionBlocking(Permission)} should be used
@@ -73,7 +71,7 @@ default <T extends Principal> T getPrincipal(Class<T> clazz) {
     boolean hasRole(String role);
 
     /**
-     * Gets the users credential of the given type, or <code>null</code> if a credential of the given type is not
+     * Gets the security identity credential of the given type, or <code>null</code> if a credential of the given type is not
      * present.
      *
      * @param credentialType The type of the credential
@@ -83,7 +81,7 @@ default <T extends Principal> T getPrincipal(Class<T> clazz) {
     <T extends Credential> T getCredential(Class<T> credentialType);
 
     /**
-     * Returns a set of all credentials owned by this user.
+     * Returns a set of all credentials owned by this security identity.
      *
      * @return a set of all credentials
      */
@@ -111,24 +109,22 @@ default <T extends Principal> T getPrincipal(Class<T> clazz) {
     Map<String, Object> getAttributes();
 
     /**
-     * Checks if a user holds a given permissions, and if so will return <code>true</code>.
+     * Checks if a security identity holds a given permission.
      * <p>
      * This method is asynchronous, as it may involve calls to a remote resource.
      *
      * @param permission The permission
-     * @return A completion stage that will resolve to true if the user has the specified permission
+     * @return Uni that will resolve to true if the security identity has the specified permission
      */
     Uni<Boolean> checkPermission(Permission permission);
 
     /**
-     * Checks if a user holds a given permissions, and if so will return <code>true</code>.
+     * Checks if a user holds a given permission.
      * <p>
-     * This method is a blocking version of {@link #checkPermission(Permission)}. By default it will
-     * just wait for the {@link CompletionStage} to be complete, however it is likely that some implementations
-     * will want to provide a more efficient version.
+     * This method is a blocking version of {@link #checkPermission(Permission)}..
      *
      * @param permission The permission
-     * @return A completion stage that will resolve to true if the user has the specified permission
+     * @return true if the security identity has the specified permission
      */
     default boolean checkPermissionBlocking(Permission permission) {
         return checkPermission(permission).await().indefinitely();