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    }