HttpMessageContext (Java EE Security API 1.0-b11 API)

All Known Implementing Classes:

HttpMessageContextWrapper
```
public interface HttpMessageContext
```
HttpMessageContext contains all of the per-request state information and encapsulates the client request, server response, container handler for authentication callbacks, and the subject representing the caller.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`void`	`cleanClientSubject()` Convenience method to clean the subject associated with this context.
`AuthenticationStatus`	`doNothing()` Instructs the container to "do nothing".
`AuthenticationStatus`	`forward(String path)` Forwards to another resource (servlet, JSP file, or HTML file) on the server.
`AuthenticationParameters`	`getAuthParameters()` Returns the parameters that were provided with the SecurityContext#authenticate(AuthParameters) call.
`Principal`	`getCallerPrincipal()` Gets the Principal set by a call to notifyContainerAboutLogin().
`Subject`	`getClientSubject()` Returns the subject for which authentication is to take place.
`Set<String>`	`getGroups()` Gets the groups set by a call to notifyContainerAboutLogin().
`CallbackHandler`	`getHandler()` Returns the low level JSR 196 handler that the runtime provided when creating this `HttpMessageContext`, and which this context uses to communicate the authentication details to the runtime.
`MessageInfo`	`getMessageInfo()` Returns the the low level JSR 196 message info instance for the current request.
`HttpServletRequest`	`getRequest()` Returns the request object associated with the current request.
`HttpServletResponse`	`getResponse()` Returns the response object associated with the current request.
`boolean`	`isAuthenticationRequest()` Checks if the current call to an authentication mechanism is the result from the application calling `SecurityContext.authenticate(HttpServletRequest, HttpServletResponse, AuthenticationParameters)`
`boolean`	`isProtected()` Checks if the currently requested resource is protected or not.
`boolean`	`isRegisterSession()` Check if the runtime has been asked to register an authentication session duing the current request.
`AuthenticationStatus`	`notifyContainerAboutLogin(CredentialValidationResult result)` Convenience method intended to pass the `CredentialValidationResult` result of an identity store directly on to the container.
`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.
`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.
`AuthenticationStatus`	`redirect(String location)` Sets the response status to SC_FOUND 302 (Found)
`AuthenticationStatus`	`responseNotFound()` Sets the response status to 404 (not found).
`AuthenticationStatus`	`responseUnauthorized()` Sets the response status to 401 (unauthorized).
`void`	`setRegisterSession(String callerName, Set<String> groups)` Asks the runtime to register an authentication session.
`void`	`setRequest(HttpServletRequest request)` Sets the request object.
`void`	`setResponse(HttpServletResponse response)` Set the response object.
`HttpMessageContext`	`withRequest(HttpServletRequest request)` Sets the request object.

- Method Detail
  - isProtected
```
boolean isProtected()
```
    Checks if the currently requested resource is protected or not. A protected resource is a resource (e.g. a Servlet, JSF page, JSP page etc) for which a constraint has been defined in e.g. web.xml.
    
    Returns:
    
    true if a protected resource was requested, false if a public resource was requested.
  - isAuthenticationRequest
```
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:
    
    true if SecurityContext#authenticate was called, false if not.
  - isRegisterSession
```
boolean isRegisterSession()
```
    Check if the runtime has been asked to register an authentication session duing the current request.
    
    Returns:
    
    true if code has asked to register an authentication session, false otherwise.
  - setRegisterSession
```
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 - the caller name for which authentication should be be remembered
    
    groups - the groups for which authentication should be remembered.
  - cleanClientSubject
```
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 JASPIC (JSR 196) for the ServerAuthModule#cleanSubject method and the HttpAuthenticationMechanism.cleanSubject(HttpServletRequest, HttpServletResponse, HttpMessageContext) method defined by this specification.
  - getAuthParameters
```
AuthenticationParameters getAuthParameters()
```
    Returns the parameters that were provided with the SecurityContext#authenticate(AuthParameters) call.
    
    Returns:
    
    the parameters that were provided with the SecurityContext#authenticate(AuthParameters) call, or a default instance. Never null.
  - getHandler
```
CallbackHandler getHandler()
```
    Returns the low level JSR 196 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:
    
    the handler that the runtime provided to this context
  - getMessageInfo
```
MessageInfo getMessageInfo()
```
    Returns the the low level JSR 196 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:
    
    the message info instance for the current request.
  - getClientSubject
```
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:
    
    the subject for which authentication is to take place.
  - getRequest
```
HttpServletRequest getRequest()
```
    Returns the request object associated with the current request.
    
    Returns:
    
    the request object associated with the current request.
  - setRequest
```
void setRequest(HttpServletRequest request)
```
    Sets the request object.
    
    Parameters:
    
    request - the request object to be set
  - withRequest
```
HttpMessageContext withRequest(HttpServletRequest request)
```
    Sets the request object.
    
    Parameters:
    
    request - the request object to be set.
    
    Returns:
    
    the HttpMessageContext instance on which this method was called, useful for fluent style call call chains.
  - getResponse
```
HttpServletResponse getResponse()
```
    Returns the response object associated with the current request.
    
    Returns:
    
    the response object associated with the current request.
  - setResponse
```
void setResponse(HttpServletResponse response)
```
    Set the response object.
    
    Parameters:
    
    response - the response object to be set.
  - redirect
```
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 - the location to redirect to
    
    Returns:
    
    AuthenticationStatus.SEND_CONTINUE
    
    See Also:
    
    HttpServletResponse.sendRedirect(String)
  - forward
```
AuthenticationStatus forward(String path)
```
    Forwards to another resource (servlet, JSP 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 - a String specifying the pathname to the resource.
    
    Returns:
    
    AuthenticationStatus.SEND_CONTINUE
    
    See Also:
    
    RequestDispatcher.forward(javax.servlet.ServletRequest, javax.servlet.ServletResponse)
  - responseUnauthorized
```
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.SEND_FAILURE
  - responseNotFound
```
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.SEND_FAILURE
  - notifyContainerAboutLogin
```
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 - the caller name that will become the caller principal
    
    groups - the groups associated with the caller principal
    
    Returns:
    
    AuthenticationStatus.SUCCESS
  - notifyContainerAboutLogin
```
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 - the Principal that will become the caller principal
    
    groups - the groups associated with the caller principal
    
    Returns:
    
    AuthenticationStatus.SUCCESS
  - notifyContainerAboutLogin
```
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 CredentialValidationResult.Status.VALID, the CallerPrincipal and groups are obtained from the CredentialValidationResult and passed into notifyContainerAboutLogin(Principal, Set).
    If the outcome from the given CredentialValidationResult.getStatus() is not equal to CredentialValidationResult.Status.VALID a failure result is returned.
    
    Parameters:
    
    result - a CredentialValidationResult which is inspected for its status and from which the principal and groups are taken.
    
    Returns:
    
    AuthenticationStatus.SUCCESS if CredentialValidationResult.getStatus() equals CredentialValidationResult.Status.VALID otherwise AuthenticationStatus.SEND_FAILURE
  - doNothing
```
AuthenticationStatus doNothing()
```
    Instructs the container to "do nothing".
    When intending to do nothing, a JSR 375 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.NOT_DONE
  - getCallerPrincipal
```
Principal getCallerPrincipal()
```
    Gets the Principal set by a call to notifyContainerAboutLogin().
    
    Returns:
    
    The caller principal
  - getGroups
```
Set<String> getGroups()
```
    Gets the groups set by a call to notifyContainerAboutLogin().
    
    Returns:
    
    The groups

Interface HttpMessageContext

Method Summary

Method Detail

isProtected

isAuthenticationRequest

isRegisterSession

setRegisterSession

cleanClientSubject

getAuthParameters

getHandler

getMessageInfo

getClientSubject

getRequest

setRequest

withRequest

getResponse

setResponse

redirect

forward

responseUnauthorized

responseNotFound

notifyContainerAboutLogin

notifyContainerAboutLogin

notifyContainerAboutLogin

doNothing

getCallerPrincipal

getGroups