PolicyContext (Java EE 5)

策略上下文标识符的值为 String，每个线程都有一个独立建立的策略上下文标识符。容器可以通过调用静态 setContextID 方法建立线程范围策略上下文标识符的值。通过调用静态 getContextID 方法，Policy 才能使用线程范围策略上下文标识符的值。

Policy 提供者还可以使用此类向调用容器请求额外的线程范围策略相关上下文对象。容器可使用静态 registerHandler 方法注册特定于容器的 PolicyContext 处理程序。处理程序注册仅限于在类范围中进行，所有线程上下文中相同的处理程序注册都处于活动状态。容器可以使用静态方法 setHandlerData 建立线程范围参数，Policy 提供者激活这些参数时会将其传递给处理程序。静态 getContext 方法用于激活处理程序并获取相应的上下文对象。

此类提供的静态存取函数允许对每个线程建立策略上下文值，并允许与其通信，而不依赖指向特定 PolicyContext 实例的公共引用。

PolicyContext 类可以封装静态 ThreadLocal 实例变量，以表示策略上下文标识符和处理程序数据值。

应用服务器必须捆绑或安装 PolicyContext 类，应用服务器容器必须防止通过未授权调用 PolicyContext 类方法的调用上下文调用这些方法。但是 getContextID 和 GetHandlerKeys 方法例外，容器必须限制并提供容器信任的调用上下文对 PolicyContext 类方法的访问，以执行容器访问决定。PolicyContext 类可以满足此要求（代表其容器），它将拒绝尚未授予 "setPolicy" SecurityPermission 的 AccessControlContext 所做的调用，并确保将 "setPolicy" 权限授予用于执行容器访问决定的 Policy 提供者。

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.

Author:

Ron Monzillo, Gary Ellison

See Also:

PolicyContextHandler

public static void setContextID(String contextID)
授权保护方法，用于修改与调用此方法的线程关联的策略上下文标识符的值。

contextID	一个 String，表示要分配给调用线程的 PolicyContext 的策略上下文标识符的值。值 null 是此参数的合法值。
Throws	SecurityException: 如果容器没有授权调用 AccessControlContext 调用此方法。

英文文档：

setContextID

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

Throws:

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

public static String getContextID()
此静态方法返回与调用此存取方法的线程关联的策略上下文标识符的值。

return	为线程建立的 String（或 null）策略上下文标识符。如果尚未通过 setContext 将线程的策略上下文标识符设置为其他值，则此方法必须返回默认的策略上下文标识符 null。
Throws	SecurityException: 如果容器没有授权调用 AccessControlContext 调用此方法。容器可以选择通过任何 AccessControlContext 授权调用此方法。

英文文档：

getContextID

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:

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.

Throws:

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 void setHandlerData(Object data)
授权保护方法，可用于将线程范围内的处理程序数据对象与 PolicyContext 关联。处理程序数据对象将可用于处理程序，它可以将处理程序提供给（或捆绑到）容器内的调用范围状态。

data	特定于容器的对象，它将与调用线程关联并被传递到 Policy 提供者激活的任何处理程序（在线程中）。值 null 对于此参数是合法值，如果在线程中尚未调用 setHandlerData，则还将在激活处理程序时使用该值。
Throws	SecurityException: 如果容器没有授权调用 AccessControlContext 调用此方法。

英文文档：

setHandlerData

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

Throws:

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

public static void registerHandler(String key, PolicyContextHandler handler, boolean replace) throws PolicyContextException
授权保护方法，可用于注册特定于容器的 PolicyContext 处理程序。可以注册一个处理程序来处理多个键，但任何时候最多只能注册一个处理程序来处理一个键。

key	标识处理程序处理的上下文对象的 String（区分大小写）。此参数的值不得为 null。
handler	实现 PolicyContextHandler 接口的对象。此参数的值不得为 null。
replace	此 boolean 值定义此方法的行为，即调用此方法时是否已经注册了 PolicyContextHandler 来处理相同的键。在这种情况下，如果此参数的值为 true，则用参数 handler 替换现有的处理程序。如果此参数的值为 false，则会保留现有注册并抛出异常。
Throws	IllegalArgumentException: 如果 handler 或 key 参数的值有一个为 null，或者 replace 参数的值为 false 且已经注册了与参数 handler 具有相同键的处理程序。
Throws	SecurityException: 如果容器没有授权调用 AccessControlContext 调用此方法。
Throws	PolicyContextException: 如果以 PolicyContextHandler 参数调用此方法的操作使其抛出此方法的签名未知的经过检查的异常。

英文文档：

registerHandler

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

Throws:

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 java.util.Set<E> getHandlerKeys()
此方法可用于获取标识容器注册的特定于容器的上下文处理程序的键。

return	一个 Set，其中的元素是 String 键值，用于标识已注册从而可能在 PolicyContext 中激活的处理程序。
Throws	SecurityException: 如果容器没有授权调用 AccessControlContext 调用此方法。容器可以选择通过任何 AccessControlContext 授权调用此方法。

英文文档：

getHandlerKeys

public static Set 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 the String key values that identify the handlers that have been registered and therefore may be activated on the PolicyContext.

Throws:

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 Object getContext(String key) throws PolicyContextException
Policy 提供者可以使用此方法激活向上下文对象键注册的 PolicyContextHandler，并使其返回容器中相应的策略上下文对象。当此方法激活处理程序时，它会将上下文对象键传递给处理程序以及与调用线程关联的处理程序数据。

key	一个 String，它标识要激活的 PolicyContextHandler 以及从处理程序中获取的上下文对象。此参数的值不得为 null。
return	包含所需上下文的特定于容器和处理程序的对象。如果已经注册了相应的处理程序，且相应上下文的值为 null，则返回 null 值。
Throws	IllegalArgumentException: 如果尚未注册 PolicyContextHandler 来处理键，或者已注册的处理程序不再支持该键。
Throws	SecurityException: 如果容器没有授权调用 AccessControlContext 调用此方法。
Throws	PolicyContextException: 如果对标识的 PolicyContextHandler 调用此方法的操作使其抛出此方法的签名未知的经过检查的异常。

英文文档：

getContext

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.

Parameters:

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.

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:

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.

Copyright 2007 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.