[jbossweb-commits] JBossWeb SVN: r1184 - trunk/java/javax/servlet/annotation.

Author: remy.maucherat(a)jboss.com Date: 2009-10-07 07:59:37 -0400 (Wed, 07 Oct 2009) New Revision: 1184 Added: trunk/java/javax/servlet/annotation/HttpConstraint.java trunk/java/javax/servlet/annotation/HttpMethodConstraint.java trunk/java/javax/servlet/annotation/ServletSecurity.java Modified: trunk/java/javax/servlet/annotation/WebListener.java Log: - Today's update: add the security annotations. Added: trunk/java/javax/servlet/annotation/HttpConstraint.java =================================================================== --- trunk/java/javax/servlet/annotation/HttpConstraint.java (rev 0) +++ trunk/java/javax/servlet/annotation/HttpConstraint.java 2009-10-07 11:59:37 UTC (rev 1184) @@ -0,0 +1,98 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 2008-2009 Sun Microsystems, Inc. All rights reserved. + * + * The contents of this file are subject to the terms of either the GNU + * General Public License Version 2 only ("GPL") or the Common Development + * and Distribution License("CDDL") (collectively, the "License"). You + * may not use this file except in compliance with the License. You can obtain + * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html + * or glassfish/bootstrap/legal/LICENSE.txt. See the License for the specific + * language governing permissions and limitations under the License. + * + * When distributing the software, include this License Header Notice in each + * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [year] + * [name of copyright owner]" + * + * Contributor(s): + * + * If you wish your version of this file to be governed by only the CDDL or + * only the GPL Version 2, indicate your decision by adding "[Contributor] + * elects to include this software in this distribution under the [CDDL or GPL + * Version 2] license." If you don't indicate a single choice of license, a + * recipient has the option to distribute your version of this file under + * either the CDDL, the GPL Version 2 or to extend the choice of license to + * its licensees as provided above. However, if you add GPL Version 2 code + * and therefore, elected the GPL Version 2 license, then the option applies + * only if the new code is made subject to such option by the copyright + * holder. + */ +package javax.servlet.annotation; + +import java.lang.annotation.Documented; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import javax.servlet.annotation.ServletSecurity.EmptyRoleSemantic; +import javax.servlet.annotation.ServletSecurity.TransportGuarantee; + +/** + * This annotation is used within the {@link ServletSecurity} annotation to + * represent the security constraints to be applied to all HTTP protocol + * methods for which a corresponding {@link HttpMethodConstraint} element does + * NOT occur within the {@link ServletSecurity} annotation. + * + * @since Servlet 3.0 + */ +@Documented +(a)Retention(RetentionPolicy.RUNTIME) +public @interface HttpConstraint { + + /** + * The default authorization semantic. + * This value is insignificant when <code>rolesAllowed</code> returns a + * non-empty array, and should not be specified when a non-empty + * array is specified for <tt>rolesAllowed<tt>. + * + * @return the {@link EmptyRoleSemantic} to be applied when + * <code>rolesAllowed</code> returns an empty (that is, zero-length) array. + */ + EmptyRoleSemantic value() default EmptyRoleSemantic.PERMIT; + + /** + * The data protection requirements (i.e., whether or not SSL/TLS is + * required) that must be satisfied by the connections on which requests + * arrive. + * + * @return the {@link TransportGuarantee} + * indicating the data protection that must be provided by the connection. + */ + TransportGuarantee transportGuarantee() default TransportGuarantee.NONE; + + /** + * The names of the authorized roles. + * + * Duplicate role names appearing in rolesAllowed are insignificant and + * may be discarded during runtime processing of the annotation. The String + * <tt>"*"</tt> has no special meaning as a role name (should it occur in + * rolesAllowed). + * + * @return an array of zero or more role names. When the array contains + * zero elements, its meaning depends on the <code>EmptyRoleSemantic</code> + * returned by the <code>value</code> method. If <code>value</code> returns + * <tt>DENY</tt>, and <code>rolesAllowed</code> returns a zero length array, + * access is to be denied independent of authentication state and identity. + * Conversely, if <code>value</code> returns <code>PERMIT</code>, it + * indicates that access is to be allowed independent of authentication + * state and identity. When the array contains the names of one or more + * roles, it indicates that access is contingent on membership in at + * least one of the named roles (independent of the + * <code>EmptyRoleSemantic</code> returned by the <code>value</code> method). + */ + String[] rolesAllowed() default {}; +} Added: trunk/java/javax/servlet/annotation/HttpMethodConstraint.java =================================================================== --- trunk/java/javax/servlet/annotation/HttpMethodConstraint.java (rev 0) +++ trunk/java/javax/servlet/annotation/HttpMethodConstraint.java 2009-10-07 11:59:37 UTC (rev 1184) @@ -0,0 +1,105 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 2008-2009 Sun Microsystems, Inc. All rights reserved. + * + * The contents of this file are subject to the terms of either the GNU + * General Public License Version 2 only ("GPL") or the Common Development + * and Distribution License("CDDL") (collectively, the "License"). You + * may not use this file except in compliance with the License. You can obtain + * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html + * or glassfish/bootstrap/legal/LICENSE.txt. See the License for the specific + * language governing permissions and limitations under the License. + * + * When distributing the software, include this License Header Notice in each + * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [year] + * [name of copyright owner]" + * + * Contributor(s): + * + * If you wish your version of this file to be governed by only the CDDL or + * only the GPL Version 2, indicate your decision by adding "[Contributor] + * elects to include this software in this distribution under the [CDDL or GPL + * Version 2] license." If you don't indicate a single choice of license, a + * recipient has the option to distribute your version of this file under + * either the CDDL, the GPL Version 2 or to extend the choice of license to + * its licensees as provided above. However, if you add GPL Version 2 code + * and therefore, elected the GPL Version 2 license, then the option applies + * only if the new code is made subject to such option by the copyright + * holder. + */ +package javax.servlet.annotation; + +import java.lang.annotation.Documented; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import javax.servlet.annotation.ServletSecurity.EmptyRoleSemantic; +import javax.servlet.annotation.ServletSecurity.TransportGuarantee; + +/** + * This annotation is used within the {@link ServletSecurity} annotation to + * represent security constraints on specific HTTP protocol messages. + * + * @since Servlet 3.0 + */ +@Documented +(a)Retention(RetentionPolicy.RUNTIME) +public @interface HttpMethodConstraint { + + /** + * Http protocol method name + * + * @return the name of an HTTP protocol method. <code>value</code> + * may not be null, or the empty string, and must be a + * legitimate HTTP Method name as defined by RFC 2616. + */ + String value(); + + /** + * The default authorization semantic. + * This value is insignificant when <code>rolesAllowed</code> returns a + * non-empty array, and should not be specified when a non-empty + * array is specified for <tt>rolesAllowed</tt>. + * + * @return the {@link EmptyRoleSemantic} to be applied when + * <code>rolesAllowed</code> returns an empty (that is, zero-length) array. + */ + EmptyRoleSemantic emptyRoleSemantic() default EmptyRoleSemantic.PERMIT; + + /** + * The data protection requirements (i.e., whether or not SSL/TLS is + * required) that must be satisfied by the connections on which requests + * arrive. + * + * @return the {@link TransportGuarantee} + * indicating the data protection that must be provided by the connection. + */ + TransportGuarantee transportGuarantee() default TransportGuarantee.NONE; + + /** + * The names of the authorized roles. + * + * Duplicate role names appearing in rolesAllowed are insignificant and + * may be discarded during runtime processing of the annotation. The String + * <tt>"*"</tt> has no special meaning as a role name (should it occur in + * rolesAllowed). + * + * @return an array of zero or more role names. When the array contains + * zero elements, its meaning depends on the value returned by + * <code>emptyRoleSemantic</code>. If <code>emptyRoleSemantic</code> returns + * <tt>DENY</tt>, and <code>rolesAllowed</code> returns a zero length array, + * access is to be denied independent of authentication state and identity. + * Conversely, if <code>emptyRoleSemantic</code> returns + * <code>PERMIT</code>, it indicates that access is to be allowed + * independent of authentication state and identity. When the array + * contains the names of one or more roles, it indicates that access is + * contingent on membership in at least one of the named roles (independent + * of the value returned by <code>emptyRoleSemantic</code>). + */ + String[] rolesAllowed() default {}; +} Added: trunk/java/javax/servlet/annotation/ServletSecurity.java =================================================================== --- trunk/java/javax/servlet/annotation/ServletSecurity.java (rev 0) +++ trunk/java/javax/servlet/annotation/ServletSecurity.java 2009-10-07 11:59:37 UTC (rev 1184) @@ -0,0 +1,117 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 2008-2009 Sun Microsystems, Inc. All rights reserved. + * + * The contents of this file are subject to the terms of either the GNU + * General Public License Version 2 only ("GPL") or the Common Development + * and Distribution License("CDDL") (collectively, the "License"). You + * may not use this file except in compliance with the License. You can obtain + * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html + * or glassfish/bootstrap/legal/LICENSE.txt. See the License for the specific + * language governing permissions and limitations under the License. + * + * When distributing the software, include this License Header Notice in each + * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [year] + * [name of copyright owner]" + * + * Contributor(s): + * + * If you wish your version of this file to be governed by only the CDDL or + * only the GPL Version 2, indicate your decision by adding "[Contributor] + * elects to include this software in this distribution under the [CDDL or GPL + * Version 2] license." If you don't indicate a single choice of license, a + * recipient has the option to distribute your version of this file under + * either the CDDL, the GPL Version 2 or to extend the choice of license to + * its licensees as provided above. However, if you add GPL Version 2 code + * and therefore, elected the GPL Version 2 license, then the option applies + * only if the new code is made subject to such option by the copyright + * holder. + */ + +package javax.servlet.annotation; + + +import java.lang.annotation.Documented; +import java.lang.annotation.ElementType; +import java.lang.annotation.Inherited; +import java.lang.annotation.Target; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; + +/** + * This annotation is used on a Servlet implementation class to specify security + * constraints to be enforced by a Servlet container on HTTP protocol messages. + * The Servlet container will enforce these constraints on the url-patterns + * mapped to the servlets mapped to the annotated class. + * + * @since Servlet 3.0 + */ + +@Inherited +@Documented +(a)Target(ElementType.TYPE) +(a)Retention(RetentionPolicy.RUNTIME) +public @interface ServletSecurity { + + /** + * Defines the access semantic to be applied to an empty rolesAllowed array. + */ + enum EmptyRoleSemantic { + /** + * access is to be permitted independent of authentication state and + * identity. + */ + PERMIT, + /** + * access is to be denied independent of authentication state and + * identity. + */ + DENY + } + + /** + * Defines the data protection requirements that must be satisfied by + * the transport + */ + enum TransportGuarantee { + /** + * no protection of user data must be performed by the transport. + */ + NONE, + /** + * All user data must be encrypted by the transport (typically + * using SSL/TLS). + */ + CONFIDENTIAL + } + + /** + * Get the {@link HttpConstraint} that defines the protection + * that is to be applied to all HTTP methods that are NOT represented in + * the array returned by <tt>httpMethodConstraints</tt>. + * + * @return a <code>HttpConstraint</code> object. + */ + HttpConstraint value() default @HttpConstraint; + + /** + * Get the HTTP method specific constraints. Each + * {@link HttpMethodConstraint} names an HTTP protocol method + * and defines the protection to be applied to it. + * + * @return an array of {@link HttpMethodConstraint} elements each + * defining the protection to be applied to one HTTP protocol method. For + * any HTTP method name, there must be at most one corresponding element in + * the returned array. If the returned array is of zero length, it indicates + * that no HTTP method specific constraints are defined. + */ + + + HttpMethodConstraint[] httpMethodConstraints() default {}; +} Modified: trunk/java/javax/servlet/annotation/WebListener.java =================================================================== --- trunk/java/javax/servlet/annotation/WebListener.java 2009-10-02 14:48:06 UTC (rev 1183) +++ trunk/java/javax/servlet/annotation/WebListener.java 2009-10-07 11:59:37 UTC (rev 1184) @@ -61,6 +61,6 @@ /** * Description of the listener */ - String description() default ""; + String value() default ""; }