1 /**
2 *
3 * Copyright 2003-2004 The Apache Software Foundation
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18
19
20
21
22
23
24 package javax.security.jacc;
25
26 /**
27 * This interface defines the methods that must be implemented by handlers that
28 * are to be registered and activated by the <code>PolicyContext</code> class.
29 * The <code>PolicyContext</code> class provides methods for containers to
30 * register and activate container-specific <code>PolicyContext</code> handlers.
31 * <code>Policy</code> providers use the <code>PolicyContext</code> class to
32 * activate handlers to obtain (from the container) additional policy relevant
33 * context to apply in their access decisions. All handlers registered and
34 * activated via the <code>PolicyContext</code> class must implement the
35 * <code>PolicyContextHandler</code> interface.
36 * @version $Rev: 46019 $ $Date: 2004-09-14 02:56:06 -0700 (Tue, 14 Sep 2004) $
37 */
38 public interface PolicyContextHandler {
39
40 /**
41 * This public method returns a boolean result indicating whether or not
42 * the handler supports the context object identified by the
43 * (case-sensitive) key value.
44 * @param key a <code>String</code< value identifying a context object
45 * that could be supported by the handler. The value of this parameter
46 * must not be null.
47 * @return a boolean indicating whether or not the context object
48 * corresponding to the argument key is handled by the handler.
49 * @throws PolicyContextException if the implementation throws a checked
50 * exception that has not been accounted for by the method signature. The
51 * exception thrown by the implementation class will be encapsulated
52 * (during construction) in the thrown PolicyContextException
53 */
54 public boolean supports(String key) throws PolicyContextException;
55
56 /**
57 * This public method returns the keys identifying the context objects
58 * supported by the handler. The value of each key supported by a handler
59 * must be a non-null String value.
60 * @return an array containing String values identifing the context objects
61 * supported by the handler. The array must not contain duplicate key
62 * values. In the unlikely case that the Handler supports no keys, the
63 * handler must return a zero length array. The value null must never be
64 * returned by this method.
65 * @throws PolicyContextException if the implementation throws a checked
66 * exception that has not been accounted for by the method signature. The
67 * exception thrown by the implementation class will be encapsulated
68 * (during construction) in the thrown PolicyContextException
69 */
70 public String[] getKeys() throws PolicyContextException;
71
72 /**
73 * This public method is used by the <code>PolicyContext/<code> class to
74 * activate the handler and obtain from it the the context object
75 * identified by the (case-sensitive) key. In addition to the key, the
76 * handler will be activated with the handler data value associated within
77 * the <code>PolicyContext</code> class with the thread on which the call
78 * to this method is made.<p>
79 *
80 * Note that the policy context identifier associated with a thread is
81 * available to the handler by calling PolicyContext.getContextID().
82 * @param key a String that identifies the context object to be returned by
83 * the handler. The value of this paramter must not be null.
84 * @param data the handler data <code>Object</code> associated with the
85 * thread on which the call to this method has been made. Note that the
86 * value passed through this parameter may be null.
87 * @return The container and handler specific <code>Object</code>
88 * containing the desired context. A null value may be returned if the
89 * value of the corresponding context is null.
90 * @throws PolicyContextException if the implementation throws a checked
91 * exception that has not been accounted for by the method signature. The
92 * exception thrown by the implementation class will be encapsulated
93 * (during construction) in the thrown PolicyContextException
94 */
95 public Object getContext(String key, Object data) throws PolicyContextException;
96 }