You are viewing a plain text version of this content. The canonical link for it is here.
Posted to scm@geronimo.apache.org by ad...@apache.org on 2003/11/18 06:30:16 UTC
cvs commit: incubator-geronimo/specs/j2ee-jacc/src/java/javax/security/jacc EJBRoleRefPermission.java PolicyContext.java PolicyContextHandler.java
adc 2003/11/17 21:30:16
Modified: specs/j2ee-jacc/src/java/javax/security/jacc
EJBRoleRefPermission.java PolicyContext.java
PolicyContextHandler.java
Log:
Some useful comments.
Revision Changes Path
1.2 +162 -102 incubator-geronimo/specs/j2ee-jacc/src/java/javax/security/jacc/EJBRoleRefPermission.java
Index: EJBRoleRefPermission.java
===================================================================
RCS file: /home/cvs/incubator-geronimo/specs/j2ee-jacc/src/java/javax/security/jacc/EJBRoleRefPermission.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- EJBRoleRefPermission.java 30 Aug 2003 01:55:12 -0000 1.1
+++ EJBRoleRefPermission.java 18 Nov 2003 05:30:16 -0000 1.2
@@ -1,102 +1,162 @@
-/* ====================================================================
- * The Apache Software License, Version 1.1
- *
- * Copyright (c) 2003 The Apache Software Foundation. All rights
- * reserved.
- *
- * Redistribution and use in source and binary forms, with or without
- * modification, are permitted provided that the following conditions
- * are met:
- *
- * 1. Redistributions of source code must retain the above copyright
- * notice, this list of conditions and the following disclaimer.
- *
- * 2. Redistributions in binary form must reproduce the above copyright
- * notice, this list of conditions and the following disclaimer in
- * the documentation and/or other materials provided with the
- * distribution.
- *
- * 3. The end-user documentation included with the redistribution,
- * if any, must include the following acknowledgment:
- * "This product includes software developed by the
- * Apache Software Foundation (http://www.apache.org/)."
- * Alternately, this acknowledgment may appear in the software itself,
- * if and wherever such third-party acknowledgments normally appear.
- *
- * 4. The names "Apache" and "Apache Software Foundation" and
- * "Apache Geronimo" must not be used to endorse or promote products
- * derived from this software without prior written permission. For
- * written permission, please contact apache@apache.org.
- *
- * 5. Products derived from this software may not be called "Apache",
- * "Apache Geronimo", nor may "Apache" appear in their name, without
- * prior written permission of the Apache Software Foundation.
- *
- * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
- * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
- * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
- * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
- * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
- * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
- * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
- * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
- * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
- * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
- * SUCH DAMAGE.
- * ====================================================================
- *
- * This software consists of voluntary contributions made by many
- * individuals on behalf of the Apache Software Foundation. For more
- * information on the Apache Software Foundation, please see
- * <http://www.apache.org/>.
- *
- * This source code implements specifications defined by the Java
- * Community Process. In order to remain compliant with the specification
- * DO NOT add / change / or delete method signatures!
- *
- * ====================================================================
- */
-
-package javax.security.jacc;
-
-import java.security.Permission;
-
-/**
- *
- * @version $Revision$ $Date$
- */
-public final class EJBRoleRefPermission extends Permission {
-
- private transient int cachedHashCode = 0;
- private String actions;
-
- public EJBRoleRefPermission(String name, String role) {
- super(name);
-
- actions = role;
- }
-
- public boolean equals(Object o) {
- if (o == null || !(o instanceof EJBRoleRefPermission)) return false;
-
- EJBRoleRefPermission other = (EJBRoleRefPermission)o;
- return getName().equals(other.getName()) && actions.equals(other.actions);
- }
-
- public String getActions() {
- return actions;
- }
-
- public int hashCode() {
- if (cachedHashCode == 0) {
- cachedHashCode = getName().hashCode() ^ actions.hashCode();
- }
- return cachedHashCode;
- }
-
- public boolean implies(Permission permission) {
- return equals(permission);
- }
-}
-
+/* ====================================================================
+ * The Apache Software License, Version 1.1
+ *
+ * Copyright (c) 2003 The Apache Software Foundation. All rights
+ * reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright
+ * notice, this list of conditions and the following disclaimer in
+ * the documentation and/or other materials provided with the
+ * distribution.
+ *
+ * 3. The end-user documentation included with the redistribution,
+ * if any, must include the following acknowledgment:
+ * "This product includes software developed by the
+ * Apache Software Foundation (http://www.apache.org/)."
+ * Alternately, this acknowledgment may appear in the software itself,
+ * if and wherever such third-party acknowledgments normally appear.
+ *
+ * 4. The names "Apache" and "Apache Software Foundation" and
+ * "Apache Geronimo" must not be used to endorse or promote products
+ * derived from this software without prior written permission. For
+ * written permission, please contact apache@apache.org.
+ *
+ * 5. Products derived from this software may not be called "Apache",
+ * "Apache Geronimo", nor may "Apache" appear in their name, without
+ * prior written permission of the Apache Software Foundation.
+ *
+ * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
+ * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
+ * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
+ * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+ * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+ * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ * SUCH DAMAGE.
+ * ====================================================================
+ *
+ * This software consists of voluntary contributions made by many
+ * individuals on behalf of the Apache Software Foundation. For more
+ * information on the Apache Software Foundation, please see
+ * <http://www.apache.org/>.
+ *
+ * This source code implements specifications defined by the Java
+ * Community Process. In order to remain compliant with the specification
+ * DO NOT add / change / or delete method signatures!
+ *
+ * ====================================================================
+ */
+
+package javax.security.jacc;
+
+import java.security.Permission;
+
+/**
+ * Class for EJB <code>isCallerInRole(String reference)</code> permissions. An
+ * EJBRoleRefPermission is a named permission and has actions.<p>
+ *
+ * The name of an EJBRoleRefPermission contains the value of the ejb-name
+ * element in the application's deployment descriptor that identifies the EJB
+ * in whose context the permission is being evalutated.<p>
+ *
+ * The actions of an EJBRoleRefPermission identifies the role reference to
+ * which the permission applies. An EJBRoleRefPermission is checked to
+ * determine if the subject is a member of the role identified by the reference.
+ * @version $Revision$ $Date$
+ */
+public final class EJBRoleRefPermission extends Permission {
+
+ private transient int cachedHashCode = 0;
+ private String actions;
+
+ /**
+ * Creates a new EJBRoleRefPermission with the specified name and actions.
+ * @param name the ejb-name that identifies the EJB in whose context the
+ * role references are to be evaluated.
+ * @param role identifies the role reference to which the permission
+ * pertains. The role reference is scoped to the EJB identified in the
+ * name parameter. The value of the role reference must not be null or
+ * the empty string.
+ */
+ public EJBRoleRefPermission(String name, String role) {
+ super(name);
+
+ if (role == null || role.length() == 0)
+ throw new IllegalArgumentException("Role reference must not be null or the empty string");
+
+ actions = role;
+ }
+
+ /**
+ * Checks two EJBRoleRefPermission objects for equality. EJBRoleRefPermission
+ * objects are equivalent if they have case equivalent name and actions values.<p>
+ *
+ * Two Permission objects, P1 and P2, are equivalent if and only if P1.implies(P2) && P2.implies(P1).
+ * @param o the EJBRoleRefPermission object being tested for equality with this EJBRoleRefPermission.
+ * @return true if the argument EJBRoleRefPermission object is equivalent to this EJBRoleRefPermission.
+ */
+ public boolean equals(Object o) {
+ if (o == null || !(o instanceof EJBRoleRefPermission)) return false;
+
+ EJBRoleRefPermission other = (EJBRoleRefPermission)o;
+ return getName().equals(other.getName()) && actions.equals(other.actions);
+ }
+
+ /**
+ * Returns a canonical String representation of the actions of this EJBRoleRefPermission.
+ * @return a String containing the canonicalized actions of this EJBRoleRefPermission.
+ */
+ public String getActions() {
+ return actions;
+ }
+
+ /**
+ * Returns the hash code value for this EJBRoleRefPermission. The properties
+ * of the returned hash code must be as follows:
+ * <ul>
+ * <li>During the lifetime of a Java application, the hashCode method must
+ * return the same integer value, every time it is called on a EJBRoleRefPermission
+ * object. The value returned by hashCode for a particular EJBRoleRefPermission
+ * need not remain consistent from one execution of an application to another.</li>
+ * <li>If two EJBRoleRefPermission objects are equal according to the equals
+ * method, then calling the hashCode method on each of the two Permission
+ * objects must produce the same integer result (within an application).</li>
+ * </ul>
+ * @return the integer hash code value for this object.
+ */
+ public int hashCode() {
+ if (cachedHashCode == 0) {
+ cachedHashCode = getName().hashCode() ^ actions.hashCode();
+ }
+ return cachedHashCode;
+ }
+
+ /**
+ * Determines if the argument Permission is "implied by" this
+ * EJBRoleRefPermission. For this to be the case,
+ *
+ * <ul>
+ * <li>The argument must be an instanceof EJBRoleRefPermission</li>
+ * <li>with name equivalent to that of this EJBRoleRefPermission, and</li>
+ * <li>with the role reference equivalent to that of this EJBRoleRefPermission applies.</li>
+ * <ul>
+ * The name and actions comparisons described above are case sensitive.
+ * @param permission "this" EJBRoleRefPermission is checked to see if it implies the argument permission.
+ * @return true if the specified permission is implied by this object, false if not.
+ */
+ public boolean implies(Permission permission) {
+ return equals(permission);
+ }
+}
+
1.2 +127 -123 incubator-geronimo/specs/j2ee-jacc/src/java/javax/security/jacc/PolicyContext.java
Index: PolicyContext.java
===================================================================
RCS file: /home/cvs/incubator-geronimo/specs/j2ee-jacc/src/java/javax/security/jacc/PolicyContext.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- PolicyContext.java 30 Aug 2003 01:55:12 -0000 1.1
+++ PolicyContext.java 18 Nov 2003 05:30:16 -0000 1.2
@@ -1,123 +1,127 @@
-/* ====================================================================
- * The Apache Software License, Version 1.1
- *
- * Copyright (c) 2003 The Apache Software Foundation. All rights
- * reserved.
- *
- * Redistribution and use in source and binary forms, with or without
- * modification, are permitted provided that the following conditions
- * are met:
- *
- * 1. Redistributions of source code must retain the above copyright
- * notice, this list of conditions and the following disclaimer.
- *
- * 2. Redistributions in binary form must reproduce the above copyright
- * notice, this list of conditions and the following disclaimer in
- * the documentation and/or other materials provided with the
- * distribution.
- *
- * 3. The end-user documentation included with the redistribution,
- * if any, must include the following acknowledgment:
- * "This product includes software developed by the
- * Apache Software Foundation (http://www.apache.org/)."
- * Alternately, this acknowledgment may appear in the software itself,
- * if and wherever such third-party acknowledgments normally appear.
- *
- * 4. The names "Apache" and "Apache Software Foundation" and
- * "Apache Geronimo" must not be used to endorse or promote products
- * derived from this software without prior written permission. For
- * written permission, please contact apache@apache.org.
- *
- * 5. Products derived from this software may not be called "Apache",
- * "Apache Geronimo", nor may "Apache" appear in their name, without
- * prior written permission of the Apache Software Foundation.
- *
- * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
- * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
- * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
- * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
- * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
- * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
- * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
- * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
- * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
- * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
- * SUCH DAMAGE.
- * ====================================================================
- *
- * This software consists of voluntary contributions made by many
- * individuals on behalf of the Apache Software Foundation. For more
- * information on the Apache Software Foundation, please see
- * <http://www.apache.org/>.
- *
- * This source code implements specifications defined by the Java
- * Community Process. In order to remain compliant with the specification
- * DO NOT add / change / or delete method signatures!
- *
- * ====================================================================
- */
-
-package javax.security.jacc;
-
-import java.security.SecurityPermission;
-import java.util.Hashtable;
-import java.util.Set;
-
-/**
- *
- * @version $Revision$ $Date$
- */
-public final class PolicyContext {
-
- private static ThreadLocal contextId = new ThreadLocal();
- private static ThreadLocal handlerData = new ThreadLocal();
- private static Hashtable handlers = new Hashtable();
-
- public static void setContextID(String contextID) {
- SecurityManager sm = System.getSecurityManager();
- if (sm != null) sm.checkPermission(new SecurityPermission("setPolicy"));
-
- contextId.set(contextID);
- }
-
- public static String getContextID() {
- return (String)contextId.get();
- }
-
- public static void setHandlerData(Object data) {
- SecurityManager sm = System.getSecurityManager();
- if (sm != null) sm.checkPermission(new SecurityPermission("setPolicy"));
-
- handlerData.set(data);
- }
-
- public static void registerHandler(String key, PolicyContextHandler handler, boolean replace) throws PolicyContextException {
- if (key == null) throw new IllegalArgumentException("Key must not be null");
- if (handler == null) throw new IllegalArgumentException("Handler must not be null");
- if (!replace && handlers.containsKey(key)) throw new IllegalArgumentException ("A handler has already been registered under '" + key + "' and replace is false.");
-
- SecurityManager sm = System.getSecurityManager();
- if (sm != null) sm.checkPermission(new SecurityPermission("setPolicy"));
-
- handlers.put(key, handler);
- }
-
- public static Set getHandlerKeys() {
- return handlers.keySet();
- }
-
- public static Object getContext(String key) throws PolicyContextException {
- if (key == null) throw new IllegalArgumentException("Key must not be null");
-
- PolicyContextHandler handler = (PolicyContextHandler)handlers.get(key);
-
- if (handler == null) throw new IllegalArgumentException("No handler can be found for the key '" + key + "'");
- if (!handler.supports(key)) throw new IllegalArgumentException ("Registered handler no longer supports the key '" + key + "'");
-
- SecurityManager sm = System.getSecurityManager();
- if (sm != null) sm.checkPermission(new SecurityPermission("setPolicy"));
-
- return handler.getContext(key, handlerData.get());
- }
-}
+/* ====================================================================
+ * The Apache Software License, Version 1.1
+ *
+ * Copyright (c) 2003 The Apache Software Foundation. All rights
+ * reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright
+ * notice, this list of conditions and the following disclaimer in
+ * the documentation and/or other materials provided with the
+ * distribution.
+ *
+ * 3. The end-user documentation included with the redistribution,
+ * if any, must include the following acknowledgment:
+ * "This product includes software developed by the
+ * Apache Software Foundation (http://www.apache.org/)."
+ * Alternately, this acknowledgment may appear in the software itself,
+ * if and wherever such third-party acknowledgments normally appear.
+ *
+ * 4. The names "Apache" and "Apache Software Foundation" and
+ * "Apache Geronimo" must not be used to endorse or promote products
+ * derived from this software without prior written permission. For
+ * written permission, please contact apache@apache.org.
+ *
+ * 5. Products derived from this software may not be called "Apache",
+ * "Apache Geronimo", nor may "Apache" appear in their name, without
+ * prior written permission of the Apache Software Foundation.
+ *
+ * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
+ * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
+ * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
+ * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+ * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+ * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ * SUCH DAMAGE.
+ * ====================================================================
+ *
+ * This software consists of voluntary contributions made by many
+ * individuals on behalf of the Apache Software Foundation. For more
+ * information on the Apache Software Foundation, please see
+ * <http://www.apache.org/>.
+ *
+ * This source code implements specifications defined by the Java
+ * Community Process. In order to remain compliant with the specification
+ * DO NOT add / change / or delete method signatures!
+ *
+ * ====================================================================
+ */
+
+package javax.security.jacc;
+
+import java.security.SecurityPermission;
+import java.security.AccessControlContext;
+import java.security.AccessController;
+import java.util.Hashtable;
+import java.util.Set;
+
+
+/**
+ *
+ * @version $Revision$ $Date$
+ */
+public final class PolicyContext {
+
+ private static ThreadLocal contextId = new ThreadLocal();
+ private static ThreadLocal handlerData = new ThreadLocal();
+ private static Hashtable handlers = new Hashtable();
+ private final static SecurityPermission SET_POLICY = new SecurityPermission("setPolicy");
+
+ public static void setContextID(String contextID) {
+ SecurityManager sm = System.getSecurityManager();
+ if (sm != null) sm.checkPermission(SET_POLICY);
+
+ contextId.set(contextID);
+ }
+
+ public static String getContextID() {
+ return (String) contextId.get();
+ }
+
+ public static void setHandlerData(Object data) {
+ SecurityManager sm = System.getSecurityManager();
+ if (sm != null) sm.checkPermission(SET_POLICY);
+
+ handlerData.set(data);
+ }
+
+ public static void registerHandler(String key, PolicyContextHandler handler, boolean replace) throws PolicyContextException {
+ if (key == null) throw new IllegalArgumentException("Key must not be null");
+ if (handler == null) throw new IllegalArgumentException("Handler must not be null");
+ if (!replace && handlers.containsKey(key)) throw new IllegalArgumentException("A handler has already been registered under '" + key + "' and replace is false.");
+
+ SecurityManager sm = System.getSecurityManager();
+ if (sm != null) sm.checkPermission(SET_POLICY);
+
+ handlers.put(key, handler);
+ }
+
+ public static Set getHandlerKeys() {
+ return handlers.keySet();
+ }
+
+ public static Object getContext(String key) throws PolicyContextException {
+ if (key == null) throw new IllegalArgumentException("Key must not be null");
+
+ PolicyContextHandler handler = (PolicyContextHandler) handlers.get(key);
+
+ if (handler == null) throw new IllegalArgumentException("No handler can be found for the key '" + key + "'");
+ if (!handler.supports(key)) throw new IllegalArgumentException("Registered handler no longer supports the key '" + key + "'");
+
+ SecurityManager sm = System.getSecurityManager();
+ if (sm != null) sm.checkPermission(SET_POLICY);
+
+ return handler.getContext(key, handlerData.get());
+ }
+}
1.2 +133 -74 incubator-geronimo/specs/j2ee-jacc/src/java/javax/security/jacc/PolicyContextHandler.java
Index: PolicyContextHandler.java
===================================================================
RCS file: /home/cvs/incubator-geronimo/specs/j2ee-jacc/src/java/javax/security/jacc/PolicyContextHandler.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- PolicyContextHandler.java 30 Aug 2003 01:55:13 -0000 1.1
+++ PolicyContextHandler.java 18 Nov 2003 05:30:16 -0000 1.2
@@ -1,74 +1,133 @@
-/* ====================================================================
- * The Apache Software License, Version 1.1
- *
- * Copyright (c) 2003 The Apache Software Foundation. All rights
- * reserved.
- *
- * Redistribution and use in source and binary forms, with or without
- * modification, are permitted provided that the following conditions
- * are met:
- *
- * 1. Redistributions of source code must retain the above copyright
- * notice, this list of conditions and the following disclaimer.
- *
- * 2. Redistributions in binary form must reproduce the above copyright
- * notice, this list of conditions and the following disclaimer in
- * the documentation and/or other materials provided with the
- * distribution.
- *
- * 3. The end-user documentation included with the redistribution,
- * if any, must include the following acknowledgment:
- * "This product includes software developed by the
- * Apache Software Foundation (http://www.apache.org/)."
- * Alternately, this acknowledgment may appear in the software itself,
- * if and wherever such third-party acknowledgments normally appear.
- *
- * 4. The names "Apache" and "Apache Software Foundation" and
- * "Apache Geronimo" must not be used to endorse or promote products
- * derived from this software without prior written permission. For
- * written permission, please contact apache@apache.org.
- *
- * 5. Products derived from this software may not be called "Apache",
- * "Apache Geronimo", nor may "Apache" appear in their name, without
- * prior written permission of the Apache Software Foundation.
- *
- * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
- * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
- * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
- * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
- * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
- * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
- * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
- * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
- * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
- * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
- * SUCH DAMAGE.
- * ====================================================================
- *
- * This software consists of voluntary contributions made by many
- * individuals on behalf of the Apache Software Foundation. For more
- * information on the Apache Software Foundation, please see
- * <http://www.apache.org/>.
- *
- * This source code implements specifications defined by the Java
- * Community Process. In order to remain compliant with the specification
- * DO NOT add / change / or delete method signatures!
- *
- * ====================================================================
- */
-
-package javax.security.jacc;
-
-/**
- *
- * @version $Revision$ $Date$
- */
-public interface PolicyContextHandler {
-
- public boolean supports(String key) throws PolicyContextException;
-
- public String[] getKeys() throws PolicyContextException;
-
- public Object getContext(String key, Object data) throws PolicyContextException;
-}
+/* ====================================================================
+ * The Apache Software License, Version 1.1
+ *
+ * Copyright (c) 2003 The Apache Software Foundation. All rights
+ * reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright
+ * notice, this list of conditions and the following disclaimer in
+ * the documentation and/or other materials provided with the
+ * distribution.
+ *
+ * 3. The end-user documentation included with the redistribution,
+ * if any, must include the following acknowledgment:
+ * "This product includes software developed by the
+ * Apache Software Foundation (http://www.apache.org/)."
+ * Alternately, this acknowledgment may appear in the software itself,
+ * if and wherever such third-party acknowledgments normally appear.
+ *
+ * 4. The names "Apache" and "Apache Software Foundation" and
+ * "Apache Geronimo" must not be used to endorse or promote products
+ * derived from this software without prior written permission. For
+ * written permission, please contact apache@apache.org.
+ *
+ * 5. Products derived from this software may not be called "Apache",
+ * "Apache Geronimo", nor may "Apache" appear in their name, without
+ * prior written permission of the Apache Software Foundation.
+ *
+ * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
+ * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
+ * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
+ * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+ * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+ * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ * SUCH DAMAGE.
+ * ====================================================================
+ *
+ * This software consists of voluntary contributions made by many
+ * individuals on behalf of the Apache Software Foundation. For more
+ * information on the Apache Software Foundation, please see
+ * <http://www.apache.org/>.
+ *
+ * This source code implements specifications defined by the Java
+ * Community Process. In order to remain compliant with the specification
+ * DO NOT add / change / or delete method signatures!
+ *
+ * ====================================================================
+ */
+
+package javax.security.jacc;
+
+/**
+ * This interface defines the methods that must be implemented by handlers that
+ * are to be registered and activated by the <code>PolicyContext</code> class.
+ * The <code>PolicyContext</code> class provides methods for containers to
+ * register and activate container-specific <code>PolicyContext</code> handlers.
+ * <code>Policy</code> providers use the <code>PolicyContext</code> class to
+ * activate handlers to obtain (from the container) additional policy relevant
+ * context to apply in their access decisions. All handlers registered and
+ * activated via the <code>PolicyContext</code> class must implement the
+ * <code>PolicyContextHandler</code> interface.
+ * @version $Revision$ $Date$
+ */
+public interface PolicyContextHandler {
+
+ /**
+ * This public method returns a boolean result indicating whether or not
+ * the handler supports the context object identified by the
+ * (case-sensitive) key value.
+ * @param key a <code>String</code< value identifying a context object
+ * that could be supported by the handler. The value of this parameter
+ * must not be null.
+ * @return a boolean indicating whether or not the context object
+ * corresponding to the argument key is handled by the handler.
+ * @throws PolicyContextException if the implementation throws a checked
+ * exception that has not been accounted for by the method signature. The
+ * exception thrown by the implementation class will be encapsulated
+ * (during construction) in the thrown PolicyContextException
+ */
+ public boolean supports(String key) throws PolicyContextException;
+
+ /**
+ * This public method returns the keys identifying the context objects
+ * supported by the handler. The value of each key supported by a handler
+ * must be a non-null String value.
+ * @return an array containing String values identifing the context objects
+ * supported by the handler. The array must not contain duplicate key
+ * values. In the unlikely case that the Handler supports no keys, the
+ * handler must return a zero length array. The value null must never be
+ * returned by this method.
+ * @throws PolicyContextException if the implementation throws a checked
+ * exception that has not been accounted for by the method signature. The
+ * exception thrown by the implementation class will be encapsulated
+ * (during construction) in the thrown PolicyContextException
+ */
+ public String[] getKeys() throws PolicyContextException;
+
+ /**
+ * This public method is used by the <code>PolicyContext/<code> class to
+ * activate the handler and obtain from it the the context object
+ * identified by the (case-sensitive) key. In addition to the key, the
+ * handler will be activated with the handler data value associated within
+ * the <code>PolicyContext</code> class with the thread on which the call
+ * to this method is made.<p>
+ *
+ * Note that the policy context identifier associated with a thread is
+ * available to the handler by calling PolicyContext.getContextID().
+ * @param key a String that identifies the context object to be returned by
+ * the handler. The value of this paramter must not be null.
+ * @param data the handler data <code>Object</code> associated with the
+ * thread on which the call to this method has been made. Note that the
+ * value passed through this parameter may be null.
+ * @return The container and handler specific <code>Object</code>
+ * containing the desired context. A null value may be returned if the
+ * value of the corresponding context is null.
+ * @throws PolicyContextException if the implementation throws a checked
+ * exception that has not been accounted for by the method signature. The
+ * exception thrown by the implementation class will be encapsulated
+ * (during construction) in the thrown PolicyContextException
+ */
+ public Object getContext(String key, Object data) throws PolicyContextException;
+}