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