EE4J 10.0.0 · jakarta.security.enterprise.authentication.mechanism.http.HttpMessageContext

Method Summary

Modifier and Type	Method and Description
public void	cleanClientSubject() Convenience method to clean the subject associated with this context.
public AuthenticationStatus	Returns: `AuthenticationStatus#NOT_DONE` doNothing() Instructs the container to "do nothing".
public AuthenticationStatus	Returns: `AuthenticationStatus#SEND_CONTINUE` forward(String a String specifying the pathname to the resource. path) Forwards to another resource (Jakarta Servlet, Jakarta Server Pages file, or HTML file) on the server.
public AuthenticationParameters	Returns: the parameters that were provided with the SecurityContext#authenticate(AuthParameters) call, or a default instance. Never null. getAuthParameters() Returns the parameters that were provided with the SecurityContext#authenticate(AuthParameters) call.
public Principal	Returns: The caller principal getCallerPrincipal() Gets the Principal set by a call to notifyContainerAboutLogin().
public Subject	Returns: the subject for which authentication is to take place. getClientSubject() Returns the subject for which authentication is to take place.
public Set<String>	Returns: The groups getGroups() Gets the groups set by a call to notifyContainerAboutLogin().
public CallbackHandler	Returns: the handler that the runtime provided to this context getHandler() Returns the low level Jakarta Authentication handler that the runtime provided when creating this `HttpMessageContext`, and which this context uses to communicate the authentication details to the runtime.
public MessageInfo	Returns: the message info instance for the current request. getMessageInfo() Returns the the low level Jakarta Authentication message info instance for the current request.
public HttpServletRequest	Returns: the request object associated with the current request. getRequest() Returns the request object associated with the current request.
public HttpServletResponse	Returns: the response object associated with the current request. getResponse() Returns the response object associated with the current request.
public boolean	Returns: true if SecurityContext#authenticate was called, false if not. isAuthenticationRequest() Checks if the current call to an authentication mechanism is the result from the application calling `SecurityContext#authenticate(HttpServletRequest, HttpServletResponse, AuthenticationParameters)` If SecurityContext#authenticate was not called, the authentication mechanism may have been invoked by the container at the start of a request.
public boolean	Returns: true if a protected resource was requested, false if a public resource was requested. isProtected() Checks if the currently requested resource is protected or not.
public boolean	Returns: true if code has asked to register an authentication session, false otherwise. isRegisterSession() Check if the runtime has been asked to register an authentication session duing the current request.
public AuthenticationStatus	Returns: `AuthenticationStatus#SUCCESS` notifyContainerAboutLogin(String the caller name that will become the caller principal callername, Set<String> the groups associated with the caller principal groups) Asks the container to register the given caller name and groups in order to make them available to the application for use with `SecurityContext#isCallerInRole(String)` etc. Note that after this call returned, the authenticated identity will not be immediately active.
public AuthenticationStatus	Returns: `AuthenticationStatus#SUCCESS` notifyContainerAboutLogin(Principal the Principal that will become the caller principal principal, Set<String> the groups associated with the caller principal groups) Asks the container to register the given caller principal and groups in order to make them available to the application for use with `SecurityContext#isCallerInRole(String)` etc. Note that this call may result in the container establishing two caller principals to represent the caller's identity -- the Principal provided here as the principal parameter, and a second principal used as the container's representation of the caller identity.
public AuthenticationStatus	Returns: `AuthenticationStatus#SUCCESS` if `CredentialValidationResult#getStatus()` equals `Status#VALID` otherwise `AuthenticationStatus#SEND_FAILURE` notifyContainerAboutLogin(CredentialValidationResult a CredentialValidationResult which is inspected for its status and from which the principal and groups are taken. result) Convenience method intended to pass the `CredentialValidationResult` result of an identity store directly on to the container.
public AuthenticationStatus	Returns: `AuthenticationStatus#SEND_CONTINUE` redirect(String the location to redirect to location) Sets the response status to SC_FOUND 302 (Found) As a convenience this method returns SEND_CONTINUE, so this method can be used in one fluent return statement from an `HttpAuthenticationMechanism`
public AuthenticationStatus	Returns: `AuthenticationStatus#SEND_FAILURE` responseNotFound() Sets the response status to 404 (not found).
public AuthenticationStatus	Returns: `AuthenticationStatus#SEND_FAILURE` responseUnauthorized() Sets the response status to 401 (unauthorized).
public void	setRegisterSession(String the caller name for which authentication should be be remembered callerName, Set<String> the groups for which authentication should be remembered. groups) Asks the runtime to register an authentication session.
public void	setRequest(HttpServletRequest the request object to be set request) Sets the request object.
public void	setResponse(HttpServletResponse the response object to be set. response) Set the response object.
public HttpMessageContext	Returns: the HttpMessageContext instance on which this method was called, useful for fluent style call call chains. withRequest(HttpServletRequest the request object to be set. request) Sets the request object.

Method Detail

cleanClientSubject back to summary

cleanClientSubject	back to summary
public void cleanClientSubject() Convenience method to clean the subject associated with this context. Cleaning this subject is done as defined by the Servlet Container Profile of Jakarta Authentication for the ServerAuthModule#cleanSubject method and the `HttpAuthenticationMechanism#cleanSubject(HttpServletRequest, HttpServletResponse, HttpMessageContext)` method defined by this specification.

public void cleanClientSubject()

Convenience method to clean the subject associated with this context.

Cleaning this subject is done as defined by the Servlet Container Profile of Jakarta Authentication for the ServerAuthModule#cleanSubject method and the HttpAuthenticationMechanism#cleanSubject(HttpServletRequest, HttpServletResponse, HttpMessageContext) method defined by this specification.

doNothing back to summary

doNothing	back to summary
public AuthenticationStatus doNothing() Instructs the container to "do nothing". When intending to do nothing, a Jakarta Security authentication mechanism has to indicate this explicitly via its return value. As a convenience this method returns NOT_DONE, so this method can be used in one fluent return statement from an `HttpAuthenticationMechanism` Returns:AuthenticationStatus `AuthenticationStatus#NOT_DONE`

public AuthenticationStatus doNothing()

Instructs the container to "do nothing".

When intending to do nothing, a Jakarta Security authentication mechanism has to indicate this explicitly via its return value.

As a convenience this method returns NOT_DONE, so this method can be used in one fluent return statement from an HttpAuthenticationMechanism

Returns:AuthenticationStatus: AuthenticationStatus#NOT_DONE

forward back to summary

forward	back to summary
public AuthenticationStatus forward(String path) Forwards to another resource (Jakarta Servlet, Jakarta Server Pages file, or HTML file) on the server. As a convenience this method returns SEND_CONTINUE, so this method can be used in one fluent return statement from an `HttpAuthenticationMechanism` Parameters path:String a String specifying the pathname to the resource. Returns:AuthenticationStatus `AuthenticationStatus#SEND_CONTINUE` See Also `RequestDispatcher#forward(jakarta.servlet.ServletRequest, jakarta.servlet.ServletResponse)`

public AuthenticationStatus forward(String path)

Forwards to another resource (Jakarta Servlet, Jakarta Server Pages file, or HTML file) on the server.

As a convenience this method returns SEND_CONTINUE, so this method can be used in one fluent return statement from an HttpAuthenticationMechanism

Parameters

path:String: a String specifying the pathname to the resource.

Returns:AuthenticationStatus

AuthenticationStatus#SEND_CONTINUE

getAuthParameters	back to summary
public AuthenticationParameters getAuthParameters() Returns the parameters that were provided with the SecurityContext#authenticate(AuthParameters) call. Returns:AuthenticationParameters the parameters that were provided with the SecurityContext#authenticate(AuthParameters) call, or a default instance. Never null.

getAuthParameters

back to summary

public AuthenticationParameters getAuthParameters()

Returns the parameters that were provided with the SecurityContext#authenticate(AuthParameters) call.

Returns:AuthenticationParameters: the parameters that were provided with the SecurityContext#authenticate(AuthParameters) call, or a default instance. Never null.

getCallerPrincipal	back to summary
public Principal getCallerPrincipal() Gets the Principal set by a call to notifyContainerAboutLogin(). Returns:Principal The caller principal

getCallerPrincipal

back to summary

public Principal getCallerPrincipal()

Gets the Principal set by a call to notifyContainerAboutLogin().

Returns:Principal: The caller principal

getClientSubject	back to summary
public Subject getClientSubject() Returns the subject for which authentication is to take place. Note This is a low level object that most higher level code would not need to use directly. Returns:Subject the subject for which authentication is to take place.

getClientSubject

back to summary

public Subject getClientSubject()

Returns the subject for which authentication is to take place.

Note

This is a low level object that most higher level code would not need to use directly.

Returns:Subject: the subject for which authentication is to take place.

getGroups	back to summary
public Set<String> getGroups() Gets the groups set by a call to notifyContainerAboutLogin(). Returns:Set<String> The groups

getGroups

back to summary

public Set<String> getGroups()

Gets the groups set by a call to notifyContainerAboutLogin().

Returns:Set<String>: The groups

getHandler back to summary

getHandler	back to summary
public CallbackHandler getHandler() Returns the low level Jakarta Authentication handler that the runtime provided when creating this `HttpMessageContext`, and which this context uses to communicate the authentication details to the runtime. Note This is a low level object that most higher level code would not need to use directly. Returns:CallbackHandler the handler that the runtime provided to this context

public CallbackHandler getHandler()

Returns the low level Jakarta Authentication handler that the runtime provided when creating this HttpMessageContext, and which this context uses to communicate the authentication details to the runtime.

Note

This is a low level object that most higher level code would not need to use directly.

Returns:CallbackHandler: the handler that the runtime provided to this context

getMessageInfo	back to summary
public MessageInfo getMessageInfo() Returns the the low level Jakarta Authentication message info instance for the current request. Note This is a low level object that most higher level code would not need to use directly. Returns:MessageInfo the message info instance for the current request.

getMessageInfo

back to summary

public MessageInfo getMessageInfo()

Returns the the low level Jakarta Authentication message info instance for the current request.

Note

This is a low level object that most higher level code would not need to use directly.

Returns:MessageInfo: the message info instance for the current request.

getRequest	back to summary
public HttpServletRequest getRequest() Returns the request object associated with the current request. Returns:HttpServletRequest the request object associated with the current request.

getRequest

back to summary

public HttpServletRequest getRequest()

Returns the request object associated with the current request.

Returns:HttpServletRequest: the request object associated with the current request.

getResponse	back to summary
public HttpServletResponse getResponse() Returns the response object associated with the current request. Returns:HttpServletResponse the response object associated with the current request.

getResponse

back to summary

public HttpServletResponse getResponse()

Returns the response object associated with the current request.

Returns:HttpServletResponse: the response object associated with the current request.

isAuthenticationRequest back to summary

isAuthenticationRequest	back to summary
public boolean isAuthenticationRequest() Checks if the current call to an authentication mechanism is the result from the application calling `SecurityContext#authenticate(HttpServletRequest, HttpServletResponse, AuthenticationParameters)` If SecurityContext#authenticate was not called, the authentication mechanism may have been invoked by the container at the start of a request. Returns:boolean true if SecurityContext#authenticate was called, false if not.

public boolean isAuthenticationRequest()

Checks if the current call to an authentication mechanism is the result from the application calling SecurityContext#authenticate(HttpServletRequest, HttpServletResponse, AuthenticationParameters)

If SecurityContext#authenticate was not called, the authentication mechanism may have been invoked by the container at the start of a request.

Returns:boolean: true if SecurityContext#authenticate was called, false if not.

isProtected back to summary

isProtected	back to summary
public boolean isProtected() Checks if the currently requested resource is protected or not. A protected resource is a resource (e.g. a Jakarta Servlet, Jakarta Faces page, Jakarta Server Pages page etc) for which a constraint has been defined in e.g. `web.xml`. Returns:boolean true if a protected resource was requested, false if a public resource was requested.

public boolean isProtected()

Checks if the currently requested resource is protected or not. A protected resource is a resource (e.g. a Jakarta Servlet, Jakarta Faces page, Jakarta Server Pages page etc) for which a constraint has been defined in e.g. web.xml.

Returns:boolean: true if a protected resource was requested, false if a public resource was requested.

isRegisterSession	back to summary
public boolean isRegisterSession() Check if the runtime has been asked to register an authentication session duing the current request. Returns:boolean true if code has asked to register an authentication session, false otherwise.

isRegisterSession

back to summary

public boolean isRegisterSession()

Check if the runtime has been asked to register an authentication session duing the current request.

Returns:boolean: true if code has asked to register an authentication session, false otherwise.

notifyContainerAboutLogin back to summary

notifyContainerAboutLogin	back to summary
public AuthenticationStatus notifyContainerAboutLogin(String callername, Set<String> groups) Asks the container to register the given caller name and groups in order to make them available to the application for use with `SecurityContext#isCallerInRole(String)` etc. Note that after this call returned, the authenticated identity will not be immediately active. This will only take place (should no errors occur) after the authentication mechanism in which this call takes place returns control back to the container (runtime). As a convenience this method returns SUCCESS, so this method can be used in one fluent return statement from an `HttpAuthenticationMechanism` Parameters callername:String the caller name that will become the caller principal groups:Set<String> the groups associated with the caller principal Returns:AuthenticationStatus `AuthenticationStatus#SUCCESS`

public AuthenticationStatus notifyContainerAboutLogin(String callername, Set<String> groups)

Asks the container to register the given caller name and groups in order to make them available to the application for use with SecurityContext#isCallerInRole(String) etc.

Note that after this call returned, the authenticated identity will not be immediately active. This will only take place (should no errors occur) after the authentication mechanism in which this call takes place returns control back to the container (runtime).

As a convenience this method returns SUCCESS, so this method can be used in one fluent return statement from an HttpAuthenticationMechanism

Parameters

callername:String: the caller name that will become the caller principal
groups:Set<String>: the groups associated with the caller principal

Returns:AuthenticationStatus

AuthenticationStatus#SUCCESS

notifyContainerAboutLogin back to summary

notifyContainerAboutLogin	back to summary
public AuthenticationStatus notifyContainerAboutLogin(Principal principal, Set<String> groups) Asks the container to register the given caller principal and groups in order to make them available to the application for use with `SecurityContext#isCallerInRole(String)` etc. Note that this call may result in the container establishing two caller principals to represent the caller's identity -- the Principal provided here as the principal parameter, and a second principal used as the container's representation of the caller identity. A second principal is added only if the container uses a different Principal type to represent the caller. If the types are the same, only one Principal is added. If a second principal is added, the value returned by `Principal#getName()` will be the same for both principals. When two principals are added, the container's caller principal is returned from `SecurityContext#getCallerPrincipal()`, and the principal supplied here as a parameter can be retrieved using `SecurityContext#getPrincipalsByType(Class)`. When only one is added, it is returned by `SecurityContext#getCallerPrincipal()`. Note that after this call returned, the authenticated identity will not be immediately active. This will only take place (should no errors occur) after the authentication mechanism in which this call takes place returns control back to the container (runtime). As a convenience this method returns SUCCESS, so this method can be used in one fluent return statement from an `HttpAuthenticationMechanism` Parameters principal:Principal the Principal that will become the caller principal groups:Set<String> the groups associated with the caller principal Returns:AuthenticationStatus `AuthenticationStatus#SUCCESS`

public AuthenticationStatus notifyContainerAboutLogin(Principal principal, Set<String> groups)

Asks the container to register the given caller principal and groups in order to make them available to the application for use with SecurityContext#isCallerInRole(String) etc.

Note that this call may result in the container establishing two caller principals to represent the caller's identity -- the Principal provided here as the principal parameter, and a second principal used as the container's representation of the caller identity. A second principal is added only if the container uses a different Principal type to represent the caller. If the types are the same, only one Principal is added.

If a second principal is added, the value returned by Principal#getName() will be the same for both principals.

When two principals are added, the container's caller principal is returned from SecurityContext#getCallerPrincipal(), and the principal supplied here as a parameter can be retrieved using SecurityContext#getPrincipalsByType(Class). When only one is added, it is returned by SecurityContext#getCallerPrincipal().

As a convenience this method returns SUCCESS, so this method can be used in one fluent return statement from an HttpAuthenticationMechanism

Parameters

principal:Principal: the Principal that will become the caller principal
groups:Set<String>: the groups associated with the caller principal

Returns:AuthenticationStatus

AuthenticationStatus#SUCCESS

notifyContainerAboutLogin back to summary

notifyContainerAboutLogin	back to summary
public AuthenticationStatus notifyContainerAboutLogin(CredentialValidationResult result) Convenience method intended to pass the `CredentialValidationResult` result of an identity store directly on to the container. If the outcome from the given `CredentialValidationResult#getStatus()` equals `Status#VALID`, the `CallerPrincipal` and groups are obtained from the `CredentialValidationResult` and passed into `HttpMessageContext#notifyContainerAboutLogin(Principal, Set)`. If the outcome from the given `CredentialValidationResult#getStatus()` is not equal to `Status#VALID` a failure result is returned. Parameters result:CredentialValidationResult a CredentialValidationResult which is inspected for its status and from which the principal and groups are taken. Returns:AuthenticationStatus `AuthenticationStatus#SUCCESS` if `CredentialValidationResult#getStatus()` equals `Status#VALID` otherwise `AuthenticationStatus#SEND_FAILURE`

public AuthenticationStatus notifyContainerAboutLogin(CredentialValidationResult result)

Convenience method intended to pass the CredentialValidationResult result of an identity store directly on to the container.

If the outcome from the given CredentialValidationResult#getStatus() equals Status#VALID, the CallerPrincipal and groups are obtained from the CredentialValidationResult and passed into HttpMessageContext#notifyContainerAboutLogin(Principal, Set).

If the outcome from the given CredentialValidationResult#getStatus() is not equal to Status#VALID a failure result is returned.

Parameters

result:CredentialValidationResult: a CredentialValidationResult which is inspected for its status and from which the principal and groups are taken.

Returns:AuthenticationStatus

AuthenticationStatus#SUCCESS if CredentialValidationResult#getStatus() equals Status#VALID otherwise AuthenticationStatus#SEND_FAILURE

redirect back to summary

redirect	back to summary
public AuthenticationStatus redirect(String location) Sets the response status to SC_FOUND 302 (Found) As a convenience this method returns SEND_CONTINUE, so this method can be used in one fluent return statement from an `HttpAuthenticationMechanism` Parameters location:String the location to redirect to Returns:AuthenticationStatus `AuthenticationStatus#SEND_CONTINUE` See Also `HttpServletResponse#sendRedirect(String)`

public AuthenticationStatus redirect(String location)

Sets the response status to SC_FOUND 302 (Found)

As a convenience this method returns SEND_CONTINUE, so this method can be used in one fluent return statement from an HttpAuthenticationMechanism

Parameters

location:String: the location to redirect to

Returns:AuthenticationStatus

AuthenticationStatus#SEND_CONTINUE

responseNotFound back to summary

responseNotFound	back to summary
public AuthenticationStatus responseNotFound() Sets the response status to 404 (not found). As a convenience this method returns SEND_FAILURE, so this method can be used in one fluent return statement from an `HttpAuthenticationMechanism` Returns:AuthenticationStatus `AuthenticationStatus#SEND_FAILURE`

public AuthenticationStatus responseNotFound()

Sets the response status to 404 (not found).

As a convenience this method returns SEND_FAILURE, so this method can be used in one fluent return statement from an HttpAuthenticationMechanism

Returns:AuthenticationStatus: AuthenticationStatus#SEND_FAILURE

responseUnauthorized back to summary

responseUnauthorized	back to summary
public AuthenticationStatus responseUnauthorized() Sets the response status to 401 (unauthorized). As a convenience this method returns SEND_FAILURE, so this method can be used in one fluent return statement from an `HttpAuthenticationMechanism` Returns:AuthenticationStatus `AuthenticationStatus#SEND_FAILURE`

public AuthenticationStatus responseUnauthorized()

Sets the response status to 401 (unauthorized).

As a convenience this method returns SEND_FAILURE, so this method can be used in one fluent return statement from an HttpAuthenticationMechanism

Returns:AuthenticationStatus: AuthenticationStatus#SEND_FAILURE

setRegisterSession back to summary

setRegisterSession	back to summary
public void setRegisterSession(String callerName, Set<String> groups) Asks the runtime to register an authentication session. This will automatically remember the logged-in status as long as the current HTTP session remains valid. Without this being asked, a `HttpAuthenticationMechanism` has to manually re-authenticate with the runtime at the start of each request. Parameters callerName:String the caller name for which authentication should be be remembered groups:Set<String> the groups for which authentication should be remembered.

public void setRegisterSession(String callerName, Set<String> groups)

Asks the runtime to register an authentication session. This will automatically remember the logged-in status as long as the current HTTP session remains valid. Without this being asked, a HttpAuthenticationMechanism has to manually re-authenticate with the runtime at the start of each request.

Parameters

callerName:String: the caller name for which authentication should be be remembered
groups:Set<String>: the groups for which authentication should be remembered.

setRequest	back to summary
public void setRequest(HttpServletRequest request) Sets the request object. Parameters request:HttpServletRequest the request object to be set

setRequest

back to summary

public void setRequest(HttpServletRequest request)

Sets the request object.

Parameters

request:HttpServletRequest: the request object to be set

setResponse	back to summary
public void setResponse(HttpServletResponse response) Set the response object. Parameters response:HttpServletResponse the response object to be set.

setResponse

back to summary

public void setResponse(HttpServletResponse response)

Set the response object.

Parameters

response:HttpServletResponse: the response object to be set.

withRequest	back to summary
public HttpMessageContext withRequest(HttpServletRequest request) Sets the request object. Parameters request:HttpServletRequest the request object to be set. Returns:HttpMessageContext the HttpMessageContext instance on which this method was called, useful for fluent style call call chains.

withRequest

back to summary

public HttpMessageContext withRequest(HttpServletRequest request)

Sets the request object.

Parameters

request:HttpServletRequest: the request object to be set.

Returns:HttpMessageContext

the HttpMessageContext instance on which this method was called, useful for fluent style call call chains.

public Interface HttpMessageContext

Method Summary

Method Detail