Author: remy.maucherat(a)jboss.com Date: 2009-11-04 17:24:35 -0500 (Wed, 04 Nov 2009) New Revision: 1239 Modified: trunk/java/javax/servlet/ServletRegistration.java trunk/java/javax/servlet/annotation/WebServlet.java trunk/java/javax/servlet/http/Cookie.java trunk/java/javax/servlet/http/LocalStrings.properties Log: - Today's spec update. Modified: trunk/java/javax/servlet/ServletRegistration.java =================================================================== --- trunk/java/javax/servlet/ServletRegistration.java 2009-11-04 18:02:20 UTC (rev 1238) +++ trunk/java/javax/servlet/ServletRegistration.java 2009-11-04 22:24:35 UTC (rev 1239) @@ -102,9 +102,9 @@ * * <p>A <tt>loadOnStartup</tt> value of greater than or equal to * zero indicates to the container the initialization priority of - * the Servlet. In this case, the container must instantiate and + * the Servlet. In this case, the container must instantiate and * initialize the Servlet during the initialization phase of the - * ServletContext, that is, after it has invoked all of the + * ServletContext, that is, after it has invoked all of the * ServletContextListener objects configured for the ServletContext * at their {@link ServletContextListener#contextInitialized} * method. @@ -125,46 +125,47 @@ /** * Sets the {@link ServletSecurityElement} to be applied to the - * mappings currently assigned to this - * <code>ServletRegistration</code>. + * mappings defined for this <code>ServletRegistration</code>. * - * <p>Any mappings added to this ServletRegistration after a call - * to this method may be secured by a subsequent call to this method. - * - * <p>If a url-pattern of this ServletRegistration is an exact - * target of a <code>security-constraint</code> that was established - * via the portable deployment descriptor, then this method does not - * change the <code>security-constraint</code> for that pattern, and - * the pattern will be included in the return value. - * - * <p>If a url-pattern of this ServletRegistration is an exact target - * of a security constraint that was established via the - * {@link javax.servlet.annotation.ServletSecurity} annotation or a - * previous call to this method, then this method replaces the - * security constraint for that pattern. + * <p>This method applies to all mappings added to this + * <code>ServletRegistration</code> up until the point that the + * <code>ServletContext</code> from which it was obtained has been + * initialized. * - * <p>If a url-pattern of this ServletRegistration is neither the - * exact target of a security constraint that was established via the - * {@link javax.servlet.annotation.ServletSecurity} annotation or - * a previous call to this method, nor the exact target of a - * </code>security-constraint</code> in the portable deployment - * descriptor, then this method establishes the security - * constraint for that pattern from the argument - * ServletSecurityElement. + * <p>If a URL pattern of this ServletRegistration is an exact target + * of a <code>security-constraint</code> that was established via + * the portable deployment descriptor, then this method does not + * change the <code>security-constraint</code> for that pattern, + * and the pattern will be included in the return value. * + * <p>If a URL pattern of this ServletRegistration is an exact + * target of a security constraint that was established via the + * {@link javax.servlet.annotation.ServletSecurity} annotation + * or a previous call to this method, then this method replaces + * the security constraint for that pattern. + * + * <p>If a URL pattern of this ServletRegistration is neither the + * exact target of a security constraint that was established via + * the {@link javax.servlet.annotation.ServletSecurity} annotation + * or a previous call to this method, nor the exact target of a + * <code>security-constraint</code> in the portable deployment + * descriptor, then this method establishes the security constraint + * for that pattern from the argument + * <code>ServletSecurityElement</code>. + * * @param constraint the {@link ServletSecurityElement} to be applied - * to the patterns currently mapped to this ServletRegistration + * to the patterns mapped to this ServletRegistration * * @return the (possibly empty) Set of URL patterns that were already * the exact target of a <code>security-constraint</code> that was * established via the portable deployment descriptor. This method - * has no effect on the patterns included in the returned set. + * has no effect on the patterns included in the returned set * * @throws IllegalArgumentException if <tt>constraint</tt> is null * * @throws IllegalStateException if the {@link ServletContext} from - * which this ServletRegistration was obtained has already been - * initialized + * which this <code>ServletRegistration</code> was obtained has + * already been initialized */ public Set<String> setServletSecurity(ServletSecurityElement constraint); @@ -175,7 +176,7 @@ * effects of the former. * * @param multipartConfig the {@link MultipartConfigElement} to be - * applied to the patterns mapped to the registration + * applied to the patterns mapped to the registration * * @throws IllegalArgumentException if <tt>multipartConfig</tt> is * null @@ -188,10 +189,10 @@ MultipartConfigElement multipartConfig); /** - * Sets the name of the runAs role for the + * Sets the name of the <code>runAs</code> role for this * <code>ServletRegistration</code>. * - * @param roleName + * @param roleName the name of the <code>runAs</code> role * * @throws IllegalArgumentException if <tt>roleName</tt> is null * Modified: trunk/java/javax/servlet/annotation/WebServlet.java =================================================================== --- trunk/java/javax/servlet/annotation/WebServlet.java 2009-11-04 18:02:20 UTC (rev 1238) +++ trunk/java/javax/servlet/annotation/WebServlet.java 2009-11-04 22:24:35 UTC (rev 1239) @@ -108,4 +108,9 @@ */ String description() default ""; + /** + * * The display name of the filter + */ + String displayName() default ""; + } Modified: trunk/java/javax/servlet/http/Cookie.java =================================================================== --- trunk/java/javax/servlet/http/Cookie.java 2009-11-04 18:02:20 UTC (rev 1238) +++ trunk/java/javax/servlet/http/Cookie.java 2009-11-04 22:24:35 UTC (rev 1239) @@ -52,10 +52,9 @@ * limitations under the License. */ - - package javax.servlet.http; +import java.io.Serializable; import java.text.MessageFormat; import java.util.ResourceBundle; @@ -93,20 +92,19 @@ * (by RFC 2109) cookie specifications. By default, cookies are * created using Version 0 to ensure the best interoperability. * - * * @author Various */ +public class Cookie implements Cloneable, Serializable { -// XXX would implement java.io.Serializable too, but can't do that -// so long as sun.servlet.* must run on older JDK 1.02 JVMs which -// don't include that support. + private static final long serialVersionUID = -6454587001725327448L; -public class Cookie implements Cloneable { + private static final String tspecials = "/()<>@,;:\\\"[]?={} \t"; private static final String LSTRING_FILE = - "javax.servlet.http.LocalStrings"; + "javax.servlet.http.LocalStrings"; + private static ResourceBundle lStrings = - ResourceBundle.getBundle(LSTRING_FILE); + ResourceBundle.getBundle(LSTRING_FILE); // // The value of the cookie itself. @@ -127,11 +125,9 @@ private boolean secure; // ;Secure ... e.g. use SSL private int version = 0; // ;Version=1 ... means RFC 2109++ style private boolean isHttpOnly = false; - - /** - * Constructs a cookie with a specified name and value. + * Constructs a cookie with the specified name and value. * * <p>The name must conform to RFC 2109. That means it can contain * only ASCII alphanumeric characters and cannot contain commas, @@ -147,49 +143,45 @@ * cookie specification. The version can be changed with the * <code>setVersion</code> method. * + * @param name the name of the cookie * - * @param name a <code>String</code> specifying the name of the cookie + * @param value the value of the cookie * - * @param value a <code>String</code> specifying the value of the cookie + * @throws IllegalArgumentException if the cookie name is null or + * empty or contains any illegal characters (for example, a comma, + * space, or semicolon) or matches a token reserved for use by the + * cookie protocol * - * @throws IllegalArgumentException if the cookie name contains illegal characters - * (for example, a comma, space, or semicolon) - * or it is one of the tokens reserved for use - * by the cookie protocol * @see #setValue * @see #setVersion - * */ - public Cookie(String name, String value) { - if (!isToken(name) - || name.equalsIgnoreCase("Comment") // rfc2019 - || name.equalsIgnoreCase("Discard") // 2019++ - || name.equalsIgnoreCase("Domain") - || name.equalsIgnoreCase("Expires") // (old cookies) - || name.equalsIgnoreCase("Max-Age") // rfc2019 - || name.equalsIgnoreCase("Path") - || name.equalsIgnoreCase("Secure") - || name.equalsIgnoreCase("Version") - || name.startsWith("$") - ) { - String errMsg = lStrings.getString("err.cookie_name_is_token"); - Object[] errArgs = new Object[1]; - errArgs[0] = name; - errMsg = MessageFormat.format(errMsg, errArgs); - throw new IllegalArgumentException(errMsg); - } + if (name == null || name.length() == 0) { + throw new IllegalArgumentException( + lStrings.getString("err.cookie_name_blank")); + } + if (!isToken(name) || + name.equalsIgnoreCase("Comment") || // rfc2019 + name.equalsIgnoreCase("Discard") || // 2019++ + name.equalsIgnoreCase("Domain") || + name.equalsIgnoreCase("Expires") || // (old cookies) + name.equalsIgnoreCase("Max-Age") || // rfc2019 + name.equalsIgnoreCase("Path") || + name.equalsIgnoreCase("Secure") || + name.equalsIgnoreCase("Version") || + name.startsWith("$")) { + String errMsg = lStrings.getString("err.cookie_name_is_token"); + Object[] errArgs = new Object[1]; + errArgs[0] = name; + errMsg = MessageFormat.format(errMsg, errArgs); + throw new IllegalArgumentException(errMsg); + } - this.name = name; - this.value = value; + this.name = name; + this.value = value; } - - - - /** - * * Specifies a comment that describes a cookie's purpose. * The comment is useful if the browser presents the cookie * to the user. Comments @@ -199,35 +191,23 @@ * to display to the user * * @see #getComment - * */ - public void setComment(String purpose) { - comment = purpose; + comment = purpose; } - - - /** * Returns the comment describing the purpose of this cookie, or * <code>null</code> if the cookie has no comment. * - * @return a <code>String</code> containing the comment, - * or <code>null</code> if none + * @return the comment of the cookie, or <code>null</code> if unspecified * * @see #setComment - * */ - public String getComment() { - return comment; + return comment; } - - - - /** * * Specifies the domain within which this cookie should be presented. @@ -239,42 +219,30 @@ * <code>a.b.foo.com</code>). By default, cookies are only returned * to the server that sent them. * + * @param domain the domain name within which this cookie is visible; + * form is according to RFC 2109 * - * @param pattern a <code>String</code> containing the domain name - * within which this cookie is visible; - * form is according to RFC 2109 - * * @see #getDomain - * */ - - public void setDomain(String pattern) { - domain = pattern.toLowerCase(); // IE allegedly needs this + public void setDomain(String domain) { + this.domain = domain.toLowerCase(); // IE allegedly needs this } - - - - /** - * Returns the domain name set for this cookie. The form of - * the domain name is set by RFC 2109. + * Gets the domain name of this Cookie. * - * @return a <code>String</code> containing the domain name + * <p>Domain names are formatted according to RFC 2109. * - * @see #setDomain + * @return the domain name of this Cookie * + * @see #setDomain */ - public String getDomain() { - return domain; + return domain; } - - - /** - * Sets the maximum age of the cookie in seconds. + * Sets the maximum age in seconds for this Cookie. * * <p>A positive value indicates that the cookie will expire * after that many seconds have passed. Note that the value is @@ -291,40 +259,28 @@ * the cookie is not stored; if zero, deletes * the cookie * - * * @see #getMaxAge - * */ - public void setMaxAge(int expiry) { - maxAge = expiry; + maxAge = expiry; } - - - /** - * Returns the maximum age of the cookie, specified in seconds, - * By default, <code>-1</code> indicating the cookie will persist - * until browser shutdown. + * Gets the maximum age in seconds of this Cookie. * + * <p>By default, <code>-1</code> is returned, which indicates that + * the cookie will persist until browser shutdown. * * @return an integer specifying the maximum age of the * cookie in seconds; if negative, means * the cookie persists until browser shutdown * - * * @see #setMaxAge - * */ - public int getMaxAge() { - return maxAge; + return maxAge; } - - - /** * Specifies a path for the cookie * to which the client should return the cookie. @@ -341,140 +297,96 @@ * * @param uri a <code>String</code> specifying a path * - * * @see #getPath - * */ - public void setPath(String uri) { - path = uri; + path = uri; } - - - /** * Returns the path on the server * to which the browser returns this cookie. The * cookie is visible to all subpaths on the server. * - * * @return a <code>String</code> specifying a path that contains * a servlet name, for example, <i>/catalog</i> * * @see #setPath - * */ - public String getPath() { - return path; + return path; } - - - - /** * Indicates to the browser whether the cookie should only be sent * using a secure protocol, such as HTTPS or SSL. * * <p>The default value is <code>false</code>. * - * @param flag if <code>true</code>, sends the cookie from the browser - * to the server only when using a secure protocol; - * if <code>false</code>, sent on any protocol + * @param flag if <code>true</code>, sends the cookie from the browser + * to the server only when using a secure protocol; if <code>false</code>, + * sent on any protocol * * @see #getSecure - * */ - public void setSecure(boolean flag) { - secure = flag; + secure = flag; } - - - /** * Returns <code>true</code> if the browser is sending cookies * only over a secure protocol, or <code>false</code> if the * browser can send cookies using any protocol. * - * @return <code>true</code> if the browser uses a secure protocol; - * otherwise, <code>true</code> + * @return <code>true</code> if the browser uses a secure protocol, + * <code>false</code> otherwise * * @see #setSecure - * */ - public boolean getSecure() { - return secure; + return secure; } - - - - /** * Returns the name of the cookie. The name cannot be changed after * creation. * - * @return a <code>String</code> specifying the cookie's name - * + * @return the name of the cookie */ - public String getName() { - return name; + return name; } - - - - /** + * Assigns a new value to this Cookie. + * + * <p>If you use a binary value, you may want to use BASE64 encoding. * - * Assigns a new value to a cookie after the cookie is created. - * If you use a binary value, you may want to use BASE64 encoding. - * * <p>With Version 0 cookies, values should not contain white * space, brackets, parentheses, equals signs, commas, * double quotes, slashes, question marks, at signs, colons, * and semicolons. Empty values may not behave the same way * on all browsers. * - * @param newValue a <code>String</code> specifying the new value + * @param newValue the new value of the cookie * - * * @see #getValue - * @see Cookie - * */ - public void setValue(String newValue) { - value = newValue; + value = newValue; } - - - /** - * Returns the value of the cookie. + * Gets the current value of this Cookie. * - * @return a <code>String</code> containing the cookie's - * present value + * @return the current value of this Cookie * * @see #setValue - * @see Cookie - * */ - public String getValue() { - return value; + return value; } - - - /** * Returns the version of the protocol this cookie complies * with. Version 1 complies with RFC 2109, @@ -482,126 +394,98 @@ * cookie specification drafted by Netscape. Cookies provided * by a browser use and identify the browser's cookie version. * - * * @return 0 if the cookie complies with the * original Netscape specification; 1 * if the cookie complies with RFC 2109 * * @see #setVersion - * */ - public int getVersion() { - return version; + return version; } - - - /** - * Sets the version of the cookie protocol this cookie complies - * with. Version 0 complies with the original Netscape cookie + * Sets the version of the cookie protocol that this Cookie complies + * with. + * + * <p>Version 0 complies with the original Netscape cookie * specification. Version 1 complies with RFC 2109. * * <p>Since RFC 2109 is still somewhat new, consider * version 1 as experimental; do not use it yet on production sites. * + * @param v 0 if the cookie should comply with the original Netscape + * specification; 1 if the cookie should comply with RFC 2109 * - * @param v 0 if the cookie should comply with - * the original Netscape specification; - * 1 if the cookie should comply with RFC 2109 - * * @see #getVersion - * */ - public void setVersion(int v) { - version = v; + version = v; } - // Note -- disabled for now to allow full Netscape compatibility - // from RFC 2068, token special case characters - // - // private static final String tspecials = "()<>@,;:\\\"/[]?={} \t"; - - private static final String tspecials = ",; "; - - - - /* * Tests a string and returns true if the string counts as a * reserved token in the Java language. * - * @param value the <code>String</code> to be tested + * @param value the <code>String</code> to be tested * - * @return <code>true</code> if the <code>String</code> is - * a reserved token; <code>false</code> - * if it is not + * @return <code>true</code> if the <code>String</code> is a reserved + * token; <code>false</code> otherwise */ - private boolean isToken(String value) { - int len = value.length(); + int len = value.length(); + for (int i = 0; i < len; i++) { + char c = value.charAt(i); + if (c < 0x20 || c >= 0x7f || tspecials.indexOf(c) != -1) { + return false; + } + } - for (int i = 0; i < len; i++) { - char c = value.charAt(i); + return true; + } - if (c < 0x20 || c >= 0x7f || tspecials.indexOf(c) != -1) - return false; - } - return true; + /** + * Overrides the standard <code>java.lang.Object.clone</code> + * method to return a copy of this Cookie. + */ + public Object clone() { + try { + return super.clone(); + } catch (CloneNotSupportedException e) { + throw new RuntimeException(e.getMessage()); + } } - - - - - /** + * Marks or unmarks this Cookie as <i>HttpOnly</i>. * - * Overrides the standard <code>java.lang.Object.clone</code> - * method to return a copy of this cookie. - * + * <p>If <tt>isHttpOnly</tt> is set to <tt>true</tt>, this cookie is + * marked as <i>HttpOnly</i>, by adding the <tt>HttpOnly</tt> attribute + * to it. * + * <p><i>HttpOnly</i> cookies are not supposed to be exposed to + * client-side scripting code, and may therefore help mitigate certain + * kinds of cross-site scripting attacks. + * + * @param isHttpOnly true if this cookie is to be marked as + * <i>HttpOnly</i>, false otherwise + * + * @since Servlet 3.0 */ - - public Object clone() { - try { - return super.clone(); - } catch (CloneNotSupportedException e) { - throw new RuntimeException(e.getMessage()); - } + public void setHttpOnly(boolean isHttpOnly) { + this.isHttpOnly = isHttpOnly; } - /** - * Marks or unmarks this cookie as <i>HttpOnly</i>. - * - * <p>If <tt>isHttpOnly</tt> is set to <tt>true</tt>, this cookie is - * marked as <i>HttpOnly</i>, by adding the <tt>HttpOnly</tt> attribute - * to it. - * - * <p><i>HttpOnly</i> cookies are not supposed to be exposed to - * client-side scripting code, and may therefore help mitigate certain - * kinds of cross-site scripting attacks. - * - * @param isHttpOnly true if this cookie is to be marked as - * <i>HttpOnly</i>, false otherwise - * - * @since Servlet 3.0 - */ - public void setHttpOnly(boolean isHttpOnly) { - this.isHttpOnly = isHttpOnly; - } - /** - * Checks whether this cookie has been marked as <i>HttpOnly</i>. - * - * @return true if this cookie has been marked as <i>HttpOnly</i>, - * false otherwise - * - * @since Servlet 3.0 - */ - public boolean isHttpOnly() { - return isHttpOnly; - } + /** + * Checks whether this Cookie has been marked as <i>HttpOnly</i>. + * + * @return true if this Cookie has been marked as <i>HttpOnly</i>, + * false otherwise + * + * @since Servlet 3.0 + */ + public boolean isHttpOnly() { + return isHttpOnly; + } } Modified: trunk/java/javax/servlet/http/LocalStrings.properties =================================================================== --- trunk/java/javax/servlet/http/LocalStrings.properties 2009-11-04 18:02:20 UTC (rev 1238) +++ trunk/java/javax/servlet/http/LocalStrings.properties 2009-11-04 22:24:35 UTC (rev 1239) @@ -56,6 +56,7 @@ # Localized for Locale en_US err.cookie_name_is_token=Cookie name \"{0}\" is a reserved token +err.cookie_name_blank=Cookie name must not be null or empty err.io.negativelength=Negative length given in write method err.io.short_read=Short Read err.ise.getWriter=Illegal to call getWriter() after getOutputStream() has been called