From 7546871d7320452b2430fec2dedbc6d5191fcfbf Mon Sep 17 00:00:00 2001 From: "R.M.Morrien" Date: Wed, 4 Feb 2026 22:53:00 +0100 Subject: [PATCH] Improve Policy.implies(Permission permissionToBeChecked, Set principals) javadoc, it was a copy of getPermissionCollection --- .../security/jacc/EJBRoleRefPermission.java | 5 +-- .../jakarta/security/jacc/HttpMethodSpec.java | 32 +++++++++++++++++-- .../java/jakarta/security/jacc/Policy.java | 17 +++------- .../security/jacc/PolicyConfiguration.java | 6 ++-- .../jakarta/security/jacc/URLPattern.java | 2 ++ .../jakarta/security/jacc/URLPatternSpec.java | 4 ++- .../security/jacc/WebResourcePermission.java | 5 +-- 7 files changed, 49 insertions(+), 22 deletions(-) diff --git a/api/src/main/java/jakarta/security/jacc/EJBRoleRefPermission.java b/api/src/main/java/jakarta/security/jacc/EJBRoleRefPermission.java index e4acfbb..7dddc5e 100755 --- a/api/src/main/java/jakarta/security/jacc/EJBRoleRefPermission.java +++ b/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 @@ * *

* 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. * *

* The actions of an EJBRoleRefPermission identifies the role reference to which the permission applies. An @@ -141,7 +142,7 @@ public int hashCode() { *

*

* The name and actions comparisons described above are case sensitive. diff --git a/api/src/main/java/jakarta/security/jacc/HttpMethodSpec.java b/api/src/main/java/jakarta/security/jacc/HttpMethodSpec.java index 67041bc..d61c5d6 100644 --- a/api/src/main/java/jakarta/security/jacc/HttpMethodSpec.java +++ b/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 ... - *

+ * HTTPMethodSpec describes the syntax of the HTTP method component of their actions values. The HTTPMethodSpec syntax + * is defined as follows: + * 

+ *
+ *          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
+ *
+ *
+ * + *

+ * If duplicates occur in the HTTPMethodSpec they must be eliminated by the permission constructor. + * + *

+ * A null or empty string HTTPMethodSpec indicates that the permission applies to all HTTP methods at the resources + * identified by the URL pattern. + * + *

+ * 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 diff --git a/api/src/main/java/jakarta/security/jacc/Policy.java b/api/src/main/java/jakarta/security/jacc/Policy.java index cb27f33..2476aad 100644 --- a/api/src/main/java/jakarta/security/jacc/Policy.java +++ b/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. - * - *

- * 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 principals) { Subject subject = new Subject(); diff --git a/api/src/main/java/jakarta/security/jacc/PolicyConfiguration.java b/api/src/main/java/jakarta/security/jacc/PolicyConfiguration.java index db04f3c..4c5efa2 100755 --- a/api/src/main/java/jakarta/security/jacc/PolicyConfiguration.java +++ b/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. * *

* 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. * *

- * 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 diff --git a/api/src/main/java/jakarta/security/jacc/URLPattern.java b/api/src/main/java/jakarta/security/jacc/URLPattern.java index ac27815..1b657ce 100644 --- a/api/src/main/java/jakarta/security/jacc/URLPattern.java +++ b/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) { * * * @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) { diff --git a/api/src/main/java/jakarta/security/jacc/URLPatternSpec.java b/api/src/main/java/jakarta/security/jacc/URLPatternSpec.java index ecb3739..2eb73f9 100644 --- a/api/src/main/java/jakarta/security/jacc/URLPatternSpec.java +++ b/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(); } diff --git a/api/src/main/java/jakarta/security/jacc/WebResourcePermission.java b/api/src/main/java/jakarta/security/jacc/WebResourcePermission.java index cd25d2d..dc018a0 100755 --- a/api/src/main/java/jakarta/security/jacc/WebResourcePermission.java +++ b/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) {