public final class PolicyContext extends Object
This utility class is used by containers to communicate policy context identifiers and other policy relevant context
to Policy
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
static setContextID
method. The value of a thread-scoped policy context identifier is available (to Policy
) by calling the static getContextID
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-specific PolicyContext
handlers using the
static registerHandler
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 method setHandlerData
to
establish a thread-scoped parameter that will be passed to handlers when they are activated by Policy
providers. The static getContext
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.
The Application server must bundle or install the PolicyContext
class, and the containers of the application
server must prevent the methods of the PolicyContext
class from being called from calling contexts that are
not authorized to call these methods. With the exception of the getContextID
and getHandlerKeys
methods, containers must restrict and afford access to the methods of the PolicyContext
class to calling
contexts trusted by the container to perform container access decisions. The PolicyContext
class may satisfy
this requirement (on behalf of its container) by rejecting calls made from an AccessControlContext
that has
not been granted the "setPolicy" SecurityPermission, and by ensuring that Policy
providers used to perform
container access decisions are granted the "setPolicy" permission.
PolicyContextHandler
Modifier and Type | Method and Description |
---|---|
static Object |
getContext(String key)
This method may be used by a
Policy provider to activate the PolicyContextHandler registered to
the context object key and cause it to return the corresponding policy context object from the container. |
static String |
getContextID()
This static method returns the value of the policy context identifier associated with the thread on which the
accessor is called.
|
static Set |
getHandlerKeys()
This method may be used to obtain the keys that identify the container specific context handlers registered by the
container.
|
static void |
registerHandler(String key,
PolicyContextHandler handler,
boolean replace)
Authorization protected method used to register a container specific
PolicyContext handler. |
static void |
setContextID(String contextID)
Authorization protected method used to modify the value of the policy context identifier associated with the
thread on which this method is called.
|
static void |
setHandlerData(Object data)
Authorization protected method that may be used to associate a thread-scoped handler data object with the
PolicyContext.
|
public static Object getContext(String key) throws PolicyContextException
This method may be used by a Policy
provider to activate the PolicyContextHandler
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.
key
- - a String
that identifies the PolicyContextHandler to activate and the context object to be
acquired from the handler. The value of this parameter must not be null.null
value is returned
if the corresponding handler has been registered, and the value of the corresponding context is null.IllegalArgumentException
- - if a PolicyContextHandler
has not been registered for the key or the registered handler no
longer supports the key.SecurityException
- - if the calling AccessControlContext
is not authorized by the container to call this method.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.public static String getContextID()
This static method returns the value of the policy context identifier associated with the thread on which the accessor is called.
String
(or null
) 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 via setContext
to another value.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
.public static Set getHandlerKeys()
This method may be used to obtain the keys that identify the container specific context handlers registered by the container.
Set
, the elements of which, are the String
key values that identify the handlers that
have been registered and therefore may be activated on the PolicyContext
.SecurityException
- - if the calling AccessControlContext
is not authorized by the container to call this method.
Containers may choose to authorize calls to this methods by any AccessControlContext
.public static void registerHandler(String key, PolicyContextHandler handler, boolean replace) throws PolicyContextException
Authorization protected method used to register a container specific PolicyContext
handler. A handler may
be registered to handle multiple keys, but at any time, at most one handler may be registered for a key.
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 the PolicyContextHandler
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, a PolicyContextHandler
has already been registered to handle the same key. In that case, and if the value
of this argument is true
, 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.IllegalArgumentException
- - if the value of either of the handler or key arguments is null, or the value of the replace argument
is false and a handler with the same key as the argument handler is already registered.SecurityException
- - if the calling AccessControlContext
is not authorized by the container to call this method.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.public static void setContextID(String contextID)
Authorization protected method used to modify the value of the policy context identifier associated with the thread on which this method is called.
contextID
- - a String
that represents the value of the policy context identifier to be assigned to the
PolicyContext
for the calling thread. The value null is a legitimate value for this parameter.SecurityException
- - if the calling AccessControlContext
is not authorized by the container to call this method.public static void setHandlerData(Object data)
Authorization protected 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.
data
- - a container-specific object that will be associated with the calling thread and passed to any handler
activated by a Policy
provider (on the thread). The value null is a legitimate value for this
parameter, and is the value that will be used in the activation of handlers if the setHandlerData
has not been called on the thread.SecurityException
- - if the calling AccessControlContext
is not authorized by the container to call this method.Copyright © 2016 JBoss by Red Hat. All rights reserved.