Top Description Fields Constructors Methods
jakarta.security.jacc

public final Class PolicyContext

extends Object
Class Inheritance
Imports
java.security.SecurityPermission, java.util.Map, .Set, java.util.concurrent.ConcurrentHashMap
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.

Authors
Ron Monzillo, Gary Ellison
See Also
PolicyContextHandler

Field Summary

Modifier and TypeField and Description
private static Map<String, PolicyContextHandler>
handlerTable

This static instance variable contains the mapping of container registered PolicyContextHandler objects with the keys that identify the context objects returned by the handlers.

private static ThreadLocal<String>
threadLocalContextID

This static instance variable contains the policy context identifier value.

private static ThreadLocal<Object>
threadLocalHandlerData

This static instance variable contains the handler parameter data object.

Constructor Summary

AccessConstructor and Description
private
PolicyContext()

Method Summary

Modifier and TypeMethod and Description
private static void
checkSetPolicyPermission()

public static <T> T

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.
getContext(String
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.
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.

public static String

Returns:

The 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.
getContextID()

This static method returns the value of the policy context identifier associated with the thread on which the accessor is called.

public static Set<E>

Returns:

A 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.
getHandlerKeys()

This method may be used to obtain the keys that identify the container specific context handlers registered by the container.

public static void
registerHandler(String
a (case-sensitive) String that identifies the context object handled by the handler. The value of this parameter must not be null.
key, PolicyContextHandler
an object that implements the PolicyContextHandler interface. The value of this parameter must not be null.
handler, boolean
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.
replace)

Authorization protected method used to register a container specific PolicyContext handler.

public static void
setContextID(String
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.
contextID)

Authorization protected method used to modify the value of the policy context identifier associated with the thread on which this method is called.

public static void
setHandlerData(Object
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.
data)

Authorization protected method that may be used to associate a thread-scoped handler data object with the PolicyContext.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

handlerTableback to summary
private static Map<String, PolicyContextHandler> handlerTable

This static instance variable contains the mapping of container registered PolicyContextHandler objects with the keys that identify the context objects returned by the handlers.

threadLocalContextIDback to summary
private static ThreadLocal<String> threadLocalContextID

This static instance variable contains the policy context identifier value. It's initial value is null.

threadLocalHandlerDataback to summary
private static ThreadLocal<Object> threadLocalHandlerData

This static instance variable contains the handler parameter data object. It's initial value is null.

Constructor Detail

PolicyContextback to summary
private PolicyContext()

Method Detail

checkSetPolicyPermissionback to summary
private static void checkSetPolicyPermission()
getContextback to summary
public static <T> T 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.

Parameters
key:String

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.

Returns:T

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.

Exceptions
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.
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.
getContextIDback to summary
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.

Returns:String

The 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.

Exceptions
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.
getHandlerKeysback to summary
public static Set<E> getHandlerKeys()

This method may be used to obtain the keys that identify the container specific context handlers registered by the container.

Returns:Set<E>

A 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.

Exceptions
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.
registerHandlerback to summary
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.

Parameters
key:String

a (case-sensitive) String that identifies the context object handled by the handler. The value of this parameter must not be null.

handler:PolicyContextHandler

an object that implements the PolicyContextHandler interface. The value of this parameter must not be null.

replace:boolean

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.

Exceptions
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.
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.
setContextIDback to summary
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.

Parameters
contextID:String

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.

Exceptions
SecurityException:
if the calling AccessControlContext is not authorized by the container to call this method.
setHandlerDataback to summary
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.

Parameters
data:Object

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.

Exceptions
SecurityException:
if the calling AccessControlContext is not authorized by the container to call this method.