001 /**
002 *
003 * Copyright 2003-2004 The Apache Software Foundation
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018 //
019 // This source code implements specifications defined by the Java
020 // Community Process. In order to remain compliant with the specification
021 // DO NOT add / change / or delete method signatures!
022 //
023
024 package javax.security.jacc;
025
026 /**
027 * This interface defines the methods that must be implemented by handlers that
028 * are to be registered and activated by the <code>PolicyContext</code> class.
029 * The <code>PolicyContext</code> class provides methods for containers to
030 * register and activate container-specific <code>PolicyContext</code> handlers.
031 * <code>Policy</code> providers use the <code>PolicyContext</code> class to
032 * activate handlers to obtain (from the container) additional policy relevant
033 * context to apply in their access decisions. All handlers registered and
034 * activated via the <code>PolicyContext</code> class must implement the
035 * <code>PolicyContextHandler</code> interface.
036 * @version $Rev: 46019 $ $Date: 2004-09-14 02:56:06 -0700 (Tue, 14 Sep 2004) $
037 */
038 public interface PolicyContextHandler {
039
040 /**
041 * This public method returns a boolean result indicating whether or not
042 * the handler supports the context object identified by the
043 * (case-sensitive) key value.
044 * @param key a <code>String</code< value identifying a context object
045 * that could be supported by the handler. The value of this parameter
046 * must not be null.
047 * @return a boolean indicating whether or not the context object
048 * corresponding to the argument key is handled by the handler.
049 * @throws PolicyContextException if the implementation throws a checked
050 * exception that has not been accounted for by the method signature. The
051 * exception thrown by the implementation class will be encapsulated
052 * (during construction) in the thrown PolicyContextException
053 */
054 public boolean supports(String key) throws PolicyContextException;
055
056 /**
057 * This public method returns the keys identifying the context objects
058 * supported by the handler. The value of each key supported by a handler
059 * must be a non-null String value.
060 * @return an array containing String values identifing the context objects
061 * supported by the handler. The array must not contain duplicate key
062 * values. In the unlikely case that the Handler supports no keys, the
063 * handler must return a zero length array. The value null must never be
064 * returned by this method.
065 * @throws PolicyContextException if the implementation throws a checked
066 * exception that has not been accounted for by the method signature. The
067 * exception thrown by the implementation class will be encapsulated
068 * (during construction) in the thrown PolicyContextException
069 */
070 public String[] getKeys() throws PolicyContextException;
071
072 /**
073 * This public method is used by the <code>PolicyContext/<code> class to
074 * activate the handler and obtain from it the the context object
075 * identified by the (case-sensitive) key. In addition to the key, the
076 * handler will be activated with the handler data value associated within
077 * the <code>PolicyContext</code> class with the thread on which the call
078 * to this method is made.<p>
079 *
080 * Note that the policy context identifier associated with a thread is
081 * available to the handler by calling PolicyContext.getContextID().
082 * @param key a String that identifies the context object to be returned by
083 * the handler. The value of this paramter must not be null.
084 * @param data the handler data <code>Object</code> associated with the
085 * thread on which the call to this method has been made. Note that the
086 * value passed through this parameter may be null.
087 * @return The container and handler specific <code>Object</code>
088 * containing the desired context. A null value may be returned if the
089 * value of the corresponding context is null.
090 * @throws PolicyContextException if the implementation throws a checked
091 * exception that has not been accounted for by the method signature. The
092 * exception thrown by the implementation class will be encapsulated
093 * (during construction) in the thrown PolicyContextException
094 */
095 public Object getContext(String key, Object data) throws PolicyContextException;
096 }