- java.lang.Object
-
- jakarta.security.jacc.PolicyContext
-
public final class PolicyContext extends java.lang.Object
This utility class is used by containers to communicate policy context identifiers and other policy relevant context toPolicy
providers.Policy
providers use the policy context identifier to select the subset of policy to apply in access decisions.The value of a policy context identifier is a
String
and each thread has an independently established policy context identifier. A container will establish the thread-scoped value of a policy context identifier by calling the staticsetContextID
method. The value of a thread-scoped policy context identifier is available (toPolicy
) by calling the staticgetContextID
method.This class is also used by
Policy
providers to request additional thread-scoped policy relevant context objects from the calling container. Containers register container-specificPolicyContext
handlers using the staticregisterHandler
method. Handler registration is scoped to the class, such that the same handler registrations are active in all thread contexts. Containers may use the static methodsetHandlerData
to establish a thread-scoped parameter that will be passed to handlers when they are activated byPolicy
providers. The staticgetContext
method is used to activate a handler and obtain the corresponding context object.The static accessor functions provided by this class allow per-thread policy context values to be established and communicated independent of a common reference to a particular PolicyContext instance.
The PolicyContext class may encapsulate static ThreadLocal instance variables to represent the policy context identifier and handler data values.
- See Also:
PolicyContextHandler
-
-
Field Summary
Fields Modifier and Type Field Description private static java.util.Map<java.lang.String,PolicyContextHandler>
handlerTable
This static instance variable contains the mapping of container registeredPolicyContextHandler
objects with the keys that identify the context objects returned by the handlers.static java.lang.String
HTTP_SERVLET_REQUEST
Key to use for getting an `jakarta.servlet.http.HttpServletRequest` fromgetContext(String)
When this handler is activated, the container must return the `HttpServletRequest` object corresponding to the component request being processed by the container.static java.lang.String
PRINCIPAL_MAPPER
Key to use for getting a `jakarta.security.jacc.PrincipalMapper` fromgetContext(String)
static java.lang.String
SOAP_MESSAGE
Key to use for getting an `jakarta.xml.soap.SOAPMessage` fromgetContext(String)
If the request being processed by the container arrived as a SOAP request at the `ServiceEndpoint` method interface, the container must return the SOAP message object when this handler is activated.static java.lang.String
SUBJECT
Key to use for getting a `javax.security.auth.Subject` fromgetContext(String)
When this handler is activated as the result of a policy decision performed by a container before dispatch into a component, this handler must return a `Subject` containing the principals and credentials of the “caller” of the component.private static java.lang.ThreadLocal<java.lang.String>
threadLocalContextID
This static instance variable contains the policy context identifier value.private static java.lang.ThreadLocal<java.lang.Object>
threadLocalHandlerData
This static instance variable contains the handler parameter data object.
-
Constructor Summary
Constructors Modifier Constructor Description private
PolicyContext()
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static <T> T
get(java.lang.String key)
This method may be used by aPolicy
provider to activate thePolicyContextHandler
registered to the context object key and cause it to return the corresponding policy context object from the container.static <T> T
getContext(java.lang.String key)
This method may be used by aPolicy
provider to activate thePolicyContextHandler
registered to the context object key and cause it to return the corresponding policy context object from the container.static java.lang.String
getContextID()
This static method returns the value of the policy context identifier associated with the thread on which the accessor is called.static java.util.Set<java.lang.String>
getHandlerKeys()
This method may be used to obtain the keys that identify the container specific context handlers registered by the container.static void
registerHandler(java.lang.String key, PolicyContextHandler handler, boolean replace)
Method used to register a container specificPolicyContext
handler.static void
setContextID(java.lang.String contextID)
Method used to modify the value of the policy context identifier associated with the thread on which this method is called.static void
setHandlerData(java.lang.Object data)
Method that may be used to associate a thread-scoped handler data object with the PolicyContext.
-
-
-
Field Detail
-
SUBJECT
public static final java.lang.String SUBJECT
Key to use for getting a `javax.security.auth.Subject` fromgetContext(String)
When this handler is activated as the result of a policy decision performed by a container before dispatch into a component, this handler must return a `Subject` containing the principals and credentials of the “caller” of the component. When activated from the scope of a dispatched call, this handler must return a `Subject` containing the principals and credentials corresponding to the identity established by the container prior to the activation of the handler. The identity established by the container will either be the component’s `runAs` identity or the caller’s identity (e.g. when a Jakarta Enterprise Beans component calls `isCallerInRole`). In all cases, if the identity of the corresponding `Subject` has not been established or authenticated, this handler must return the value null.- See Also:
- Constant Field Values
-
PRINCIPAL_MAPPER
public static final java.lang.String PRINCIPAL_MAPPER
Key to use for getting a `jakarta.security.jacc.PrincipalMapper` fromgetContext(String)
- See Also:
- Constant Field Values
-
HTTP_SERVLET_REQUEST
public static final java.lang.String HTTP_SERVLET_REQUEST
Key to use for getting an `jakarta.servlet.http.HttpServletRequest` fromgetContext(String)
When this handler is activated, the container must return the `HttpServletRequest` object corresponding to the component request being processed by the container.- See Also:
- Constant Field Values
-
SOAP_MESSAGE
public static final java.lang.String SOAP_MESSAGE
Key to use for getting an `jakarta.xml.soap.SOAPMessage` fromgetContext(String)
If the request being processed by the container arrived as a SOAP request at the `ServiceEndpoint` method interface, the container must return the SOAP message object when this handler is activated. Otherwise, this handler must return the value- See Also:
- Constant Field Values
-
threadLocalContextID
private static java.lang.ThreadLocal<java.lang.String> threadLocalContextID
This static instance variable contains the policy context identifier value. It's initial value is null.
-
threadLocalHandlerData
private static java.lang.ThreadLocal<java.lang.Object> threadLocalHandlerData
This static instance variable contains the handler parameter data object. It's initial value is null.
-
handlerTable
private static java.util.Map<java.lang.String,PolicyContextHandler> handlerTable
This static instance variable contains the mapping of container registeredPolicyContextHandler
objects with the keys that identify the context objects returned by the handlers.
-
-
Method Detail
-
setContextID
public static void setContextID(java.lang.String contextID)
Method used to modify the value of the policy context identifier associated with the thread on which this method is called.- Parameters:
contextID
- aString
that represents the value of the policy context identifier to be assigned to the PolicyContext for the calling thread. The valuenull
is a legitimate value for this parameter.
-
getContextID
public static java.lang.String getContextID()
This static method returns the value of the policy context identifier associated with the thread on which the accessor is called.- Returns:
- The
String
(ornull
) policy context identifier established for the thread. This method must return the default policy context identifier,null
, if the policy context identifier of the thread has not been set viasetContext
to another value. - Throws:
java.lang.SecurityException
- if the calling AccessControlContext is not authorized by the container to call this method. Containers may choose to authorize calls to this method by any AccessControlContext.
-
setHandlerData
public static void setHandlerData(java.lang.Object data)
Method that may be used to associate a thread-scoped handler data object with the PolicyContext. The handler data object will be made available to handlers, where it can serve to supply or bind the handler to invocation scoped state within the container.- Parameters:
data
- a container-specific object that will be associated with the calling thread and passed to any handler activated by aPolicy
provider (on the thread). The valuenull
is a legitimate value for this parameter, and is the value that will be used in the activation of handlers if thesetHandlerData
has not been called on the thread.
-
registerHandler
public static void registerHandler(java.lang.String key, PolicyContextHandler handler, boolean replace) throws PolicyContextException
Method used to register a container specificPolicyContext
handler. A handler may be registered to handle multiple keys, but at any time, at most one handler may be registered for a key.- Parameters:
key
- a (case-sensitive)String
that identifies the context object handled by the handler. The value of this parameter must not be null.handler
- an object that implements thePolicyContextHandler
interface. The value of this parameter must not be null.replace
- this boolean value defines the behavior of this method if, when it is called, aPolicyContextHandler
has already been registered to handle the same key. In that case, and if the value of this argument istrue
, the existing handler is replaced with the argument handler. If the value of this parameter is false the existing registration is preserved and an exception is thrown.- Throws:
java.lang.IllegalArgumentException
- if the value of either of the handler or key arguments is null, or the value of the replace argument isfalse
and a handler with the same key as the argument handler is already registered.PolicyContextException
- if an operation by this method on the argument PolicyContextHandler causes it to throw a checked exception that is not accounted for in the signature of this method.
-
getHandlerKeys
public static java.util.Set<java.lang.String> getHandlerKeys()
This method may be used to obtain the keys that identify the container specific context handlers registered by the container.- Returns:
- A
Set
, the elements of which, are theString
key values that identify the handlers that have been registered and therefore may be activated on thePolicyContext
. - Throws:
java.lang.SecurityException
- if the calling AccessControlContext is not authorized by the container to call this method. Containers may choose to authorize calls to this method by any AccessControlContext.
-
getContext
public static <T> T getContext(java.lang.String key) throws PolicyContextException
This method may be used by aPolicy
provider to activate thePolicyContextHandler
registered to the context object key and cause it to return the corresponding policy context object from the container. When this method activates a handler, it passes to the handler the context object key and the handler data associated with the calling thread.- Parameters:
key
- aString
that identifies thePolicyContextHandler
to activate and the context object to be acquired from the handler. The value of this parameter must not be null.- Returns:
- the container and handler specific object containing the desired context. A
null
value is returned if the corresponding handler has been registered, and the value of the corresponding context is null. - Throws:
java.lang.IllegalArgumentException
- if aPolicyContextHandler
has not been registered for the key or the registered handler no longer supports the key.PolicyContextException
- if an operation by this method on the identified PolicyContextHandler causes it to throw a checked exception that is not accounted for in the signature of this method.
-
get
public static <T> T get(java.lang.String key)
This method may be used by aPolicy
provider to activate thePolicyContextHandler
registered to the context object key and cause it to return the corresponding policy context object from the container. When this method activates a handler, it passes to the handler the context object key and the handler data associated with the calling thread.- Parameters:
key
- aString
that identifies thePolicyContextHandler
to activate and the context object to be acquired from the handler. The value of this parameter must not be null.- Returns:
- the container and handler specific object containing the desired context. A
null
value is returned if the corresponding handler has been registered, and the value of the corresponding context is null. - Throws:
java.lang.IllegalArgumentException
- if aPolicyContextHandler
has not been registered for the key or the registered handler no longer supports the key.java.lang.IllegalStateException
- if an operation by this method on the identified PolicyContextHandler causes it to throw a checked exception that is not accounted for in the signature of this method. The IllegalStateException may contain a PolicyContextException containing the actual cause.
-
-