Add canonicalization clarification to methods that accept paths

api/src/main/java/jakarta/servlet/ServletContext.java

@@ -212,6 +212,10 @@ public interface ServletContext {
      * application) security constraints. Care should be taken both when constructing the path (e.g. avoid unsanitized user
      * provided data) and when using the result not to create a security vulnerability in the application.
      * 
+     * <p>
+     * The provided {@code path} parameter is canonicalized as per section 3.5.2 of the specification before being used to
+     * match resources.
+     * 
      * @param path the partial path used to match the resources, which must start with a <tt>/</tt>
      * @return a Set containing the directory listing, or null if there are no resources in the web application whose path
      * begins with the supplied path.
@@ -257,6 +261,10 @@ public interface ServletContext {
      * application) security constraints. Care should be taken both when constructing the path (e.g. avoid unsanitized user
      * provided data) and when using the result not to create a security vulnerability in the application.
      *
+     * <p>
+     * The provided {@code path} parameter is canonicalized as per section 3.5.2 of the specification before being used to
+     * match a resource.
+     * 
      * @param path a <code>String</code> specifying the path to the resource
      *
      * @return the resource located at the named path, or <code>null</code> if there is no resource at that path
@@ -291,6 +299,10 @@ public interface ServletContext {
      * application) security constraints. Care should be taken both when constructing the path (e.g. avoid unsanitized user
      * provided data) and when using the result not to create a security vulnerability in the application.
      *
+     * <p>
+     * The provided {@code path} parameter is canonicalized as per section 3.5.2 of the specification before being used to
+     * match a resource.
+     * 
      * @param path a <code>String</code> specifying the path to the resource
      *
      * @return the <code>InputStream</code> returned to the servlet, or <code>null</code> if no resource exists at the
@@ -317,6 +329,10 @@ public interface ServletContext {
      * application) security constraints. Care should be taken both when constructing the path (e.g. avoid unsanitized user
      * provided data) and when using the result not to create a security vulnerability in the application.
      * 
+     * <p>
+     * The provided {@code path} parameter is canonicalized as per section 3.5.2 of the specification before being used to
+     * match a resource.
+     * 
      * @param path a <code>String</code> specifying the pathname to the resource
      *
      * @return a <code>RequestDispatcher</code> object that acts as a wrapper for the resource at the specified path, or
@@ -400,6 +416,10 @@ public interface ServletContext {
      * application) security constraints. Care should be taken both when constructing the path (e.g. avoid unsanitized user
      * provided data) and when using the result not to create a security vulnerability in the application.
      * 
+     * <p>
+     * The provided {@code path} parameter is canonicalized as per section 3.5.2 of the specification before being
+     * translated to a real path.
+     * 
      * @param path the <i>virtual</i> path to be translated to a <i>real</i> path
      *
      * @return the <i>real</i> path, or <tt>null</tt> if the translation cannot be performed

spec/src/main/asciidoc/servlet-spec-body.adoc

@@ -8570,8 +8570,8 @@ headers with the same name are present in the `HttpServletRequest`. The expected
 behaviour is aligned with `getHeader()`. 
 
 link:https://github.com/eclipse-ee4j/servlet-api/issues/453[Issue 453]::
-Add a security warning to all `ServletContext` methods that accept a path
-parameter.
+Add a security warning and a clarification of canonicalization requirements to
+all `ServletContext` methods that accept a path parameter.
 
 link:https://github.com/eclipse-ee4j/servlet-api/issues/463[Issue 463]::
 Clarify Javadoc for `MultipartConfigElement` and `MultipartConfig` that sizes