[jboss-cvs] JBossAS SVN: r102732 - in projects/specs/trunk: jboss-jacc-api_1.4_spec and 2 other directories.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Mon Mar 22 15:15:14 EDT 2010
Author: sguilhen at redhat.com
Date: 2010-03-22 15:15:14 -0400 (Mon, 22 Mar 2010)
New Revision: 102732
Added:
projects/specs/trunk/jboss-jacc-api_1.4_spec/
Modified:
projects/specs/trunk/jboss-jacc-api_1.4_spec/pom.xml
projects/specs/trunk/jboss-jacc-api_1.4_spec/src/main/java/javax/security/jacc/EJBMethodPermission.java
projects/specs/trunk/jboss-jacc-api_1.4_spec/src/main/java/javax/security/jacc/EJBRoleRefPermission.java
projects/specs/trunk/jboss-jacc-api_1.4_spec/src/main/java/javax/security/jacc/PolicyConfiguration.java
projects/specs/trunk/jboss-jacc-api_1.4_spec/src/main/java/javax/security/jacc/PolicyConfigurationFactory.java
projects/specs/trunk/jboss-jacc-api_1.4_spec/src/main/java/javax/security/jacc/PolicyContext.java
projects/specs/trunk/jboss-jacc-api_1.4_spec/src/main/java/javax/security/jacc/PolicyContextException.java
projects/specs/trunk/jboss-jacc-api_1.4_spec/src/main/java/javax/security/jacc/PolicyContextHandler.java
projects/specs/trunk/jboss-jacc-api_1.4_spec/src/main/java/javax/security/jacc/URLPattern.java
projects/specs/trunk/jboss-jacc-api_1.4_spec/src/main/java/javax/security/jacc/URLPatternSpec.java
projects/specs/trunk/jboss-jacc-api_1.4_spec/src/main/java/javax/security/jacc/WebResourcePermission.java
projects/specs/trunk/jboss-jacc-api_1.4_spec/src/main/java/javax/security/jacc/WebRoleRefPermission.java
projects/specs/trunk/jboss-jacc-api_1.4_spec/src/main/java/javax/security/jacc/WebUserDataPermission.java
projects/specs/trunk/jboss-specs-parent/pom.xml
Log:
JBEE-33: created the JACC 1.4 API
Copied: projects/specs/trunk/jboss-jacc-api_1.4_spec (from rev 102575, projects/specs/trunk/jboss-jacc-api_1.1_spec)
Modified: projects/specs/trunk/jboss-jacc-api_1.4_spec/pom.xml
===================================================================
--- projects/specs/trunk/jboss-jacc-api_1.1_spec/pom.xml 2010-03-18 18:33:02 UTC (rev 102575)
+++ projects/specs/trunk/jboss-jacc-api_1.4_spec/pom.xml 2010-03-22 19:15:14 UTC (rev 102732)
@@ -7,16 +7,16 @@
</parent>
<modelVersion>4.0.0</modelVersion>
<groupId>org.jboss.spec.javax.security.jacc</groupId>
- <artifactId>jboss-jacc-api_1.1_spec</artifactId>
+ <artifactId>jboss-jacc-api_1.4_spec</artifactId>
<version>1.0.0-SNAPSHOT</version>
<packaging>jar</packaging>
- <name>JACC 1.1 API</name>
- <description>The Java Authorization Contract for Containers 1.1 API classes</description>
+ <name>JACC 1.4 API</name>
+ <description>The Java Authorization Contract for Containers 1.4 API classes</description>
<scm>
- <connection>scm:svn:http://anonsvn.jboss.org/repos/jbossas/projects/specs/trunk/jboss-jacc-api_1.1_spec</connection>
- <developerConnection>scm:svn:https://svn.jboss.org/repos/jbossas/projects/specs/trunk/jboss-jacc-api_1.1_spec</developerConnection>
- <url>http://fisheye.jboss.org/browse/JBossAS/projects/specs/trunk/jboss-jacc-api_1.1_spec</url>
+ <connection>scm:svn:http://anonsvn.jboss.org/repos/jbossas/projects/specs/trunk/jboss-jacc-api_1.4_spec</connection>
+ <developerConnection>scm:svn:https://svn.jboss.org/repos/jbossas/projects/specs/trunk/jboss-jacc-api_1.4_spec</developerConnection>
+ <url>http://fisheye.jboss.org/browse/JBossAS/projects/specs/trunk/jboss-jacc-api_1.4_spec</url>
</scm>
<dependencies>
Modified: projects/specs/trunk/jboss-jacc-api_1.4_spec/src/main/java/javax/security/jacc/EJBMethodPermission.java
===================================================================
--- projects/specs/trunk/jboss-jacc-api_1.1_spec/src/main/java/javax/security/jacc/EJBMethodPermission.java 2010-03-18 18:33:02 UTC (rev 102575)
+++ projects/specs/trunk/jboss-jacc-api_1.4_spec/src/main/java/javax/security/jacc/EJBMethodPermission.java 2010-03-22 19:15:14 UTC (rev 102732)
@@ -1,59 +1,64 @@
/*
-* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
-* by the @authors tag. See the copyright.txt in the distribution for a
-* full listing of individual contributors.
-*
-* This is free software; you can redistribute it and/or modify it
-* under the terms of the GNU Lesser General Public License as
-* published by the Free Software Foundation; either version 2.1 of
-* the License, or (at your option) any later version.
-*
-* This software is distributed in the hope that it will be useful,
-* but WITHOUT ANY WARRANTY; without even the implied warranty of
-* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-* Lesser General Public License for more details.
-*
-* You should have received a copy of the GNU Lesser General Public
-* License along with this software; if not, write to the Free
-* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
-* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
-*/
+ * JBoss, Home of Professional Open Source. Copyright 2010, Red Hat Middleware
+ * LLC, and individual contributors as indicated by the @author tags. See the
+ * copyright.txt file in the distribution for a full listing of individual
+ * contributors.
+ *
+ * This is free software; you can redistribute it and/or modify it under the
+ * terms of the GNU Lesser General Public License as published by the Free
+ * Software Foundation; either version 2.1 of the License, or (at your option)
+ * any later version.
+ *
+ * This software is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this software; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA, or see the FSF
+ * site: http://www.fsf.org.
+ */
package javax.security.jacc;
-import java.io.Serializable;
-import java.io.ObjectStreamField;
+import java.io.IOException;
import java.io.ObjectInputStream;
-import java.io.IOException;
import java.io.ObjectOutputStream;
+import java.io.ObjectStreamField;
+import java.io.Serializable;
import java.lang.reflect.Method;
import java.security.Permission;
import java.util.ArrayList;
+import java.util.List;
import java.util.StringTokenizer;
import org.jboss.util.id.SerialVersion;
-/** A security permission for ejb-method permissions. The name of an
- * EJBMethodPermission contains the value of the ejb-name element in the
- * application's deployment descriptor that identifies the target EJB.
+/**
+ * <p>
+ * Class for EJB method permissions.
+ * </p>
*
- * The actions of an EJBMethodPermission identifies the methods of the EJB to
- * which the permission applies.
+ * <p>
+ * The name of an EJBMethodPermission contains the value of the ejb-name element in the application’s deployment
+ * descriptor that identifies the target EJB.
+ * </p>
*
- * Implementations of this class MAY implement newPermissionCollection or
- * inherit its implementation from the super class.
+ * <p>
+ * The actions of an EJBMethodPermission identifies the methods of the EJB to which the permission applies.
+ * </p>
*
- * @link http://java.sun.com/j2ee/1.4/docs/api/
+ * <p>
+ * Implementations of this class MAY implement newPermissionCollection or inherit its implementation from the super
+ * class.
+ * </p>
*
- * @author Scott.Stark at jboss.org
- * @author Ron Monzillo, Gary Ellison (javadoc)
- * @version $Revision$
+ * @author <a href="mailto:scott.stark at jboss.org">Scott Stark</a>
+ * @author <a href="mailto:sguilhen at redhat.com">Stefan Guilhen</a>
+ * @see {@link Permission}
*/
-public final class EJBMethodPermission
- extends Permission
- implements Serializable
+public final class EJBMethodPermission extends Permission implements Serializable
{
- /** @since 4.0.2 */
private static final long serialVersionUID;
static
{
@@ -66,72 +71,86 @@
/**
* @serialField actions String the actions string.
*/
- private static final ObjectStreamField[] serialPersistentFields = {
- new ObjectStreamField("actions", String.class)
- };
+ private static final ObjectStreamField[] serialPersistentFields = {new ObjectStreamField("actions", String.class)};
private transient String methodName;
+
private transient String methodInterface;
+
private transient String methodSig;
- /** Creates a new EJBMethodPermission with the specified name and actions.
-
- The name contains the value of the ejb-name element corresponding to an EJB
- in the application's deployment descriptor.
-
- The actions contains a methodSpec. The syntax of the actions parameter is
- defined as follows:
-
- methodNameSpec ::= methodName | emptyString
-
- methodInterfaceName ::= String
-
- methodInterfaceSpec ::= methodInterfaceName | emptyString
-
- typeName ::= typeName | typeName []
-
- methodParams ::= typeName | methodParams comma typeName
-
- methodParamsSpec ::= emptyString | methodParams
-
- methodSpec ::= null |
- methodNameSpec |
- methodNameSpec comma methodInterfaceName |
- methodNameSpec comma methodInterfaceSpec comma methodParamsSpec
-
-
- A MethodInterfaceName is a non-empty String and should contain a method-intf
- value as defined for use in EJB deployment descriptors. An implementation
- must be flexible such that it supports additional interface names especially
- if they are standardized by the EJB Specification. The EJB Specification
- currently defines the following method-intf values:
-
- { "Home", "LocalHome", "Remote", "Local", "ServiceEndpoint" }
-
-
- A null or empty string methodSpec indicates that the permission applies to
- all methods of the EJB. A methodSpec with a methodNameSpec of the empty
- string matches all methods of the EJB that match the methodInterface and
- methodParams elements of the methodSpec.
-
- A methodSpec with a methodInterfaceSpec of the empty string matches all
- methods of the EJB that match the methodNameSpec and methodParamsSpec
- elements of the methodSpec.
-
- A methodSpec without a methodParamsSpec matches all methods of the EJB that
- match the methodNameSpec and methodInterface elements of the methodSpec.
-
- The order of the typeNames in methodParams array must match the order of
- occurence of the corresponding parameters in the method signature of the
- target method(s). Each typeName in the methodParams must contain the
- canonical form of the corresponding parameter's typeName as defined by the
- getActions method. A methodSpec with an empty methodParamsSpec matches all
- 0 argument methods of the EJB that match the methodNameSpec and
- methodInterfaceSpec elements of the methodSpec.
-
- * @param name - the ejb-name to which the permission pertains.
- * @param actions - identifies the methods of the EJB to which the permission
- * pertains.
+ /**
+ * <p>
+ * Creates a new EJBMethodPermission with the specified name and actions.
+ * </p>
+ *
+ * <p>
+ * The name contains the value of the ejb-name element corresponding to an EJB in the application's deployment
+ * descriptor.
+ * </p>
+ *
+ * <p>
+ * The actions contains a methodSpec. The syntax of the actions parameter is defined as follows:
+ * </p>
+ *
+ * <pre>
+ * methodNameSpec ::= methodName | emptyString
+ *
+ * methodInterfaceName ::= String
+ *
+ * methodInterfaceSpec ::= methodInterfaceName | emptyString
+ *
+ * typeName ::= typeName | typeName []
+ *
+ * methodParams ::= typeName | methodParams comma typeName
+ *
+ * methodParamsSpec ::= emptyString | methodParams
+ *
+ * methodSpec ::= null | methodNameSpec | methodNameSpec comma
+ * methodInterfaceName | methodNameSpec comma methodInterfaceSpec comma
+ * methodParamsSpec
+ * </pre>
+ *
+ * <p>
+ * A MethodInterfaceName is a non-empty String and should contain a method-intf value as defined for use in EJB
+ * deployment descriptors. An implementation must be flexible such that it supports additional interface names
+ * especially if they are standardized by the EJB Specification. The EJB Specification currently defines the
+ * following method-intf values:
+ * </p>
+ *
+ * <pre>
+ *
+ * {"Home", "LocalHome", "Remote", "Local", "ServiceEndpoint"}
+ * </pre>
+ *
+ * <p>
+ * A null or empty string methodSpec indicates that the permission applies to all methods of the EJB. A methodSpec
+ * with a methodNameSpec of the empty string matches all methods of the EJB that match the methodInterface and
+ * methodParams elements of the methodSpec.
+ * </p>
+ *
+ * <p>
+ * A methodSpec with a methodInterfaceSpec of the empty string matches all methods of the EJB that match the
+ * methodNameSpec and methodParamsSpec elements of the methodSpec.
+ * </p>
+ *
+ * <p>
+ * A methodSpec without a methodParamsSpec matches all methods of the EJB that match the methodNameSpec and
+ * methodInterface elements of the methodSpec.
+ * </p>
+ *
+ * <p>
+ * The order of the typeNames in methodParams array must match the order of occurrence of the corresponding
+ * parameters in the method signature of the target method(s). Each typeName in the methodParams must contain the
+ * canonical form of the corresponding parameter's typeName as defined by the getActions method. A methodSpec with an
+ * empty methodParamsSpec matches all 0 argument methods of the EJB that match the methodNameSpec and
+ * methodInterfaceSpec elements of the methodSpec.
+ * </p>
+ *
+ * @param name
+ * - the ejb-name to which the permission pertains.
+ * @param actions
+ * - identifies the methods of the EJB to which the permission pertains.
*/
public EJBMethodPermission(String name, String actions)
{
@@ -139,113 +158,127 @@
parseMethodSpec(actions);
}
- /** Creates a new EJBMethodPermission with name corresponding to the EJBName
- * and actions composed from methodInterface, and the Method object.
+ /**
+ * <p>
+ * Creates a new EJBMethodPermission with name corresponding to the EJBName and actions composed from
+ * methodInterface, and the Method object.
+ * </p>
*
- * A container uses this constructor prior to checking if a caller has
- * permission to call the method of an EJB.
+ * <p>
+ * A container uses this constructor prior to checking if a caller has permission to call the method of an EJB.
+ * </p>
*
- * @param ejbName - the ejb-name of the target EJB
- * @param methodInterface - A string that may be used to specify the EJB
- * interface to which the permission pertains. A value of null or "",
- * indicates that the permission pertains to all methods that match the other
- * parameters of the permission specification without consideration of the
- * interface they occur on.
- * @param method - an instance of the Java.lang.reflect.Method class
- * corresponding to the method that the container is trying to determine
- * whether the caller has permission to access. This value must not be null.
+ * @param ejbName
+ * - The string representation of the name of the EJB as it appears in the corresponding ejb-name element
+ * in the deployment descriptor.
+ * @param methodInterface
+ * - A string that may be used to specify the EJB interface to which the permission pertains. A value of
+ * null or "", indicates that the permission pertains to all methods that match the other parameters of the
+ * permission specification without consideration of the interface they occur on.
+ * @param method
+ * - an instance of the Java.lang.reflect.Method class corresponding to the method that the container is
+ * trying to determine whether the caller has permission to access. This value must not be null.
*/
public EJBMethodPermission(String ejbName, String methodInterface, Method method)
{
- this(ejbName, method.getName(), methodInterface,
- convertParameters(method.getParameterTypes()));
+ this(ejbName, method.getName(), methodInterface, convertParameters(method.getParameterTypes()));
}
- /** Creates a new EJBMethodPermission with name corresponding to the EJBName
- * and actions composed from methodName, methodInterface, and methodParams.
+ /**
+ * <p>
+ * Creates a new EJBMethodPermission with name corresponding to the EJBName and actions composed from methodName,
+ * methodInterface, and methodParams.
+ * </p>
*
- * @param ejbName - the ejb-name of the target EJB
- * @param methodName - A string that may be used to indicate the method of the
- * EJB to which the permission pertains. A value of null or "" indicates that
- * the permission pertains to all methods that match the other parameters of
- * the permission specification without consideration of method name.
- * @param methodInterface - A string that may be used to specify the EJB
- * interface to which the permission pertains. A value of null or "",
- * indicates that the permission pertains to all methods that match the
- * other parameters of the permission specification without consideration of
- * the interface they occur on.
- * @param methodParams - An array of strings that may be used to specify
- * (by typeNames) the parameter signature of the target methods. The order of
- * the typeNames in methodParams array must match the order of occurence of
- * the corresponding parameters in the method signature of the target
- * method(s). Each typeName in the methodParams array must contain the
- * canonical form of the corresponding parameter's typeName as defined by the
- * getActions method. An empty methodParams array is used to represent a
- * method signature with no arguments. A value of null indicates that the
- * permission pertains to all methods that match the other parameters of the
- * permission specification without consideration of method signature.
+ * @param ejbName
+ * - The string representation of the name of the EJB as it appears in the corresponding ejb-name element
+ * in the deployment descriptor.
+ * @param methodName
+ * - A string that may be used to indicate the method of the EJB to which the permission pertains. A value
+ * of null or "" indicates that the permission pertains to all methods that match the other parameters of
+ * the permission specification without consideration of method name.
+ * @param methodInterface
+ * - A string that may be used to specify the EJB interface to which the permission pertains. A value of
+ * null or "", indicates that the permission pertains to all methods that match the other parameters of the
+ * permission specification without consideration of the interface they occur on.
+ * @param methodParams
+ * - An array of strings that may be used to specify (by typeNames) the parameter signature of the target
+ * methods. The order of the typeNames in methodParams array must match the order of occurrence of the
+ * corresponding parameters in the method signature of the target method(s). Each typeName in the
+ * methodParams array must contain the canonical form of the corresponding parameter's typeName as defined
+ * by the getActions method. An empty methodParams array is used to represent a method signature with no
+ * arguments. A value of null indicates that the permission pertains to all methods that match the other
+ * parameters of the permission specification without consideration of method signature.
*/
- public EJBMethodPermission(String ejbName, String methodName,
- String methodInterface, String[] methodParams)
+ public EJBMethodPermission(String ejbName, String methodName, String methodInterface, String[] methodParams)
{
super(ejbName);
this.methodInterface = methodInterface;
this.methodName = methodName;
- if( methodParams == null )
+ if (methodParams == null)
methodSig = null;
else
{
StringBuffer tmp = new StringBuffer();
- for(int n = 0; n < methodParams.length; n ++)
+ for (String methodParam : methodParams)
{
- tmp.append(methodParams[n]);
+ tmp.append(methodParam);
tmp.append(',');
}
- if( tmp.length() > 0 )
- tmp.setLength(tmp.length()-1);
+ if (tmp.length() > 0)
+ tmp.setLength(tmp.length() - 1);
methodSig = tmp.toString();
}
}
- /** Compare two EJBMethodPermissions.
+ /**
+ * <p>
+ * Checks two EJBMethodPermission objects for equality. EJBMethodPermission objects are equivalent if they have case
+ * sensitive equivalent name and actions values.
+ * </p>
*
- * @param p the EJBMethodPermission instance to compare against
- * @return true if p equates to this permission, false otherwise
+ * <p>
+ * Two Permission objects, P1 and P2, are equivalent if and only if P1.implies(P2) && P2.implies(P1).
+ * </p>
+ *
+ * @param o
+ * - The EJBMethodPermission object being tested for equality with this EJBMethodPermission
+ * @return true if the argument EJBMethodPermission object is equivalent to this EJBMethodPermission.
*/
- public boolean equals(Object p)
+ @Override
+ public boolean equals(Object o)
{
boolean equals = false;
- if( p == null || !(p instanceof EJBMethodPermission) )
+ if (o == null || !(o instanceof EJBMethodPermission))
return false;
- EJBMethodPermission perm = (EJBMethodPermission) p;
+ EJBMethodPermission perm = (EJBMethodPermission) o;
equals = getName().equals(perm.getName());
- if( equals == true )
+ if (equals == true)
{
// Check the method names
- if( methodName != null )
+ if (methodName != null)
{
- if( perm.methodName == null )
+ if (perm.methodName == null)
return false;
- if( methodName.equals(perm.methodName) == false )
+ if (methodName.equals(perm.methodName) == false)
return false;
}
- else if( perm.methodName != null )
+ else if (perm.methodName != null)
{
return false;
}
// Check the method interfaces
equals = methodInterface != perm.methodInterface;
- if( equals == false && methodInterface != null )
+ if (equals == false && methodInterface != null)
equals = methodInterface.equals(perm.methodInterface);
- if( equals == false )
+ if (equals == false)
return false;
// Check the method parameters
- if( methodSig != null )
+ if (methodSig != null)
{
- equals = perm.methodSig != null &&
- methodSig.equals(perm.methodSig);
+ equals = perm.methodSig != null && methodSig.equals(perm.methodSig);
}
else
{
@@ -255,116 +288,147 @@
return equals;
}
- /** Calculates the hash code as the hash of the methodName,
- * methodInterface and methodSig for each that is non-null.
- * @return has the method represented.
- */
+ /**
+ * <p>
+ * Returns the hash code value for this EJBMethodPermission. 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 EJBMethodPermission object. The value returned by hashCode for a particular EJBMethodPermission
+ * need not remain consistent from one execution of an application to another.</li>
+ * <li>If two EJBMethodPermission objects are equal according to the equals method, then calling the hash- Code
+ * method on each of the two Permission objects must produce the same integer result (within an application).</li>
+ * </ul>
+ * </p>
+ *
+ * @return the integer hash code value for this object.
+ */
+ @Override
public int hashCode()
{
int hashCode = 0;
- if( methodName != null )
+ if (methodName != null)
hashCode += methodName.hashCode();
- if( methodInterface != null )
+ if (methodInterface != null)
hashCode += methodInterface.hashCode();
- if( methodSig != null )
+ if (methodSig != null)
hashCode += methodSig.hashCode();
return hashCode;
}
- /** Returns a String containing a canonical representation of the actions of
- this EJBMethodPermission. The Canonical form of the actions of an
- EJBMethodPermission is described by the following syntax description.
-
- methodNameSpec ::= methodName | emptyString
- methodInterfaceName ::= String
- methodInterfaceSpec ::= methodInterfaceName | emptyString
- typeName ::= typeName | typeName []
- methodParams ::= typeName | methodParams comma typeName
- methodParamsSpec ::= emptyString | methodParams
- methodSpec ::= null |
- methodName |
- methodNameSpec comma methodInterfaceName |
- methodNameSpec comma methodInterfaceSpec comma methodParamsSpec
-
-
- The canonical form of each typeName must begin with the fully qualified Java
- name of the corresponding parameter's type. The canonical form of a typeName
- for an array parameter is the fully qualified Java name of the array's
- component type followed by as many instances of the string "[]" as there are
- dimensions to the array. No additional characters (e.g. blanks) may occur in
- the canonical form.
-
- A MethodInterfaceName is a non-empty String and should contain a method-intf
- value as defined for use in EJB deployment descriptors. An implementation
- must be flexible such p it supports additional interface names especially
- if they are standardized by the EJB Specification. The EJB Specification
- currently defines the following method-intf values:
- { "Home", "LocalHome", "Remote", "Local", "ServiceEndpoint" }
-
- @return the canonicalized actions of this EJBMethodPermission
+ /**
+ * <p>
+ * Returns a String containing a canonical representation of the actions of this EJBMethodPermission. The Canonical
+ * form of the actions of an EJBMethodPermission is described by the following syntax description.
+ * </p>
+ *
+ * <pre>
+ * methodNameSpec ::= methodName | emptyString
+ *
+ * methodInterfaceName ::= String
+ *
+ * methodInterfaceSpec ::= methodInterfaceName | emptyString
+ *
+ * typeName ::= typeName | typeName []
+ *
+ * methodParams ::= typeName | methodParams comma typeName
+ *
+ * methodParamsSpec ::= emptyString | methodParams
+ *
+ * methodSpec ::= null |
+ * methodName |
+ * methodNameSpec comma methodInterfaceName |
+ * methodNameSpec comma methodInterfaceSpec comma methodParamsSpec
+ * </pre>
+ *
+ * <p>
+ * The canonical form of each typeName must begin with the fully qualified Java name of the corresponding parameter's
+ * type. The canonical form of a typeName for an array parameter is the fully qualified Java name of the array's
+ * component type followed by as many instances of the string "[]" as there are dimensions to the array. No
+ * additional characters (e.g. blanks) may occur in the canonical form.
+ * </p>
+ *
+ * <p>
+ * A MethodInterfaceName is a non-empty String and should contain a method-intf value as defined for use in EJB
+ * deployment descriptors. An implementation must be flexible such p it supports additional interface names
+ * especially if they are standardized by the EJB Specification. The EJB Specification currently defines the
+ * following method-intf values: { "Home", "LocalHome", "Remote", "Local", "ServiceEndpoint" }
+ * </p>
+ *
+ * @return a String containing the canonicalized actions of this EJBMethodPermission.
*/
+ @Override
public String getActions()
{
StringBuffer actions = new StringBuffer();
- if( methodName != null )
+ if (methodName != null)
actions.append(methodName);
- if( methodInterface != null )
+ if (methodInterface != null)
{
actions.append(',');
actions.append(methodInterface);
}
- else if( methodSig != null )
+ else if (methodSig != null)
{
- actions.append(',');
+ actions.append(',');
}
- if( methodSig != null )
+ if (methodSig != null)
{
actions.append(',');
actions.append(methodSig);
}
String methodSpec = null;
- if( actions.length() > 0 )
+ if (actions.length() > 0)
methodSpec = actions.toString();
return methodSpec;
}
- /** Determines if the argument Permission is "implied by" this
- * EJBMethodPermission. For this to be the case the following must apply:
- * The argument must be an instanceof EJBMethodPermission
- * with name equivalent to p of this EJBMethodPermission, and
- * the methods to which the argument permission applies (as defined in its actions)
- * must be a subset of the methods to which this EJBMethodPermission applies
- * (as defined in its actions).
- *
- * The argument permission applies to a subset of the methods to which this
- * permission applies if all of the following conditions are met:
- * - the method name component of the methodNameSpec of this permission is null,
- * the empty string, or equivalent to the method name of the argument permission
- * - the method interface component of the methodNameSpec of this permission
- * is null, the empty string, or equivalent to the method interface of the
- * argument permission
- * - the method parameter list component of the methodNameSpec of this
- * permission is null, the empty string, or equivalent to the method
- * parameter list of the argument permission.
+ /**
+ * <p>
+ * Determines if the argument Permission is "implied by" this EJBMethodPermission. For this to be the case,
+ * <ul>
+ * <li>The argument must be an instance of EJBMethodPermission</li>
+ * <li>with name equivalent to that of this EJBMethodPermission, and</li>
+ * <li>the methods to which the argument permission applies (as defined in its actions) must be a subset of the
+ * methods to which this EJBMethodPermission applies (as defined in its actions).</li>
+ * </ul>
+ * </p>
*
- * The name and actions comparisons described above are case sensitive.
+ * <p>
+ * The argument permission applies to a subset of the methods to which this permission applies if all of the
+ * following conditions are met:
+ * <ul>
+ * <li>the method name component of the methodNameSpec of this permission is null, the empty string, or equivalent to
+ * the method name of the argument permission, and</li>
+ * <li>the method interface component of the methodNameSpec of this permission is null, the empty string, or
+ * equivalent to the method interface of the argument permission, and</li>
+ * <li>the method parameter list component of the methodNameSpec of this permission is null, the empty string, or
+ * equivalent to the method parameter list of the argument permission.</li>
+ * </ul>
+ * </p>
*
- * @param p the EJBMethodPermission checked to see if it this.
- * @return true if the specified permission is implied by this object, false if not
+ * <p>
+ * The name and actions comparisons described above are case sensitive.
+ * </p>
+ *
+ * @param permission
+ * - “this” EJBMethodPermission 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 p)
+ @Override
+ public boolean implies(Permission permission)
{
boolean implies = false;
- if( p == null || !(p instanceof EJBMethodPermission) )
+ if (permission instanceof EJBMethodPermission == false)
return false;
- EJBMethodPermission perm = (EJBMethodPermission) p;
+ EJBMethodPermission perm = (EJBMethodPermission) permission;
implies = getName().equals(perm.getName());
- if( implies == false )
+ if (implies == false)
return false;
- // See if perm is a subset of the method names
- if( methodName != null )
+ // See if permission is a subset of the method names
+ if (methodName != null)
{
implies = methodName.equals(perm.methodName);
}
@@ -372,65 +436,81 @@
implies = true;
// Check the method interface
- if( implies == true && methodInterface != null )
+ if (implies == true && methodInterface != null)
{
implies = methodInterface.equals(perm.methodInterface);
}
// Check the method signature
- if( implies == true && methodSig != null )
+ if (implies == true && methodSig != null)
{
implies = methodSig.equals(perm.methodSig);
- }
+ }
return implies;
- }
+ }
- /** Method string represented by this permission
- * @return [methodInterface :] methodName (params)
- */
- public String toString()
- {
- StringBuffer tmp = new StringBuffer(super.toString());
- tmp.append('[');
- if( methodInterface != null )
- {
- tmp.append(methodInterface);
- tmp.append(':');
- }
- else
- {
- tmp.append("*:");
- }
- if( methodName != null )
- {
- tmp.append(methodName);
- }
- else
- {
- tmp.append("*");
- }
- tmp.append('(');
- if( methodSig != null )
- {
- tmp.append(methodSig);
- }
- tmp.append(")]");
- return tmp.toString();
+ /**
+ * <p>
+ * Returns the {@code String} representation of this permission, which has the following form:
+ *
+ * <pre>
+ * [methodInterface:methodName(params)]
+ * </pre>
+ *
+ * </p>
+ */
+ @Override
+ public String toString()
+ {
+ StringBuffer tmp = new StringBuffer(super.toString());
+ tmp.append('[');
+ if (methodInterface != null)
+ {
+ tmp.append(methodInterface);
+ tmp.append(':');
+ }
+ else
+ {
+ tmp.append("*:");
+ }
+ if (methodName != null)
+ {
+ tmp.append(methodName);
+ }
+ else
+ {
+ tmp.append("*");
+ }
+ tmp.append('(');
+ if (methodSig != null)
+ {
+ tmp.append(methodSig);
+ }
+ tmp.append(")]");
+ return tmp.toString();
}
- private static String[] convertParameters(Class[] params)
+ /**
+ * <p>
+ * Converts the specified method parameter classes to {@code String}.
+ * </p>
+ *
+ * @param params
+ * - the array of classes to be converted.
+ * @return a {@code String[]} containing the classes names as {@code String}.
+ */
+ private static String[] convertParameters(Class<?>[] params)
{
- ArrayList tmp = new ArrayList();
- for(int p = 0; p < params.length; p++)
+ List<String> tmp = new ArrayList<String>();
+ for (Class<?> c : params)
{
- Class c = params[p];
- if( c.isArray() )
+ if (c.isArray())
{
StringBuffer sb = new StringBuffer();
- Class subType = c.getComponentType();
+ Class<?> subType = c.getComponentType();
sb.append(subType.getName());
// Convert to type[][]...[]
- while( subType != null )
+ while (subType != null)
{
sb.append("[]");
subType = subType.getComponentType();
@@ -447,64 +527,70 @@
return sig;
}
- /** Parse the methodSpec string into methodName, methodInterface and methodSig.
-
- The syntax of the methodSpec parameter is defined as follows:
-
- methodNameSpec ::= methodName | emptyString
-
- methodInterfaceName ::= String
-
- methodInterfaceSpec ::= methodInterfaceName | emptyString
-
- typeName ::= typeName | typeName []
-
- methodParams ::= typeName | methodParams comma typeName
-
- methodParamsSpec ::= emptyString | methodParams
-
- methodSpec ::= null |
- methodNameSpec |
- methodNameSpec comma methodInterfaceName |
- methodNameSpec comma methodInterfaceSpec comma methodParamsSpec
-
- @param methodSpec the string matching the format above
- */
+ /**
+ * <p>
+ * Parse the methodSpec string into methodName, methodInterface and methodSig.
+ * </p>
+ *
+ * <p>
+ * The syntax of the methodSpec parameter is defined as follows:
+ * </p>
+ *
+ * <pre>
+ * methodNameSpec ::= methodName | emptyString
+ *
+ * methodInterfaceName ::= String
+ *
+ * methodInterfaceSpec ::= methodInterfaceName | emptyString
+ *
+ * typeName ::= typeName | typeName []
+ *
+ * methodParams ::= typeName | methodParams comma typeName
+ *
+ * methodParamsSpec ::= emptyString | methodParams
+ *
+ * methodSpec ::= null | methodNameSpec | methodNameSpec comma methodInterfaceName | methodNameSpec comma
+ * methodInterfaceSpec comma methodParamsSpec
+ * </pre>
+ *
+ * @param methodSpec
+ * - the string matching the format above
+ */
private void parseMethodSpec(String methodSpec)
{
methodName = null;
methodInterface = null;
methodSig = null;
- if( methodSpec != null )
+ if (methodSpec != null)
{
StringTokenizer tokenizer = new StringTokenizer(methodSpec, ",", true);
// Method name
- if( tokenizer.hasMoreTokens() )
+ if (tokenizer.hasMoreTokens())
{
methodName = tokenizer.nextToken();
- if( methodName.equals(",") )
+ if (methodName.equals(","))
methodName = null;
}
// Method interface
- if( tokenizer.hasMoreTokens() )
+ if (tokenizer.hasMoreTokens())
{
methodInterface = tokenizer.nextToken();
- if( methodName != null && methodInterface.equals(",") )
+ if (methodName != null && methodInterface.equals(","))
methodInterface = tokenizer.nextToken();
- if( methodInterface.equals(",") )
+ if (methodInterface.equals(","))
{
methodInterface = null;
methodSig = "";
}
}
// Method args
- if( tokenizer.hasMoreTokens() )
+ if (tokenizer.hasMoreTokens())
{
- if( methodInterface != null )
+ if (methodInterface != null)
tokenizer.nextToken();
StringBuffer tmp = new StringBuffer();
- while( tokenizer.hasMoreTokens() )
+ while (tokenizer.hasMoreTokens())
{
tmp.append(tokenizer.nextToken());
}
@@ -513,20 +599,17 @@
}
}
- // Private -------------------------------------------------------
- private void readObject(ObjectInputStream ois)
- throws ClassNotFoundException, IOException
+ private void readObject(ObjectInputStream ois) throws ClassNotFoundException, IOException
{
ObjectInputStream.GetField fields = ois.readFields();
String actions = (String) fields.get("actions", null);
parseMethodSpec(actions);
}
- private void writeObject(ObjectOutputStream oos)
- throws IOException
+ private void writeObject(ObjectOutputStream oos) throws IOException
{
- ObjectOutputStream.PutField fields = oos.putFields();
- fields.put("actions",this.getActions());
+ ObjectOutputStream.PutField fields = oos.putFields();
+ fields.put("actions", this.getActions());
oos.writeFields();
}
}
Modified: projects/specs/trunk/jboss-jacc-api_1.4_spec/src/main/java/javax/security/jacc/EJBRoleRefPermission.java
===================================================================
--- projects/specs/trunk/jboss-jacc-api_1.1_spec/src/main/java/javax/security/jacc/EJBRoleRefPermission.java 2010-03-18 18:33:02 UTC (rev 102575)
+++ projects/specs/trunk/jboss-jacc-api_1.4_spec/src/main/java/javax/security/jacc/EJBRoleRefPermission.java 2010-03-22 19:15:14 UTC (rev 102732)
@@ -1,24 +1,24 @@
/*
-* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
-* by the @authors tag. See the copyright.txt in the distribution for a
-* full listing of individual contributors.
-*
-* This is free software; you can redistribute it and/or modify it
-* under the terms of the GNU Lesser General Public License as
-* published by the Free Software Foundation; either version 2.1 of
-* the License, or (at your option) any later version.
-*
-* This software is distributed in the hope that it will be useful,
-* but WITHOUT ANY WARRANTY; without even the implied warranty of
-* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-* Lesser General Public License for more details.
-*
-* You should have received a copy of the GNU Lesser General Public
-* License along with this software; if not, write to the Free
-* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
-* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
-*/
+ * JBoss, Home of Professional Open Source. Copyright 2010, Red Hat Middleware
+ * LLC, and individual contributors as indicated by the @author tags. See the
+ * copyright.txt file in the distribution for a full listing of individual
+ * contributors.
+ *
+ * This is free software; you can redistribute it and/or modify it under the
+ * terms of the GNU Lesser General Public License as published by the Free
+ * Software Foundation; either version 2.1 of the License, or (at your option)
+ * any later version.
+ *
+ * This software is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this software; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA, or see the FSF
+ * site: http://www.fsf.org.
+ */
package javax.security.jacc;
import java.io.Serializable;
@@ -26,29 +26,33 @@
import org.jboss.util.id.SerialVersion;
-/** Class for EJB isCallerInRole (String reference) permissions. An
- * EJBRoleRefPermission is a named permission and has actions.
+/**
+ * <p>
+ * Class for EJB <i>isCallerInRole (String reference)</i> 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 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 evaluated.
+ * </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.
+ * <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.
+ * </p>
*
- * Implementations of this class MAY implement newPermissionCollection or
- * inherit its implementation from the super class.
+ * <p>
+ * Implementations of this class MAY implement newPermissionCollection or inherit its implementation from the super
+ * class.
+ * </p>
*
- * @author Scott.Stark at jboss.org
- * @author Ron Monzillo, Gary Ellison (javadoc)
- * @version $Revision$
+ * @author <a href="mailto:scott.stark at jboss.org">Scott Stark</a>
+ * @author <a href="mailto:sguilhen at redhat.com">Stefan Guilhen</a>
+ * @see {@link Permission}
*/
-public final class EJBRoleRefPermission
- extends Permission
- implements Serializable
+public final class EJBRoleRefPermission extends Permission implements Serializable
{
- /** @since 4.0.2 */
private static final long serialVersionUID;
static
{
@@ -60,17 +64,21 @@
/** The security-role-ref/role-link value */
private String actions;
+
private transient int hashCode;
- /** Creates a new EJBRoleRefPermission with the specified name and actions.
+ /**
+ * <p>
+ * Creates a new EJBRoleRefPermission with the specified name and actions.
+ * </p>
*
- * @param ejbName - the ejb-name that identifies the EJB in whose context the
- * role references are to be evaluated.
- * @param actions - 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.
- */
+ * @param ejbName
+ * - the ejb-name that identifies the EJB in whose context the role references are to be evaluated.
+ * @param actions
+ * - 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 {@code null} or the
+ * empty string.
+ */
public EJBRoleRefPermission(String ejbName, String actions)
{
super(ejbName);
@@ -78,64 +86,106 @@
this.hashCode = ejbName.hashCode() + actions.hashCode();
}
- /** Test an EJBRoleRefPermission for equality.
+ /**
+ * <p>
+ * Checks two EJBRoleRefPermission objects for equality. EJBRoleRefPermission objects are equivalent if they have
+ * case equivalent name and actions values.
+ * </p>
*
- * @param p
- * @return
- */
- public boolean equals(Object p)
+ * <p>
+ * Two Permission objects, P1 and P2, are equivalent if and only if P1.implies(P2) && P2.implies(P1).
+ * </p>
+ *
+ * @param o
+ * - the EJBRoleRefPermission object being tested for equality with this EJBRoleRefPermission.
+ * @return true if the argument EJBRoleRefPermission object is equivalent to this EJBRoleRefPermission.
+ */
+ @Override
+ public boolean equals(Object o)
{
- if( p == this )
- return true;
- if( (p instanceof EJBRoleRefPermission) == false )
+ if ((o instanceof EJBRoleRefPermission) == false)
return false;
boolean equals = false;
- EJBRoleRefPermission errp = (EJBRoleRefPermission) p;
+ EJBRoleRefPermission errp = (EJBRoleRefPermission) o;
String pname = errp.getName();
- if( this.getName().equals(pname) )
+ if (this.getName().equals(pname))
{
String pactions = errp.getActions();
- if( this.getActions().equals(pactions) )
+ if (this.getActions().equals(pactions))
equals = true;
}
return equals;
}
+ /**
+ * <p>
+ * Returns a canonical String representation of the actions of this EJBRoleRefPermission.
+ * </p>
+ *
+ * @return a String containing the canonicalized actions of this EJBRoleRefPermission.
+ */
+ @Override
public String getActions()
{
return actions;
}
+ /**
+ * <p>
+ * 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 hash- Code
+ * method on each of the two Permission objects must produce the same integer result (within an application).</li>
+ * </ul>
+ * </p>
+ *
+ * @return the integer hash code value for this object.
+ */
+ @Override
public int hashCode()
{
return hashCode;
}
- /** Determines if the argument Permission is "implied by" this
- * EJBRoleRefPermission. For this to be the case,
+ /**
+ * <p>
+ * Determines if the argument Permission is "implied by" this EJBRoleRefPermission. For this to be the case,
+ * <ul>
+ * <li>The argument must be an instance of EJBRoleRefPermission with name equivalent to that of this
+ * EJBRoleRefPermission, and with the role reference equivalent to that of this EJBRoleRefPermission applies.</li>
+ * </ul>
+ * </p>
*
- * - The argument must be an instanceof EJBRoleRefPermission
- * - with name equivalent to that of this EJBRoleRefPermission, and
- * - with the role reference equivalent to that of this EJBRoleRefPermission
- * applies.
+ * <p>
+ * The name and actions comparisons described above are case sensitive.
+ * </p>
*
- * 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);
+ }
+
+ /**
+ * <p>
+ * Returns the {@code String} representation of this permission, which has the following form:
*
- * @param p - the EJBRoleRefPermission to test
- * @return true if the specified permission is implied by this object, false
- * otherwise.
- */
- public boolean implies(Permission p)
+ * <pre>
+ * [ejb-name,role-ref=actions]
+ * </pre>
+ *
+ * </p>
+ */
+ public String toString()
{
- return equals(p);
- }
-
- /**
- * Returns a string describing this Permission.
- */
- public String toString()
- {
- return "[" + getName() + ",role-ref=" + actions + "]";
+ return "[" + getName() + ",role-ref=" + actions + "]";
}
}
Modified: projects/specs/trunk/jboss-jacc-api_1.4_spec/src/main/java/javax/security/jacc/PolicyConfiguration.java
===================================================================
--- projects/specs/trunk/jboss-jacc-api_1.1_spec/src/main/java/javax/security/jacc/PolicyConfiguration.java 2010-03-18 18:33:02 UTC (rev 102575)
+++ projects/specs/trunk/jboss-jacc-api_1.4_spec/src/main/java/javax/security/jacc/PolicyConfiguration.java 2010-03-22 19:15:14 UTC (rev 102732)
@@ -1,389 +1,516 @@
/*
-* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
-* by the @authors tag. See the copyright.txt in the distribution for a
-* full listing of individual contributors.
-*
-* This is free software; you can redistribute it and/or modify it
-* under the terms of the GNU Lesser General Public License as
-* published by the Free Software Foundation; either version 2.1 of
-* the License, or (at your option) any later version.
-*
-* This software is distributed in the hope that it will be useful,
-* but WITHOUT ANY WARRANTY; without even the implied warranty of
-* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-* Lesser General Public License for more details.
-*
-* You should have received a copy of the GNU Lesser General Public
-* License along with this software; if not, write to the Free
-* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
-* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
-*/
+ * JBoss, Home of Professional Open Source. Copyright 2010, Red Hat Middleware
+ * LLC, and individual contributors as indicated by the @author tags. See the
+ * copyright.txt file in the distribution for a full listing of individual
+ * contributors.
+ *
+ * This is free software; you can redistribute it and/or modify it under the
+ * terms of the GNU Lesser General Public License as published by the Free
+ * Software Foundation; either version 2.1 of the License, or (at your option)
+ * any later version.
+ *
+ * This software is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this software; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA, or see the FSF
+ * site: http://www.fsf.org.
+ */
package javax.security.jacc;
import java.security.Permission;
import java.security.PermissionCollection;
-/** The methods of this interface are used by containers to
- create policy statements in a Policy provider.
- An object that implements the PolicyConfiguration interface provides the
- policy statement configuration interface for a corresponding policy context
- within the corresponding Policy provider.
-
- The life cycle of a policy context is defined by three states; "open",
- "inService", and "deleted". A policy context is in one of these three states.
-
- A policy context in the "open" state is in the process of being
- configured, and may be operated on by any of the methods of the
- PolicyConfiguration interface. A policy context in the "open" state
- must not be assimilated at <code>Policy.refresh</code> into the policy
- statements used by the Policy provider in performing its access decisions.
- In order for the policy statements of a policy context to be assimilated
- by the associated provider, the policy context must be in the
- "inService" state. A policy context in the "open" state is transitioned to
- the "inService" state by calling the commit method.
-
- A policy context in the "inService" state is available for assimilation
- into the policy statements being used to perform access decisions by the
- associated Policy provider. Providers assimilate policy contexts containing
- policy statements when the refresh method of the provider is called. When
- a provider's refresh method is called, it must assimilate only those policy
- contexts whose state is "inService" and it must ensure that the policy
- statements put into service for each policy context are only those defined
- in the context at the time of the call to refresh. A policy context in the
- "inService" state is not available for additional configuration and may be
- returned to the "open" state by calling the getPolicyConfiguration method
- of the PolicyConfigurationFactory.
-
- A policy context in the "deleted" state is neither available for
- configuration, nor is it available for assimilation into the Provider. A
- policy context whose state is "deleted" may be reclaimed for subsequent
- processing by calling the getPolicyConfiguration method of the associated
- PolicyConfigurationFactory. A "deleted" policy context
- is transitioned to the "open" state when it it returned as a result of
- a call to getPolicyConfiguration.
-
- The following table captures the correspondence between the policy context
- life cycle and the methods of the PolicyConfiguration interface.
- The rightmost 3 columns of the table correspond to the
- PolicyConfiguration state identified at the head of the column.
- The values in the cells of these columns indicate
- the next state resulting from a call to the method
- identifed in the leftmost column of the corresponding row, or that
- calling the method is unsupported in the state
- represented by the column (in which case the state will remain unchanged).
-
- <table border="1" width="90%" nosave="" align="center">
- <caption>PolicyConfiguration State Table</caption>
- <tr>
- <th valign="middle" rowspan="2" colspan="1" align="center">
- <font size="-2">Method</font></th>
- <th valign="top" rowspan="1" colspan="3" align="center">
- <font size="-2">Current State to Next State</font></th>
- </tr>
-
- <tr>
- <th width="25%" align="center"><font size="-2">deleted</font></th>
- <th width="12%" align="center"><font size="-2">open</font></th>
- <th width="25%" align="center"><font size="-2">inService</font></th>
- </tr>
- <tr>
- <td width="28%"><font size="-2">addToExcludedPolicy</font></td>
-
- <td width="25%" align="center">
- <font size="-2">Unsupported Operation</font></td>
- <td width="12%" align="center">
- <font size="-2">open</font></td>
- <td width="25%" align="center">
- <font size="-2">Unsupported Operation</font></td>
- </tr>
-
- <tr>
- <td width="28%"><font size="-2">addToRole</font></td>
- <td width="25%" align="center">
- <font size="-2">Unsupported Operation</font></td>
- <td width="12%" align="center">
- <font size="-2">open</font></td>
- <td width="25%" align="center">
-
- <font size="-2">Unsupported Operation</font></td>
- </tr>
- <tr>
- <td width="28%"><font size="-2">addToUncheckedPolicy</font></td>
- <td width="25%" align="center">
- <font size="-2">Unsupported Operation</font></td>
- <td width="12%" align="center">
-
- <font size="-2">open</font></td>
- <td width="25%" align="center">
- <font size="-2">Unsupported Operation</font></td>
- </tr>
- <tr>
- <td width="28%"><font size="-2">commit</font></td>
- <td width="25%" align="center">
-
- <font size="-2">Unsupported Operation</font></td>
- <td width="12%" align="center">
- <font size="-2">inService</font></td>
- <td width="25%" align="center">
- <font size="-2">inService</font></td>
- </tr>
- <tr>
-
- <td width="28%"><font size="-2">delete</font></td>
- <td width="25%" align="center">
- <font size="-2">deleted</font></td>
- <td width="12%" align="center">
- <font size="-2">deleted</font></td>
- <td width="25%" align="center">
- <font size="-2">deleted</font></td>
-
- </tr>
- <tr>
- <td width="28%"><font size="-2">getContextID</font></td>
- <td width="25%" align="center">
- <font size="-2">deleted</font></td>
- <td width="12%" align="center">
- <font size="-2">open</font></td>
-
- <td width="25%" align="center">
- <font size="-2">inService</font></td>
- </tr>
- <tr>
- <td width="28%"><font size="-2">inService</font></td>
- <td width="25%" align="center">
- <font size="-2">deleted</font></td>
-
- <td width="12%" align="center">
- <font size="-2">open</font></td>
- <td width="25%" align="center">
- <font size="-2">inService</font></td>
- </tr>
- <tr>
- <td width="28%"><font size="-2">linkConfiguration</font></td>
-
- <td width="25%" align="center">
- <font size="-2">Unsupported Operation</font></td>
- <td width="12%" align="center">
- <font size="-2">open</font></td>
- <td width="25%" align="center">
- <font size="-2">Unsupported Operation</font></td>
- </tr>
-
- <tr>
- <td width="28%"><font size="-2">removeExcludedPolicy</font></td>
- <td width="25%" align="center">
- <font size="-2">Unsupported Operation</font></td>
- <td width="12%" align="center"><font size="-2">
- open</font></td>
- <td width="25%" align="center">
-
- <font size="-2">Unsupported Operation</font></td>
- </tr>
- <tr>
- <td width="28%"><font size="-2">removeRole</font></td>
- <td width="25%" align="center">
- <font size="-2">Unsupported Operation</font></td>
- <td width="12%" align="center">
-
- <font size="-2">open</font></td>
- <td width="25%" align="center">
- <font size="-2">Unsupported Operation</font></td>
- </tr>
- <tr>
- <td width="28%"><font size="-2">removeUncheckedPolicy</font></td>
- <td width="25%" align="center">
-
- <font size="-2">Unsupported Operation</font></td>
- <td width="12%" align="center">
- <font size="-2">open</font></td>
- <td width="25%" align="center">
- <font size="-2">Unsupported Operation</font></td>
- </tr>
- </table>
-
- For a provider implementation to be compatible with multi-threaded
- environments, it may be necessary to synchronize the refresh method of
- the provider with the methods of its PolicyConfiguration interface and
- with the getPolicyConfiguration and inService methods of its
- PolicyConfigurationFactory.
-
- * @see http://java.sun.com/j2ee/1.4/docs/api/
+/**
+ * <p>
+ * The methods of this interface are used by containers to create policy statements in a Policy provider. An object that
+ * implements the PolicyConfiguration interface provides the policy statement configuration interface for a
+ * corresponding policy context within the corresponding Policy provider.
+ * </p>
*
- * @author Scott.Stark at jboss.org
- * @author Ron Monzillo, Gary Ellison (javadoc)
- * @version $Revision$
+ * <p>
+ * The life cycle of a policy context is defined by three states; "open", "inService", and "deleted". A policy context
+ * is in one of these three states.
+ * </p>
+ *
+ * <p>
+ * A policy context in the "open" state is in the process of being configured, and may be operated on by any of the
+ * methods of the PolicyConfiguration interface. A policy context in the "open" state must not be assimilated at {@code
+ * Policy.refresh} into the policy statements used by the Policy provider in performing its access decisions. In order
+ * for the policy statements of a policy context to be assimilated by the associated provider, the policy context must
+ * be in the "inService" state. A policy context in the "open" state is transitioned to the "inService" state by calling
+ * the commit method.
+ * </p>
+ *
+ * <p>
+ * A policy context in the "inService" state is available for assimilation into the policy statements being used to
+ * perform access decisions by the associated Policy provider. Providers assimilate policy contexts containing policy
+ * statements when the refresh method of the provider is called. When a provider's refresh method is called, it must
+ * assimilate only those policy contexts whose state is "inService" and it must ensure that the policy statements put
+ * into service for each policy context are only those defined in the context at the time of the call to refresh. A
+ * policy context in the "inService" state is not available for additional configuration and may be returned to the
+ * "open" state by calling the getPolicyConfiguration method of the PolicyConfigurationFactory.
+ * </p>
+ *
+ * <p>
+ * A policy context in the "deleted" state is neither available for configuration, nor is it available for assimilation
+ * into the Provider. A policy context whose state is "deleted" may be reclaimed for subsequent processing by calling
+ * the getPolicyConfiguration method of the associated PolicyConfigurationFactory. A "deleted" policy context is
+ * transitioned to the "open" state when it it returned as a result of a call to getPolicyConfiguration.
+ * </p>
+ *
+ * <p>
+ * The following table captures the correspondence between the policy context life cycle and the methods of the
+ * PolicyConfiguration interface. The rightmost 3 columns of the table correspond to the PolicyConfiguration state
+ * identified at the head of the column. The values in the cells of these columns indicate the next state resulting from
+ * a call to the method identified in the leftmost column of the corresponding row, or that calling the method is
+ * unsupported in the state represented by the column (in which case the state will remain unchanged).
+ * </p>
+ *
+ * <table border="1" width="90%" nosave="" align="center">
+ * <caption>PolicyConfiguration State Table</caption>
+ * <tr>
+ * <th valign="middle" rowspan="2" colspan="1" align="center">
+ * <font size="-2">Method</font></th>
+ * <th valign="top" rowspan="1" colspan="3" align="center">
+ * <font size="-2">Current State to Next State</font></th>
+ * </tr>
+ *
+ * <tr>
+ * <th width="25%" align="center"><font size="-2">deleted</font></th>
+ * <th width="12%" align="center"><font size="-2">open</font></th>
+ * <th width="25%" align="center"><font size="-2">inService</font></th>
+ * </tr>
+ * <tr>
+ * <td width="28%"><font size="-2">addToExcludedPolicy</font></td>
+ *
+ * <td width="25%" align="center">
+ * <font size="-2">Unsupported Operation</font></td>
+ * <td width="12%" align="center">
+ * <font size="-2">open</font></td>
+ * <td width="25%" align="center">
+ * <font size="-2">Unsupported Operation</font></td>
+ * </tr>
+ *
+ * <tr>
+ * <td width="28%"><font size="-2">addToRole</font></td>
+ * <td width="25%" align="center">
+ * <font size="-2">Unsupported Operation</font></td>
+ * <td width="12%" align="center">
+ * <font size="-2">open</font></td>
+ * <td width="25%" align="center">
+ *
+ * <font size="-2">Unsupported Operation</font></td>
+ * </tr>
+ * <tr>
+ * <td width="28%"><font size="-2">addToUncheckedPolicy</font></td>
+ * <td width="25%" align="center">
+ * <font size="-2">Unsupported Operation</font></td>
+ * <td width="12%" align="center">
+ *
+ * <font size="-2">open</font></td>
+ * <td width="25%" align="center">
+ * <font size="-2">Unsupported Operation</font></td>
+ * </tr>
+ * <tr>
+ * <td width="28%"><font size="-2">commit</font></td>
+ * <td width="25%" align="center">
+ *
+ * <font size="-2">Unsupported Operation</font></td>
+ * <td width="12%" align="center">
+ * <font size="-2">inService</font></td>
+ * <td width="25%" align="center">
+ * <font size="-2">inService</font></td>
+ * </tr>
+ * <tr>
+ *
+ * <td width="28%"><font size="-2">delete</font></td>
+ * <td width="25%" align="center">
+ * <font size="-2">deleted</font></td>
+ * <td width="12%" align="center">
+ * <font size="-2">deleted</font></td>
+ * <td width="25%" align="center">
+ * <font size="-2">deleted</font></td>
+ *
+ * </tr>
+ * <tr>
+ * <td width="28%"><font size="-2">getContextID</font></td>
+ * <td width="25%" align="center">
+ * <font size="-2">deleted</font></td>
+ * <td width="12%" align="center">
+ * <font size="-2">open</font></td>
+ *
+ * <td width="25%" align="center">
+ * <font size="-2">inService</font></td>
+ * </tr>
+ * <tr>
+ * <td width="28%"><font size="-2">inService</font></td>
+ * <td width="25%" align="center">
+ * <font size="-2">deleted</font></td>
+ *
+ * <td width="12%" align="center">
+ * <font size="-2">open</font></td>
+ * <td width="25%" align="center">
+ * <font size="-2">inService</font></td>
+ * </tr>
+ * <tr>
+ * <td width="28%"><font size="-2">linkConfiguration</font></td>
+ *
+ * <td width="25%" align="center">
+ * <font size="-2">Unsupported Operation</font></td>
+ * <td width="12%" align="center">
+ * <font size="-2">open</font></td>
+ * <td width="25%" align="center">
+ * <font size="-2">Unsupported Operation</font></td>
+ * </tr>
+ *
+ * <tr>
+ * <td width="28%"><font size="-2">removeExcludedPolicy</font></td>
+ * <td width="25%" align="center">
+ * <font size="-2">Unsupported Operation</font></td>
+ * <td width="12%" align="center"><font size="-2"> open</font></td>
+ * <td width="25%" align="center">
+ *
+ * <font size="-2">Unsupported Operation</font></td>
+ * </tr>
+ * <tr>
+ * <td width="28%"><font size="-2">removeRole</font></td>
+ * <td width="25%" align="center">
+ * <font size="-2">Unsupported Operation</font></td>
+ * <td width="12%" align="center">
+ *
+ * <font size="-2">open</font></td>
+ * <td width="25%" align="center">
+ * <font size="-2">Unsupported Operation</font></td>
+ * </tr>
+ * <tr>
+ * <td width="28%"><font size="-2">removeUncheckedPolicy</font></td>
+ * <td width="25%" align="center">
+ *
+ * <font size="-2">Unsupported Operation</font></td>
+ * <td width="12%" align="center">
+ * <font size="-2">open</font></td>
+ * <td width="25%" align="center">
+ * <font size="-2">Unsupported Operation</font></td>
+ * </tr>
+ * </table>
+ *
+ * <p>
+ * For a provider implementation to be compatible with multi-threaded environments, it may be necessary to synchronize
+ * the refresh method of the provider with the methods of its PolicyConfiguration interface and with the
+ * getPolicyConfiguration and inService methods of its PolicyConfigurationFactory.
+ * </p>
+ *
+ * @author <a href="mailto:scott.stark at jboss.org">Scott Stark</a>
+ * @author <a href="mailto:sguilhen at redhat.com">Stefan Guilhen</a>
+ * @see {@link Permission}, {@link PermissionCollection}, {@link PolicyContextException},
+ * {@link PolicyConfigurationFactory}.
*/
public interface PolicyConfiguration
{
- /** Adds a single excluded permission to the PolicyConfiguration.
+ /**
+ * <p>
+ * Used to add a single excluded policy statement to this PolicyConfiguration.
+ * </p>
+ *
* @param permission
+ * - the permission to be added to the excluded policy statements.
+ * @throws SecurityException
+ * - if called by an AccessControlContext that has not been granted the “setPolicy” SecurityPermission.
+ * @throws UnsupportedOperationException
+ * - if the state of the policy context whose interface is this PolicyConfiguration Object is “deleted” or
+ * “inService” when this method is called.
* @throws PolicyContextException
- */
- public void addToExcludedPolicy(Permission permission)
- throws PolicyContextException;
+ * - if the implementation throws a checked exception that has not been accounted for by the
+ * addToExcludedPolicy method signature. The exception thrown by the implementation class will be
+ * encapsulated (during construction) in the thrown PolicyContextException.
+ */
+ public void addToExcludedPolicy(Permission permission) throws PolicyContextException;
- /** Adds a collection of excluded permissions to the PolicyConfiguration
+ /**
+ * <p>
+ * Used to add excluded policy statements to this PolicyConfiguration.
+ * </p>
*
* @param permissions
+ * - the collection of permissions to be added to the excluded policy statements. The collection may be
+ * either a homogeneous or heterogeneous collection.
+ * @throws SecurityException
+ * - if called by an AccessControlContext that has not been granted the “setPolicy” SecurityPermission.
+ * @throws UnsupportedOperationException
+ * - if the state of the policy context whose interface is this PolicyConfiguration Object is “deleted” or
+ * “inService” when this method is called.
* @throws PolicyContextException
- */
- public void addToExcludedPolicy(PermissionCollection permissions)
- throws PolicyContextException;
+ * - if the implementation throws a checked exception that has not been accounted for by the
+ * addToExcludedPolicy method signature. The exception thrown by the implementation class will be
+ * encapsulated (during construction) in the thrown PolicyContextException.
+ */
+ public void addToExcludedPolicy(PermissionCollection permissions) throws PolicyContextException;
- /** Add a single permission to a named role in the PolicyConfiguration. If
- * the named Role does not exist in the PolicyConfiguration, it is created
- * as a result of the call to this function.
+ /**
+ * <p>
+ * Used to add a single permission to a named role in this PolicyConfiguration. If the named role does not exist in
+ * the PolicyConfiguration, it is created as a result of the call to this function.
+ * </p>
*
+ * <p>
+ * It is the job of the Policy provider to ensure that all the permissions added to a role are granted to principals
+ * “mapped to the role”.
+ * </p>
+ *
* @param roleName
+ * - the name of the Role to which the permission is to be added.
* @param permission
+ * - the permission to be added to the role.
+ * @throws SecurityException
+ * - if called by an AccessControlContext that has not been granted the “setPolicy” SecurityPermission.
+ * @throws UnsupportedOperationException
+ * - if the state of the policy context whose interface is this PolicyConfiguration Object is “deleted” or
+ * “inService” when this method is called.
* @throws PolicyContextException
- */
- public void addToRole(String roleName, Permission permission)
- throws PolicyContextException;
+ * - if the implementation throws a checked exception that has not been accounted for by the addToRole
+ * method signature. The exception thrown by the implementation class will be encapsulated (during
+ * construction) in the thrown PolicyContextException.
+ */
+ public void addToRole(String roleName, Permission permission) throws PolicyContextException;
- /** Add permissions to a named role in the PolicyConfiguration. If
- * the named Role does not exist in the PolicyConfiguration, it is created
- * as a result of the call to this function.
+ /**
+ * <p>
+ * Used to add permissions to a named role in this PolicyConfiguration. If the named role does not exist in the
+ * PolicyConfiguration, it is created as a result of the call to this function.
+ * </p>
+ * <p>
+ * It is the job of the Policy provider to ensure that all the permissions added to a role are granted to principals
+ * “mapped to the role”.
+ * </p>
+ *
* @param roleName
+ * - the name of the Role to which the permissions are to be added.
* @param permissions
+ * - the collection of permissions to be added to the role. The collection may be either a homogeneous or
+ * heterogeneous collection.
+ * @throws SecurityException
+ * - if called by an AccessControlContext that has not been granted the “setPolicy” SecurityPermission.
+ * @throws UnsupportedOperationException
+ * - if the state of the policy context whose interface is this PolicyConfiguration Object is “deleted” or
+ * “inService” when this method is called.
* @throws PolicyContextException
- */
- public void addToRole(String roleName, PermissionCollection permissions)
- throws PolicyContextException;
+ * - if the implementation throws a checked exception that has not been accounted for by the addToRole
+ * method signature. The exception thrown by the implementation class will be encapsulated (during
+ * construction) in the thrown PolicyContextException.
+ */
+ public void addToRole(String roleName, PermissionCollection permissions) throws PolicyContextException;
- /** Add a single unchecked permission to the PolicyConfiguration.
+ /**
+ * <p>
+ * Used to add a single unchecked policy statement to this PolicyConfiguration.
+ * </p>
*
* @param permission
+ * - the permission to be added to the unchecked policy statements.
+ * @throws SecurityException
+ * - if called by an AccessControlContext that has not been granted the “setPolicy” SecurityPermission.
+ * @throws UnsupportedOperationException
+ * - if the state of the policy context whose interface is this PolicyConfiguration Object is “deleted” or
+ * “inService” when this method is called.
* @throws PolicyContextException
- */
- public void addToUncheckedPolicy(Permission permission)
- throws PolicyContextException;
+ * - if the implementation throws a checked exception that has not been accounted for by the
+ * addToUncheckedPolicy method signature. The exception thrown by the implementation class will be
+ * encapsulated (during construction) in the thrown PolicyContextException.
+ */
+ public void addToUncheckedPolicy(Permission permission) throws PolicyContextException;
- /** Add unchecked permissions to the PolicyConfiguration.
+ /**
+ * <p>
+ * Used to add unchecked policy statements to this PolicyConfiguration.
+ * </p>
*
* @param permissions
+ * - the collection of permissions to be added as unchecked policy statements. The collection may be either
+ * a homogeneous or heterogeneous collection.
+ * @throws SecurityException
+ * - if called by an AccessControlContext that has not been granted the “setPolicy” SecurityPermission.
+ * @throws UnsupportedOperationException
+ * - if the state of the policy context whose interface is this PolicyConfiguration Object is “deleted” or
+ * “inService” when this method is called.
* @throws PolicyContextException
- */
- public void addToUncheckedPolicy(PermissionCollection permissions)
- throws PolicyContextException;
+ * - if the implementation throws a checked exception that has not been accounted for by the
+ * addToUncheckedPolicy method signature. The exception thrown by the implementation class will be
+ * encapsulated (during construction) in the thrown PolicyContextException.
+ */
+ public void addToUncheckedPolicy(PermissionCollection permissions) throws PolicyContextException;
- /** This method is used to set to "inService" the state of the policy context
- * whose interface is this PolicyConfiguration Object. Only those policy
- * contexts whose state is "inService" will be included in the policy
- * contexts processed by the Policy.refresh method. A policy context whose
- * state is "inService" may be returned to the "open" state by calling the
- * getPolicyConfiguration method of the PolicyConfiguration factory with the
- * policy context identifier of the policy context.
+ /**
+ * <p>
+ * This method is used to set to "inService" the state of the policy context whose interface is this
+ * PolicyConfiguration Object. Only those policy contexts whose state is "inService" will be included in the policy
+ * contexts processed by the Policy.refresh method. A policy context whose state is "inService" may be returned to
+ * the "open" state by calling the getPolicyConfiguration method of the PolicyConfiguration factory with the policy
+ * context identifier of the policy context.
+ * </p>
*
- * When the state of a policy context is "inService", calling any method other
- * than commit, delete, getContextID, or inService on its PolicyConfiguration
- * Object will cause an UnsupportedOperationException to be thrown.
+ * <p>
+ * When the state of a policy context is "inService", calling any method other than commit, delete, getContextID, or
+ * inService on its PolicyConfiguration Object will cause an UnsupportedOperationException to be thrown.
+ * </p>
*
- * @throws SecurityException - when the caller does not have a
- * SecurityPermission("setPolicy") permission.
- * @throws UnsupportedOperationException - if the state of the policy context
- * whose interface is this PolicyConfiguration Object is "deleted" when this
- * method is called.
- * @throws PolicyContextException - if the implementation throws a checked
- * exception that has not been accounted for by the commit method signature.
- */
- public void commit()
- throws PolicyContextException;
+ * @throws SecurityException
+ * - if called by an AccessControlContext that has not been granted the “setPolicy” SecurityPermission.
+ * @throws UnsupportedOperationException
+ * - if the state of the policy context whose interface is this PolicyConfiguration Object is "deleted"
+ * when this method is called.
+ * @throws PolicyContextException
+ * - if the implementation throws a checked exception that has not been accounted for by the commit method
+ * signature. The exception thrown by the implementation class will be encapsulated (during construction)
+ * in the thrown PolicyContextException.
+ */
+ public void commit() throws PolicyContextException;
- /** Causes all policy statements to be deleted from this PolicyConfiguration
- * and sets its internal state such that calling any method, other than
- * delete, getContextID, or inService on the PolicyConfiguration will be
- * rejected and cause an UnsupportedOperationException to be thrown.
+ /**
+ * <p>
+ * Causes all policy statements to be deleted from this PolicyConfiguration and sets its internal state such that
+ * calling any method, other than delete, getContextID, or inService on the PolicyConfiguration will be rejected and
+ * cause an UnsupportedOperationException to be thrown.
+ * </p>
*
- * This operation has no affect on any linked PolicyConfigurations other than
- * removing any links involving the deleted PolicyConfiguration.
+ * <p>
+ * This operation has no affect on any linked PolicyConfigurations other than removing any links involving the
+ * deleted PolicyConfiguration.
+ * </p>
*
- * @throws SecurityException - when the caller does not have a
- * SecurityPermission("setPolicy") permission.
+ * @throws SecurityException
+ * - if called by an AccessControlContext that has not been granted the “setPolicy” SecurityPermission.
* @throws PolicyContextException
- */
- public void delete()
- throws PolicyContextException;
+ * - if the implementation throws a checked exception that has not been accounted for by the delete method
+ * signature. The exception thrown by the implementation class will be encapsulated (during construction)
+ * in the thrown PolicyContextException.
+ */
+ public void delete() throws PolicyContextException;
- /** This method returns this object's policy context identifier.
+ /**
+ * <p>
+ * This method returns this object’s policy context identifier.
+ * </p>
*
* @return this object's policy context identifier.
*
- * @throws SecurityException - when the caller does not have a
- * SecurityPermission("setPolicy") permission.
+ * @throws SecurityException
+ * - if called by an AccessControlContext that has not been granted the “setPolicy” SecurityPermission.
* @throws PolicyContextException
- */
- public String getContextID()
- throws PolicyContextException;
+ * - if the implementation throws a checked exception that has not been accounted for by the getContextID
+ * method signature. The exception thrown by the implementation class will be encapsulated (during
+ * construction) in the thrown PolicyContextException.
+ */
+ public String getContextID() throws PolicyContextException;
- /** This method is used to determine if the policy context whose interface is
- * this PolicyConfiguration Object is in the "inService" state.
+ /**
+ * <p>
+ * This method is used to determine if the policy context whose interface is this PolicyConfiguration Object is in
+ * the "inService" state.
+ * </p>
*
- * @return true if the state of the associated policy context is "inService",
- * false otherwise.
+ * @return true if the state of the associated policy context is "inService"; false otherwise.
+ * @throws SecurityException
+ * - if called by an AccessControlContext that has not been granted the “setPolicy” SecurityPermission.
* @throws PolicyContextException
- */
- public boolean inService()
- throws PolicyContextException;
+ * - if the implementation throws a checked exception that has not been accounted for by the inService
+ * method signature. The exception thrown by the implementation class will be encapsulated (during
+ * construction) in the thrown PolicyContextException.
+ */
+ public boolean inService() throws PolicyContextException;
- /** Creates a relationship between this configuration and another such that
- * they share the same principal-to-role mappings. PolicyConfigurations are
- * linked to apply a common principal-to-role mapping to multiple seperately
- * manageable PolicyConfigurations, as is required when an application is
- * composed of multiple modules.
+ /**
+ * <p>
+ * Creates a relationship between this configuration and another such that they share the same principal-to- role
+ * mappings. PolicyConfigurations are linked to apply a common principal-to-role mapping to multiple separately
+ * manageable PolicyConfigurations, as is required when an application is composed of multiple modules.
+ * </p>
*
- * @param link - a reference to a different PolicyConfiguration than this
- * PolicyConfiguration. The relationship formed by this method is symetric,
- * transitive and idempotent. If the argument PolicyConfiguration does not
- * have a different Policy context identifier than this PolicyConfiguration
- * no relationship is formed, and an IllegalArgumentException is thrown.
+ * <p>
+ * Note that the policy statements which comprise a role, or comprise the excluded or unchecked policy collections in
+ * a PolicyConfiguration are unaffected by the configuration being linked to another.
+ * </p>
*
- * @throws SecurityException - when the caller does not have a
- * SecurityPermission("setPolicy") permission.
- * @throws IllegalArgumentException - if called with an argument
- * PolicyConfiguration whose Policy context is equivalent to that of this
- * PolicyConfiguration.
+ * @param link
+ * - a reference to a different PolicyConfiguration than this PolicyConfiguration. The relationship formed
+ * by this method is symmetric, transitive and idempotent. If the argument PolicyConfiguration does not
+ * have a different Policy context identifier than this PolicyConfiguration no relationship is formed, and
+ * an IllegalArgumentException is thrown.
+ *
+ * @throws SecurityException
+ * - if called by an AccessControlContext that has not been granted the “setPolicy” SecurityPermission.
+ * @throws UnsupportedOperationException
+ * - if the state of the policy context whose interface is this PolicyConfiguration Object is “deleted” or
+ * “inService” when this method is called.
+ * @throws IllegalArgumentException
+ * - if called with an argument PolicyConfiguration whose Policy context is equivalent to that of this
+ * PolicyConfiguration.
* @throws PolicyContextException
- */
- public void linkConfiguration(PolicyConfiguration link)
- throws PolicyContextException;
+ * - if the implementation throws a checked exception that has not been accounted for by the
+ * linkConfiguration method signature. The exception thrown by the implementation class will be
+ * encapsulated (during construction) in the thrown PolicyContextException.
+ */
+ public void linkConfiguration(PolicyConfiguration link) throws PolicyContextException;
- /** Used to remove any excluded policy statements from this PolicyConfiguration
+ /**
+ * <p>
+ * Used to remove any excluded policy statements from this PolicyConfiguration. This method has no effect on the
+ * links between this PolicyConfiguration and others.
+ * </p>
*
- * @throws SecurityException - when the caller does not have a
- * SecurityPermission("setPolicy") permission.
- * @throws UnsupportedOperationException - if the state of the policy context
- * whose interface is this PolicyConfiguration Object is "deleted" or
- * "inService" when this method is called.
+ * @throws SecurityException
+ * - if called by an AccessControlContext that has not been granted the “setPolicy” SecurityPermission.
+ * @throws UnsupportedOperationException
+ * - if the state of the policy context whose interface is this PolicyConfiguration Object is “deleted” or
+ * “inService” when this method is called.
* @throws PolicyContextException
- */
- public void removeExcludedPolicy()
- throws PolicyContextException;
+ * - if the implementation throws a checked exception that has not been accounted for by the
+ * removeExcludedPolicy method signature. The exception thrown by the implementation class will be
+ * encapsulated (during construction) in the thrown PolicyContextException.
+ */
+ public void removeExcludedPolicy() throws PolicyContextException;
- /** Used to remove a role and all its permissions from this PolicyConfiguration.
+ /**
+ * <p>
+ * Used to remove a role and all its permissions from this PolicyConfiguration. This method has no effect on the
+ * links between this PolicyConfiguration and others.
+ * </p>
*
- * @param roleName - the name of the Role to remove from this PolicyConfiguration.
+ * @param roleName
+ * - the name of the role to remove from this PolicyConfiguration. If the value of the roleName parameter
+ * is “*” and no role with name “*” exists in this PolicyConfiguration, then all roles must be removed from
+ * this PolicyConfiguration.
*
- * @throws SecurityException - when the caller does not have a
- * SecurityPermission("setPolicy") permission.
- * @throws UnsupportedOperationException - if the state of the policy context
- * whose interface is this PolicyConfiguration Object is "deleted" or
- * "inService" when this method is called.
+ * @throws SecurityException
+ * - if called by an AccessControlContext that has not been granted the “setPolicy” SecurityPermission.
+ * @throws UnsupportedOperationException
+ * - if the state of the policy context whose interface is this PolicyConfiguration Object is “deleted” or
+ * “inService” when this method is called.
* @throws PolicyContextException
- */
- public void removeRole(String roleName)
- throws PolicyContextException;
+ * - if the implementation throws a checked exception that has not been accounted for by the removeRole
+ * method signature. The exception thrown by the implementation class will be encapsulated (during
+ * construction) in the thrown PolicyContextException.
+ */
+ public void removeRole(String roleName) throws PolicyContextException;
- /** Used to remove any unchecked policy statements from this PolicyConfiguration.
+ /**
+ * <p>
+ * Used to remove any unchecked policy statements from this PolicyConfiguration. This method has no effect on the
+ * links between this PolicyConfiguration and others.
+ * </p>
*
- * @throws SecurityException - when the caller does not have a
- * SecurityPermission("setPolicy") permission.
- * @throws UnsupportedOperationException - if the state of the policy context
- * whose interface is this PolicyConfiguration Object is "deleted" or
- * "inService" when this method is called.
+ * @throws SecurityException
+ * - if called by an AccessControlContext that has not been granted the “setPolicy” SecurityPermission.
+ * @throws UnsupportedOperationException
+ * - if the state of the policy context whose interface is this PolicyConfiguration Object is “deleted” or
+ * “inService” when this method is called.
* @throws PolicyContextException
- */
- public void removeUncheckedPolicy()
- throws PolicyContextException;
+ * - if the implementation throws a checked exception that has not been accounted for by the
+ * removeUncheckedPolicy method signature. The exception thrown by the implementation class will be
+ * encapsulated (during construction) in the thrown PolicyContextException.
+ */
+ public void removeUncheckedPolicy() throws PolicyContextException;
}
Modified: projects/specs/trunk/jboss-jacc-api_1.4_spec/src/main/java/javax/security/jacc/PolicyConfigurationFactory.java
===================================================================
--- projects/specs/trunk/jboss-jacc-api_1.1_spec/src/main/java/javax/security/jacc/PolicyConfigurationFactory.java 2010-03-18 18:33:02 UTC (rev 102575)
+++ projects/specs/trunk/jboss-jacc-api_1.4_spec/src/main/java/javax/security/jacc/PolicyConfigurationFactory.java 2010-03-22 19:15:14 UTC (rev 102732)
@@ -1,66 +1,87 @@
/*
-* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
-* by the @authors tag. See the copyright.txt in the distribution for a
-* full listing of individual contributors.
-*
-* This is free software; you can redistribute it and/or modify it
-* under the terms of the GNU Lesser General Public License as
-* published by the Free Software Foundation; either version 2.1 of
-* the License, or (at your option) any later version.
-*
-* This software is distributed in the hope that it will be useful,
-* but WITHOUT ANY WARRANTY; without even the implied warranty of
-* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-* Lesser General Public License for more details.
-*
-* You should have received a copy of the GNU Lesser General Public
-* License along with this software; if not, write to the Free
-* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
-* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
-*/
+ * JBoss, Home of Professional Open Source. Copyright 2010, Red Hat Middleware
+ * LLC, and individual contributors as indicated by the @author tags. See the
+ * copyright.txt file in the distribution for a full listing of individual
+ * contributors.
+ *
+ * This is free software; you can redistribute it and/or modify it under the
+ * terms of the GNU Lesser General Public License as published by the Free
+ * Software Foundation; either version 2.1 of the License, or (at your option)
+ * any later version.
+ *
+ * This software is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this software; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA, or see the FSF
+ * site: http://www.fsf.org.
+ */
package javax.security.jacc;
+import java.security.Permission;
import java.security.SecurityPermission;
import java.security.AccessController;
import java.security.PrivilegedExceptionAction;
import java.security.PrivilegedActionException;
/**
- * @author Scott.Stark at jboss.org
- * @author Ron Monzillo, Gary Ellison (javadoc)
- * @version $Revision$
+ * <p>
+ * Abstract factory and finder class for obtaining the instance of the class that implements the
+ * PolicyConfigurationFactory of a provider. The factory will be used to instantiate PolicyConfiguration objects that
+ * will be used by the deployment tools of the container to create and manage policy contexts within the Policy
+ * Provider.
+ * </p>
+ *
+ * <p>
+ * Implementation classes must have a public no argument constructor that may be used to create an operational instance
+ * of the factory implementation class.
+ * </p>
+ *
+ * @author <a href="mailto:scott.stark at jboss.org">Scott Stark</a>
+ * @author <a href="mailto:sguilhen at redhat.com">Stefan Guilhen</a>
+ * @see {@link Permission}, {@link PolicyConfiguration}, {@link PolicyContextException}
*/
public abstract class PolicyConfigurationFactory
{
- /** The standard name of the system property specifying the JACC
- PolicyConfigurationFactory implementation class name.
+ /**
+ * The standard name of the system property specifying the JACC PolicyConfigurationFactory implementation class name.
*/
- private static final String FACTORY_PROP =
- "javax.security.jacc.PolicyConfigurationFactory.provider";
+ private static final String FACTORY_PROP = "javax.security.jacc.PolicyConfigurationFactory.provider";
+
/** The default PolicyConfigurationFactory implementation */
- private static final String DEFAULT_FACTORY_NAME =
- "org.jboss.security.jacc.JBossPolicyConfigurationFactory";
+ private static final String DEFAULT_FACTORY_NAME = "org.jboss.security.jacc.JBossPolicyConfigurationFactory";
+
/** The loaded PolicyConfigurationFactory provider */
private static PolicyConfigurationFactory factory;
- /** This static method uses the javax.security.jacc.PolicyConfigurationFactory.provider
- * system property to create a provider factory implementation. The provider
- * class must provide a public no-arg ctor.
+ /**
+ * <p>
+ * This static method uses a system property to find and instantiate (via a public constructor) a provider spe- cific
+ * factory implementation class. The name of the provider specific factory implementation class is obtained from the
+ * value of the system property,
*
- * @return the PolicyConfigurationFactory singleton
- * @throws SecurityException - when the caller does not have a
- * SecurityPermission(setPolicy) permission.
- * @throws ClassNotFoundException - when the class named by the system
- * property could not be found or because the value of the system
- * property is null.
- * @throws PolicyContextException - if the PolicyConfigurationFactory ctor
- * throws an exception other than those in the getPolicyConfigurationFactory
- * method signature. The exception will be encapsulated in a
- * PolicyContextException as its cause.
+ * <pre>
+ * javax.security.jacc.PolicyConfigurationFactory.provider.
+ * </pre>
+ *
+ * </p>
+ *
+ * @return the singleton instance of the provider specific PolicyConfigurationFactory implementation class.
+ * @throws SecurityException
+ * - when called by an AccessControlContext that has not been granted the “setPolicy” SecurityPermission.
+ * @throws ClassNotFoundException
+ * - when the class named by the system property could not be found including because the value of the
+ * system property has not be set.
+ * @throws PolicyContextException
+ * - if the implementation throws a checked exception that has not been accounted for by the
+ * getPolicyConfigurationFactory method signature. The exception thrown by the implementation class will
+ * be encapsulated (during construction) in the thrown PolicyContextException
*/
- public static PolicyConfigurationFactory getPolicyConfigurationFactory()
- throws ClassNotFoundException, PolicyContextException
+ public static PolicyConfigurationFactory getPolicyConfigurationFactory() throws ClassNotFoundException,
+ PolicyContextException
{
// Validate the caller permission
SecurityManager sm = System.getSecurityManager();
@@ -70,13 +91,13 @@
if (factory == null)
{
String factoryName = null;
- Class clazz = null;
+ Class<?> clazz = null;
try
{
LoadAction action = new LoadAction();
try
{
- clazz = (Class) AccessController.doPrivileged(action);
+ clazz = AccessController.doPrivileged(action);
factoryName = action.getName();
}
catch (PrivilegedActionException ex)
@@ -86,7 +107,7 @@
if (e instanceof ClassNotFoundException)
throw (ClassNotFoundException) e;
else
- throw new PolicyContextException("Failure during load of class: "+action.getName(), e);
+ throw new PolicyContextException("Failure during load of class: " + action.getName(), e);
}
factory = (PolicyConfigurationFactory) clazz.newInstance();
}
@@ -108,14 +129,14 @@
catch (ClassCastException e)
{
StringBuffer msg = new StringBuffer(factoryName + " Is not a PolicyConfigurationFactory, ");
- msg.append("PCF.class.CL: "+PolicyConfigurationFactory.class.getClassLoader());
- msg.append("\nPCF.class.CS: "+PolicyConfigurationFactory.class.getProtectionDomain().getCodeSource());
- msg.append("\nPCF.class.hash: "+System.identityHashCode(PolicyConfigurationFactory.class));
- msg.append("\nclazz.CL: "+clazz.getClassLoader());
- msg.append("\nclazz.CS: "+clazz.getProtectionDomain().getCodeSource());
- msg.append("\nclazz.super.CL: "+clazz.getSuperclass().getClassLoader());
- msg.append("\nclazz.super.CS: "+clazz.getSuperclass().getProtectionDomain().getCodeSource());
- msg.append("\nclazz.super.hash: "+System.identityHashCode(clazz.getSuperclass()));
+ msg.append("PCF.class.CL: " + PolicyConfigurationFactory.class.getClassLoader());
+ msg.append("\nPCF.class.CS: " + PolicyConfigurationFactory.class.getProtectionDomain().getCodeSource());
+ msg.append("\nPCF.class.hash: " + System.identityHashCode(PolicyConfigurationFactory.class));
+ msg.append("\nclazz.CL: " + clazz.getClassLoader());
+ msg.append("\nclazz.CS: " + clazz.getProtectionDomain().getCodeSource());
+ msg.append("\nclazz.super.CL: " + clazz.getSuperclass().getClassLoader());
+ msg.append("\nclazz.super.CS: " + clazz.getSuperclass().getProtectionDomain().getCodeSource());
+ msg.append("\nclazz.super.hash: " + System.identityHashCode(clazz.getSuperclass()));
ClassCastException cce = new ClassCastException(msg.toString());
cce.initCause(e);
throw cce;
@@ -124,76 +145,97 @@
return factory;
}
- /** This method is used to obtain an instance of the provider specific class
- * that implements the PolicyConfiguration interface that corresponds to the
- * identified policy context within the provider. The methods of the
- * PolicyConfiguration interface are used to define the policy statements of
- * the identified policy context.
+ /**
+ * <p>
+ * This method is used to obtain an instance of the provider specific class that implements the PolicyConfiguration
+ * interface that corresponds to the identified policy context within the provider. The methods of the
+ * PolicyConfiguration interface are used to define the policy statements of the identified policy context.
+ * </p>
*
- * If at the time of the call, the identified policy context does not exist
- * in the provider, then the policy context will be created in the provider
- * and the Object that implements the context's PolicyConfiguration Interface
- * will be returned. If the state of the identified context is "deleted" or
- * "inService" it will be transitioned to the "open" state as a result of the
- * call. The states in the lifecycle of a policy context are defined by the
+ * <p>
+ * If at the time of the call, the identified policy context does not exist in the provider, then the policy context
+ * will be created in the provider and the Object that implements the context’s PolicyConfiguration Interface will be
+ * returned. If the state of the identified context is “deleted” or “inService” it will be transitioned to the “open”
+ * state as a result of the call. The states in the lifecycle of a policy context are defined by the
* PolicyConfiguration interface.
+ * </p>
*
- * For a given value of policy context identifier, this method must always
- * return the same instance of PolicyConfiguration and there must be at most
- * one actual instance of a PolicyConfiguration with a given policy context
- * identifier (during a process context).
+ * <p>
+ * For a given value of policy context identifier, this method must always return the same instance of
+ * PolicyConfiguration and there must be at most one actual instance of a PolicyConfiguration with a given policy
+ * context identifier (during a process context).
+ * </p>
*
- * To preserve the invariant that there be at most one PolicyConfiguration
- * object for a given policy context, it may be necessary for this method to
- * be thread safe.
+ * <p>
+ * To preserve the invariant that there be at most one PolicyConfiguration object for a given policy context, it may
+ * be necessary for this method to be thread safe.
+ * </p>
*
- * @param contextID - the policy context ID indicates which
- * PolicyConfiguration to return. This must not be null.
- * @param remove - A boolean flag that establishes whether or not the policy
- * statements of an existing policy context are to be removed before its
- * PolicyConfiguration object is returned. If the value passed to this
- * parameter is true, the policy statements of an existing policy context
- * will be removed. If the value is false, they will not be removed.
- * @return a PolicyConfiguration instance
+ * @param contextID
+ * - A String identifying the policy context whose PolicyConfiguration interface is to be returned. The
+ * value passed to this parameter must not be null.
+ * @param remove
+ * - A boolean value that establishes whether or not the policy statements and linkages of an existing
+ * policy context are to be removed before its PolicyConfiguration object is returned. If the value passed
+ * to this parameter is true, the policy statements and linkages of an existing policy context will be
+ * removed. If the value is false, they will not be removed.
+ * @return an Object that implements the PolicyConfiguration Interface matched to the Policy provider and
+ * corresponding to the identified policy context.
+ * @throws SecurityException
+ * - when called by an AccessControlContext that has not been granted the “setPolicy” SecurityPermission.
* @throws PolicyContextException
+ * - if the implementation throws a checked exception that has not been accounted for by the
+ * getPolicyConfiguration method signature. The exception thrown by the implementation class will be
+ * encapsulated (during construction) in the thrown PolicyContextException.
*/
- public abstract PolicyConfiguration getPolicyConfiguration(String contextID,
- boolean remove)
- throws PolicyContextException;
+ public abstract PolicyConfiguration getPolicyConfiguration(String contextID, boolean remove)
+ throws PolicyContextException;
- /** This method determines if the identified policy context exists with state
- * "inService" in the Policy provider associated with the factory.
+ /**
+ * <p>
+ * This method determines if the identified policy context exists with state “inService” in the Policy provider
+ * associated with the factory.
+ * </p>
*
- * @param contextID - the context ID for selecting the policy
- * @return true if the identified policy context exists within the provider
- * and its state is "inService", false otherwise.
+ * @param contextID
+ * - A string identifying a policy context.
+ * @return true if the identified policy context exists within the provider and its state is “inService”, false
+ * otherwise.
+ * @throws SecurityException
+ * - when called by an AccessControlContext that has not been granted the “setPolicy” SecurityPermission.
* @throws PolicyContextException
+ * - if the implementation throws a checked exception that has not been accounted for by the inService
+ * method signature. The exception thrown by the implementation class will be encapsulated (during
+ * construction) in the thrown PolicyContextException.
*/
- public abstract boolean inService(String contextID)
- throws PolicyContextException;
+ public abstract boolean inService(String contextID) throws PolicyContextException;
- /** A PrivilegedExceptionAction that looks up the class name identified
- * by the javax.security.jacc.PolicyConfigurationFactory.provider system
- * property and loads the class using the thread context class loader.
- */
- private static class LoadAction implements PrivilegedExceptionAction
+ /**
+ * <p>
+ * A PrivilegedExceptionAction that looks up the class name identified by the {@code
+ * javax.security.jacc.PolicyConfigurationFactory.provider} system property and loads the class using the thread
+ * context class loader.
+ * </p>
+ */
+ private static class LoadAction implements PrivilegedExceptionAction<Class<?>>
{
private String name;
+
public String getName()
{
return name;
}
- public Object run()
- throws Exception
+
+ public Class<?> run() throws Exception
{
name = System.getProperty(FACTORY_PROP);
- if( name == null )
+ if (name == null)
{
- // Use the default factory impl
+ // Use the default factory implementation.
name = DEFAULT_FACTORY_NAME;
}
ClassLoader loader = Thread.currentThread().getContextClassLoader();
- Class factoryClass = loader.loadClass(name);
+ Class<?> factoryClass = loader.loadClass(name);
return factoryClass;
}
}
Modified: projects/specs/trunk/jboss-jacc-api_1.4_spec/src/main/java/javax/security/jacc/PolicyContext.java
===================================================================
--- projects/specs/trunk/jboss-jacc-api_1.1_spec/src/main/java/javax/security/jacc/PolicyContext.java 2010-03-18 18:33:02 UTC (rev 102575)
+++ projects/specs/trunk/jboss-jacc-api_1.4_spec/src/main/java/javax/security/jacc/PolicyContext.java 2010-03-22 19:15:14 UTC (rev 102732)
@@ -1,24 +1,24 @@
/*
-* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
-* by the @authors tag. See the copyright.txt in the distribution for a
-* full listing of individual contributors.
-*
-* This is free software; you can redistribute it and/or modify it
-* under the terms of the GNU Lesser General Public License as
-* published by the Free Software Foundation; either version 2.1 of
-* the License, or (at your option) any later version.
-*
-* This software is distributed in the hope that it will be useful,
-* but WITHOUT ANY WARRANTY; without even the implied warranty of
-* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-* Lesser General Public License for more details.
-*
-* You should have received a copy of the GNU Lesser General Public
-* License along with this software; if not, write to the Free
-* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
-* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
-*/
+ * JBoss, Home of Professional Open Source. Copyright 2010, Red Hat Middleware
+ * LLC, and individual contributors as indicated by the @author tags. See the
+ * copyright.txt file in the distribution for a full listing of individual
+ * contributors.
+ *
+ * This is free software; you can redistribute it and/or modify it under the
+ * terms of the GNU Lesser General Public License as published by the Free
+ * Software Foundation; either version 2.1 of the License, or (at your option)
+ * any later version.
+ *
+ * This software is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this software; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA, or see the FSF
+ * site: http://www.fsf.org.
+ */
package javax.security.jacc;
import java.util.Set;
@@ -27,177 +27,195 @@
import java.util.HashMap;
import java.security.SecurityPermission;
-/** This utility class is used by containers to communicate policy context
- * identifiers and other policy relevant context to Policy providers. Policy
- * providers use the policy context identifier to select the subset of policy
- * to apply in access decisions.
+/**
+ * <p>
+ * This utility class is used by containers to communicate policy context identifiers and other policy relevant context
+ * to {@code Policy} providers. {@code Policy} providers use the policy context identifier to select the subset of
+ * policy to apply in access decisions.
+ * </p>
*
- * The value of a policy context identifier is a String and each thread has an
- * independently established policy context identifier. A container will
- * establish the thread-scoped value of a policy context identifier by calling
- * the static setContextID method. The value of a thread-scoped policy context
- * identifier is available (to Policy) by calling the static getContextID method.
+ * <p>
+ * The value of a policy context identifier is a {@code String} and each thread has an independently established policy
+ * context identifier. A container will establish the thread-scoped value of a policy context identifier by calling the
+ * static {@code setContextID} method. The value of a thread-scoped policy context identifier is available (to {@code
+ * Policy}) by calling the static {@code getContextID} method.
+ * </p>
*
- * This class is also used by Policy providers to request additional
- * thread-scoped policy relevant context objects from the calling container.
- * Containers register container-specific PolicyContext handlers using the
- * static registerHandler method. Handler registration is scoped to the class,
- * such that the same handler registrations are active in all thread contexts.
- * Containers may use the static method setHandlerData to establish a
- * thread-scoped parameter that will be passed to handlers when they are
- * activated by Policy providers. The static getContext method is used to
- * activate a handler and obtain the corresponding context object.
+ * <p>
+ * This class is also used by {@code Policy} providers to request additional thread-scoped policy relevant context
+ * objects from the calling container. Containers register container-specific {@code PolicyContext} handlers using the
+ * static {@code registerHandler} method. Handler registration is scoped to the class, such that the same handler
+ * registrations are active in all thread contexts. Containers may use the static method {@code setHandlerData} to
+ * establish a thread-scoped parameter that will be passed to handlers when they are activated by {@code Policy}
+ * providers. The static {@code getContext} method is used to activate a handler and obtain the corresponding context
+ * object.
+ * </p>
*
- * The static accessor functions provided by this class allow per-thread policy
- * context values to be established and communicated independent of a common
- * reference to a particular PolicyContext instance.
+ * <p>
+ * The static accessor functions provided by this class allow per-thread policy context values to be established and
+ * communicated independent of a common reference to a particular {@code PolicyContext} instance.
+ * </p>
*
- * The PolicyContext class may encapsulate static ThreadLocal instance variables
- * to represent the policy context identifier and handler data values.
+ * <p>
+ * The {@code PolicyContext} class may encapsulate static {@code ThreadLocal} instance variables to represent the policy
+ * context identifier and handler data values.
+ * </p>
*
- * The Application server must bundle or install the PolicyContext class, and
- * the containers of the application server must prevent the methods of the
- * PolicyContext class from being called from calling contexts that are not
- * authorized to call these methods. With the exception of the getContextID
- * and GetHandlerKeys methods, containers must restrict and afford access to
- * the methods of the PolicyContext class to calling contexts trusted by the
- * container to perform container access decisions. The PolicyContext class may
- * satisfy this requirement (on behalf of its container) by rejecting calls made
- * from an AccessControlContext that has not been granted the "setPolicy"
- * SecurityPermission, and by ensuring that Policy providers used to perform
+ * <p>
+ * The Application server must bundle or install the {@code PolicyContext} class, and the containers of the application
+ * server must prevent the methods of the {@code PolicyContext} class from being called from calling contexts that are
+ * not authorized to call these methods. With the exception of the {@code getContextID} and {@code getHandlerKeys}
+ * methods, containers must restrict and afford access to the methods of the {@code PolicyContext} class to calling
+ * contexts trusted by the container to perform container access decisions. The {@code PolicyContext} class may satisfy
+ * this requirement (on behalf of its container) by rejecting calls made from an {@code AccessControlContext} that has
+ * not been granted the "setPolicy" SecurityPermission, and by ensuring that {@code Policy} providers used to perform
* container access decisions are granted the "setPolicy" permission.
+ * </p>
*
- * @see http://java.sun.com/j2ee/1.4/docs/api/
- *
- * @author Scott.Stark at jboss.org
- * @author Ron Monzillo, Gary Ellison (javadoc)
- * @version $Revision$
+ * @author <a href="mailto:scott.stark at jboss.org">Scott Stark</a>
+ * @author <a href="mailto:sguilhen at redhat.com">Stefan Guilhen</a>
+ * @see {@link PolicyContextHandler}
*/
public final class PolicyContext
{
private static SecurityPermission setPolicy = new SecurityPermission("setPolicy");
+
private static SecurityPermission getPolicy = new SecurityPermission("getPolicy");
- private static ThreadLocal handlerDataLocal = new ThreadLocal();
- private static ThreadLocal contextIDLocal = new ThreadLocal();
- private static Map handlerMap = Collections.synchronizedMap(new HashMap());
- /** This method may be used by a Policy provider to activate the
- * PolicyContextHandler registered to the context object key and cause it to
- * return the corresponding policy context object from the container. When
- * this method activates a handler, it passes to the handler the context
- * object key and the handler data associated with the calling thread.
+ private static ThreadLocal<Object> handlerDataLocal = new ThreadLocal<Object>();
+
+ private static ThreadLocal<String> contextIDLocal = new ThreadLocal<String>();
+
+ private static Map<String, PolicyContextHandler> handlerMap = Collections
+ .synchronizedMap(new HashMap<String, PolicyContextHandler>());
+
+ /**
+ * <p>
+ * This method may be used by a {@code Policy} provider to activate the {@code PolicyContextHandler} registered to
+ * the context object key and cause it to return the corresponding policy context object from the container. When
+ * this method activates a handler, it passes to the handler the context object key and the handler data associated
+ * with the calling thread.
+ * </p>
*
- * @param key - a non-null String that identifies the PolicyContextHandler to
- * activate as well as the context object to be acquired from the handler.
- * @return the container and handler specific object containing the desired
- * context. A null value is returned if the corresponding handler has been
- * registered, and the value of the corresponding context is null.
- * @throws IllegalArgumentException - if a PolicyContextHandler has not been
- * registered for the key or the registered handler no longer supports the key.
- * @throws SecurityException - if the caller does not have the
- * SecurityPermission("getPolicy") permission.
- * @throws PolicyContextException - if an operation by this method on the
- * identified PolicyContextHandler causes it to throw a checked exception
- * that is not accounted for in the signature of this method.
+ * @param key
+ * - a {@code String} that identifies the PolicyContextHandler to activate and the context object to be
+ * acquired from the handler. The value of this parameter must not be null.
+ * @return the container and handler specific object containing the desired context. A {@code null} value is returned
+ * if the corresponding handler has been registered, and the value of the corresponding context is null.
+ * @throws IllegalArgumentException
+ * - if a {@code PolicyContextHandler} has not been registered for the key or the registered handler no
+ * longer supports the key.
+ * @throws SecurityException
+ * - if the calling {@code AccessControlContext} is not authorized by the container to call this method.
+ * @throws PolicyContextException
+ * - if an operation by this method on the identified {@code PolicyContextHandler} causes it to throw a
+ * checked exception that is not accounted for in the signature of this method.
*/
- public static Object getContext(String key)
- throws PolicyContextException
+ public static Object getContext(String key) throws PolicyContextException
{
- if( key == null || handlerMap.containsKey(key) == false )
- throw new IllegalArgumentException("No PolicyContextHandler for key="+key);
+ if (key == null || handlerMap.containsKey(key) == false)
+ throw new IllegalArgumentException("No PolicyContextHandler for key=" + key);
SecurityManager sm = System.getSecurityManager();
if (sm != null)
sm.checkPermission(getPolicy);
PolicyContextHandler handler = (PolicyContextHandler) handlerMap.get(key);
- if( handler.supports(key) == false )
- throw new IllegalArgumentException("PolicyContextHandler does not support key="+key);
+ if (handler.supports(key) == false)
+ throw new IllegalArgumentException("PolicyContextHandler does not support key=" + key);
Object data = handlerDataLocal.get();
Object context = handler.getContext(key, data);
return context;
}
- /** This method returns the value of the policy context identifier associated
- * with the thread on which the accessor is called.
+ /**
+ * <p>
+ * This static method returns the value of the policy context identifier associated with the thread on which the
+ * accessor is called.
+ * </p>
*
- * @return the possibly null policy context identifier established for the
- * thread. This method must return the default policy context identifier,
- * null, if the policy context identifier of the thread has not been set via
- * setContext to another value.
- */
+ * @return The {@code String} (or {@code null}) policy context identifier established for the thread. This method
+ * must return the default policy context identifier, {@code null}, if the policy context identifier of the
+ * thread has not been set via {@code setContext} to another value.
+ * @throws SecurityException
+ * - if the calling {@code AccessControlContext} is not authorized by the container to call this method.
+ * Containers may choose to authorize calls to this method by any {@code AccessControlContext}.
+ */
public static String getContextID()
{
String contextID = (String) contextIDLocal.get();
return contextID;
}
- /** This method may be used to obtain the keys that identify the container
- * specific context handlers registered by the container.
+ /**
+ * <p>
+ * This method may be used to obtain the keys that identify the container specific context handlers registered by the
+ * container.
+ * </p>
*
- * @return A Set, the elements of which, are the String key values that
- * identify the handlers that have been registered and therefore may be
- * activated on the PolicyContext
- */
+ * @return A {@code Set}, the elements of which, are the {@code String} key values that identify the handlers that
+ * have been registered and therefore may be activated on the {@code PolicyContext}.
+ */
+ @SuppressWarnings("unchecked")
public static Set getHandlerKeys()
{
return handlerMap.keySet();
}
- /** Authorization protected method used to register a container specific
- * PolicyContext handler. A handler may be registered to handle multiple keys,
- * but at any time, at most one handler may be registered for a key.
+ /**
+ * <p>
+ * Authorization protected method used to register a container specific {@code PolicyContext} handler. A handler may
+ * be registered to handle multiple keys, but at any time, at most one handler may be registered for a key.
+ * </p>
*
- * @param key - a case-sensitive, non-null String that identifies the context
- * object handled by the handler.
- * @param handler - an non-null object that implements the PolicyContextHandler
- * interface.
- * @param replace - this boolean value defines the behavior of this method
- * if, when it is called, a PolicyContextHandler has already been registered
- * to handle the same key. In that case, and if the value of this argument is
- * true, the existing handler is replaced with the argument handler. If the
- * value of this parameter is false the existing registration is preserved
- * and an exception is thrown.
- *
- * @throws IllegalArgumentException - if the value of either of the handler
- * or key arguments is null, or the value of the replace argument is false
- * and a handler with the same key as the argument handler is already
- * registered.
- * @throws SecurityException - if the caller does not have the
- * SecurityPermission("setPolicy") permission.
- * @throws PolicyContextException - if an operation by this method on the
- * argument PolicyContextHandler causes it to throw a checked exception that
- * is not accounted for in the signature of this method.
- */
- public static void registerHandler(String key, PolicyContextHandler handler,
- boolean replace)
- throws PolicyContextException
+ * @param key
+ * - a (case-sensitive) {@code String} that identifies the context object handled by the handler. The value
+ * of this parameter must not be null.
+ * @param handler
+ * - an object that implements the {@code PolicyContextHandler} interface. The value of this parameter must
+ * not be null.
+ * @param replace
+ * - this boolean value defines the behavior of this method if, when it is called, a {@code
+ * PolicyContextHandler} has already been registered to handle the same key. In that case, and if the value
+ * of this argument is {@code true}, the existing handler is replaced with the argument handler. If the
+ * value of this parameter is false the existing registration is preserved and an exception is thrown.
+ * @throws IllegalArgumentException
+ * - if the value of either of the handler or key arguments is null, or the value of the replace argument
+ * is false and a handler with the same key as the argument handler is already registered.
+ * @throws SecurityException
+ * - if the calling {@code AccessControlContext} is not authorized by the container to call this method.
+ * @throws PolicyContextException
+ * - if an operation by this method on the argument {@code PolicyContextHandler} causes it to throw a
+ * checked exception that is not accounted for in the signature of this method.
+ */
+ public static void registerHandler(String key, PolicyContextHandler handler, boolean replace)
+ throws PolicyContextException
{
- if( key == null )
+ if (key == null)
throw new IllegalArgumentException("The key may not be null");
- if( handler == null )
+ if (handler == null)
throw new IllegalArgumentException("The handler may not be null");
SecurityManager sm = System.getSecurityManager();
if (sm != null)
sm.checkPermission(setPolicy);
- if( replace == false && handlerMap.containsKey(key) == true )
+ if (replace == false && handlerMap.containsKey(key) == true)
{
- String msg = "Handler for key="+key+", exists, handler: "+handlerMap.get(key);
+ String msg = "Handler for key=" + key + ", exists, handler: " + handlerMap.get(key);
throw new IllegalArgumentException(msg);
}
-
handlerMap.put(key, handler);
}
- /** Authorization protected method used to modify the value of the policy
- * context identifier associated with the thread on which this method is
- * called
+ /**
+ * <p>
+ * Authorization protected method used to modify the value of the policy context identifier associated with the
+ * thread on which this method is called.
+ * </p>
*
- * @param contextID - a String that represents the value of the policy
- * context identifier to be assigned to the PolicyContext for the calling
- * thread. The value null is a legitimate value for this parameter.
- * @throws SecurityException - if the caller does not have the
- * SecurityPermission("setPolicy") permission.
- *
+ * @param contextID
+ * - a {@code String} that represents the value of the policy context identifier to be assigned to the
+ * {@code PolicyContext} for the calling thread. The value null is a legitimate value for this parameter.
+ * @throws SecurityException
+ * - if the calling {@code AccessControlContext} is not authorized by the container to call this method.
*/
public static void setContextID(String contextID)
{
@@ -207,18 +225,20 @@
contextIDLocal.set(contextID);
}
- /** Authorization protected method that may be used to associate a
- * thread-scoped handler data object with the PolicyContext. The handler data
- * object will be made available to handlers, where it can serve to supply or
- * bind the handler to invocation scoped state within the container.
+ /**
+ * <p>
+ * Authorization protected method that may be used to associate a thread-scoped handler data object with the
+ * PolicyContext. The handler data object will be made available to handlers, where it can serve to supply or bind
+ * the handler to invocation scoped state within the container.
+ * </p>
*
- * @param data - a container-specific object that will be associated with the
- * calling thread and passed to any handler activated by a Policy provider
- * (on the thread). The value null is a legitimate value for this parameter,
- * and is the value that will be used in the activation of handlers if the
- * setHandlerData has not been called on the thread.
- * @throws SecurityException - if the caller does not have the
- * SecurityPermission("setPolicy") permission.
+ * @param data
+ * - a container-specific object that will be associated with the calling thread and passed to any handler
+ * activated by a {@code Policy} provider (on the thread). The value null is a legitimate value for this
+ * parameter, and is the value that will be used in the activation of handlers if the {@code
+ * setHandlerData} has not been called on the thread.
+ * @throws SecurityException
+ * - if the calling {@code AccessControlContext} is not authorized by the container to call this method.
*/
public static void setHandlerData(Object data)
{
@@ -228,6 +248,11 @@
handlerDataLocal.set(data);
}
+ /**
+ * <p>
+ * Private constructor.
+ * </p>
+ */
private PolicyContext()
{
}
Modified: projects/specs/trunk/jboss-jacc-api_1.4_spec/src/main/java/javax/security/jacc/PolicyContextException.java
===================================================================
--- projects/specs/trunk/jboss-jacc-api_1.1_spec/src/main/java/javax/security/jacc/PolicyContextException.java 2010-03-18 18:33:02 UTC (rev 102575)
+++ projects/specs/trunk/jboss-jacc-api_1.4_spec/src/main/java/javax/security/jacc/PolicyContextException.java 2010-03-22 19:15:14 UTC (rev 102732)
@@ -1,54 +1,99 @@
/*
-* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
-* by the @authors tag. See the copyright.txt in the distribution for a
-* full listing of individual contributors.
-*
-* This is free software; you can redistribute it and/or modify it
-* under the terms of the GNU Lesser General Public License as
-* published by the Free Software Foundation; either version 2.1 of
-* the License, or (at your option) any later version.
-*
-* This software is distributed in the hope that it will be useful,
-* but WITHOUT ANY WARRANTY; without even the implied warranty of
-* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-* Lesser General Public License for more details.
-*
-* You should have received a copy of the GNU Lesser General Public
-* License along with this software; if not, write to the Free
-* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
-* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
-*/
+ * JBoss, Home of Professional Open Source. Copyright 2010, Red Hat Middleware
+ * LLC, and individual contributors as indicated by the @author tags. See the
+ * copyright.txt file in the distribution for a full listing of individual
+ * contributors.
+ *
+ * This is free software; you can redistribute it and/or modify it under the
+ * terms of the GNU Lesser General Public License as published by the Free
+ * Software Foundation; either version 2.1 of the License, or (at your option)
+ * any later version.
+ *
+ * This software is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this software; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA, or see the FSF
+ * site: http://www.fsf.org.
+ */
package javax.security.jacc;
-/** This checked exception is thrown by the policy context and configuration
- * classes.
+/**
+ * <p>
+ * This checked exception is thrown by implementations of the {@code javax.security.jacc.PolicyConfiguration} interface,
+ * the {@code javax.security.jacc.PolicyConfigurationFactory} abstract class, the {@code
+ * javax.security.jacc.PolicyContext} utility class, and implementations of the {@code
+ * javax.security.jacc.PolicyContextException} interface.
+ * </p>
*
- * @see http://java.sun.com/j2ee/1.4/docs/api/
- * @see javax.security.jacc.PolicyConfiguration
- * @see javax.security.jacc.PolicyConfigurationFactory
- * @see javax.security.jacc.PolicyContext
+ * <p>
+ * This exception is used by javax.security.jacc implementation classes to re-throw checked exceptions occurring within
+ * an implementation that are not declared by the interface or class being implemented.
+ * </p>
*
- * @author Scott.Stark at jboss.org
- * @author Ron Monzillo, Gary Ellison (javadoc)
- * @version $Revision$
+ * @author <a href="mailto:scott.stark at jboss.org">Scott Stark</a>
+ * @author <a href="mailto:sguilhen at redhat.com">Stefan Guilhen</a>
+ * @see {@link Exception}, {@link PolicyConfiguration}, {@link PolicyConfigurationFactory}, {@link PolicyContext},
+ * {@link PolicyContextHandler}
*/
public class PolicyContextException extends Exception
{
+ private static final long serialVersionUID = 3925692572777572935L;
+
+ /**
+ * <p>
+ * Constructs a new PolicyContextException with null as its detail message. describing the cause of the exception.
+ * </p>
+ */
public PolicyContextException()
{
}
+ /**
+ * <p>
+ * Constructs a new {@code PolicyContextException} with the specified detail message.
+ * </p>
+ *
+ * @param msg
+ * - a {@code String} containing a detail message describing the cause of the exception.
+ */
public PolicyContextException(String msg)
{
super(msg);
}
+ /**
+ * <p>
+ * Constructs a new {@code PolicyContextException} with the specified detail message and cause. The cause will be
+ * encapsulated in the constructed exception.
+ * </p>
+ *
+ * @param msg
+ * - a {@code String} containing a detail message describing the cause of the exception.
+ * @param cause
+ * - the {@code Throwable} that is “causing” this exception to be constructed. A null value is permitted,
+ * and the value passed through this parameter may subsequently be retrieved by calling {@code getCause()}
+ * on the constructed exception.
+ */
public PolicyContextException(String msg, Throwable cause)
{
super(msg, cause);
}
+ /**
+ * <p>
+ * Constructs a new {@code PolicyContextException} with the specified cause. The cause will be encapsulated in the
+ * constructed exception.
+ * </p>
+ *
+ * @param cause
+ * - the {@code Throwable} that is “causing” this exception to be constructed. A null value is permitted,
+ * and the value passed through this parameter may subsequently be retrieved by calling {@code getCause()}
+ * on the constructed exception.
+ */
public PolicyContextException(Throwable cause)
{
super(cause);
Modified: projects/specs/trunk/jboss-jacc-api_1.4_spec/src/main/java/javax/security/jacc/PolicyContextHandler.java
===================================================================
--- projects/specs/trunk/jboss-jacc-api_1.1_spec/src/main/java/javax/security/jacc/PolicyContextHandler.java 2010-03-18 18:33:02 UTC (rev 102575)
+++ projects/specs/trunk/jboss-jacc-api_1.4_spec/src/main/java/javax/security/jacc/PolicyContextHandler.java 2010-03-22 19:15:14 UTC (rev 102732)
@@ -1,72 +1,100 @@
/*
-* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
-* by the @authors tag. See the copyright.txt in the distribution for a
-* full listing of individual contributors.
-*
-* This is free software; you can redistribute it and/or modify it
-* under the terms of the GNU Lesser General Public License as
-* published by the Free Software Foundation; either version 2.1 of
-* the License, or (at your option) any later version.
-*
-* This software is distributed in the hope that it will be useful,
-* but WITHOUT ANY WARRANTY; without even the implied warranty of
-* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-* Lesser General Public License for more details.
-*
-* You should have received a copy of the GNU Lesser General Public
-* License along with this software; if not, write to the Free
-* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
-* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
-*/
+ * JBoss, Home of Professional Open Source. Copyright 2010, Red Hat Middleware
+ * LLC, and individual contributors as indicated by the @author tags. See the
+ * copyright.txt file in the distribution for a full listing of individual
+ * contributors.
+ *
+ * This is free software; you can redistribute it and/or modify it under the
+ * terms of the GNU Lesser General Public License as published by the Free
+ * Software Foundation; either version 2.1 of the License, or (at your option)
+ * any later version.
+ *
+ * This software is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this software; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA, or see the FSF
+ * site: http://www.fsf.org.
+ */
package javax.security.jacc;
-/** JACC interface which defines the methods that must be implemented by
- * handlers that are to be registered and activated by PolicyContexts
+/**
+ * <p>
+ * This interface defines the methods that must be implemented by handlers that are to be registered and activated by
+ * the {@code PolicyContext} class. {@code The PolicyContext} class provides methods for containers to register and
+ * activate container-specific {@code PolicyContext} handlers. {@code Policy} providers use the {@code PolicyContext}
+ * 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} class must implement the {@code
+ * PolicyContextHandler} interface.
+ * </p>
*
- * @see http://java.sun.com/j2ee/1.4/docs/api/
- *
- * @author Scott.Stark at jboss.org
- * @author Ron Monzillo, Gary Ellison (javadoc)
- * @version $Revision$
+ * @author <a href="mailto:scott.stark at jboss.org">Scott Stark</a>
+ * @author <a href="mailto:sguilhen at redhat.com">Stefan Guilhen</a>
*/
public interface PolicyContextHandler
{
- /** Used by the PolicyContext class to activate the handler and obtain from
- * it the context object identified by the given key. In addition
- * to the key, the handler will be activated with the handler data value
- * associated within the PolicyContext class with the thread on which the
- * call to this method is made.
- *
- * @param key - a non-null key indicating which context to return.
- * @param data - the possiblye null handler data Object associated with the
- * thread on which the call to this method has been made.
- * @return The container and handler specific Object containing the desired
- * context. A null value may be returned if the value of the corresponding
- * context is null.
+ /**
+ * <p>
+ * This public method is used by the {@code PolicyContext} class to activate the handler and obtain from it 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} class with the thread on which the call to this
+ * method is made.
+ * </p>
+ *
+ * <p>
+ * Note that the policy context identifier associated with a thread is available to the handler by calling {@code
+ * PolicyContext.getContextID()}.
+ * </p>
+ *
+ * @param key
+ * - a {@code String} that identifies the context object to be returned by the handler. The value of this
+ * parameter must not be null.
+ * @param data
+ * - the handler data {@code Object} associated with the thread on which the call to this method has been
+ * made. Note that the value passed through this parameter may be {@code null}.
+ * @return The container and handler specific {@code Object} containing the desired context. A {@code null} value may
+ * be returned if the value of the corresponding context is {@code null}.
* @throws PolicyContextException
- */
- public Object getContext(String key, Object data)
- 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 {@code PolicyContextException}.
+ */
+ public Object getContext(String key, Object data) throws PolicyContextException;
- /** Get the keys identifying the context objects supported by this handlers
- * getContext(String, Object) method.
- * The value of each key supported by a handler must be a non-null String
- * value.
+ /**
+ * <p>
+ * 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 {@code String} value.
+ * </p>
*
- * @return the list of supported context object keys.
+ * @return an array containing {@code String} values identifying 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
- */
- public String[] getKeys()
- 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 {@code PolicyContextException}.
+ */
+ public String[] getKeys() throws PolicyContextException;
- /** Query the handler to see if its getContext(String, Object) method
- * supports the given key.
+ /**
+ * <p>
+ * This public method returns a boolean result indicating whether or not the handler supports the context object
+ * identified by the (case-sensitive) key value.
+ * </p>
*
- * @param key - the context object key to check.
- * @return true if the key is supported, false otherwise
+ * @param key
+ * - a {@code String} 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
- */
- public boolean supports(String key)
- 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 {@code PolicyContextException}.
+ */
+ public boolean supports(String key) throws PolicyContextException;
}
Modified: projects/specs/trunk/jboss-jacc-api_1.4_spec/src/main/java/javax/security/jacc/URLPattern.java
===================================================================
--- projects/specs/trunk/jboss-jacc-api_1.1_spec/src/main/java/javax/security/jacc/URLPattern.java 2010-03-18 18:33:02 UTC (rev 102575)
+++ projects/specs/trunk/jboss-jacc-api_1.4_spec/src/main/java/javax/security/jacc/URLPattern.java 2010-03-22 19:15:14 UTC (rev 102732)
@@ -1,104 +1,152 @@
/*
-* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
-* by the @authors tag. See the copyright.txt in the distribution for a
-* full listing of individual contributors.
-*
-* This is free software; you can redistribute it and/or modify it
-* under the terms of the GNU Lesser General Public License as
-* published by the Free Software Foundation; either version 2.1 of
-* the License, or (at your option) any later version.
-*
-* This software is distributed in the hope that it will be useful,
-* but WITHOUT ANY WARRANTY; without even the implied warranty of
-* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-* Lesser General Public License for more details.
-*
-* You should have received a copy of the GNU Lesser General Public
-* License along with this software; if not, write to the Free
-* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
-* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
-*/
+ * JBoss, Home of Professional Open Source. Copyright 2010, Red Hat Middleware
+ * LLC, and individual contributors as indicated by the @author tags. See the
+ * copyright.txt file in the distribution for a full listing of individual
+ * contributors.
+ *
+ * This is free software; you can redistribute it and/or modify it under the
+ * terms of the GNU Lesser General Public License as published by the Free
+ * Software Foundation; either version 2.1 of the License, or (at your option)
+ * any later version.
+ *
+ * This software is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this software; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA, or see the FSF
+ * site: http://www.fsf.org.
+ */
package javax.security.jacc;
-/** The representation of a URLPattern in the WebResourcePermission and
- * WebUserDataPermission URLPatternSpecs.
- *
- * @author Scott.Stark at jboss.org
- * @version $Revison:$
+/**
+ * <p>
+ * The representation of a <b>URLPattern</b> in the {@code WebResourcePermission} and {@code WebUserDataPermission}
+ * <b>URLPatternSpecs</b>.
+ * </p>
+ *
+ * @author <a href="mailto:scott.stark at jboss.org">Scott Stark</a>
+ * @author <a href="mailto:sguilhen at redhat.com">Stefan Guilhen</a>
+ * @see {@link WebResourcePermission}, {@link WebUserDataPermission}
*/
class URLPattern
{
- /** the '/' pattern */
- static final int DEFAULT = 0;
- /** the '/*' pattern */
- static final int THE_PATH_PREFIX = 1;
- /** a '/.../*' pattern */
- static final int PATH_PREFIX = 2;
- /** a '*.xxx' pattern */
- static final int EXTENSION = 3;
- /** an exact pattern */
- static final int EXACT = 4;
+ private enum PatternType {
+ /** the '/' pattern */
+ DEFAULT,
+ /** the '/*' pattern */
+ THE_PATH_PREFIX,
+ /** a '/.../*' pattern */
+ PATH_PREFIX,
+ /** a '*.xxx' pattern */
+ EXTENSION,
+ /** an exact pattern */
+ EXACT
+ };
private String pattern;
+
private String ext;
+
private int length;
- private int type = -1;
+ private PatternType type;
+
+ /**
+ * <p>
+ * Creates a {@code URLPattern} instance from the specified pattern {@code String}.
+ * </p>
+ *
+ * @param pattern
+ * the pattern {@code String}.
+ */
URLPattern(String pattern)
{
this.pattern = pattern;
length = pattern.length();
- if( pattern.equals("/") )
- type = DEFAULT;
- else if( pattern.startsWith("/*") )
- type = THE_PATH_PREFIX;
- else if( length > 0 && pattern.charAt(0) == '/' && pattern.endsWith("/*") )
- type = PATH_PREFIX;
- else if( pattern.startsWith("*.") )
+ if (pattern.equals("/"))
+ type = PatternType.DEFAULT;
+ else if (pattern.startsWith("/*"))
+ type = PatternType.THE_PATH_PREFIX;
+ else if (length > 0 && pattern.charAt(0) == '/' && pattern.endsWith("/*"))
+ type = PatternType.PATH_PREFIX;
+ else if (pattern.startsWith("*."))
{
- type = EXTENSION;
+ type = PatternType.EXTENSION;
ext = pattern.substring(1);
}
else
- type = EXACT;
+ type = PatternType.EXACT;
}
- /** The matching rules from the WebResourcePermission implies:
-
- 1. their pattern values are String equivalent, or
- 2. this pattern is the path-prefix pattern "/*", or
- 3. this pattern is a path-prefix pattern (that is, it starts with "/" and ends
- with "/*") and the argument pattern starts with the substring of this
- pattern, minus its last 2 characters, and the next character of the
- argument pattern, if there is one, is "/", or
- 4. this pattern is an extension pattern (that is, it starts with "*.") and the
- argument pattern ends with this pattern, or
- 5. the reference pattern is the special default pattern, "/", which matches all
- argument patterns.
- */
+ /**
+ * <p>
+ * Checks if this pattern matches the specified {@code URLPattern}.
+ * </p>
+ *
+ * <p>
+ * The matching rules from the {@code WebResourcePermission#implies}:
+ * <ol>
+ * <li>their pattern values are {@code String} equivalent, or</li>
+ * <li>this pattern is the path-prefix pattern "/*", or</li>
+ * <li>this pattern is a path-prefix pattern (that is, it starts with "/" and ends with "/*") and the argument
+ * pattern starts with the substring of this pattern, minus its last 2 characters, and the next character of the
+ * argument pattern, if there is one, is "/", or</li>
+ * <li>this pattern is an extension pattern (that is, it starts with "*.") and the argument pattern ends with this
+ * pattern, or 5. the reference pattern is the special default pattern, "/", which matches all argument patterns.</li>
+ * </ol>
+ * </p>
+ *
+ * @param url
+ * the {@code URLPattern} instance to which this pattern is to be matched.
+ * @return {@code true} if this pattern matches the specified {@code URLPattern}; {@code false} otherwise.
+ */
boolean matches(URLPattern url)
{
return matches(url.pattern);
}
+ /**
+ * <p>
+ * Checks if this pattern matches the specified pattern String.
+ * </p>
+ *
+ * <p>
+ * The matching rules from the {@code WebResourcePermission#implies}:
+ * <ol>
+ * <li>their pattern values are {@code String} equivalent, or</li>
+ * <li>this pattern is the path-prefix pattern "/*", or</li>
+ * <li>this pattern is a path-prefix pattern (that is, it starts with "/" and ends with "/*") and the argument
+ * pattern starts with the substring of this pattern, minus its last 2 characters, and the next character of the
+ * argument pattern, if there is one, is "/", or</li>
+ * <li>this pattern is an extension pattern (that is, it starts with "*.") and the argument pattern ends with this
+ * pattern, or 5. the reference pattern is the special default pattern, "/", which matches all argument patterns.</li>
+ * </ol>
+ * </p>
+ *
+ * @param urlPattern
+ * a {@code String} representing the pattern to which this pattern is to be matched.
+ * @return {@code true} if this pattern matches the specified {@code URLPattern}; {@code false} otherwise.
+ */
boolean matches(String urlPattern)
{
// 2 or 5
- if( type == DEFAULT || type == THE_PATH_PREFIX )
+ if (type == PatternType.DEFAULT || type == PatternType.THE_PATH_PREFIX)
return true;
// 4, extension pattern
- if( type == EXTENSION && urlPattern.endsWith(ext) )
+ if (type == PatternType.EXTENSION && urlPattern.endsWith(ext))
return true;
// 3. a path-prefix pattern
- if( type == PATH_PREFIX )
+ if (type == PatternType.PATH_PREFIX)
{
- if( urlPattern.regionMatches(0,pattern, 0, length-2) )
+ if (urlPattern.regionMatches(0, pattern, 0, length - 2))
{
int last = length - 2;
- if( urlPattern.length() > last && urlPattern.charAt(last) != '/' )
+ if (urlPattern.length() > last && urlPattern.charAt(last) != '/')
return false;
return true;
}
@@ -106,44 +154,98 @@
}
// 1. pattern values are String equivalent for exact pattern
- if( pattern.equals(urlPattern) )
+ if (pattern.equals(urlPattern))
return true;
return false;
}
+ /**
+ * <p>
+ * Obtains the {@code String} representation of this pattern.
+ * </p>
+ *
+ * @return this pattern's {@code String} representation.
+ */
String getPattern()
{
- return pattern;
+ return this.pattern;
}
+
+ /**
+ * <p>
+ * Checks if this pattern is a default (i.e. '/') pattern.
+ * </p>
+ *
+ * @return {@code true} if this is a default pattern; {@code false} otherwise.
+ */
boolean isDefault()
{
- return type == DEFAULT;
+ return this.type == PatternType.DEFAULT;
}
+
+ /**
+ * <p>
+ * Checks if this pattern is an exact pattern.
+ * </p>
+ *
+ * @return {@code true} if this is an exact pattern; {@code false} otherwise.
+ */
boolean isExact()
{
- return type == EXACT;
+ return this.type == PatternType.EXACT;
}
+
+ /**
+ * <p>
+ * Checks if this pattern is an extension (i.e. '*.xxx') pattern.
+ * </p>
+ *
+ * @return {@code true} if this is an extension pattern; {@code false} otherwise.
+ */
boolean isExtension()
{
- return type == EXTENSION;
+ return this.type == PatternType.EXTENSION;
}
+
+ /**
+ * <p>
+ * Checks if this pattern is a prefix (i.e. '/*' or '/.../*') pattern.
+ * </p>
+ *
+ * @return {@code true} if this is a prefix pattern; {@code false} otherwise.
+ */
boolean isPrefix()
{
- return type == THE_PATH_PREFIX || type == PATH_PREFIX;
+ return this.type == PatternType.THE_PATH_PREFIX || this.type == PatternType.PATH_PREFIX;
}
+ /*
+ * (non-Javadoc)
+ *
+ * @see java.lang.Object#hashCode()
+ */
+ @Override
public int hashCode()
{
- return pattern.hashCode();
+ return this.pattern.hashCode();
}
- boolean equals(URLPattern p)
+ /*
+ * (non-Javadoc)
+ *
+ * @see java.lang.Object#equals(java.lang.Object)
+ */
+ @Override
+ public boolean equals(Object o)
{
- boolean equals = type == p.type;
- if( equals )
+ if (o instanceof URLPattern == false)
+ return false;
+ URLPattern pattern = (URLPattern) o;
+ boolean equals = this.type == pattern.type;
+ if (equals)
{
- equals = pattern.equals(p.pattern);
+ equals = this.pattern.equals(pattern.pattern);
}
return equals;
}
Modified: projects/specs/trunk/jboss-jacc-api_1.4_spec/src/main/java/javax/security/jacc/URLPatternSpec.java
===================================================================
--- projects/specs/trunk/jboss-jacc-api_1.1_spec/src/main/java/javax/security/jacc/URLPatternSpec.java 2010-03-18 18:33:02 UTC (rev 102575)
+++ projects/specs/trunk/jboss-jacc-api_1.4_spec/src/main/java/javax/security/jacc/URLPatternSpec.java 2010-03-22 19:15:14 UTC (rev 102732)
@@ -1,236 +1,240 @@
/*
-* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
-* by the @authors tag. See the copyright.txt in the distribution for a
-* full listing of individual contributors.
-*
-* This is free software; you can redistribute it and/or modify it
-* under the terms of the GNU Lesser General Public License as
-* published by the Free Software Foundation; either version 2.1 of
-* the License, or (at your option) any later version.
-*
-* This software is distributed in the hope that it will be useful,
-* but WITHOUT ANY WARRANTY; without even the implied warranty of
-* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-* Lesser General Public License for more details.
-*
-* You should have received a copy of the GNU Lesser General Public
-* License along with this software; if not, write to the Free
-* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
-* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
-*/
+ * JBoss, Home of Professional Open Source. Copyright 2010, Red Hat Middleware
+ * LLC, and individual contributors as indicated by the @author tags. See the
+ * copyright.txt file in the distribution for a full listing of individual
+ * contributors.
+ *
+ * This is free software; you can redistribute it and/or modify it under the
+ * terms of the GNU Lesser General Public License as published by the Free
+ * Software Foundation; either version 2.1 of the License, or (at your option)
+ * any later version.
+ *
+ * This software is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this software; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA, or see the FSF
+ * site: http://www.fsf.org.
+ */
package javax.security.jacc;
import java.util.HashSet;
-import java.util.StringTokenizer;
-import java.util.Iterator;
-/** Encapsulation of the URLPatternSpec defined in the WebResourcePermission
- * and WebUserDataPermission.
+/**
+ * <p>
+ * Encapsulation of the <b>URLPatternSpec</b> defined in the {@code WebResourcePermission} and {@code
+ * WebUserDataPermission} classes.
+ * </p>
*
- * @link WebResourcePermission(String, String)
- * @link WebUserDataPermission(String, String)
- *
- * @author Scott.Stark at jboss.org
- * @version $Revison:$
+ * @author <a href="mailto:scott.stark at jboss.org">Scott Stark</a>
+ * @author <a href="mailto:sguilhen at redhat.com">Stefan Guilhen</a>
+ * @see {@link WebResourcePermission}, {@link WebUserDataPermission}
*/
class URLPatternSpec
{
- /** The first or only URLPattern in the spec */
+ /** The first or only URLPattern in the specification */
URLPattern urlPattern;
+
/** */
- HashSet urlPatternList;
+ HashSet<URLPattern> urlPatternList;
- /** The spec contains a URLPatternSpec that identifies the web resources to
- which the permissions applies. The syntax of a URLPatternSpec is as follows:
-
- URLPatternList ::= URLPattern | URLPatternList colon URLPattern
- URLPatternSpec ::= null | URLPattern | URLPattern colon URLPatternList
-
- A null URLPatternSpec is translated to the default URLPattern, "/", by the
- permission constructor. The empty string is an exact URLPattern, and may
- occur anywhere in a URLPatternSpec that an exact URLPattern may occur. The
- first URLPattern in a URLPatternSpec may be any of the pattern types, exact,
- path-prefix, extension, or default as defined in the Java Servlet
- Specification). When a URLPatternSpec includes a URLPatternList, the
- patterns of the URLPatternList identify the resources to which the
- permission does NOT apply and depend on the pattern type and value of the
- first pattern as follows:
-
- - No pattern may exist in the URLPatternList that matches the first pattern.
- - If the first pattern is a path-prefix pattern, only exact patterns matched
- by the first pattern and path-prefix patterns matched by, but different
- from, the first pattern may occur in the URLPatternList.
- - If the first pattern is an extension pattern, only exact patterns that are
- matched by the first pattern and path-prefix patterns may occur in the
- URLPatternList.
- - If the first pattern is the default pattern, "/", any pattern except the
- default pattern may occur in the URLPatternList.
- - If the first pattern is an exact pattern a URLPatternList must not be
- present in the URLPatternSpec.
-
- @param spec
- */
+ /**
+ * <p>
+ * The specification contains a {@code URLPatternSpec} that identifies the web resources to which the permissions
+ * applies. The syntax of a {@code URLPatternSpec} is as follows:
+ * </p>
+ *
+ * <pre>
+ * URLPatternList ::= URLPattern | URLPatternList colon URLPattern
+ * URLPatternSpec ::= null | URLPattern | URLPattern colon URLPatternList
+ * </pre>
+ *
+ * <p>
+ * A null {@code URLPatternSpec} is translated to the default {@code URLPattern}, "/", by the permission constructor.
+ * The empty string is an exact {@code URLPattern}, and may occur anywhere in a {@code URLPatternSpec} that an exact
+ * {@code URLPattern} may occur. The first {@code URLPattern} in a {@code URLPatternSpec} may be any of the pattern
+ * types, exact, path-prefix, extension, or default as defined in the Java Servlet Specification). When a {@code
+ * URLPatternSpec} includes a {@code URLPatternList}, the patterns of the {@code URLPatternList} identify the
+ * resources to which the permission does NOT apply and depend on the pattern type and value of the first pattern as
+ * follows:
+ * <ul>
+ * <li>No pattern may exist in the {@code URLPatternList} that matches the first pattern.</li>
+ * <li>If the first pattern is a path-prefix pattern, only exact patterns matched by the first pattern and
+ * path-prefix patterns matched by, but different from, the first pattern may occur in the {@code URLPatternList}.</li>
+ * <li>If the first pattern is an extension pattern, only exact patterns that are matched by the first pattern and
+ * path-prefix patterns may occur in the {@code URLPatternList}.</li>
+ * <li>If the first pattern is the default pattern, "/", any pattern except the default pattern may occur in the
+ * {@code URLPatternList}.</li>
+ * <li>If the first pattern is an exact pattern a {@code URLPatternList} must not be present in the {@code
+ * URLPatternSpec}.</li>
+ * </ul>
+ * </p>
+ *
+ * @param spec
+ * the {@code String} representation of the {@code URLPatternSpec} as defined by the JACC specification.
+ */
URLPatternSpec(String spec)
{
- if( spec == null )
- urlPattern = new URLPattern("/");
- else if( spec.indexOf(':') > 0 )
+ if (spec == null)
+ this.urlPattern = new URLPattern("/");
+ else if (spec.indexOf(WebResourcePermission.ENCODED_COLON) > 0)
{
- StringTokenizer tokenizer = new StringTokenizer(spec, ":");
- urlPatternList = new HashSet();
- while( tokenizer.hasMoreTokens() )
+ String[] patterns = spec.split(WebResourcePermission.ENCODED_COLON);
+ this.urlPatternList = new HashSet<URLPattern>();
+ for (String pattern : patterns)
{
- String pattern = tokenizer.nextToken();
URLPattern p = new URLPattern(pattern);
- if( urlPattern == null )
- urlPattern = p;
+ if (this.urlPattern == null)
+ this.urlPattern = p;
else
{
// Enforce the constraints
- if( p.matches(urlPattern) )
+ if (p.matches(this.urlPattern))
{
- /* No pattern may exist in the URLPatternList that matches
- the first pattern.
- */
- String msg = "1: URLPatternList item: "+pattern+" matches: "
- +urlPattern.getPattern();
+ /*
+ * No pattern may exist in the URLPatternList that matches the first pattern.
+ */
+ String msg = "1: URLPatternList item: " + pattern + " matches: " + this.urlPattern.getPattern();
throw new IllegalArgumentException(msg);
}
- else if( urlPattern.isPrefix() )
+ else if (this.urlPattern.isPrefix())
{
- /* If the first pattern is a path-prefix pattern, only exact
- patterns matched by the first pattern and path-prefix patterns
- matched by, but different from, the first pattern may occur
- in the URLPatternList.
- */
- if( p.isPrefix() == false && p.isExact() == false )
+ /*
+ * If the first pattern is a path-prefix pattern, only exact patterns matched by the first pattern and
+ * path-prefix patterns matched by, but different from, the first pattern may occur in the
+ * URLPatternList.
+ */
+ if (p.isPrefix() == false && p.isExact() == false)
{
- String msg = "2: URLPatternList item: "+pattern+
- " is not an exact or prefix pattern";
+ String msg = "2: URLPatternList item: " + pattern + " is not an exact or prefix pattern";
throw new IllegalArgumentException(msg);
}
}
- else if( urlPattern.isExtension() )
+ else if (this.urlPattern.isExtension())
{
- /* If the first pattern is an extension pattern, only exact
- patterns that are matched by the first pattern and path-prefix
- patterns may occur in the URLPatternList.
- */
- if( p.isPrefix() == false && p.isExact() == false )
+ /*
+ * If the first pattern is an extension pattern, only exact patterns that are matched by the first
+ * pattern and path-prefix patterns may occur in the URLPatternList.
+ */
+ if (p.isPrefix() == false && p.isExact() == false)
{
- String msg = "3: URLPatternList item: "+pattern+
- " is not an exact or prefix pattern";
+ String msg = "3: URLPatternList item: " + pattern + " is not an exact or prefix pattern";
throw new IllegalArgumentException(msg);
}
}
- else if( urlPattern.isDefault() )
+ else if (this.urlPattern.isDefault())
{
- /* If the first pattern is the default pattern, "/", any
- pattern except the default pattern may occur in the
- URLPatternList.
- */
- if( p.isDefault() )
+ /*
+ * If the first pattern is the default pattern, "/", any pattern except the default pattern may occur
+ * in the URLPatternList.
+ */
+ if (p.isDefault())
{
- String msg = "4: URLPatternList item: "+pattern+
- " cannot be the default pattern";
+ String msg = "4: URLPatternList item: " + pattern + " cannot be the default pattern";
throw new IllegalArgumentException(msg);
}
}
- else if( urlPattern.isExact() )
+ else if (this.urlPattern.isExact())
{
- /* If the first pattern is an exact pattern a URLPatternList
- must not be present in the URLPatternSpec.
- */
- String msg = "5: URLPatternList item: "+pattern+
- " is not allowed in an exact pattern";
+ /*
+ * If the first pattern is an exact pattern a URLPatternList must not be present in the
+ * URLPatternSpec.
+ */
+ String msg = "5: URLPatternList item: " + pattern + " is not allowed in an exact pattern";
throw new IllegalArgumentException(msg);
}
- urlPatternList.add(p);
+ this.urlPatternList.add(p);
}
}
}
else
{
- urlPattern = new URLPattern(spec);
+ this.urlPattern = new URLPattern(spec);
}
}
- /** Perform the permission URLPattern matching
- - The first URLPattern in the name of the argument permission is matched
- by the first URLPattern in the name of this permission.
- - The first URLPattern in the name of the argument permission is NOT
- matched by any URLPattern in the URLPatternList of the URLPatternSpec
- of this permission.
- - If the first URLPattern in the name of the argument permission matches
- the first URLPattern in the URLPatternSpec of this permission, then every
- URLPattern in the URLPatternList of the URLPatternSpec of this permission
- is matched by a URLPattern in the URLPatternList of the argument permission.
-
- URLPattern matching is performed using the Servlet matching rules where
- two URL patterns match if they are related as follows:
- - their pattern values are String equivalent, or
- - this pattern is the path-prefix pattern "/*", or
- - this pattern is a path-prefix pattern (that is, it starts with "/" and
- ends with "/*") and the argument pattern starts with the substring of this
- pattern, minus its last 2 characters, and the next character of the argument
- pattern, if there is one, is "/", or
- - this pattern is an extension pattern (that is, it starts with "*.") and
- the argument pattern ends with this pattern, or
- - the reference pattern is the special default pattern, "/", which matches
- all argument patterns.
-
- All of the comparisons described above are case sensitive.
- @param spec
- @return true if this implies spec, false otherwise
- */
+ /**
+ * <p>
+ * Perform the permission {@code URLPattern} matching:
+ * <ul>
+ * <li>the first {@code URLPattern} in the name of the argument permission is matched by the first {@code URLPattern}
+ * in the name of this permission.</li>
+ * <li>the first {@code URLPattern} in the name of the argument permission is NOT matched by any {@code URLPattern}
+ * in the {@code URLPatternList} of the {@code URLPatternSpec} of this permission.</li>
+ * <li>if the first {@code URLPattern} in the name of the argument permission matches the first {@code URLPattern} in
+ * the {@code URLPatternSpec} of this permission, then every {@code URLPattern} in the {@code URLPatternList} of the
+ * {@code URLPatternSpec} of this permission is matched by a {@code URLPattern} in the {@code URLPatternList} of the
+ * argument permission.</li>
+ * </ul>
+ * </p>
+ *
+ * <p>
+ * {@code URLPattern} matching is performed using the Servlet matching rules where two {@code URL} patterns match if
+ * they are related as follows:
+ * <ul>
+ * <li>their pattern values are {@code String} equivalent, or</li>
+ * <li>this pattern is the path-prefix pattern "/*", or</li>
+ * <li>this pattern is a path-prefix pattern (that is, it starts with "/" and ends with "/*") and the argument
+ * pattern starts with the substring of this pattern, minus its last 2 characters, and the next character of the
+ * argument pattern, if there is one, is "/", or</li>
+ * <li>this pattern is an extension pattern (that is, it starts with "*.") and the argument pattern ends with this
+ * pattern, or</li>
+ * <li>the reference pattern is the special default pattern, "/", which matches all argument patterns.</li>
+ * </ul>
+ * </p>
+ *
+ * <p>
+ * All of the comparisons described above are case sensitive.
+ * </p>
+ *
+ * @param spec
+ * the {@code URLPatternSpec} to which this {@code URLPatternSpec} is to be compared.
+ * @return {@code true} if this implies spec; {@code false} otherwise.
+ */
boolean implies(URLPatternSpec spec)
{
- /* The first URLPattern in the name of the argument permission is matched
- by the first URLPattern in the name of this permission.
- */
- boolean implies = urlPattern.matches(spec.urlPattern);
- if( implies )
+ /*
+ * The first URLPattern in the name of the argument permission is matched by the first URLPattern in the name of
+ * this permission.
+ */
+ boolean implies = this.urlPattern.matches(spec.urlPattern);
+ if (implies)
{
- /* The first URLPattern in the name of the argument permission is NOT
- matched by any URLPattern in the URLPatternList of the URLPatternSpec
- of this permission.
- */
- if( urlPatternList != null )
+ /*
+ * The first URLPattern in the name of the argument permission is NOT matched by any URLPattern in the
+ * URLPatternList of the URLPatternSpec of this permission.
+ */
+ if (this.urlPatternList != null)
{
- Iterator iter = urlPatternList.iterator();
- while( iter.hasNext() )
+ for (URLPattern p : this.urlPatternList)
{
- URLPattern p = (URLPattern) iter.next();
- if( p.matches(spec.urlPattern) )
+ if (p.matches(spec.urlPattern))
return false;
}
}
- /* If the first URLPattern in the name of the argument permission
- matches the first URLPattern in the URLPatternSpec of this permission,
- then every URLPattern in the URLPatternList of the URLPatternSpec of
- this permission is matched by a URLPattern in the URLPatternList of the
- argument permission.
- */
- if( urlPatternList != null && spec.urlPatternList != null )
+ /*
+ * If the first URLPattern in the name of the argument permission matches the first URLPattern in the
+ * URLPatternSpec of this permission, then every URLPattern in the URLPatternList of the URLPatternSpec of this
+ * permission is matched by a URLPattern in the URLPatternList of the argument permission.
+ */
+ if (this.urlPatternList != null && spec.urlPatternList != null)
{
- Iterator iter = urlPatternList.iterator();
- while( iter.hasNext() )
+ for (URLPattern p : this.urlPatternList)
{
- URLPattern p = (URLPattern) iter.next();
boolean hasMatch = false;
- Iterator iter2 = spec.urlPatternList.iterator();
- while( iter2.hasNext() )
+ for (URLPattern p2 : spec.urlPatternList)
{
- URLPattern p2 = (URLPattern) iter2.next();
- if( p.matches(p2) )
+ if (p.matches(p2))
{
hasMatch = true;
break;
}
}
- if( hasMatch == false )
+ if (hasMatch == false)
return false;
}
}
@@ -238,24 +242,39 @@
return implies;
}
- int hash()
+ /*
+ * (non-Javadoc)
+ *
+ * @see java.lang.Object#hashCode()
+ */
+ @Override
+ public int hashCode()
{
- int hashCode = urlPattern.hashCode();
- if( urlPatternList != null )
- hashCode += urlPatternList.hashCode();
- return hashCode;
+ int result = 17;
+ result = 37 * result + this.urlPattern.hashCode();
+ if (this.urlPatternList != null)
+ result = 37 * result + this.urlPatternList.hashCode();
+ return result;
}
- boolean equals(URLPatternSpec spec)
+ /*
+ * (non-Javadoc)
+ *
+ * @see java.lang.Object#equals(java.lang.Object)
+ */
+ @Override
+ public boolean equals(Object obj)
{
- if( urlPattern.equals(spec.urlPattern) == true )
+ if (obj instanceof URLPatternSpec == false)
+ return false;
+ URLPatternSpec other = (URLPatternSpec) obj;
+ if (this.urlPattern.equals(other.urlPattern) == true)
{
- if( urlPatternList == null || urlPatternList.equals(spec.urlPatternList) )
+ if (this.urlPatternList == null || this.urlPatternList.equals(other.urlPatternList))
{
return true;
}
}
-
return false;
}
}
Modified: projects/specs/trunk/jboss-jacc-api_1.4_spec/src/main/java/javax/security/jacc/WebResourcePermission.java
===================================================================
--- projects/specs/trunk/jboss-jacc-api_1.1_spec/src/main/java/javax/security/jacc/WebResourcePermission.java 2010-03-18 18:33:02 UTC (rev 102575)
+++ projects/specs/trunk/jboss-jacc-api_1.4_spec/src/main/java/javax/security/jacc/WebResourcePermission.java 2010-03-22 19:15:14 UTC (rev 102732)
@@ -1,67 +1,72 @@
/*
-* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
-* by the @authors tag. See the copyright.txt in the distribution for a
-* full listing of individual contributors.
-*
-* This is free software; you can redistribute it and/or modify it
-* under the terms of the GNU Lesser General Public License as
-* published by the Free Software Foundation; either version 2.1 of
-* the License, or (at your option) any later version.
-*
-* This software is distributed in the hope that it will be useful,
-* but WITHOUT ANY WARRANTY; without even the implied warranty of
-* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-* Lesser General Public License for more details.
-*
-* You should have received a copy of the GNU Lesser General Public
-* License along with this software; if not, write to the Free
-* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
-* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
-*/
+ * JBoss, Home of Professional Open Source. Copyright 2010, Red Hat Middleware
+ * LLC, and individual contributors as indicated by the @author tags. See the
+ * copyright.txt file in the distribution for a full listing of individual
+ * contributors.
+ *
+ * This is free software; you can redistribute it and/or modify it under the
+ * terms of the GNU Lesser General Public License as published by the Free
+ * Software Foundation; either version 2.1 of the License, or (at your option)
+ * any later version.
+ *
+ * This software is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this software; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA, or see the FSF
+ * site: http://www.fsf.org.
+ */
package javax.security.jacc;
-import java.io.Serializable;
-import java.io.ObjectStreamField;
+import java.io.IOException;
import java.io.ObjectInputStream;
-import java.io.IOException;
import java.io.ObjectOutputStream;
+import java.io.ObjectStreamField;
+import java.io.Serializable;
import java.security.Permission;
+import java.util.StringTokenizer;
import java.util.TreeSet;
-import java.util.StringTokenizer;
-import java.util.Iterator;
+
import javax.servlet.http.HttpServletRequest;
import org.jboss.util.id.SerialVersion;
-/** Class for Servlet web resource permissions. A WebResourcePermission is a
- * named permission and has actions.
+/**
+ * <p>
+ * Class for Servlet web resource permissions. A {@code WebResourcePermission} is a named permission and has actions.
+ * </p>
*
- * The name of a WebResourcePermission (also referred to as the target name)
- * identifies the Web resources to which the permission pertains.
+ * <p>
+ * The name of a {@code WebResourcePermission} (also referred to as the target name) identifies the Web resources to
+ * which the permission pertains.
+ * </p>
*
- * Implementations of this class MAY implement newPermissionCollection or
- * inherit its implementation from the super class.
+ * <p>
+ * Implementations of this class MAY implement {@code newPermissionCollection} or inherit its implementation from the
+ * super class.
+ * </p>
*
- *
- * @author Scott.Stark at jboss.org
- * @author Anil.Saldhana at jboss.org
- * @author Ron Monzillo, Gary Ellison (javadoc)
- * @version $Revision$
+ * @author <a href="mailto:scott.stark at jboss.org">Scott Stark</a>
+ * @author <a href="mailto:sguilhen at redhat.com">Stefan Guilhen</a>
+ * @see {@link Permission}
*/
-public final class WebResourcePermission
- extends Permission
- implements Serializable
+ at SuppressWarnings({"unchecked", "unused"})
+public final class WebResourcePermission extends Permission implements Serializable
{
/** @since 4.0.2 */
private static final long serialVersionUID;
- private static TreeSet ALL_HTTP_METHODS = new TreeSet();
+
+ private static TreeSet<String> ALL_HTTP_METHODS = new TreeSet<String>();
+
+ static final String ENCODED_COLON = "%3A";
+
/**
* @serialField actions String the actions string.
*/
- private static final ObjectStreamField[] serialPersistentFields = {
- new ObjectStreamField("actions", String.class)
- };
+ private static final ObjectStreamField[] serialPersistentFields = {new ObjectStreamField("actions", String.class)};
static
{
@@ -79,264 +84,299 @@
}
private transient URLPatternSpec urlSpec;
+
+ private transient TreeSet<String> httpMethods;
+
private transient String httpMethodsString;
- private transient TreeSet httpMethods;
- private transient TreeSet httpExceptionList;
+
+ private transient TreeSet<String> httpExceptionList;
+
private transient String httpExceptionString;
- /** Creates a new WebResourcePermission from the HttpServletRequest object.
+ /**
+ * <p>
+ * Creates a new WebResourcePermission from the HttpServletRequest object.
+ * </p>
*
- * @param request - the HttpServletRequest object corresponding to the
- * Servlet operation to which the permission pertains. The permission name is
- * the substring of the requestURI (HttpServletRequest.getRequestURI()) that
- * begins after the contextPath (HttpServletRequest.getContextPath()). When
- * the substring operation yields the string "/", the permission is
- * constructed with the empty string as its name. The permission's actions
- * field is obtained from HttpServletRequest.getMethod().
+ * @param request
+ * - the {@code HttpServletRequest} object corresponding to the Servlet operation to which the permission
+ * pertains. The permission name is the substring of the requestURI ({@code
+ * HttpServletRequest.getRequestURI()}) that begins after the contextPath ({@code
+ * HttpServletRequest.getContextPath()}). When the substring operation yields the string “/”, the
+ * permission is constructed with the empty string as its name. The permission’s actions field is obtained
+ * from {@code HttpServletRequest.getMethod()}. The constructor must transform all colon characters
+ * occurring in the name to escaped encoding as defined in RFC 2396.
*/
public WebResourcePermission(HttpServletRequest request)
{
this(requestURI(request), request.getMethod());
}
- /** Creates a new WebResourcePermission with the specified name and actions.
-
- The name contains a URLPatternSpec that identifies the web resources to which
- the permissions applies. The syntax of a URLPatternSpec is as follows:
-
- URLPatternList ::= URLPattern | URLPatternList colon URLPattern
-
- URLPatternSpec ::= null | URLPattern | URLPattern colon URLPatternList
-
-
-
- A null URLPatternSpec is translated to the default URLPattern, "/", by the
- permission constructor. The empty string is an exact URLPattern, and may
- occur anywhere in a URLPatternSpec that an exact URLPattern may occur. The
- first URLPattern in a URLPatternSpec may be any of the pattern types, exact,
- path-prefix, extension, or default as defined in the Java Servlet
- Specification). When a URLPatternSpec includes a URLPatternList, the
- patterns of the URLPatternList identify the resources to which the
- permission does NOT apply and depend on the pattern type and value of the
- first pattern as follows:
-
- - No pattern may exist in the URLPatternList that matches the first pattern.
- - If the first pattern is a path-prefix pattern, only exact patterns matched
- by the first pattern and path-prefix patterns matched by, but different
- from, the first pattern may occur in the URLPatternList.
- - If the first pattern is an extension pattern, only exact patterns that are
- matched by the first pattern and path-prefix patterns may occur in the
- URLPatternList.
- - If the first pattern is the default pattern, "/", any pattern except the
- default pattern may occur in the URLPatternList.
- - If the first pattern is an exact pattern a URLPatternList must not be
- present in the URLPatternSpec.
-
- The actions parameter contains a comma seperated list of HTTP methods. The
- syntax of the actions parameter is defined as follows:
-
- HTTPMethod ::= "GET" | "POST" | "PUT" | "DELETE" | "HEAD" |
- "OPTIONS" | "TRACE"
-
- HTTPMethodExceptionList ::= exclaimationPoint HTTPMethodList
- HTTPMethodList ::= HTTPMethod | HTTPMethodList comma HTTPMethod
- HTTPMethodSpec ::= null | emptyString | HTTPMethodExceptionList | HTTPMethodList
-
-
- If duplicates occur in the HTTPMethodSpec they must be eliminated by the
- permission constructor.
-
- A null or empty string HTTPMethodSpec indicates that the permission applies
- to all HTTP methods at the resources identified by the URL pattern.
-
- @param name - the URLPatternSpec that identifies the application specific web
- resources to which the permission pertains. All URLPatterns in the
- URLPatternSpec are relative to the context path of the deployed web
- application module, and the same URLPattern must not occur more than once
- in a URLPatternSpec. A null URLPatternSpec is translated to the default
- URLPattern, "/", by the permission constructor.
- @param actions - identifies the HTTP methods to which the permission
- pertains. If the value passed through this parameter is null or the empty
- string, then the permission is constructed with actions corresponding to
- all the possible HTTP methods.
+ /**
+ * <p>
+ * Creates a new WebResourcePermission with the specified name and actions.
+ * </p>
+ *
+ * <p>
+ * The name contains a URLPatternSpec that identifies the web resources to which the permissions applies. The syntax
+ * of a URLPatternSpec is as follows:
+ * </p>
+ *
+ * <pre>
+ * URLPatternList ::= URLPattern | URLPatternList colon URLPattern
+ *
+ * URLPatternSpec ::= null | URLPattern | URLPattern colon URLPatternList
+ * </pre>
+ *
+ * <p>
+ * A null URLPatternSpec is translated to the default URLPattern, "/", by the permission constructor. The empty
+ * string is an exact URLPattern, and may occur anywhere in a URLPatternSpec that an exact URLPattern may occur. The
+ * first URLPattern in a URLPatternSpec may be any of the pattern types, exact, path-prefix, extension, or default as
+ * defined in the <i>Java Servlet Specification</i>). When a URLPatternSpec includes a URLPatternList, the patterns
+ * of the URLPatternList identify the resources to which the permission does NOT apply and depend on the pattern type
+ * and value of the first pattern as follows:
+ * <ul>
+ * <li>No pattern may exist in the URLPatternList that matches the first pattern.</li>
+ * <li>If the first pattern is a path-prefix pattern, only exact patterns matched by the first pattern and
+ * path-prefix patterns matched by, but different from, the first pattern may occur in the URLPatternList.</li>
+ * <li>If the first pattern is an extension pattern, only exact patterns that are matched by the first pattern and
+ * path-prefix patterns may occur in the URLPatternList.</li>
+ * <li>If the first pattern is the default pattern, "/", any pattern except the default pattern may occur in the
+ * URLPatternList.</li>
+ * <li>If the first pattern is an exact pattern a URLPatternList must not be present in the URLPatternSpec.</li>
+ * </ul>
+ * </p>
+ *
+ * <p>
+ * The actions parameter contains a comma separated list of HTTP methods. The syntax of the actions parameter is
+ * defined as follows:
+ * </p>
+ *
+ * <pre>
+ * ExtensionMethod ::= any token as defined by RFC 2616
+ * (that is, 1*[any CHAR except CTLs or separators])
+ *
+ * HTTPMethod ::= "GET" | "POST" | "PUT" | "DELETE" | "HEAD" | "OPTIONS" | "TRACE | ExtensionMethod"
+ *
+ * HTTPMethodList ::= HTTPMethod | HTTPMethodList comma HTTPMethod
+ *
+ * HTTPMethodExceptionList ::= exclaimationPoint HTTPMethodList
+ *
+ * HTTPMethodSpec ::= null | HTTPMethodExceptionList | HTTPMethodList
+ * </pre>
+ *
+ * <p>
+ * If duplicates occur in the HTTPMethodSpec they must be eliminated by the permission constructor.
+ * </p>
+ *
+ * <p>
+ * A null or empty string HTTPMethodSpec indicates that the permission applies to all HTTP methods at the resources
+ * identified by the URL pattern.
+ * </p>
+ *
+ * <p>
+ * If the HTTPMethodSpec contains an HTTPMethodExceptionList (i.e., it begins with an exclamation- Point), the
+ * permission pertains to all methods except those occurring in the exception list.
+ * </p>
+ *
+ * @param name
+ * - the URLPatternSpec that identifies the application specific web resources to which the permission
+ * pertains. All URLPatterns in the URLPatternSpec are relative to the context path of the deployed web
+ * application module, and the same URLPattern must not occur more than once in a URLPatternSpec. A null
+ * URLPatternSpec is translated to the default URLPattern, “/”, by the permission constructor. All colons
+ * occurring within the URLPattern elements of the URLPatternSpec must be represented in escaped encoding
+ * as defined in RFC 2396.
+ * @param actions
+ * - identifies the HTTP methods to which the permission pertains. If the value passed through this
+ * parameter is null or the empty string, then the permission is constructed with actions corresponding to
+ * all the possible HTTP methods.
*/
public WebResourcePermission(String name, String actions)
{
super(name == null ? "/" : name);
- if( name == null )
+ if (name == null)
name = "/";
this.urlSpec = new URLPatternSpec(name);
parseActions(actions);
}
- /** Creates a new WebResourcePermission with name corresponding to the
- * URLPatternSpec, and actions composed from the array of HTTP methods.
+ /**
+ * <p>
+ * Creates a new WebResourcePermission with name corresponding to the URLPatternSpec, and actions composed from the
+ * array of HTTP methods.
+ * </p>
*
- * @param urlPatternSpec - the URLPatternSpec that identifies the app
- * specific web resources to which the permission pertains. All URLPatterns
- * in the URLPatternSpec are relative to the context path of the deployed web
- * application module, and the same URLPattern must not occur more than once
- * in a URLPatternSpec. A null URLPatternSpec is translated to the default
- * URLPattern, "/", by the permission constructor.
- * @param httpMethods - an array of strings each element of which contains
- * the value of an HTTP method. If the value passed through this parameter is
- * null or is an array with no elements, then the permission is constructed
- * with actions corresponding to all the possible HTTP methods.
+ * @param urlPatternSpec
+ * - the URLPatternSpec that identifies the application specific web resources to which the permission
+ * pertains. All URLPatterns in the URLPatternSpec are relative to the context path of the deployed web
+ * application module, and the same URLPattern must not occur more than once in a URLPatternSpec. A null
+ * URLPatternSpec is translated to the default URLPattern, “/”, by the permission constructor. All colons
+ * occurring within the URLPattern elements of the URLPatternSpec must be represented in escaped encoding
+ * as defined in RFC 2396.
+ * @param httpMethods
+ * - an array of strings each element of which contains the value of an HTTP method. If the value passed
+ * through this parameter is null or is an array with no elements, then the permission is constructed with
+ * actions corresponding to all the possible HTTP methods.
*/
public WebResourcePermission(String urlPatternSpec, String[] httpMethods)
{
super(urlPatternSpec);
this.urlSpec = new URLPatternSpec(urlPatternSpec);
Object[] methodInfo = canonicalMethods(httpMethods);
- this.httpMethods = (TreeSet) methodInfo[0];
+ this.httpMethods = (TreeSet<String>) methodInfo[0];
this.httpMethodsString = (String) methodInfo[1];
}
- /** Checks two WebResourcePermission objects for equality. WebResourcePermission
- * objects are equivalent if their URLPatternSpec and (canonicalized) actions
- * values are equivalent. The URLPatternSpec of a reference permission is
- * equivalent to that of an argument permission if their first patterns are
- * equivalent, and the patterns of the URLPatternList of the reference
- * permission collectively match exactly the same set of patterns as are
- * matched by the patterns of the URLPatternList of the argument permission.
+ /**
+ * <p>
+ * Checks two WebResourcePermission objects for equality. WebResourcePermission objects are equivalent if their
+ * URLPatternSpec and (canonicalized) actions values are equivalent. The URLPatternSpec of a refer- ence permission
+ * is equivalent to that of an argument permission if their first patterns are equivalent, and the patterns of the
+ * URLPatternList of the reference permission collectively match exactly the same set of pat- terns as are matched by
+ * the patterns of the URLPatternList of the argument permission.
+ * </p>
*
- * @param p - the WebResourcePermission object being tested for equality
- * with this WebResourcePermission.
- * @return true if the argument WebResourcePermission object is equivalent to
- * this WebResourcePermission.
+ * <p>
+ * Two Permission objects, P1 and P2, are equivalent if and only if P1.implies(P2) && P2.implies(P1).
+ * </p>
+ *
+ * @param p
+ * - the WebResourcePermission object being tested for equality with this WebResourcePermission.
+ * @return true if the argument WebResourcePermission object is equivalent to this WebResourcePermission.
*/
+ @Override
public boolean equals(Object p)
{
- //boolean equals = false;
- if( p == null || !(p instanceof WebResourcePermission) )
+ if (p instanceof WebResourcePermission == false)
return false;
WebResourcePermission perm = (WebResourcePermission) p;
-
- /**
- * Two permissions p1 and p2 are equivalent if and only if p1.implies(p2)
- * and p2.implies(p1)
- */
+
+ // Two permissions p1 and p2 are equivalent if and only if p1.implies(p2) and p2.implies(p1)
return this.implies(perm) && perm.implies(this);
- /*
- equals = urlSpec.equals(perm.urlSpec);
- if( equals == true )
- {
- String a0 = getActions();
- String a1 = perm.getActions();
- equals = (a0 != null && a0.equals(a1)) || (a0 == a1);
- }
- return equals;*/
}
- /** Returns a canonical String representation of the actions of this
- * WebResourcePermission. WebResourcePermission actions are canonicalized by
- * sorting the HTTP methods into ascending lexical order. There may be no
- * duplicate HTTP methods in the canonical form, and the canonical form of
- * the set of all HTTP methods is the value null.
+ /**
+ * <p>
+ * Returns a canonical String representation of the actions of this WebResourcePermission. WebResourcePermission
+ * actions are canonicalized by sorting the HTTP methods into ascending lexical order. There may be no duplicate HTTP
+ * methods in the canonical form, and the canonical form of the set of all HTTP methods is the value null.
+ * </p>
*
- * @return a String containing the canonicalized actions of this
- * WebResourcePermission (or the null value).
+ * @return a String containing the canonicalized actions of this WebResourcePermission (or the null value).
*/
+ @Override
public String getActions()
{
- return httpMethodsString;
+ return this.httpMethodsString;
}
- /** Returns the hash code value for this WebResourcePermission. The properties
- * of the returned hash code must be as follows:
+ /**
+ * <p>
+ * Returns the hash code value for this WebResourcePermission. 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 WebResourcePermission object. The value returned by hashCode for a particular
+ * WebResourcePermission need not remain consistent from one execution of an application to another.</li>
+ * <li>If two WebResourcePermission 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>
+ * </p>
*
- * - During the lifetime of a Java application, the hashCode method must return
- * the same integer value, every time it is called on a WebResourcePermission
- * object. The value returned by hashCode for a particular
- * WebResourcePermission need not remain consistent from one execution of an
- * application to another.
- * - If two WebResourcePermission 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).
* @return the integer hash code value for this object.
*/
+ @Override
public int hashCode()
{
- int hashCode = urlSpec.hash();
- if( httpMethods != null )
- hashCode += httpMethods.hashCode();
+ int hashCode = 17;
+ hashCode = 37 * hashCode + this.urlSpec.hashCode();
+ if (this.httpMethods != null)
+ hashCode = 37 * hashCode + this.httpMethods.hashCode();
return hashCode;
}
- /** Determines if the argument Permission is "implied by" this
- * WebResourcePermission. For this to be the case, all of the following must
- * be true:
-
- * - The argument is an instanceof WebResourcePermission
- * - The first URLPattern in the name of the argument permission is matched
- * by the first URLPattern in the name of this permission.
- * - The first URLPattern in the name of the argument permission is NOT
- * matched by any URLPattern in the URLPatternList of the URLPatternSpec
- * of this permission.
- * - If the first URLPattern in the name of the argument permission matches
- * the first URLPattern in the URLPatternSpec of this permission, then every
- * URLPattern in the URLPatternList of the URLPatternSpec of this permission
- * is matched by a URLPattern in the URLPatternList of the argument permission.
- * - The HTTP methods in the actions of the argument permission are a subset
- * of the HTTP methods in the actions of this permission.
+ /**
+ * <p>
+ * Determines if the argument Permission is "implied by" this WebResourcePermission. For this to be the case, all of
+ * the following must be true:
+ * <ul>
+ * <li>The argument is an instance of WebResourcePermission</li>
+ * <li>The first URLPattern in the name of the argument permission is matched by the first URLPattern in the name of
+ * this permission.</li>
+ * <li>The first URLPattern in the name of the argument permission is NOT matched by any URLPattern in the
+ * URLPatternList of the URLPatternSpec of this permission.</li>
+ * <li>If the first URLPattern in the name of the argument permission matches the first URLPattern in the
+ * URLPatternSpec of this permission, then every URLPattern in the URLPatternList of the URLPatternSpec of this
+ * permission is matched by a URLPattern in the URLPatternList of the argument permission.</li>
+ * <li>The HTTP methods in the actions of the argument permission are a subset of the HTTP methods in the actions of
+ * this permission.</li>
+ * </ul>
+ * </p>
*
- * URLPattern matching is performed using the Servlet matching rules where
- * two URL patterns match if they are related as follows:
- * - their pattern values are String equivalent, or
- * - this pattern is the path-prefix pattern "/*", or
- * - this pattern is a path-prefix pattern (that is, it starts with "/" and
- * ends with "/*") and the argument pattern starts with the substring of this
- * pattern, minus its last 2 characters, and the next character of the argument
- * pattern, if there is one, is "/", or
- * - this pattern is an extension pattern (that is, it starts with "*.") and
- * the argument pattern ends with this pattern, or
- * - the reference pattern is the special default pattern, "/", which matches
- * all argument patterns.
+ * <p>
+ * URLPattern matching is performed using the <i>Servlet matching</i> rules where two URL patterns match if they are
+ * related as follows:
+ * <ul>
+ * <li>their pattern values are String equivalent, or</li>
+ * <li>this pattern is the path-prefix pattern "/*", or</li>
+ * <li>this pattern is a path-prefix pattern (that is, it starts with "/" and ends with "/*") and the argument
+ * pattern starts with the substring of this pattern, minus its last 2 characters, and the next character of the
+ * argument pattern, if there is one, is "/", or</li>
+ * <li>this pattern is an extension pattern (that is, it starts with "*.") and the argument pattern ends with this
+ * pattern, or - the reference pattern is the special default pattern, "/", which matches all argument patterns.</li>
+ * </ul>
+ * </p>
*
- * All of the comparisons described above are case sensitive.
+ * <p>
+ * All of the comparisons described above are case sensitive.
+ * </p>
*
- * @param p
- * @return
+ * @param permission
+ * - “this” WebResourcePermission 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 p)
+ @Override
+ public boolean implies(Permission permission)
{
- if( p == null || !(p instanceof WebResourcePermission) )
+ if (permission instanceof WebResourcePermission == false)
return false;
- WebResourcePermission perm = (WebResourcePermission) p;
+ WebResourcePermission perm = (WebResourcePermission) permission;
// Check the URL patterns
- boolean implies = urlSpec.implies(perm.urlSpec);
- if( implies == true )
+ boolean implies = this.urlSpec.implies(perm.urlSpec);
+ if (implies == true)
{
- if(httpExceptionList != null)
- implies = matchExceptionList(httpExceptionList, perm.httpExceptionList);
- //Check the http methods
- if( httpMethods != null && perm.httpMethods != null)
- implies = httpMethods.containsAll(perm.httpMethods);
+ if (this.httpExceptionList != null)
+ implies = matchExceptionList(this.httpExceptionList, perm.httpExceptionList);
+ // Check the http methods
+ if (this.httpMethods != null && perm.httpMethods != null)
+ implies = this.httpMethods.containsAll(perm.httpMethods);
}
-
return implies;
}
- /** Build a permission name from the substring of the
- * HttpServletRequest.getRequestURI()) that begins after the contextPath
- * (HttpServletRequest.getContextPath()). When the substring operation yields
- * the string "/", the permission is constructed with the empty string as
- * its name.
- * @param request - the servlet request
- * @return the resource permission name
- */
+ /**
+ * <p>
+ * Build a permission name from the substring of the {@code HttpServletRequest.getRequestURI()}) that begins after
+ * the contextPath ({@code HttpServletRequest.getContextPath()}). When the substring operation yields the string "/",
+ * the permission is constructed with the empty string as its name.
+ * </p>
+ *
+ * @param request
+ * - the Servlet request object.
+ * @return the resource permission name.
+ */
static String requestURI(HttpServletRequest request)
{
String uri = request.getRequestURI();
- if( uri != null )
+ if (uri != null)
{
String contextPath = request.getContextPath();
int length = contextPath == null ? 0 : contextPath.length();
- if( length > 0 )
+ if (length > 0)
{
uri = uri.substring(length);
}
- if( uri.equals("/") )
+ if (uri.equals("/"))
{
uri = "";
}
@@ -345,54 +385,48 @@
{
uri = "";
}
+
+ // according to the JACC specification, all colons must be escaped.
+ if (uri.indexOf(':') > 0)
+ uri = uri.replaceAll(":", ENCODED_COLON);
return uri;
}
- static Object[] canonicalMethods(String[] methods)
+ static Object[] canonicalMethods(String methods)
{
- TreeSet actions = new TreeSet();
- int length = methods != null ? methods.length : 0;
- for(int n = 0; n < length; n++)
- {
- actions.add(methods[n]);
- }
- return canonicalMethods(actions);
+ String[] methodsArray = null;
+ if (methods != null && methods.length() > 0)
+ methodsArray = methods.split(",");
+
+ return canonicalMethods(methodsArray);
}
- /** Parse the comma seperated http methods into a
- * @param methods
- * @return
- */
- static Object[] canonicalMethods(String methods)
+ static Object[] canonicalMethods(String[] methods)
{
- if( methods == null || methods.length() == 0 )
- return new Object[]{ALL_HTTP_METHODS, null};
-
- StringTokenizer tokenizer = new StringTokenizer(methods, ",");
- TreeSet actions = new TreeSet();
- while( tokenizer.hasMoreTokens() )
+ // add the HTTP methods to a set to remove duplicates.
+ TreeSet<String> actions = new TreeSet<String>();
+ if (methods != null)
{
- String action = tokenizer.nextToken();
- actions.add(action);
+ for (String method : methods)
+ actions.add(method);
}
return canonicalMethods(actions);
}
- static Object[] canonicalMethods(TreeSet actions)
+ static Object[] canonicalMethods(TreeSet<String> actions)
{
- Object[] info = {null, null};
- if( actions.equals(ALL_HTTP_METHODS) || actions.size() == 0 )
+ Object[] info = {ALL_HTTP_METHODS, null};
+ if (actions.equals(ALL_HTTP_METHODS) || actions.size() == 0)
return info;
info[0] = actions;
- Iterator iter = actions.iterator();
StringBuffer tmp = new StringBuffer();
- while( iter.hasNext() )
+ for (String action : actions)
{
- tmp.append(iter.next());
+ tmp.append(action);
tmp.append(',');
}
- if( tmp.length() > 0 )
+ if (tmp.length() > 0)
tmp.setLength(tmp.length() - 1);
info[1] = tmp.toString();
return info;
@@ -402,55 +436,52 @@
private void parseActions(String actions)
{
boolean exclusionListNeeded = actions != null && actions.startsWith("!");
- if(exclusionListNeeded)
- actions = actions.substring(1);
-
+ if (exclusionListNeeded)
+ actions = actions.substring(1);
+
Object[] methodInfo = canonicalMethods(actions);
- if(exclusionListNeeded)
+ if (exclusionListNeeded)
{
- this.httpExceptionList = (TreeSet) methodInfo[0];
- this.httpExceptionString = (String) methodInfo[1];
+ this.httpExceptionList = (TreeSet<String>) methodInfo[0];
+ this.httpExceptionString = (String) methodInfo[1];
}
else
- {
- this.httpMethods = (TreeSet) methodInfo[0];
+ {
+ this.httpMethods = (TreeSet<String>) methodInfo[0];
this.httpMethodsString = (String) methodInfo[1];
}
}
- private void readObject(ObjectInputStream ois)
- throws ClassNotFoundException, IOException
+ static boolean matchExceptionList(TreeSet<String> myExceptionList, TreeSet<String> matchingExceptionList)
{
+ boolean bothnull = (myExceptionList == null && matchingExceptionList == null);
+ boolean onenull = (myExceptionList == null && matchingExceptionList != null)
+ || (myExceptionList != null && matchingExceptionList == null);
+
+ if (bothnull)
+ return true;
+ if (onenull)
+ return false;
+
+ for (String httpMethod : matchingExceptionList)
+ {
+ if (myExceptionList.contains(httpMethod))
+ return false;
+ }
+ return true;
+ }
+
+ private void readObject(ObjectInputStream ois) throws ClassNotFoundException, IOException
+ {
ObjectInputStream.GetField fields = ois.readFields();
String actions = (String) fields.get("actions", null);
parseActions(actions);
}
- private void writeObject(ObjectOutputStream oos)
- throws IOException
+ private void writeObject(ObjectOutputStream oos) throws IOException
{
- ObjectOutputStream.PutField fields = oos.putFields();
+ ObjectOutputStream.PutField fields = oos.putFields();
fields.put("actions", this.getActions());
oos.writeFields();
- }
-
- static boolean matchExceptionList(TreeSet<String> myExceptionList,
- TreeSet<String> matchingExceptionList)
- {
- boolean bothnull = (myExceptionList == null && matchingExceptionList == null);
- boolean onenull = (myExceptionList == null && matchingExceptionList != null)
- || (myExceptionList != null && matchingExceptionList == null);
-
- if(bothnull)
- return true;
- if(onenull)
- return false;
-
- for(String httpMethod: matchingExceptionList)
- {
- if(myExceptionList.contains(httpMethod))
- return false;
- }
- return true;
}
}
Modified: projects/specs/trunk/jboss-jacc-api_1.4_spec/src/main/java/javax/security/jacc/WebRoleRefPermission.java
===================================================================
--- projects/specs/trunk/jboss-jacc-api_1.1_spec/src/main/java/javax/security/jacc/WebRoleRefPermission.java 2010-03-18 18:33:02 UTC (rev 102575)
+++ projects/specs/trunk/jboss-jacc-api_1.4_spec/src/main/java/javax/security/jacc/WebRoleRefPermission.java 2010-03-22 19:15:14 UTC (rev 102732)
@@ -1,24 +1,24 @@
/*
-* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
-* by the @authors tag. See the copyright.txt in the distribution for a
-* full listing of individual contributors.
-*
-* This is free software; you can redistribute it and/or modify it
-* under the terms of the GNU Lesser General Public License as
-* published by the Free Software Foundation; either version 2.1 of
-* the License, or (at your option) any later version.
-*
-* This software is distributed in the hope that it will be useful,
-* but WITHOUT ANY WARRANTY; without even the implied warranty of
-* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-* Lesser General Public License for more details.
-*
-* You should have received a copy of the GNU Lesser General Public
-* License along with this software; if not, write to the Free
-* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
-* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
-*/
+ * JBoss, Home of Professional Open Source. Copyright 2010, Red Hat Middleware
+ * LLC, and individual contributors as indicated by the @author tags. See the
+ * copyright.txt file in the distribution for a full listing of individual
+ * contributors.
+ *
+ * This is free software; you can redistribute it and/or modify it under the
+ * terms of the GNU Lesser General Public License as published by the Free
+ * Software Foundation; either version 2.1 of the License, or (at your option)
+ * any later version.
+ *
+ * This software is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this software; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA, or see the FSF
+ * site: http://www.fsf.org.
+ */
package javax.security.jacc;
import java.io.Serializable;
@@ -26,32 +26,34 @@
import org.jboss.util.id.SerialVersion;
-/** Class for Servlet isUserInRole (String reference) permissions. A
- * WebRoleRefPermission is a named permission and has actions.
+/**
+ * <p>
+ * Class for Servlet <i>isUserInRole (String reference)</i> permissions. A WebRoleRefPermission is a named permission
+ * and has actions.
+ * </p>
*
- * The name of an WebRoleRefPermission (also referred to as the target name)
- * identifies a Web resource by the servlet name (in the deployment descriptor
- * corresponding to the component from which the call to isUserInRole
- * (String reference) is being made.
+ * <p>
+ * The name of an WebRoleRefPermission (also referred to as the target name) identifies a Web resource by the servlet
+ * name (in the deployment descriptor corresponding to the component from which the call to <i>isUserInRole (String
+ * reference)</i> is being made).
+ * </p>
*
- * The actions of an WebRoleRefPermission identifies the role reference to which
- * the permission applies. A WebRoleRefPermission is checked to determine if the
- * subject is a member of the role identified by the reference.
+ * <p>
+ * The actions of an WebRoleRefPermission identifies the role reference to which the permission applies. A
+ * WebRoleRefPermission is checked to determine if the subject is a member of the role identified by the reference.
+ * </p>
*
- * Implementations of this class MAY implement newPermissionCollection or
- * inherit its implementation from the super class.
+ * <p>
+ * Implementations of this class MAY implement newPermissionCollection or inherit its implementation from the super
+ * class.
+ * </p>
*
- * @link http://java.sun.com/j2ee/1.4/docs/api/
- *
- * @author Scott.Stark at jboss.org
- * @author Ron Monzillo, Gary Ellison (javadoc)
- * @version $Revision$
+ * @author <a href="mailto:scott.stark at jboss.org">Scott Stark</a>
+ * @author <a href="mailto:sguilhen at redhat.com">Stefan Guilhen</a>
+ * @see {@link Permission}
*/
-public final class WebRoleRefPermission
- extends Permission
- implements Serializable
+public final class WebRoleRefPermission extends Permission implements Serializable
{
- /** @since 4.0.2 */
private static final long serialVersionUID;
static
{
@@ -63,17 +65,22 @@
/** The security-role-ref/role-link value */
private String actions;
+
private transient int hashCode;
- /** Creates a new WebRoleRefPermission with the specified name and actions.
+ /**
+ * <p>
+ * Creates a new WebRoleRefPermission with the specified name and actions.
+ * </p>
*
- * @param name - the servlet-name that identifies the application specific
- * web resource in whose context the role references are to be evaluated.
- * @param actions - identifies the role reference to which the permission
- * pertains. The role reference is scoped to the Web resource identified in
- * the name parameter. The value of the role reference must not be null or
- * the empty string.
- */
+ * @param name
+ * - the servlet-name that identifies the application specific web resource in whose context the role
+ * references are to be evaluated.
+ * @param actions
+ * - identifies the role reference to which the permission pertains. The role reference is scoped to the
+ * Web resource identified in the name parameter. The value of the role reference must not be null or the
+ * empty string.
+ */
public WebRoleRefPermission(String name, String actions)
{
super(name);
@@ -81,72 +88,97 @@
this.hashCode = name.hashCode() + actions.hashCode();
}
- /** Checks two WebRoleRefPermission objects for equality.
- * WebRoleRefPermission objects are equivalent if they have case equivalent
- * name and actions values.
+ /**
+ * <p>
+ * Checks two WebRoleRefPermission objects for equality. WebRoleRefPermission objects are equivalent if they have
+ * case equivalent name and actions values.
+ * </p>
*
- * @param p the permission to check for equality
- * @return true if this is equivalent to p, false otherwise.
+ * <p>
+ * Two Permission objects, P1 and P2, are equivalent if and only if P1.implies(P2) && P2.implies(P1).
+ * </p>
+ *
+ * <p>
+ * The name and actions comparisons described above are case sensitive.
+ * </p>
+ *
+ * @param p
+ * - the WebRoleRefPermission object being tested for equality with this WebRoleRefPermission.
+ * @return true if the argument WebRoleRefPermission object is equivalent to this WebRoleRefPermission.
*/
+ @Override
public boolean equals(Object p)
{
- if( p == this )
+ if (p == this)
return true;
- if( (p instanceof WebRoleRefPermission) == false )
+ if ((p instanceof WebRoleRefPermission) == false)
return false;
boolean equals = false;
WebRoleRefPermission wrrp = (WebRoleRefPermission) p;
String pname = wrrp.getName();
- if( this.getName().equals(pname) )
+ if (this.getName().equals(pname))
{
String pactions = wrrp.getActions();
- if( this.getActions().equals(pactions) )
+ if (this.getActions().equals(pactions))
equals = true;
}
return equals;
}
- /** Returns the security-role-ref target role name.
+ /**
+ * <p>
+ * Returns a canonical String representation of the actions of this WebRoleRefPermission.
+ * </p>
*
- * @return the security-role-ref target role name.
- */
+ * @return a String containing the canonicalized actions of this WebRoleRefPermission.
+ */
+ @Override
public String getActions()
{
return actions;
}
- /** Returns the hash code value for this WebRoleRefPermission. The properties
- * of the returned hash code must be as follows:
+ /**
+ * <p>
+ * Returns the hash code value for this WebRoleRefPermission. 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 WebRoleRefPermission object. The value returned by hashCode for a particular
+ * WebRoleRefPermission need not remain consistent from one execution of an application to another.</li>
+ * <li>If two WebRoleRefPermission 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>
+ * </p>
*
- * - During the lifetime of a Java application, the hashCode method must
- * return the same integer value, every time it is called on a
- * WebRoleRefPermission object. The value returned by hashCode for a
- * particular WebRoleRefPermission need not remain consistent from one
- * execution of an application to another.
- * - If two WebRoleRefPermission 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).
- *
- * @return the permission hash code.
- */
+ * @return the integer hash code value for this object.
+ */
+ @Override
public int hashCode()
{
return hashCode;
}
- /** Determines if the argument Permission is "implied by" this
- * WebRoleRefPermission. For this to be the case:
+ /**
+ * <p>
+ * Determines if the argument Permission is "implied by" this WebRoleRefPermission. For this to be the case:
+ * <ul>
+ * <li>The argument must be an instance of WebRoleRefPermission</li>
+ * <li>with name equivalent to this WebRoleRefPermission, and</li>
+ * <li>with role reference equivalent to this WebRoleRefPermission (as defined in their actions)</li>
+ * </ul>
+ * </p>
*
- * - The argument must be an instanceof WebRoleRefPermission
- * - with name equivalent to this WebRoleRefPermission, and
- * - with role reference equivalent to this WebRoleRefPermission
- * (as defined in their actions)
+ * <p>
+ * The comparisons described above are case sensitive.
+ * </p>
*
* @param p
- * @return true if the specified permission is implied by this object, false
- * otherwise.
- */
+ * - “this” WebRoleRefPermission is checked to see if it implies the argument permission.
+ * @return true if the specified permission is implied by this object, false if not.
+ */
+ @Override
public boolean implies(Permission p)
{
return equals(p);
Modified: projects/specs/trunk/jboss-jacc-api_1.4_spec/src/main/java/javax/security/jacc/WebUserDataPermission.java
===================================================================
--- projects/specs/trunk/jboss-jacc-api_1.1_spec/src/main/java/javax/security/jacc/WebUserDataPermission.java 2010-03-18 18:33:02 UTC (rev 102575)
+++ projects/specs/trunk/jboss-jacc-api_1.4_spec/src/main/java/javax/security/jacc/WebUserDataPermission.java 2010-03-22 19:15:14 UTC (rev 102732)
@@ -1,24 +1,24 @@
/*
-* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
-* by the @authors tag. See the copyright.txt in the distribution for a
-* full listing of individual contributors.
-*
-* This is free software; you can redistribute it and/or modify it
-* under the terms of the GNU Lesser General Public License as
-* published by the Free Software Foundation; either version 2.1 of
-* the License, or (at your option) any later version.
-*
-* This software is distributed in the hope that it will be useful,
-* but WITHOUT ANY WARRANTY; without even the implied warranty of
-* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-* Lesser General Public License for more details.
-*
-* You should have received a copy of the GNU Lesser General Public
-* License along with this software; if not, write to the Free
-* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
-* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
-*/
+ * JBoss, Home of Professional Open Source. Copyright 2010, Red Hat Middleware
+ * LLC, and individual contributors as indicated by the @author tags. See the
+ * copyright.txt file in the distribution for a full listing of individual
+ * contributors.
+ *
+ * This is free software; you can redistribute it and/or modify it under the
+ * terms of the GNU Lesser General Public License as published by the Free
+ * Software Foundation; either version 2.1 of the License, or (at your option)
+ * any later version.
+ *
+ * This software is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this software; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA, or see the FSF
+ * site: http://www.fsf.org.
+ */
package javax.security.jacc;
import java.io.Serializable;
@@ -32,22 +32,23 @@
import org.jboss.util.id.SerialVersion;
-/** Class for Servlet Web user data permissions. A WebUserDataPermission is a
- * named permission and has actions.
+/**
+ * <p>
+ * Class for Servlet Web user data permissions. A WebUserDataPermission is a named permission and has actions.
+ * </p>
*
- * The name of a WebUserDataPermission (also referred to as the target name)
- * identifies a Web resource by its context path relative URL pattern.
- *
- * @link http://java.sun.com/j2ee/1.4/docs/api/
+ * <p>
+ * The name of a WebUserDataPermission (also referred to as the target name) identifies a Web resource by its context
+ * path relative URL pattern.
+ * </p>
*
- * @author Scott.Stark at jboss.org
- * @author Anil.Saldhana at jboss.org
- * @author Ron Monzillo, Gary Ellison (javadoc)
- * @version $Revision$
+ * @author <a href="mailto:scott.stark at jboss.org">Scott Stark</a>
+ * @author <a href="mailto:anil.saldhana at jboss.org">Anil Saldhana</a>
+ * @author <a href="mailto:sguilhen at redhat.com">Stefan Guilhen</a>
+ * @see {@link Permission}
*/
-public final class WebUserDataPermission
- extends Permission
- implements Serializable
+ at SuppressWarnings({"unused", "unchecked"})
+public final class WebUserDataPermission extends Permission implements Serializable
{
/** @since 4.0.2 */
private static final long serialVersionUID;
@@ -62,362 +63,404 @@
/**
* @serialField actions String the actions string.
*/
- private static final ObjectStreamField[] serialPersistentFields = {
- new ObjectStreamField("actions", String.class)
- };
+ private static final ObjectStreamField[] serialPersistentFields = {new ObjectStreamField("actions", String.class)};
private transient URLPatternSpec urlSpec;
+
private transient String httpMethodsString;
+
private transient String transportType;
- private transient TreeSet httpMethods;
- private transient TreeSet httpExceptionList;
+
+ private transient TreeSet<String> httpMethods;
+
+ private transient TreeSet<String> httpExceptionList;
+
private transient String httpExceptionString;
- /** Creates a new WebUserDataPermission from the HttpServletRequest object.
+ /**
+ * <p>
+ * Creates a new WebUserDataPermission from the HttpServletRequest object.
+ * </p>
*
- * @param request - the HttpServletRequest object corresponding to the
- * Servlet operation to which the permission pertains. The permission name is
- * the substring of the requestURI (HttpServletRequest.getRequestURI()) that
- * begins after the contextPath (HttpServletRequest.getContextPath()). When
- * the substring operation yields the string "/", the permission is
- * constructed with the empty string as its name. The HTTP method component
- * of the permission's actions is as obtained from HttpServletRequest.getMethod().
- * The TransportType component of the permission's actions is determined by
- * calling HttpServletRequest.isSecure().
- */
+ * @param request
+ * - the HttpServletRequest object corresponding to the Servlet operation to which the permission pertains.
+ * The permission name is the substring of the requestURI (HttpServletRequest.getRequestURI()) that begins
+ * after the contextPath (HttpServletRequest.getContextPath()). When the substring operation yields the
+ * string “/”, the permission is constructed with the empty string as its name. The constructor must
+ * transform all colon characters occurring in the name to escaped encoding as defined in RFC 2396. The HTTP
+ * method component of the permission’s actions is as obtained from HttpServletRequest.getMethod(). The
+ * TransportType component of the permission’s actions is determined by calling
+ * HttpServletRequest.isSecure().
+ */
public WebUserDataPermission(HttpServletRequest request)
{
- this(WebResourcePermission.requestURI(request),
- requestActions(request));
+ this(WebResourcePermission.requestURI(request), requestActions(request));
}
- /** Creates a new WebUserDataPermission with the specified name and actions.
- The name contains a URLPatternSpec that identifies the web resources to which
- the permissions applies. The syntax of a URLPatternSpec is as follows:
-
- URLPatternList ::= URLPattern | URLPatternList colon URLPattern
-
- URLPatternSpec ::= null | URLPattern | URLPattern colon URLPatternList
-
- A null URLPatternSpec is translated to the default URLPattern, "/", by the
- permission constructor. The empty string is an exact URLPattern, and may
- occur anywhere in a URLPatternSpec that an exact URLPattern may occur.
- The first URLPattern in a URLPatternSpec may be any of the pattern types,
- exact, path-prefix, extension, or default as defined in the Java Servlet
- Specification). When a URLPatternSpec includes a URLPatternList, the
- patterns of the URLPatternList identify the resources to which the
- permission does NOT apply and depend on the pattern type and value of the
- first pattern as follows:
-
- - No pattern may exist in the URLPatternList that matches the first pattern.
- - If the first pattern is a path-prefix pattern, only exact patterns matched
- by the first pattern and path-prefix patterns matched by, but different from,
- the first pattern may occur in the URLPatternList.
- - If the first pattern is an extension pattern, only exact patterns that are
- matched by the first pattern and path-prefix patterns may occur in the
- URLPatternList.
- - If the first pattern is the default pattern, "/", any pattern except the
- default pattern may occur in the URLPatternList.
- - If the first pattern is an exact pattern a URLPatternList must not be
- present in the URLPatternSpec.
-
- The actions parameter contains a comma separated list of HTTP methods that
- may be followed by a transportType separated from the HTTP method by a colon.
-
- HTTPMethod ::= "Get" | "POST" | "PUT" | "DELETE" | "HEAD" |
- "OPTIONS" | "TRACE"
-
- HTTPMethodList ::= HTTPMethod | HTTPMethodList comma HTTPMethod
-
- HTTPMethodExceptionList ::= exclaimationPoint HTTPMethodList
-
- HTTPMethodSpec ::= emptyString | HTTPMethodExceptionList |
- HTTPMethodList
-
- transportType ::= "INTEGRAL" | "CONFIDENTIAL" | "NONE"
-
- actions ::= null | HTTPMethodSpec |
- HTTPMethodSpec colon transportType
-
-
- If duplicates occur in the HTTPMethodSpec they must be eliminated by the
- permission constructor.
-
- An empty string HTTPMethodSpec is a shorthand for a List containing all the
- possible HTTP methods.
-
- An actions string without a transportType is a shorthand for a actions string
- with the value "NONE" as its TransportType.
-
- A granted permission representing a transportType of "NONE", indicates that
- the associated resources may be accessed using any conection type.
-
- @param name - the URLPatternSpec that identifies the application specific
- web resources to which the permission pertains. All URLPatterns in the
- URLPatternSpec are relative to the context path of the deployed web
- application module, and the same URLPattern must not occur more than once
- in a URLPatternSpec. A null URLPatternSpec is translated to the default
- URLPattern, "/", by the permission constructor.
- @param actions - identifies the HTTP methods and transport type to which
- the permission pertains. If the value passed through this parameter is
- null or the empty string, then the permission is constructed with actions
- corresponding to all the possible HTTP methods and transportType "NONE".
- */
+ /**
+ * <p>
+ * Creates a new WebUserDataPermission with the specified name and actions.
+ * </p>
+ *
+ * <p>
+ * The name contains a URLPatternSpec that identifies the web resources to which the permissions applies. The syntax
+ * of a URLPatternSpec is as follows:
+ *
+ * <pre>
+ * URLPatternList ::= URLPattern | URLPatternList colon URLPattern
+ *
+ * URLPatternSpec ::= null | URLPattern | URLPattern colon URLPatternList
+ * </pre>
+ *
+ * </p>
+ *
+ * <p>
+ * A null URLPatternSpec is translated to the default URLPattern, "/", by the permission constructor. The empty
+ * string is an exact URLPattern, and may occur anywhere in a URLPatternSpec that an exact URLPattern may occur. The
+ * first URLPattern in a URLPatternSpec may be any of the pattern types, exact, path-prefix, extension, or default as
+ * defined in the Java Servlet Specification). When a URLPatternSpec includes a URLPatternList, the patterns of the
+ * URLPatternList identify the resources to which the permission does NOT apply and depend on the pattern type and
+ * value of the first pattern as follows:
+ * <ul>
+ * <li>No pattern may exist in the URLPatternList that matches the first pattern.</li>
+ * <li>If the first pattern is a path-prefix pattern, only exact patterns matched by the first pattern and
+ * path-prefix patterns matched by, but different from, the first pattern may occur in the URLPatternList.</li>
+ * <li>If the first pattern is an extension pattern, only exact patterns that are matched by the first pattern and
+ * path-prefix patterns may occur in the URLPatternList.</li>
+ * <li>If the first pattern is the default pattern, "/", any pattern except the default pattern may occur in the
+ * URLPatternList.</li>
+ * <li>If the first pattern is an exact pattern a URLPatternList must not be present in the URLPatternSpec.</li>
+ * </ul>
+ * </p>
+ *
+ * <p>
+ * The actions parameter contains a comma separated list of HTTP methods that may be followed by a transportType
+ * separated from the HTTP method by a colon.
+ *
+ * <pre>
+ * ExtensionMethod ::= any token as defined by RFC 2616
+ * (that is, 1*[any CHAR except CTLs or separators])
+ *
+ * HTTPMethod ::= "Get" | "POST" | "PUT" | "DELETE" | "HEAD" |
+ * "OPTIONS" | "TRACE" | ExtensionMethod
+ *
+ * HTTPMethodList ::= HTTPMethod | HTTPMethodList comma HTTPMethod
+ *
+ * HTTPMethodExceptionList ::= exclaimationPoint HTTPMethodList
+ *
+ * HTTPMethodSpec ::= emptyString | HTTPMethodExceptionList |
+ * HTTPMethodList
+ *
+ * transportType ::= "INTEGRAL" | "CONFIDENTIAL" | "NONE"
+ *
+ * actions ::= null | HTTPMethodSpec |
+ * HTTPMethodSpec colon transportType
+ * </pre>
+ *
+ * </p>
+ *
+ * <p>
+ * If duplicates occur in the HTTPMethodSpec they must be eliminated by the permission constructor.
+ * </p>
+ *
+ * <p>
+ * An empty string HTTPMethodSpec is a shorthand for a List containing all the possible HTTP methods.
+ * </p>
+ *
+ * <p>
+ * An actions string without a transportType is a shorthand for a actions string with the value "NONE" as its
+ * TransportType.
+ * </p>
+ *
+ * <p>
+ * A granted permission representing a transportType of "NONE", indicates that the associated resources may be
+ * accessed using any connection type.
+ * </p>
+ *
+ * @param name
+ * - the URLPatternSpec that identifies the application specific web resources to which the permission
+ * pertains. All URLPatterns in the URLPatternSpec are relative to the context path of the deployed web
+ * application module, and the same URLPattern must not occur more than once in a URLPatternSpec. A null
+ * URLPatternSpec is translated to the default URLPattern, “/”, by the permission constructor. All colons
+ * occurring within the URLPattern elements of the URLPatternSpec must be represented in escaped encoding
+ * as defined in RFC 2396.
+ * @param actions
+ * - identifies the HTTP methods and transport type to which the permission pertains. If the value passed
+ * through this parameter is null or the empty string, then the permission is constructed with actions
+ * corresponding to all the possible HTTP methods and transportType "NONE".
+ */
public WebUserDataPermission(String name, String actions)
{
super(name == null ? "/" : name);
- if( name == null )
+ if (name == null)
name = "/";
this.urlSpec = new URLPatternSpec(name);
parseActions(actions);
}
- /** Creates a new WebUserDataPermission with name corresponding to the
- * URLPatternSpec, and actions composed from the array of HTTP methods and
- * the transport type.
+ /**
+ * <p>
+ * Creates a new WebUserDataPermission with name corresponding to the URLPatternSpec, and actions composed from the
+ * array of HTTP methods and the transport type.
+ * </p>
*
- * @param urlPatternSpec - the URLPatternSpec that identifies the application
- * specific web resources to which the permission pertains. All URLPatterns
- * in the URLPatternSpec are relative to the context path of the deployed web
- * application module, and the same URLPattern must not occur more than once
- * in a URLPatternSpec. A null URLPatternSpec is translated to the default
- * URLPattern, "/", by the permission constructor.
- * @param httpMethods - an array of strings each element of which contains
- * the value of an HTTP method. If the value passed through this parameter is
- * null or is an array with no elements, then the permission is constructed
- * with actions containing all the possible HTTP methods.
- * @param transportType - a String whose value is a transportType. If the
- * value passed through this parameter is null, then the permission is
- * constructed with actions containing transportType "NONE".
- */
- public WebUserDataPermission(String urlPatternSpec, String[] httpMethods,
- String transportType)
+ * @param urlPatternSpec
+ * - the URLPatternSpec that identifies the application specific web resources to which the permission
+ * pertains. All URLPatterns in the URLPatternSpec are relative to the context path of the deployed web
+ * application module, and the same URLPattern must not occur more than once in a URLPatternSpec. A null
+ * URLPatternSpec is translated to the default URLPattern, “/”, by the permission constructor. All colons
+ * occurring within the URLPattern elements of the URLPatternSpec must be represented in escaped encoding
+ * as defined in RFC 2396.
+ * @param httpMethods
+ * - an array of strings each element of which contains the value of an HTTP method. If the value passed
+ * through this parameter is null or is an array with no elements, then the permission is constructed with
+ * actions containing all the possible HTTP methods.
+ * @param transportType
+ * - a String whose value is a transportType. If the value passed through this parameter is null, then the
+ * permission is constructed with actions containing transportType "NONE".
+ */
+ public WebUserDataPermission(String urlPatternSpec, String[] httpMethods, String transportType)
{
super(urlPatternSpec);
this.urlSpec = new URLPatternSpec(urlPatternSpec);
Object[] methodInfo = WebResourcePermission.canonicalMethods(httpMethods);
- this.httpMethods = (TreeSet) methodInfo[0];
+ this.httpMethods = (TreeSet<String>) methodInfo[0];
this.httpMethodsString = (String) methodInfo[1];
- if( transportType != null && transportType.equalsIgnoreCase("NONE") )
+ if (transportType != null && transportType.equalsIgnoreCase("NONE"))
transportType = null;
this.transportType = transportType;
}
- /** Checks two WebUserDataPermission objects for equality. WebUserDataPermission
- * objects are equivalent if their URLPatternSpec and (canonicalized) actions
- * values are equivalent. The URLPatternSpec of a reference permission is
- * equivalent to that of an argument permission if their first patterns are
- * equivalent, and the patterns of the URLPatternList of the reference
- * permission collectively match exactly the same set of patterns as are
- * matched by the patterns of the URLPatternList of the argument permission.
+ /**
+ * <p>
+ * Checks two WebUserDataPermission objects for equality. WebUserDataPermission objects are equivalent if their
+ * URLPatternSpec and (canonicalized) actions values are equivalent. The URLPatternSpec of a reference permission is
+ * equivalent to that of an argument permission if their first patterns are equivalent, and the patterns of the
+ * URLPatternList of the reference permission collectively match exactly the same set of patterns as are matched by
+ * the patterns of the URLPatternList of the argument permission.
+ * </p>
*
- * @param p - the WebUserDataPermission object being tested for equality.
- * @return true if the argument WebUserDataPermission object is equivalent to
- * this, false otherwise.
- */
+ * <p>
+ * Two Permission objects, P1 and P2, are equivalent if and only if P1.implies(P2) && P2.implies(P1).
+ * </p>
+ *
+ * @param p
+ * - the WebUserDataPermission object being tested for equality with this WebUserDataPermission.
+ * @return true if the argument WebUserDataPermission object is equivalent to this WebUserDataPermission.
+ */
+ @Override
public boolean equals(Object p)
{
- //boolean equals = false;
- if( p == null || !(p instanceof WebUserDataPermission) )
+ // boolean equals = false;
+ if (p == null || !(p instanceof WebUserDataPermission))
return false;
WebUserDataPermission perm = (WebUserDataPermission) p;
/**
- * Two Permission objects, P1 and P2, are equivalent
- * if and only if P1.implies(P2) && P2.implies(P1).
+ * Two Permission objects, P1 and P2, are equivalent if and only if P1.implies(P2) && P2.implies(P1).
*/
return this.implies(perm) && perm.implies(this);
- /*equals = urlSpec.equals(perm.urlSpec);
- if( equals == true )
- {
- String a0 = getActions();
- String a1 = perm.getActions();
- equals = (a0 != null && a0.equals(a1)) || (a0 == a1);
- }
- return equals;*/
}
- /** Returns a canonical String representation of the actions of this
- * WebUserDataPermission. The canonical form of the actions of a
- * WebUserDataPermission is described by the following syntax description.
- * HTTPMethod ::= "Get" | "POST" | "PUT" | "DELETE" | "HEAD" | "OPTIONS" | "TRACE"
+ /**
+ * <p>
+ * Returns a canonical String representation of the actions of this WebUserDataPermission. The canonical form of the
+ * actions of a WebUserDataPermission is described by the following syntax description.
+ *
+ * <pre>
+ * ExtensionMethod ::= any token as defined by RFC 2616
+ * (that is, 1*[any CHAR except CTLs or separators])
+ * HTTPMethod ::= "GET" | "POST" | "PUT" | "DELETE" | "HEAD" |
+ * "OPTIONS" | "TRACE" | ExtensionMethod
* HTTPMethodList ::= HTTPMethod | HTTPMethodList comma HTTPMethod
- * HTTPMethodSpec ::= emptyString | HTTPMethodList
+ * HTTPMethodExceptionList ::= exclaimationPoint HTTPMethodList
+ * HTTPMethodSpec ::= emptyString | HTTPMethodExceptionList |
+ * HTTPMethodList
* transportType ::= "INTEGRAL" | "CONFIDENTIAL" | "NONE"
- * actions ::= null | HTTPMethodList | HTTPMethodSpec colon transportType
- *
- * If the permission's HTTP methods include the entire HTTP method set and
- * the permission's transport type is "INTEGRAL" or "CONFIDENTIAL", the HTTP
- * methods shall be represented in the canonical form by an empty string
- * HTTPMethodSpec. If the permission's HTTP methods include the entire HTTP
- * method set and the permission's transport type is not "INTEGRAL"or
- * "CONFIDENTIAL", the canonical actions value shall be the null value. If
- * the permission's methods do not include the entire HTTP method set,
- * duplicates must be eliminated and the remaining elements must be sorted
- * into ascending lexical order. The resulting HTTPMethodList must be
- * included in the canonical form, and if the permission's transport type is
- * not "INTEGRAL" or "CONFIDENTIAL", the canonical actions value must be
- * exactly the resulting HTTPMethodList.
+ * actions ::= null | HTTPMethodList |
+ * HTTPMethodSpec colon transportType
+ * </pre>
*
- * @return a String containing the canonicalized actions of this
- * WebUserDataPermission (or the null value).
- */
+ * </p>
+ *
+ * <p>
+ * If the permission's HTTP methods include the entire HTTP method set and the permission's transport type is
+ * "INTEGRAL" or "CONFIDENTIAL", the HTTP methods shall be represented in the canonical form by an empty string
+ * HTTPMethodSpec. If the permission's HTTP methods include the entire HTTP method set and the permission's transport
+ * type is not "INTEGRAL"or "CONFIDENTIAL", the canonical actions value shall be the null value.
+ * </p>
+ *
+ * <p>
+ * If the permission's methods do not include the entire HTTP method set, duplicates must be eliminated and the
+ * remaining elements must be sorted into ascending lexical order. The resulting HTTPMethodList must be included in
+ * the canonical form, and if the permission's transport type is not "INTEGRAL" or "CONFIDENTIAL", the canonical
+ * actions value must be exactly the resulting HTTPMethodList.
+ * </p>
+ *
+ * @return a String containing the canonicalized actions of this WebUserDataPermission (or the null value).
+ */
+ @Override
public String getActions()
{
String actions = null;
- if( httpMethodsString != null )
+ if (httpMethodsString != null)
{
- if( transportType != null )
+ if (transportType != null)
actions = httpMethodsString + ":" + transportType;
else
actions = httpMethodsString;
}
- else if( transportType != null )
+ else if (transportType != null)
{
actions = ":" + transportType;
}
return actions;
}
- /** Returns the hash code value for this WebUserDataPermission. The properties
- * of the returned hash code must be as follows:
-
- * - During the lifetime of a Java application, the hashCode method shall
- * return the same integer value every time it is called on a
- * WebUserDataPermission object. The value returned by hashCode for a
- * particular EJBMethod permission need not remain consistent from one
- * execution of an application to another.
- * - If two WebUserDataPermission 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).
- * @return the int hash code.
- */
+ /**
+ * <p>
+ * Returns the hash code value for this WebUserDataPermission. The properties of the returned hash code must be as
+ * follows:
+ * <ul>
+ * <li>During the lifetime of a Java application, the hashCode method shall return the same integer value every time
+ * it is called on a WebUserDataPermission object. The value returned by hashCode for a particular EJBMethod
+ * permission need not remain consistent from one execution of an application to another.</li>
+ * <li>If two WebUserDataPermission objects are equal according to the equals method, then calling the hash- Code
+ * method on each of the two Permission objects must produce the same integer result (within an application).</li>
+ * </ul>
+ * </p>
+ *
+ * @return the integer hash code value for this object.
+ */
+ @Override
public int hashCode()
{
- int hashCode = urlSpec.hash();
- if( httpMethods != null )
- hashCode += httpMethods.hashCode();
+ int hashCode = 17;
+ hashCode = 37 * hashCode + this.urlSpec.hashCode();
+ if (this.httpMethods != null)
+ hashCode = 37 * hashCode + this.httpMethods.hashCode();
return hashCode;
}
- /** Determines if the argument Permission is "implied by" this
- * WebUserDataPermission. For this to be the case all of the following must
- * be true:
-
- * - The argument is an instanceof WebUserDataPermission.
- * - The first URLPattern in the name of the argument permission is matched
- * by the first URLPattern in the name of this permission.
- * - The first URLPattern in the name of the argument permission is NOT
- * matched by any URLPattern in the URLPatternList of the URLPatternSpec of
- * this permission.
- * - If the first URLPattern in the name of the argument permission matches
- * the first URLPattern in the URLPatternSpec of this permission, then every
- * URLPattern in the URLPatternList of the URLPatternSpec of this permission
- * is matched by a URLPattern in the URLPatternList of the argument
- * permission.
- * - The HTTP methods in the actions of the argument permission are a subset
- * of the HTTP methods in the actions of this permission.
- * - The transportType in the actions of this permission either corresponds
- * to the value "NONE", or equals the transportType in the actions of the
- * argument permission.
+ /**
+ * <p>
+ * Determines if the argument Permission is "implied by" this WebUserDataPermission. For this to be the case all of
+ * the following must be true:
+ * <ul>
+ * <li>The argument is an instance of WebUserDataPermission.</li>
+ * <li>The first URLPattern in the name of the argument permission is matched by the first URLPattern in the name of
+ * this permission.</li>
+ * <li>The first URLPattern in the name of the argument permission is NOT matched by any URLPattern in the
+ * URLPatternList of the URLPatternSpec of this permission.</li>
+ * <li>If the first URLPattern in the name of the argument permission matches the first URLPattern in the
+ * URLPatternSpec of this permission, then every URLPattern in the URLPatternList of the URLPatternSpec of this
+ * permission is matched by a URLPattern in the URLPatternList of the argument permission.</li>
+ * <li>The HTTP methods in the actions of the argument permission are a subset of the HTTP methods in the actions of
+ * this permission.</li>
+ * <li>The transportType in the actions of this permission either corresponds to the value "NONE", or equals the
+ * transportType in the actions of the argument permission.</li>
+ * </ul>
+ * </p>
*
- * URLPattern matching is performed using the Servlet matching rules where
- * two URL patterns match if they are related as follows:
-
- * - their pattern values are String equivalent, or
- * - this pattern is the path-prefix pattern "/*", or
- * - this pattern is a path-prefix pattern (that is, it starts with "/" and
- * ends with "/*") and the argument pattern starts with the substring of this
- * pattern, minus its last 2 characters, and the next character of the
- * argument pattern, if there is one, is "/", or
- * - this pattern is an extension pattern (that is, it starts with "*.") and
- * the argument pattern ends with this pattern, or
- * - the reference pattern is the special default pattern, "/", which matches
- * all argument patterns.
+ * <p>
+ * URLPattern matching is performed using the <i>Servlet matching rules</i> where two URL patterns match if they are
+ * related as follows:
+ * <ul>
+ * <li>their pattern values are String equivalent, or</li>
+ * <li>this pattern is the path-prefix pattern "/*", or</li>
+ * <li>this pattern is a path-prefix pattern (that is, it starts with "/" and ends with "/*") and the argument
+ * pattern starts with the substring of this pattern, minus its last 2 characters, and the next character of the
+ * argument pattern, if there is one, is "/", or</li>
+ * <li>this pattern is an extension pattern (that is, it starts with "*.") and the argument pattern ends with this
+ * pattern, or</li>
+ * <li>the reference pattern is the special default pattern, "/", which matches all argument patterns.</li>
+ * </ul>
+ * </p>
*
- * All of the comparisons described above are case sensitive.
+ * <p>
+ * All of the comparisons described above are case sensitive.
+ * </p>
*
- * @param p - the WebUserDataPermission to test
- * @return true if this implies the argument permission
- */
+ * @param p
+ * - “this” WebUserDataPermission is checked to see if it implies the argument permission.
+ * @return true if the specified permission is implied by this object, false if not.
+ */
+ @Override
public boolean implies(Permission p)
{
- if( p == null || !(p instanceof WebUserDataPermission) )
+ if (p == null || !(p instanceof WebUserDataPermission))
return false;
WebUserDataPermission perm = (WebUserDataPermission) p;
// Check the URL patterns
boolean implies = urlSpec.implies(perm.urlSpec);
- if( implies == true )
+ if (implies == true)
{
- if(httpExceptionList != null)
- implies = WebResourcePermission.matchExceptionList(httpExceptionList,
- perm.httpExceptionList);
- //Check the http methods
- if( httpMethods != null && perm.httpMethods != null)
- implies = httpMethods.containsAll(perm.httpMethods);
- // Check the transport guarentee
- if( implies == true && transportType != null )
+ if (httpExceptionList != null)
+ implies = WebResourcePermission.matchExceptionList(httpExceptionList, perm.httpExceptionList);
+ // Check the http methods
+ if (httpMethods != null && perm.httpMethods != null)
+ implies = httpMethods.containsAll(perm.httpMethods);
+ // Check the transport guarantee
+ if (implies == true && transportType != null)
implies = transportType.equals(perm.transportType);
- }
-
+ }
+
return implies;
}
// Private -------------------------------------------------------
- /** Build the request permission actions from the HTTP method component
- * using HttpServletRequest.getMethod() + the TransportType component of the
- * action from HttpServletRequest.isSecure().
+ /**
+ * Build the request permission actions from the HTTP method component using HttpServletRequest.getMethod() + the
+ * TransportType component of the action from HttpServletRequest.isSecure().
*
- * @param request - the servlet request
+ * @param request
+ * - the servlet request
* @return the permission actions string
- */
+ */
private static String requestActions(HttpServletRequest request)
{
- String actions = request.getMethod() +
- (request.isSecure() ? ":CONFIDENTIAL" : "");
+ String actions = request.getMethod() + (request.isSecure() ? ":CONFIDENTIAL" : "");
return actions;
}
private void parseActions(String actions)
{
// Remove any transport spec
- if( actions != null )
+ if (actions != null)
{
int colon = actions.indexOf(':');
- if( colon >= 0 )
+ if (colon >= 0)
{
- this.transportType = actions.substring(colon+1);
- if( transportType.equalsIgnoreCase("NONE") )
+ this.transportType = actions.substring(colon + 1);
+ if (transportType.equalsIgnoreCase("NONE"))
transportType = null;
actions = actions.substring(0, colon);
}
}
boolean exceptionListNeeded = actions != null && actions.startsWith("!");
-
+
Object[] methodInfo = WebResourcePermission.canonicalMethods(actions);
- if(exceptionListNeeded)
+ if (exceptionListNeeded)
{
- this.httpExceptionList = (TreeSet) methodInfo[0];
+ this.httpExceptionList = (TreeSet<String>) methodInfo[0];
this.httpExceptionString = (String) methodInfo[1];
}
else
- {
- this.httpMethods = (TreeSet) methodInfo[0];
+ {
+ this.httpMethods = (TreeSet<String>) methodInfo[0];
this.httpMethodsString = (String) methodInfo[1];
}
}
- private void readObject(ObjectInputStream ois)
- throws ClassNotFoundException, IOException
+ private void readObject(ObjectInputStream ois) throws ClassNotFoundException, IOException
{
ObjectInputStream.GetField fields = ois.readFields();
String actions = (String) fields.get("actions", null);
parseActions(actions);
}
- private void writeObject(ObjectOutputStream oos)
- throws IOException
+ private void writeObject(ObjectOutputStream oos) throws IOException
{
- ObjectOutputStream.PutField fields = oos.putFields();
+ ObjectOutputStream.PutField fields = oos.putFields();
fields.put("actions", this.getActions());
oos.writeFields();
}
Modified: projects/specs/trunk/jboss-specs-parent/pom.xml
===================================================================
--- projects/specs/trunk/jboss-specs-parent/pom.xml 2010-03-22 19:00:47 UTC (rev 102731)
+++ projects/specs/trunk/jboss-specs-parent/pom.xml 2010-03-22 19:15:14 UTC (rev 102732)
@@ -58,6 +58,7 @@
<module>../jboss-el-api_2.2_spec</module>
<module>../jboss-interceptors-api_1.1_spec</module>
<module>../jboss-jacc-api_1.1_spec</module>
+ <module>../jboss-jacc-api_1.4_spec</module>
<module>../jboss-jad-api_1.2_spec</module>
<module>../jboss-jaspi-api_1.0_spec</module>
<module>../jboss-jaxr-api_1.0_spec</module>
More information about the jboss-cvs-commits
mailing list