PolicyContext


1   /*
2    * The contents of this file are subject to the terms 
3    * of the Common Development and Distribution License 
4    * (the License).  You may not use this file except in
5    * compliance with the License.
6    * 
7    * You can obtain a copy of the license at 
8    * https://glassfish.dev.java.net/public/CDDLv1.0.html or
9    * glassfish/bootstrap/legal/CDDLv1.0.txt.
10   * See the License for the specific language governing 
11   * permissions and limitations under the License.
12   * 
13   * When distributing Covered Code, include this CDDL 
14   * Header Notice in each file and include the License file 
15   * at glassfish/bootstrap/legal/CDDLv1.0.txt.  
16   * If applicable, add the following below the CDDL Header, 
17   * with the fields enclosed by brackets [] replaced by
18   * you own identifying information: 
19   * "Portions Copyrighted [year] [name of copyright owner]"
20   * 
21   * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
22   */
23  
24  package javax.security.jacc;
25  
26  import java.util.Hashtable  ;
27  
28  import java.util.Set  ;
29  
30  import java.security.SecurityPermission  ;
31  
32  import javax.security.jacc.PolicyContextHandler  ;
33  
34  /**
35   * This utility class is used by containers to communicate policy context
36   * identifiers and other policy relevant context to <code>Policy</code> 
37   * providers. <code>Policy</code> providers use the policy context identifier
38   * to select the subset of policy to apply in access decisions.
39   * <P>
40   * The value of a policy context identifier is a <code>
41   * String</code> and each thread has an independently 
42   * established policy context identifier. 
43   * A container will establish the thread-scoped value
44   * of a policy context identifier by calling the static
45   * <code>setContextID</code> method. The value of a thread-scoped policy 
46   * context identifier is available (to <code>Policy</code>) by calling the
47   * static <code>getContextID</code> method.
48   * <P>
49   * This class is also used by <code>Policy</code> providers to 
50   * request additional
51   * thread-scoped policy relevant context objects from the calling container.
52   * Containers register container-specific <code>PolicyContext</code> handlers
53   * using the static <code>registerHandler</code> method.
54   * Handler registration is scoped to the class, such that the same handler
55   * registrations are active in all thread contexts. Containers may
56   * use the static method <code>setHandlerData</code> to
57   * establish a thread-scoped parameter that will be passed to handlers
58   * when they are activated by <code>Policy</code> providers. The 
59   * static <code>getContext</code> method is used to activate a 
60   * handler and obtain the corresponding context object.
61   * <P>
62   * The static accessor functions provided by this class 
63   * allow per-thread policy context values to be
64   * established and communicated independent of a common reference to a 
65   * particular PolicyContext instance. 
66   * <P> 
67   * The PolicyContext class may encapsulate
68   * static ThreadLocal instance variables to represent the policy context
69   * identifier and handler data values.
70   * <P>
71   * The Application server must bundle or install the PolicyContext class, and 
72   * the containers of the application server must prevent the methods of 
73   * the PolicyContext class from being called from calling contexts that are not 
74   * authorized to call these methods.
75   * With the exception of the getContextID and GetHandlerKeys methods, containers must
76   * restrict and afford access to the methods of the PolicyContext class to
77   * calling contexts trusted by the container to perform container access decisions.
78   * The PolicyContext class may satisfy this requirement (on behalf
79   * of its container) by rejecting calls made from an AccessControlContext that has not 
80   * been granted the "setPolicy" SecurityPermission, and by ensuring
81   * that Policy providers used to perform container access decisions 
82   * are granted the "setPolicy" permission.
83   *
84   * @see javax.security.jacc.PolicyContextHandler
85   *
86   * @author Ron Monzillo
87   * @author Gary Ellison
88   */
89  
90  public final class PolicyContext {
91  
92      private PolicyContext() {
93      }
94  
95      /** This static instance variable contains the policy context identifier
96       * value. It's initial value is null.
97       */
98  
99      private static ThreadLocal   thisContextID = new ThreadLocal  ();
100 
101     /** This static instance variable contains the handler parameter data
102      * object. It's initial value is null.
103      */
104 
105     private static ThreadLocal   thisHandlerData = new ThreadLocal  ();
106 
107     /** This static instance variable contains the mapping of container
108      * registered <code>PolicyContextHandler</code> objects with the 
109      * keys that identify the context objects returned by the handlers.
110      */
111 
112     private static Hashtable   handlerTable = new Hashtable  ();
113 
114     /** Authorization protected method used to modify the value of the 
115      * policy context identifier associated with the thread on which 
116      * this method is called.
117      * 
118      * @param contextID a <code>String</code> that represents
119      * the value of the policy context identifier to be assigned to the
120      * PolicyContext for the calling thread. The value <code>null
121      * </code> is a legitimate value for this parameter.
122      *
123      * @throws java.lang.SecurityException
124      * if the calling AccessControlContext is not authorized by the container
125      * to call this method.
126      */
127 
128     public static void setContextID(String   contextID)
129     {
130     java.lang.SecurityManager   sm = System.getSecurityManager();
131     if (sm != null) 
132         sm.checkPermission(new SecurityPermission  ("setPolicy"));
133      
134     thisContextID.set(contextID);
135     }
136 
137     /** This static method returns the value of the policy context identifier
138      * associated with the thread on which the accessor is called.
139      * 
140      * @return The <code>String</code> (or <code>null</code>) policy context 
141      * identifier established for the thread. This method must 
142      * return the default policy context 
143      * identifier, <code>null</code>, if the policy context
144      * identifier of the thread has not been set via <code>setContext</code>
145      * to another value.
146      *
147      * @throws java.lang.SecurityException
148      * if the calling AccessControlContext is not authorized by the container
149      * to call this method. Containers may choose to authorize calls to this
150      * method by any AccessControlContext.
151      */
152 
153     public static String   getContextID()
154     {
155     return (String  ) thisContextID.get();
156     }
157 
158     /** Authorization protected method that may be used to associate a 
159      * thread-scoped handler data object with the PolicyContext. 
160      * The handler data object will be made available to handlers, 
161      * where it can serve to supply or bind the handler to invocation
162      * scoped state within the container.
163      * 
164      * @param data a container-specific object that will be associated 
165      * with the calling thread and passed to any handler activated by a
166      * <code>Policy</code> provider (on the thread).
167      * The value <code>null</code> is a legitimate value for this parameter,
168      * and is the value that will be used in the activation of handlers
169      * if the <code>setHandlerData</code> has not been called on the thread.
170      *
171      * @throws java.lang.SecurityException
172      * if the calling AccessControlContext is not authorized by the container
173      * to call this method.
174      */
175 
176     public static void setHandlerData(Object   data)
177     {
178 
179     java.lang.SecurityManager   sm = System.getSecurityManager();
180     if (sm != null) 
181         sm.checkPermission(new SecurityPermission  ("setPolicy"));
182      
183     thisHandlerData.set(data);
184     }
185 
186     /** Authorization protected method used to register a container specific
187      * <code>PolicyContext</code> handler. A handler may be registered
188      * to handle multiple keys, but at any time, at most one handler may be
189      * registered for a key.
190      * 
191      * @param key a (case-sensitive) <code>String</code> that identifies
192      * the context object handled by the handler.
193      * The value of this parameter must not be null.
194      * @param handler an object that implements the 
195      * <code>PolicyContextHandler</code> interface. The value of
196      * this parameter must not be null.
197      * @param replace this boolean value defines the behavior of this
198      * method if, when it is called, a <code>PolicyContextHandler</code> 
199      * has already been registered to handle the same key.
200      * In that case, and if the value of this argument is <code>true</code>,
201      * the existing handler is replaced with the argument handler. If the
202      * value of this parameter is false the existing registration is preserved
203      * and an exception is thrown.
204      *
205      * @throws java.lang.IllegalArgumentException
206      * if the value of either of the handler or key arguments is null,
207      * or the value of the replace argument is <code>false</code> and a handler
208      * with the same key as the argument handler is already registered.
209      *
210      * @throws java.lang.SecurityException
211      * if the calling AccessControlContext is not authorized by the container
212      * to call this method.
213      *
214      * @throws javax.security.jacc.PolicyContextException
215      * if an operation by this method on the argument PolicyContextHandler
216      * causes it to throw a checked exception that is not accounted for
217      * in the signature of this method.
218      */
219 
220     public static void 
221     registerHandler(String   key, PolicyContextHandler   handler, boolean replace)
222     throws javax.security.jacc.PolicyContextException  
223     {
224     if (handler == null || key == null)
225         throw new 
226         IllegalArgumentException  ("invalid (null) key or handler");
227     if (!handler.supports(key))
228         throw new IllegalArgumentException  ("handler does not support key");
229     java.lang.SecurityManager   sm = System.getSecurityManager();
230     if (sm != null) 
231         sm.checkPermission(new SecurityPermission  ("setPolicy"));
232 
233     if (handlerTable.containsKey(key) && replace == false)
234         throw new IllegalArgumentException  ("handler exists");
235     handlerTable.put(key,handler);
236     }
237 
238     /** This method may be used to obtain the keys that identify the
239      * container specific context handlers registered by the container.
240      *
241      * @return A <code>Set</code>, the elements of which, are the
242      * <code>String</code> key values that identify 
243      * the handlers that have been registered
244      * and therefore may be activated on the <code>PolicyContext</code>.     
245      *
246      * @throws java.lang.SecurityException
247      * if the calling AccessControlContext is not authorized by the container
248      * to call this method. Containers may choose to authorize calls to this
249      * method by any AccessControlContext.
250      */
251 
252     public static Set   getHandlerKeys()
253     {
254     return handlerTable.keySet();
255     }
256 
257     /** This method may be used by a 
258      * <code>Policy</code> provider to activate the
259      * <code>PolicyContextHandler</code> registered to the context object key
260      * and cause it to return the corresponding policy context object from
261      * the container. When this method activates a handler,
262      * it passes to the handler the context
263      * object key and the handler data associated with the calling thread.
264      *
265      * @param key a <code>String</code> that identifies the
266      * <code>PolicyContextHandler</code> to activate and the context object
267      * to be acquired from the handler. The value of this parameter must
268      * not be null.
269      * @return the container and handler specific object containing
270      * the desired context. A <code>null</code> value is returned if
271      * the corresponding handler has been registered, and the value
272      * of the corresponding context is null. 
273      *
274      * @throws java.lang.IllegalArgumentException
275      * if a <code>PolicyContextHandler</code> has not been registered
276      * for the key or the registered handler no longer supports the key.
277      *
278      * @throws java.lang.SecurityException
279      * if the calling AccessControlContext is not authorized by the container
280      * to call this method.
281      *
282      * @throws javax.security.jacc.PolicyContextException
283      * if an operation by this method on the identified PolicyContextHandler
284      * causes it to throw a checked exception that is not accounted for
285      * in the signature of this method.
286      */
287 
288     public static Object   getContext(String   key)
289     throws javax.security.jacc.PolicyContextException  
290     {
291         if (key == null)
292         throw new IllegalArgumentException  ("invalid key");
293     PolicyContextHandler   handler =
294         (PolicyContextHandler  ) handlerTable.get(key);
295     if (handler == null || !handler.supports(key))
296         throw new IllegalArgumentException  ("unknown handler key");
297     
298     java.lang.SecurityManager   sm = System.getSecurityManager();
299     if (sm != null) 
300         sm.checkPermission(new SecurityPermission  ("setPolicy"));
301 
302     return handler.getContext(key,thisHandlerData.get());
303     }
304 
305 }
306 
307 
308 
309 
310 
311
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags