java.security.Principal that represents
+ * Retrieve the platform-specific {@code java.security.Principal} that represents
* the name of authenticated caller, or null if the current caller is not authenticated.
*
* @return Principal representing the name of the current authenticated user, or null if not authenticated.
@@ -57,7 +57,7 @@ public interface SecurityContext {
* Modifications to the returned Set will not affect the internal Principal Set.
*
* @param pType Class object representing the type of Principal to return.
- * @param pType argument
+ * @param false.
+ * If the caller is not authenticated, this always returns {@code false}.
*
*
* This method can not be used to test for roles that are mapped to specific named Jakarta Servlets or
- * named Jakarta Enterprise Beans. For a Servlet an example of this would be the role-name nested in a
- * security-role-ref element nested in a servlet element in web.xml.
+ * named Jakarta Enterprise Beans. For a Servlet an example of this would be the {@code role-name} nested in a
+ * {@code security-role-ref} element nested in a {@code servlet} element in {@code web.xml}.
*
*
* Should code in either such Jakarta Servlet or Jakarta Enterprise Bean wish to take such mapped (aka referenced, linked)
* roles into account, the facilities for that specific container should be used instead. For instance for Servlet that
* would be {@link HttpServletRequest#isUserInRole(String)} and for Jakarta Enterprise Beans that would be
- * jakarta.ejb.SessionContext#isCallerInRole(String).
+ * {@code jakarta.ejb.SessionContext#isCallerInRole(String)}.
*
- * @param role a String specifying the name of the logical application role
- * @return true if the authenticated caller is in the given role, false if the caller is not authentication or
+ * @param role a {@code String} specifying the name of the logical application role
+ * @return {@code true} if the authenticated caller is in the given role, false if the caller is not authentication or
* is not in the given role.
*/
boolean isCallerInRole(String role);
@@ -109,12 +109,14 @@ public interface SecurityContext {
* A caller has access if the web resource is either not protected (constrained), or when it is protected by a role
* and the caller is in that role.
*
- * @param resource the name of the web resource to test access for. This is a URLPatternSpec that
- * identifies the application specific web resources to which the permission pertains. For a full specification of this
- * pattern see {@link jakarta.security.jacc.WebResourcePermission#WebResourcePermission(String, String)}.
- * @param methods one or more methods to check for whether the caller has access to the web resource using one of those methods.
+ * @param resource the name of the web resource to test access for. This is a {@code URLPatternSpec} that identifies
+ * the application specific web resources to which the permission pertains. For a full specification of this pattern
+ * see {@link jakarta.security.jacc.WebResourcePermission#WebResourcePermission(String, String)}.
+ * @param methods HTTP methods to check for whether the caller has access to the web resource using one of those
+ * methods. If no methods are provided, this method will return {@code true} only if the caller can access the resource using all HTTP methods
*
- * @return true if the caller has access to the web resource using one of the given methods, false otherwise.
+ * @return {@code true} if the caller has access to the web resource using one of the given methods, or using all
+ * supported HTTP methods, if no method is provided. Otherwise returns {@code false}.
*/
boolean hasAccessToWebResource(String resource, String... methods);
@@ -130,14 +132,14 @@ public interface SecurityContext {
* Whether the authentication dialog is to be started or continued depends on the (logical) state of the authentication dialog. If
* such dialog is currently in progress, a call to this method will continue it. If such dialog is not in progress a new one will be
* started. A new dialog can be forced to be started regardless of one being in progress or not by providing a value of
- * true for the {@link AuthenticationParameters#newAuthentication} parameter with this call.
+ * {@code true} for the {@link AuthenticationParameters#newAuthentication} parameter with this call.
*
*
* This method requires an {@link HttpServletRequest} and {@link HttpServletResponse} argument to be passed in, and
* can therefore only be used in a valid Servlet context.
*
- * @param request The HttpServletRequest associated with the current web resource invocation.
- * @param response The HttpServletResponse associated with the given HttpServletRequest.
+ * @param request The {@code HttpServletRequest} associated with the current web resource invocation.
+ * @param response The {@code HttpServletResponse} associated with the given {@code HttpServletRequest}.
* @param parameters The parameters that are provided along with a programmatic authentication request, for instance the credentials.
* collected by the application for continuing an authentication dialog.
*
diff --git a/spec/src/main/asciidoc/securityContext.adoc b/spec/src/main/asciidoc/securityContext.adoc
index 5820530..b815525 100644
--- a/spec/src/main/asciidoc/securityContext.adoc
+++ b/spec/src/main/asciidoc/securityContext.adoc
@@ -59,14 +59,68 @@ As an example, consider the following Servlet definition:
public class ProtectedServlet extends HttpServlet { ... }
----
-And the following call to _hasAccessToWebResource()_:
+And the following calls to _hasAccessToWebResource()_:
[source,java]
----
-securityContext.hasAccessToWebResource("/protectedServlet", GET)
+securityContext.hasAccessToWebResource("/protectedServlet")
----
-The above _hasAccessToWebResource()_ call would return true if and only if the caller is in role "foo".
+[source,java]
+----
+securityContext.hasAccessToWebResource("/protectedServlet", "GET")
+----
+
+[source,java]
+----
+securityContext.hasAccessToWebResource("/protectedServlet", "GET", "POST")
+----
+
+All the above _hasAccessToWebResource()_ calls would return `true` if and only if the caller is in role "foo".
+
+'''
+
+As another example, consider the following definition, which gives access to the resource:
+
+* for the role "bar" only via the GET method
+* for the role "foo" via all methods except the GET method
+
+[source,java]
+----
+@WebServlet("/protectedServlet")
+@ServletSecurity(
+ value = @HttpConstraint(rolesAllowed = "foo"),
+ httpMethodConstraints = {
+ @HttpMethodConstraint(value = "GET", rolesAllowed = "bar"),
+ })
+public class ProtectedServlet extends HttpServlet { ... }
+----
+
+And the following calls to _hasAccessToWebResource()_:
+
+[source,java]
+----
+securityContext.hasAccessToWebResource("/protectedServlet", "GET")
+----
+
+The above _hasAccessToWebResource()_ call would return `true` if and only if the caller is in role "bar".
+
+[source,java]
+----
+securityContext.hasAccessToWebResource("/protectedServlet", "POST", "PUT")
+----
+
+The above _hasAccessToWebResource()_ call would return `true` if and only if the caller is in role "foo".
+
+On the other hand, the following call, with no method arguments:
+
+[source,java]
+----
+securityContext.hasAccessToWebResource("/protectedServlet")
+----
+
+would always return `false` because no role has access via all HTTP methods - role "bar" has access via the GET method, roles "foo" has access via all other methods but not via the GET.
+
=== Triggering the Authentication Process