Improve Policy.implies() javadoc, it was a copy of getPermissionCollection()

api/src/main/java/jakarta/security/jacc/EJBRoleRefPermission.java

@@ -1,4 +1,5 @@
 /*
+ * Copyright (c) 2026 Contributors to Eclipse Foundation. All rights reserved.
  * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved.
  *
  * This program and the accompanying materials are made available under the
@@ -28,7 +29,7 @@
  * 
  * <p>
  * The name of an EJBRoleRefPermission contains the value of the ejb-name element in the application's deployment
- * descriptor that identifies the Jakarta Enterprise Bean in whose context the permission is being evalutated.
+ * descriptor that identifies the Jakarta Enterprise Bean in whose context the permission is being evaluated.
  * 
  * <p>
  * The actions of an EJBRoleRefPermission identifies the role reference to which the permission applies. An
@@ -141,7 +142,7 @@ public int hashCode() {
      * <ul>
      * <li>The argument must be an <code>instanceof</code> <code>EJBRoleRefPermission</code>
      * <li>with name equivalent to that of this <code>EJBRoleRefPermission</code>, and
-     * <li>with the role reference equivalent to that of this <code>EJBRoleRefPermission</code> applies.
+     * <li>with the role reference equivalent to that of this <code>EJBRoleRefPermission</code>.
      * </ul>
      * <p>
      * The name and actions comparisons described above are case sensitive.

api/src/main/java/jakarta/security/jacc/HttpMethodSpec.java

@@ -1,4 +1,5 @@
 /*
+ * Copyright (c) 2026 Contributors to Eclipse Foundation. All rights reserved.
  * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved.
  *
  * This program and the accompanying materials are made available under the
@@ -23,8 +24,35 @@
 import java.util.List;
 
 /**
- * This class is used ...
- * <P>
+ * HTTPMethodSpec describes the syntax of the HTTP method component of their actions values. The HTTPMethodSpec syntax
+ * is defined as follows:
+ * <pre>
+ *
+ *          ExtensionMethod ::= any token as defined by RFC 2616
+ *                    (that is, 1*[any CHAR except CTLs or separators])
+ *
+ *          HTTPMethod ::= "GET" | "POST" | "PUT" | "DELETE" | "HEAD" |
+ *                   "OPTIONS" | "TRACE" | ExtensionMethod
+ *
+ *          HTTPMethodList ::= HTTPMethod | HTTPMethodList comma HTTPMethod
+ *
+ *          HTTPMethodExceptionList ::= exclaimationPoint HTTPMethodList
+ *
+ *          HTTPMethodSpec ::= null | HTTPMethodExceptionList |
+ *                   HTTPMethodList
+ *
+ * </pre>
+ *
+ * <p>
+ * If duplicates occur in the HTTPMethodSpec they must be eliminated by the permission constructor.
+ *
+ * <p>
+ * A null or empty string HTTPMethodSpec indicates that the permission applies to all HTTP methods at the resources
+ * identified by the URL pattern.
+ *
+ * <p>
+ * If the HTTPMethodSpec contains an HTTPMethodExceptionList (i.e., it begins with an exclaimationPoint), the permission
+ * pertains to all methods except those occurring in the exception list.
  *
  * @author Ron Monzillo
  * @author Gary Ellison

api/src/main/java/jakarta/security/jacc/Policy.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2023, 2024 Contributors to Eclipse Foundation. All rights reserved.
+ * Copyright (c) 2023, 2026 Contributors to Eclipse Foundation. All rights reserved.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License v. 2.0, which is available at
@@ -125,19 +125,12 @@ default boolean implies(Permission permissionToBeChecked) {
     }
 
     /**
-     * Returns a collection of at least all declared permissions associated with the caller principal
-     * contained in the set of principals being passed in.
-     *
-     * <p>
-     * Policies can represent remote authorization systems which may not be able to provide all permissions, and
-     * there for this method cannot guarantee all permissions are indeed returned. The policy should however
-     * return at least all permissions which are declared or set within a Jakarta EE application. Examples of such permissions
-     * are the permissions transformed from the Jakarta Servlet security constraints expression in @{web.xml}, via annotations
-     * or programmatically using the Jakarta Servlet API.
+     * This method checks whether the permission represented by the @{permissionToBeChecked} parameter is granted
+     * to the given set of principals.
      *
      * @param permissionToBeChecked the permission this policy is going to check
-     * @param principals collection containing the (obscured) caller principal
-     * @return a collection of permissions associated with the caller principal
+     * @param principals the set of principals representing the identity to authorize
+     * @return true if the set of principals allows the requested permission, false otherwise
      */
     default boolean implies(Permission permissionToBeChecked, Set<Principal> principals) {
         Subject subject = new Subject();

api/src/main/java/jakarta/security/jacc/PolicyConfiguration.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2021, 2023 Contributors to Eclipse Foundation. All rights reserved.
+ * Copyright (c) 2021, 2026 Contributors to Eclipse Foundation. All rights reserved.
  * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved.
  *
  * This program and the accompanying materials are made available under the
@@ -53,7 +53,7 @@
  * A policy context in the "deleted" state is neither available for configuration, nor is it available for assimilation
  * into the Provider. A policy context whose state is "deleted" may be reclaimed for subsequent processing by calling
  * the getPolicyConfiguration method of the associated PolicyConfigurationFactory. A "deleted" policy context is
- * transitioned to the "open" state when it it returned as a result of a call to getPolicyConfiguration.
+ * transitioned to the "open" state when it is returned as a result of a call to getPolicyConfiguration.
  *
  * <p>
  * The following table captures the correspondence between the policy context life cycle and the methods of the
@@ -383,7 +383,7 @@ default void addToExcludedPolicy(PermissionCollection permissions) throws Policy
      * cause an UnsupportedOperationException to be thrown.
      *
      * <p>
-     * This operation has no affect on any linked PolicyConfigurations other than removing any links involving the deleted
+     * This operation has no effect on any linked PolicyConfigurations other than removing any links involving the deleted
      * PolicyConfiguration.
      *
      * @throws PolicyContextException if the implementation throws a checked exception that has not been

api/src/main/java/jakarta/security/jacc/URLPattern.java

@@ -1,4 +1,5 @@
 /*
+ * Copyright (c) 2026 Contributors to Eclipse Foundation. All rights reserved.
  * Copyright (c) 1997-2020 Oracle and/or its affiliates. All rights reserved.
  * Copyright 2004 The Apache Software Foundation
  *
@@ -117,6 +118,7 @@ public int compareTo(URLPattern that) {
      * </ul>
      *
      * @param that URLPattern to determine if implied by (matched by) this URLPattern to
+     * @return true if this pattern implies the argument pattern.
      */
     public boolean implies(URLPattern that) {
 

api/src/main/java/jakarta/security/jacc/URLPatternSpec.java

@@ -1,4 +1,5 @@
 /*
+ * Copyright (c) 2026 Contributors to Eclipse Foundation. All rights reserved.
  * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved.
  *
  * This program and the accompanying materials are made available under the
@@ -84,8 +85,9 @@ public URLPatternSpec(String urlPatternSpec) {
 
     /**
      * This method returns a String containing the first URLPattern in this URLPatternSpec.
+     * 
+     * @return a String containing the first URLPattern in this URLPatternSpec.
      */
-
     public String getURLPattern() {
         return super.toString();
     }

api/src/main/java/jakarta/security/jacc/WebResourcePermission.java

@@ -1,4 +1,5 @@
 /*
+ * Copyright (c) 2026 Contributors to Eclipse Foundation. All rights reserved.
  * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved.
  *
  * This program and the accompanying materials are made available under the
@@ -131,7 +132,7 @@ public final class WebResourcePermission extends Permission {
      * @param name the URLPatternSpec that identifies the application specific web resources to which the permission
      * pertains. All URLPatterns in the URLPatternSpec are relative to the context path of the deployed web application
      * module, and the same URLPattern must not occur more than once in a URLPatternSpec. A null URLPatternSpec is
-     * translated to the default URLPattern, "/", by the permission constructor. All colons occuring within the URLPattern
+     * translated to the default URLPattern, "/", by the permission constructor. All colons occurring within the URLPattern
      * elements of the URLPatternSpec must be represented in escaped encoding as defined in RFC 2396.
      * @param actions identifies the HTTP methods to which the permission pertains. If the value passed through this
      * parameter is null or the empty string, then the permission pertains to all the possible HTTP methods.
@@ -168,7 +169,7 @@ public WebResourcePermission(String urlPatternSpec, String[] HTTPMethods) {
      * The permission name is the substring of the requestURI (HttpServletRequest.getRequestURI()) that begins after the
      * contextPath (HttpServletRequest.getContextPath()). When the substring operation yields the string "/", the permission
      * is constructed with the empty string as its name. The permission's actions field is obtained from
-     * HttpServletRequest.getMethod(). The constructor must transform all colon characters occuring in the name to escaped
+     * HttpServletRequest.getMethod(). The constructor must transform all colon characters occurring in the name to escaped
      * encoding as defined in RFC 2396.
      */
     public WebResourcePermission(HttpServletRequest request) {