/*
-* Licensed to the Apache Software Foundation (ASF) under one or more
-* contributor license agreements. See the NOTICE file distributed with
-* this work for additional information regarding copyright ownership.
-* The ASF licenses this file to You under the Apache License, Version 2.0
-* (the "License"); you may not use this file except in compliance with
-* the License. You may obtain a copy of the License at
-*
-* http://www.apache.org/licenses/LICENSE-2.0
-*
-* Unless required by applicable law or agreed to in writing, software
-* distributed under the License is distributed on an "AS IS" BASIS,
-* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-* See the License for the specific language governing permissions and
-* limitations under the License.
-*/
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
package javax.servlet.http;
import java.io.Serializable;
import java.util.ResourceBundle;
/**
- *
- * Creates a cookie, a small amount of information sent by a servlet to
- * a Web browser, saved by the browser, and later sent back to the server.
- * A cookie's value can uniquely
- * identify a client, so cookies are commonly used for session management.
- *
- * <p>A cookie has a name, a single value, and optional attributes
- * such as a comment, path and domain qualifiers, a maximum age, and a
- * version number. Some Web browsers have bugs in how they handle the
- * optional attributes, so use them sparingly to improve the interoperability
- * of your servlets.
- *
- * <p>The servlet sends cookies to the browser by using the
- * {@link HttpServletResponse#addCookie} method, which adds
- * fields to HTTP response headers to send cookies to the
- * browser, one at a time. The browser is expected to
- * support 20 cookies for each Web server, 300 cookies total, and
+ * Creates a cookie, a small amount of information sent by a servlet to a Web
+ * browser, saved by the browser, and later sent back to the server. A cookie's
+ * value can uniquely identify a client, so cookies are commonly used for
+ * session management.
+ * <p>
+ * A cookie has a name, a single value, and optional attributes such as a
+ * comment, path and domain qualifiers, a maximum age, and a version number.
+ * Some Web browsers have bugs in how they handle the optional attributes, so
+ * use them sparingly to improve the interoperability of your servlets.
+ * <p>
+ * The servlet sends cookies to the browser by using the
+ * {@link HttpServletResponse#addCookie} method, which adds fields to HTTP
+ * response headers to send cookies to the browser, one at a time. The browser
+ * is expected to support 20 cookies for each Web server, 300 cookies total, and
* may limit cookie size to 4 KB each.
+ * <p>
+ * The browser returns cookies to the servlet by adding fields to HTTP request
+ * headers. Cookies can be retrieved from a request by using the
+ * {@link HttpServletRequest#getCookies} method. Several cookies might have the
+ * same name but different path attributes.
+ * <p>
+ * Cookies affect the caching of the Web pages that use them. HTTP 1.0 does not
+ * cache pages that use cookies created with this class. This class does not
+ * support the cache control defined with HTTP 1.1.
+ * <p>
+ * This class supports both the Version 0 (by Netscape) and Version 1 (by RFC
+ * 2109) cookie specifications. By default, cookies are created using Version 0
+ * to ensure the best interoperability.
*
- * <p>The browser returns cookies to the servlet by adding
- * fields to HTTP request headers. Cookies can be retrieved
- * from a request by using the {@link HttpServletRequest#getCookies} method.
- * Several cookies might have the same name but different path attributes.
- *
- * <p>Cookies affect the caching of the Web pages that use them.
- * HTTP 1.0 does not cache pages that use cookies created with
- * this class. This class does not support the cache control
- * defined with HTTP 1.1.
- *
- * <p>This class supports both the Version 0 (by Netscape) and Version 1
- * (by RFC 2109) cookie specifications. By default, cookies are
- * created using Version 0 to ensure the best interoperability.
- *
- *
- * @author Various
- * @version $Version$
- *
+ * @author Various
+ * @version $Version$
*/
public class Cookie implements Cloneable, Serializable {
private static final long serialVersionUID = 1L;
- private static final String LSTRING_FILE =
- "javax.servlet.http.LocalStrings";
- private static ResourceBundle lStrings =
- ResourceBundle.getBundle(LSTRING_FILE);
-
+ private static final String LSTRING_FILE = "javax.servlet.http.LocalStrings";
+ private static ResourceBundle lStrings = ResourceBundle.getBundle(LSTRING_FILE);
+
//
// The value of the cookie itself.
//
-
- private String name; // NAME= ... "$Name" style is reserved
- private String value; // value of NAME
+
+ private String name; // NAME= ... "$Name" style is reserved
+ private String value; // value of NAME
//
// Attributes encoded in the header's cookie fields.
//
-
- private String comment; // ;Comment=VALUE ... describes cookie's use
- // ;Discard ... implied by maxAge < 0
- private String domain; // ;Domain=VALUE ... domain that sees cookie
- private int maxAge = -1; // ;Max-Age=VALUE ... cookies auto-expire
- private String path; // ;Path=VALUE ... URLs that see the cookie
- private boolean secure; // ;Secure ... e.g. use SSL
- private int version = 0; // ;Version=1 ... means RFC 2109++ style
- private boolean httpOnly; // Not in cookie specs, but supported by browsers
-
+
+ private String comment; // ;Comment=VALUE ... describes cookie's use
+ // ;Discard ... implied by maxAge < 0
+ private String domain; // ;Domain=VALUE ... domain that sees cookie
+ private int maxAge = -1; // ;Max-Age=VALUE ... cookies auto-expire
+ private String path; // ;Path=VALUE ... URLs that see the cookie
+ private boolean secure; // ;Secure ... e.g. use SSL
+ private int version = 0; // ;Version=1 ... means RFC 2109++ style
+ private boolean httpOnly; // Not in cookie specs, but supported by browsers
/**
* Constructs a cookie with a 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,
- * semicolons, or white space or begin with a $ character. The cookie's
- * name cannot be changed after creation.
- *
- * <p>The value can be anything the server chooses to send. Its
- * value is probably of interest only to the server. The cookie's
- * value can be changed after creation with the
- * <code>setValue</code> method.
- *
- * <p>By default, cookies are created according to the Netscape
- * cookie specification. The version can be changed with the
+ * <p>
+ * The name must conform to RFC 2109. That means it can contain only ASCII
+ * alphanumeric characters and cannot contain commas, semicolons, or white
+ * space or begin with a $ character. The cookie's name cannot be changed
+ * after creation.
+ * <p>
+ * The value can be anything the server chooses to send. Its value is
+ * probably of interest only to the server. The cookie's value can be
+ * changed after creation with the <code>setValue</code> method.
+ * <p>
+ * By default, cookies are created according to the Netscape cookie
+ * specification. The version can be changed with the
* <code>setVersion</code> method.
- *
- *
- * @param name a <code>String</code> specifying the name of the cookie
- *
- * @param value a <code>String</code> specifying the value of the cookie
- *
- * @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
+ *
+ * @param name
+ * a <code>String</code> specifying the name of the cookie
+ * @param value
+ * a <code>String</code> specifying the value of the cookie
+ * @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 (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("$")
- ) {
+ 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;
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
- * are not supported by Netscape Version 0 cookies.
- *
- * @param purpose a <code>String</code> specifying the comment
- * to display to the user
- *
+ * Specifies a comment that describes a cookie's purpose. The comment is
+ * useful if the browser presents the cookie to the user. Comments are not
+ * supported by Netscape Version 0 cookies.
+ *
+ * @param purpose
+ * a <code>String</code> specifying the comment 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 a <code>String</code> containing the comment, or
+ * <code>null</code> if none
* @see #setComment
- *
- */
-
+ */
public String getComment() {
- return comment;
+ return comment;
}
-
-
-
-
/**
- *
* Specifies the domain within which this cookie should be presented.
- *
- * <p>The form of the domain name is specified by RFC 2109. A domain
- * name begins with a dot (<code>.foo.com</code>) and means that
- * the cookie is visible to servers in a specified Domain Name System
- * (DNS) zone (for example, <code>www.foo.com</code>, but not
- * <code>a.b.foo.com</code>). By default, cookies are only returned
- * to the server that sent them.
- *
- *
- * @param pattern a <code>String</code> containing the domain name
- * within which this cookie is visible;
- * form is according to RFC 2109
- *
+ * <p>
+ * The form of the domain name is specified by RFC 2109. A domain name
+ * begins with a dot (<code>.foo.com</code>) and means that the cookie is
+ * visible to servers in a specified Domain Name System (DNS) zone (for
+ * example, <code>www.foo.com</code>, but not <code>a.b.foo.com</code>). By
+ * default, cookies are only returned to the server that sent them.
+ *
+ * @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(Locale.ENGLISH); // IE allegedly needs this
+ domain = pattern.toLowerCase(Locale.ENGLISH); // IE allegedly needs this
}
-
-
-
-
/**
- * Returns the domain name set for this cookie. The form of
- * the domain name is set by RFC 2109.
- *
- * @return a <code>String</code> containing the domain name
- *
+ * Returns the domain name set for this cookie. The form of the domain name
+ * is set by RFC 2109.
+ *
+ * @return a <code>String</code> containing the domain name
* @see #setDomain
- *
- */
-
+ */
public String getDomain() {
- return domain;
+ return domain;
}
-
-
-
/**
* Sets the maximum age of the cookie in seconds.
- *
- * <p>A positive value indicates that the cookie will expire
- * after that many seconds have passed. Note that the value is
- * the <i>maximum</i> age when the cookie will expire, not the cookie's
- * current age.
- *
- * <p>A negative value means
- * that the cookie is not stored persistently and will be deleted
- * when the Web browser exits. A zero value causes the cookie
- * to be deleted.
- *
- * @param expiry an integer specifying the maximum age of the
- * cookie in seconds; if negative, means
- * the cookie is not stored; if zero, deletes
- * the cookie
- *
- *
+ * <p>
+ * A positive value indicates that the cookie will expire after that many
+ * seconds have passed. Note that the value is the <i>maximum</i> age when
+ * the cookie will expire, not the cookie's current age.
+ * <p>
+ * A negative value means that the cookie is not stored persistently and
+ * will be deleted when the Web browser exits. A zero value causes the
+ * cookie to be deleted.
+ *
+ * @param expiry
+ * an integer specifying the maximum age of the cookie in
+ * seconds; if negative, means 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.
- *
- *
- * @return an integer specifying the maximum age of the
- * cookie in seconds; if negative, means
- * the cookie persists until browser shutdown
- *
- *
+ * Returns the maximum age of the cookie, specified in seconds, By default,
+ * <code>-1</code> indicating 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.
- *
- * <p>The cookie is visible to all the pages in the directory
- * you specify, and all the pages in that directory's subdirectories.
- * A cookie's path must include the servlet that set the cookie,
- * for example, <i>/catalog</i>, which makes the cookie
- * visible to all directories on the server under <i>/catalog</i>.
- *
- * <p>Consult RFC 2109 (available on the Internet) for more
- * information on setting path names for cookies.
- *
- *
- * @param uri a <code>String</code> specifying a path
- *
- *
+ * Specifies a path for the cookie to which the client should return the
+ * cookie.
+ * <p>
+ * The cookie is visible to all the pages in the directory you specify, and
+ * all the pages in that directory's subdirectories. A cookie's path must
+ * include the servlet that set the cookie, for example, <i>/catalog</i>,
+ * which makes the cookie visible to all directories on the server under
+ * <i>/catalog</i>.
+ * <p>
+ * Consult RFC 2109 (available on the Internet) for more information on
+ * setting path names for cookies.
+ *
+ * @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>
- *
+ * 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
- *
+ * 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
* @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>
- *
+ * 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>
* @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 a <code>String</code> specifying the cookie's name
*/
-
public String getName() {
- return name;
+ return name;
}
-
-
-
-
/**
- *
- * 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
- *
- *
+ * 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
* @see #getValue
* @see Cookie
- *
*/
-
public void setValue(String newValue) {
- value = newValue;
+ value = newValue;
}
-
-
-
/**
* Returns the value of the cookie.
- *
- * @return a <code>String</code> containing the cookie's
- * present value
- *
+ *
+ * @return a <code>String</code> containing the cookie's present value
* @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,
- * and version 0 complies with the original
- * cookie specification drafted by Netscape. Cookies provided
- * by a browser use and identify the browser's cookie version.
+ * Returns the version of the protocol this cookie complies with. Version 1
+ * complies with RFC 2109, and version 0 complies with the original 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
- *
+ * @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
- * 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
- *
+ * Sets the version of the cookie protocol this cookie complies with.
+ * 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
* @see #getVersion
- *
*/
-
public void setVersion(int v) {
- version = v;
+ version = v;
}
// Note -- disabled for now to allow full Netscape compatibility
private static final String tspecials2NoSlash = "()<>@,;:\\\"[]?={} \t";
private static final String tspecials2WithSlash = tspecials2NoSlash + "/";
private static final String tspecials2;
-
+
/**
* If set to true, we parse cookies strictly according to the servlet,
* cookie and HTTP specs by default.
*/
private static final boolean STRICT_NAMING;
-
static {
- STRICT_SERVLET_COMPLIANCE = Boolean.valueOf(System.getProperty(
- "org.apache.catalina.STRICT_SERVLET_COMPLIANCE",
- "false")).booleanValue();
+ STRICT_SERVLET_COMPLIANCE = Boolean.valueOf(
+ System.getProperty(
+ "org.apache.catalina.STRICT_SERVLET_COMPLIANCE",
+ "false")).booleanValue();
- String fwdSlashIsSeparator = System.getProperty(
- "org.apache.tomcat.util.http.ServerCookie.FWD_SLASH_IS_SEPARATOR");
+ String fwdSlashIsSeparator = System.getProperty("org.apache.tomcat.util.http.ServerCookie.FWD_SLASH_IS_SEPARATOR");
if (fwdSlashIsSeparator == null) {
FWD_SLASH_IS_SEPARATOR = STRICT_SERVLET_COMPLIANCE;
} else {
- FWD_SLASH_IS_SEPARATOR =
- Boolean.valueOf(fwdSlashIsSeparator).booleanValue();
+ FWD_SLASH_IS_SEPARATOR = Boolean.valueOf(fwdSlashIsSeparator).booleanValue();
}
if (FWD_SLASH_IS_SEPARATOR) {
} else {
tspecials2 = tspecials2NoSlash;
}
-
- String strictNaming = System.getProperty(
- "org.apache.tomcat.util.http.ServerCookie.STRICT_NAMING");
+
+ String strictNaming = System.getProperty("org.apache.tomcat.util.http.ServerCookie.STRICT_NAMING");
if (strictNaming == null) {
STRICT_NAMING = STRICT_SERVLET_COMPLIANCE;
} else {
- STRICT_NAMING =
- Boolean.valueOf(strictNaming).booleanValue();
+ STRICT_NAMING = Boolean.valueOf(strictNaming).booleanValue();
}
}
-
-
-
/*
- * 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
- *
- * @return <code>true</code> if the <code>String</code> is
- * a reserved token; <code>false</code>
- * if it is not
+ * 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
+ * @return <code>true</code> if the <code>String</code> is a reserved token;
+ * <code>false</code> if it is not
*/
private boolean isToken(String possibleToken) {
int len = possibleToken.length();
return true;
}
-
-
/**
- *
- * Overrides the standard <code>java.lang.Object.clone</code>
- * method to return a copy of this cookie.
- *
- *
+ * Overrides the standard <code>java.lang.Object.clone</code> method to
+ * return a copy of this cookie.
*/
-
@Override
public Object clone() {
- try {
- return super.clone();
- } catch (CloneNotSupportedException e) {
- throw new RuntimeException(e.getMessage());
- }
+ try {
+ return super.clone();
+ } catch (CloneNotSupportedException e) {
+ throw new RuntimeException(e.getMessage());
+ }
}
/**
- *
* @return
- * @since Servlet 3.0
- * TODO SERVLET3 - Add comments
+ * @since Servlet 3.0 TODO SERVLET3 - Add comments
*/
public boolean isHttpOnly() {
return httpOnly;
}
/**
- *
* @param httpOnly
- * @since Servlet 3.0
- * TODO SERVLET3 - Add comments
+ * @since Servlet 3.0 TODO SERVLET3 - Add comments
*/
public void setHttpOnly(boolean httpOnly) {
this.httpOnly = httpOnly;
}
}
-
/*
-* Licensed to the Apache Software Foundation (ASF) under one or more
-* contributor license agreements. See the NOTICE file distributed with
-* this work for additional information regarding copyright ownership.
-* The ASF licenses this file to You under the Apache License, Version 2.0
-* (the "License"); you may not use this file except in compliance with
-* the License. You may obtain a copy of the License at
-*
-* http://www.apache.org/licenses/LICENSE-2.0
-*
-* Unless required by applicable law or agreed to in writing, software
-* distributed under the License is distributed on an "AS IS" BASIS,
-* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-* See the License for the specific language governing permissions and
-* limitations under the License.
-*/
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
package javax.servlet.http;
import java.util.Enumeration;
/**
- *
- * Extends the {@link javax.servlet.ServletRequest} interface
- * to provide request information for HTTP servlets.
- *
- * <p>The servlet container creates an <code>HttpServletRequest</code>
- * object and passes it as an argument to the servlet's service
- * methods (<code>doGet</code>, <code>doPost</code>, etc).
- *
- *
- * @author Various
- * @version $Version$
- *
- *
+ * Extends the {@link javax.servlet.ServletRequest} interface to provide request
+ * information for HTTP servlets.
+ * <p>
+ * The servlet container creates an <code>HttpServletRequest</code> object and
+ * passes it as an argument to the servlet's service methods (<code>doGet</code>, <code>doPost</code>, etc).
+ *
+ * @author Various
+ * @version $Version$
*/
-
public interface HttpServletRequest extends ServletRequest {
/**
- * String identifier for Basic authentication. Value "BASIC"
- */
+ * String identifier for Basic authentication. Value "BASIC"
+ */
public static final String BASIC_AUTH = "BASIC";
/**
- * String identifier for Form authentication. Value "FORM"
- */
+ * String identifier for Form authentication. Value "FORM"
+ */
public static final String FORM_AUTH = "FORM";
/**
- * String identifier for Client Certificate authentication. Value "CLIENT_CERT"
- */
+ * String identifier for Client Certificate authentication. Value
+ * "CLIENT_CERT"
+ */
public static final String CLIENT_CERT_AUTH = "CLIENT_CERT";
/**
- * String identifier for Digest authentication. Value "DIGEST"
- */
+ * String identifier for Digest authentication. Value "DIGEST"
+ */
public static final String DIGEST_AUTH = "DIGEST";
/**
- * Returns the name of the authentication scheme used to protect
- * the servlet. All servlet containers support basic, form and client
- * certificate authentication, and may additionally support digest
- * authentication.
- * If the servlet is not authenticated <code>null</code> is returned.
- *
- * <p>Same as the value of the CGI variable AUTH_TYPE.
- *
- *
- * @return one of the static members BASIC_AUTH,
- * FORM_AUTH, CLIENT_CERT_AUTH, DIGEST_AUTH
- * (suitable for == comparison) or
- * the container-specific string indicating
- * the authentication scheme, or
- * <code>null</code> if the request was
- * not authenticated.
- *
- */
-
+ * Returns the name of the authentication scheme used to protect the
+ * servlet. All servlet containers support basic, form and client
+ * certificate authentication, and may additionally support digest
+ * authentication. If the servlet is not authenticated <code>null</code> is
+ * returned.
+ * <p>
+ * Same as the value of the CGI variable AUTH_TYPE.
+ *
+ * @return one of the static members BASIC_AUTH, FORM_AUTH, CLIENT_CERT_AUTH,
+ * DIGEST_AUTH (suitable for == comparison) or the
+ * container-specific string indicating the authentication scheme,
+ * or <code>null</code> if the request was not authenticated.
+ */
public String getAuthType();
-
-
-
/**
- *
- * Returns an array containing all of the <code>Cookie</code>
- * objects the client sent with this request.
- * This method returns <code>null</code> if no cookies were sent.
- *
- * @return an array of all the <code>Cookies</code>
- * included with this request, or <code>null</code>
- * if the request has no cookies
- *
- *
+ * Returns an array containing all of the <code>Cookie</code> objects the
+ * client sent with this request. This method returns <code>null</code> if
+ * no cookies were sent.
+ *
+ * @return an array of all the <code>Cookies</code> included with this
+ * request, or <code>null</code> if the request has no cookies
*/
-
public Cookie[] getCookies();
-
-
-
-
- /**
- *
- * Returns the value of the specified request header
- * as a <code>long</code> value that represents a
- * <code>Date</code> object. Use this method with
- * headers that contain dates, such as
- * <code>If-Modified-Since</code>.
- *
- * <p>The date is returned as
- * the number of milliseconds since January 1, 1970 GMT.
- * The header name is case insensitive.
- *
- * <p>If the request did not have a header of the
- * specified name, this method returns -1. If the header
- * can't be converted to a date, the method throws
+
+ /**
+ * Returns the value of the specified request header as a <code>long</code>
+ * value that represents a <code>Date</code> object. Use this method with
+ * headers that contain dates, such as <code>If-Modified-Since</code>.
+ * <p>
+ * The date is returned as the number of milliseconds since January 1, 1970
+ * GMT. The header name is case insensitive.
+ * <p>
+ * If the request did not have a header of the specified name, this method
+ * returns -1. If the header can't be converted to a date, the method throws
* an <code>IllegalArgumentException</code>.
- *
- * @param name a <code>String</code> specifying the
- * name of the header
- *
- * @return a <code>long</code> value
- * representing the date specified
- * in the header expressed as
- * the number of milliseconds
- * since January 1, 1970 GMT,
- * or -1 if the named header
- * was not included with the
- * request
- *
- * @exception IllegalArgumentException If the header value
- * can't be converted
- * to a date
- *
+ *
+ * @param name
+ * a <code>String</code> specifying the name of the header
+ * @return a <code>long</code> value representing the date specified in the
+ * header expressed as the number of milliseconds since January 1,
+ * 1970 GMT, or -1 if the named header was not included with the
+ * request
+ * @exception IllegalArgumentException
+ * If the header value can't be converted to a date
*/
-
public long getDateHeader(String name);
-
-
-
-
- /**
- *
- * Returns the value of the specified request header
- * as a <code>String</code>. If the request did not include a header
- * of the specified name, this method returns <code>null</code>.
- * If there are multiple headers with the same name, this method
- * returns the first head in the request.
- * The header name is case insensitive. You can use
- * this method with any request header.
- *
- * @param name a <code>String</code> specifying the
- * header name
- *
- * @return a <code>String</code> containing the
- * value of the requested
- * header, or <code>null</code>
- * if the request does not
- * have a header of that name
- *
- */
-
- public String getHeader(String name);
-
-
-
-
- /**
- *
- * Returns all the values of the specified request header
- * as an <code>Enumeration</code> of <code>String</code> objects.
- *
- * <p>Some headers, such as <code>Accept-Language</code> can be sent
- * by clients as several headers each with a different value rather than
- * sending the header as a comma separated list.
- *
- * <p>If the request did not include any headers
- * of the specified name, this method returns an empty
- * <code>Enumeration</code>.
- * The header name is case insensitive. You can use
- * this method with any request header.
- *
- * @param name a <code>String</code> specifying the
- * header name
- *
- * @return an <code>Enumeration</code> containing
- * the values of the requested header. If
- * the request does not have any headers of
- * that name return an empty
- * enumeration. If
- * the container does not allow access to
- * header information, return null
- *
- */
-
- public Enumeration<String> getHeaders(String name);
-
-
-
-
-
- /**
- *
- * Returns an enumeration of all the header names
- * this request contains. If the request has no
- * headers, this method returns an empty enumeration.
- *
- * <p>Some servlet containers do not allow
- * servlets to access headers using this method, in
- * which case this method returns <code>null</code>
- *
- * @return an enumeration of all the
- * header names sent with this
- * request; if the request has
- * no headers, an empty enumeration;
- * if the servlet container does not
- * allow servlets to use this method,
- * <code>null</code>
- *
- *
+
+ /**
+ * Returns the value of the specified request header as a
+ * <code>String</code>. If the request did not include a header of the
+ * specified name, this method returns <code>null</code>. If there are
+ * multiple headers with the same name, this method returns the first head
+ * in the request. The header name is case insensitive. You can use this
+ * method with any request header.
+ *
+ * @param name
+ * a <code>String</code> specifying the header name
+ * @return a <code>String</code> containing the value of the requested
+ * header, or <code>null</code> if the request does not have a
+ * header of that name
*/
+ public String getHeader(String name);
+
+ /**
+ * Returns all the values of the specified request header as an
+ * <code>Enumeration</code> of <code>String</code> objects.
+ * <p>
+ * Some headers, such as <code>Accept-Language</code> can be sent by clients
+ * as several headers each with a different value rather than sending the
+ * header as a comma separated list.
+ * <p>
+ * If the request did not include any headers of the specified name, this
+ * method returns an empty <code>Enumeration</code>. The header name is case
+ * insensitive. You can use this method with any request header.
+ *
+ * @param name
+ * a <code>String</code> specifying the header name
+ * @return an <code>Enumeration</code> containing the values of the requested
+ * header. If the request does not have any headers of that name
+ * return an empty enumeration. If the container does not allow
+ * access to header information, return null
+ */
+ public Enumeration<String> getHeaders(String name);
+ /**
+ * Returns an enumeration of all the header names this request contains. If
+ * the request has no headers, this method returns an empty enumeration.
+ * <p>
+ * Some servlet containers do not allow servlets to access headers using
+ * this method, in which case this method returns <code>null</code>
+ *
+ * @return an enumeration of all the header names sent with this request; if
+ * the request has no headers, an empty enumeration; if the servlet
+ * container does not allow servlets to use this method,
+ * <code>null</code>
+ */
public Enumeration<String> getHeaderNames();
-
-
-
/**
- *
- * Returns the value of the specified request header
- * as an <code>int</code>. If the request does not have a header
- * of the specified name, this method returns -1. If the
- * header cannot be converted to an integer, this method
+ * Returns the value of the specified request header as an <code>int</code>.
+ * If the request does not have a header of the specified name, this method
+ * returns -1. If the header cannot be converted to an integer, this method
* throws a <code>NumberFormatException</code>.
- *
- * <p>The header name is case insensitive.
- *
- * @param name a <code>String</code> specifying the name
- * of a request header
- *
- * @return an integer expressing the value
- * of the request header or -1
- * if the request doesn't have a
- * header of this name
- *
- * @exception NumberFormatException If the header value
- * can't be converted
- * to an <code>int</code>
+ * <p>
+ * The header name is case insensitive.
+ *
+ * @param name
+ * a <code>String</code> specifying the name of a request header
+ * @return an integer expressing the value of the request header or -1 if the
+ * request doesn't have a header of this name
+ * @exception NumberFormatException
+ * If the header value can't be converted to an
+ * <code>int</code>
*/
-
public int getIntHeader(String name);
-
-
-
-
- /**
- *
- * Returns the name of the HTTP method with which this
- * request was made, for example, GET, POST, or PUT.
- * Same as the value of the CGI variable REQUEST_METHOD.
- *
- * @return a <code>String</code>
- * specifying the name
- * of the method with which
- * this request was made
- *
- */
-
+
+ /**
+ * Returns the name of the HTTP method with which this request was made, for
+ * example, GET, POST, or PUT. Same as the value of the CGI variable
+ * REQUEST_METHOD.
+ *
+ * @return a <code>String</code> specifying the name of the method with
+ * which this request was made
+ */
public String getMethod();
-
-
-
-
- /**
- *
- * Returns any extra path information associated with
- * the URL the client sent when it made this request.
- * The extra path information follows the servlet path
- * but precedes the query string and will start with
- * a "/" character.
- *
- * <p>This method returns <code>null</code> if there
- * was no extra path information.
- *
- * <p>Same as the value of the CGI variable PATH_INFO.
- *
- *
- * @return a <code>String</code>, decoded by the
- * web container, specifying
- * extra path information that comes
- * after the servlet path but before
- * the query string in the request URL;
- * or <code>null</code> if the URL does not have
- * any extra path information
- *
- */
-
- public String getPathInfo();
-
-
-
-
- /**
- *
- * Returns any extra path information after the servlet name
- * but before the query string, and translates it to a real
- * path. Same as the value of the CGI variable PATH_TRANSLATED.
- *
- * <p>If the URL does not have any extra path information,
- * this method returns <code>null</code> or the servlet container
- * cannot translate the virtual path to a real path for any reason
- * (such as when the web application is executed from an archive).
- *
- * The web container does not decode this string.
- *
- *
- * @return a <code>String</code> specifying the
- * real path, or <code>null</code> if
- * the URL does not have any extra path
- * information
- *
- *
+
+ /**
+ * Returns any extra path information associated with the URL the client
+ * sent when it made this request. The extra path information follows the
+ * servlet path but precedes the query string and will start with a "/"
+ * character.
+ * <p>
+ * This method returns <code>null</code> if there was no extra path
+ * information.
+ * <p>
+ * Same as the value of the CGI variable PATH_INFO.
+ *
+ * @return a <code>String</code>, decoded by the web container, specifying
+ * extra path information that comes after the servlet path but
+ * before the query string in the request URL; or <code>null</code>
+ * if the URL does not have any extra path information
*/
+ public String getPathInfo();
+ /**
+ * Returns any extra path information after the servlet name but before the
+ * query string, and translates it to a real path. Same as the value of the
+ * CGI variable PATH_TRANSLATED.
+ * <p>
+ * If the URL does not have any extra path information, this method returns
+ * <code>null</code> or the servlet container cannot translate the virtual
+ * path to a real path for any reason (such as when the web application is
+ * executed from an archive). The web container does not decode this string.
+ *
+ * @return a <code>String</code> specifying the real path, or
+ * <code>null</code> if the URL does not have any extra path
+ * information
+ */
public String getPathTranslated();
-
-
-
/**
- *
- * Returns the portion of the request URI that indicates the context
- * of the request. The context path always comes first in a request
- * URI. The path starts with a "/" character but does not end with a "/"
- * character. For servlets in the default (root) context, this method
- * returns "". The container does not decode this string.
- *
- *
- * @return a <code>String</code> specifying the
- * portion of the request URI that indicates the context
- * of the request
- *
- *
+ * Returns the portion of the request URI that indicates the context of the
+ * request. The context path always comes first in a request URI. The path
+ * starts with a "/" character but does not end with a "/" character. For
+ * servlets in the default (root) context, this method returns "". The
+ * container does not decode this string.
+ *
+ * @return a <code>String</code> specifying the portion of the request URI
+ * that indicates the context of the request
*/
-
public String getContextPath();
-
-
-
/**
- *
- * Returns the query string that is contained in the request
- * URL after the path. This method returns <code>null</code>
- * if the URL does not have a query string. Same as the value
- * of the CGI variable QUERY_STRING.
- *
- * @return a <code>String</code> containing the query
- * string or <code>null</code> if the URL
- * contains no query string. The value is not
- * decoded by the container.
- *
+ * Returns the query string that is contained in the request URL after the
+ * path. This method returns <code>null</code> if the URL does not have a
+ * query string. Same as the value of the CGI variable QUERY_STRING.
+ *
+ * @return a <code>String</code> containing the query string or
+ * <code>null</code> if the URL contains no query string. The value
+ * is not decoded by the container.
*/
-
public String getQueryString();
-
-
-
/**
- *
- * Returns the login of the user making this request, if the
- * user has been authenticated, or <code>null</code> if the user
- * has not been authenticated.
- * Whether the user name is sent with each subsequent request
- * depends on the browser and type of authentication. Same as the
- * value of the CGI variable REMOTE_USER.
- *
- * @return a <code>String</code> specifying the login
- * of the user making this request, or <code>null</code>
- * if the user login is not known
- *
+ * Returns the login of the user making this request, if the user has been
+ * authenticated, or <code>null</code> if the user has not been
+ * authenticated. Whether the user name is sent with each subsequent request
+ * depends on the browser and type of authentication. Same as the value of
+ * the CGI variable REMOTE_USER.
+ *
+ * @return a <code>String</code> specifying the login of the user making
+ * this request, or <code>null</code> if the user login is not known
*/
-
public String getRemoteUser();
-
-
-
/**
- *
* Returns a boolean indicating whether the authenticated user is included
- * in the specified logical "role". Roles and role membership can be
- * defined using deployment descriptors. If the user has not been
- * authenticated, the method returns <code>false</code>.
- *
- * @param role a <code>String</code> specifying the name
- * of the role
- *
- * @return a <code>boolean</code> indicating whether
- * the user making this request belongs to a given role;
- * <code>false</code> if the user has not been
- * authenticated
- *
+ * in the specified logical "role". Roles and role membership can be defined
+ * using deployment descriptors. If the user has not been authenticated, the
+ * method returns <code>false</code>.
+ *
+ * @param role
+ * a <code>String</code> specifying the name of the role
+ * @return a <code>boolean</code> indicating whether the user making this
+ * request belongs to a given role; <code>false</code> if the user
+ * has not been authenticated
*/
-
public boolean isUserInRole(String role);
-
-
-
/**
- *
- * Returns a <code>java.security.Principal</code> object containing
- * the name of the current authenticated user. If the user has not been
+ * Returns a <code>java.security.Principal</code> object containing the name
+ * of the current authenticated user. If the user has not been
* authenticated, the method returns <code>null</code>.
- *
- * @return a <code>java.security.Principal</code> containing
- * the name of the user making this request;
- * <code>null</code> if the user has not been
- * authenticated
- *
+ *
+ * @return a <code>java.security.Principal</code> containing the name of the
+ * user making this request; <code>null</code> if the user has not
+ * been authenticated
*/
-
public java.security.Principal getUserPrincipal();
-
-
-
-
- /**
- *
- * Returns the session ID specified by the client. This may
- * not be the same as the ID of the current valid session
- * for this request.
- * If the client did not specify a session ID, this method returns
- * <code>null</code>.
- *
- *
- * @return a <code>String</code> specifying the session
- * ID, or <code>null</code> if the request did
- * not specify a session ID
- *
- * @see #isRequestedSessionIdValid
- *
- */
- public String getRequestedSessionId();
-
-
-
-
- /**
- *
- * Returns the part of this request's URL from the protocol
- * name up to the query string in the first line of the HTTP request.
- * The web container does not decode this String.
- * For example:
- *
+ /**
+ * Returns the session ID specified by the client. This may not be the same
+ * as the ID of the current valid session for this request. If the client
+ * did not specify a session ID, this method returns <code>null</code>.
*
+ * @return a <code>String</code> specifying the session ID, or
+ * <code>null</code> if the request did not specify a session ID
+ * @see #isRequestedSessionIdValid
+ */
+ public String getRequestedSessionId();
+ /**
+ * Returns the part of this request's URL from the protocol name up to the
+ * query string in the first line of the HTTP request. The web container
+ * does not decode this String. For example:
* <table summary="Examples of Returned Values">
- * <tr align=left><th>First line of HTTP request </th>
- * <th> Returned Value</th>
- * <tr><td>POST /some/path.html HTTP/1.1<td><td>/some/path.html
- * <tr><td>GET http://foo.bar/a.html HTTP/1.0
- * <td><td>/a.html
- * <tr><td>HEAD /xyz?a=b HTTP/1.1<td><td>/xyz
+ * <tr align=left>
+ * <th>First line of HTTP request</th>
+ * <th>Returned Value</th>
+ * <tr>
+ * <td>POST /some/path.html HTTP/1.1
+ * <td>
+ * <td>/some/path.html
+ * <tr>
+ * <td>GET http://foo.bar/a.html HTTP/1.0
+ * <td>
+ * <td>/a.html
+ * <tr>
+ * <td>HEAD /xyz?a=b HTTP/1.1
+ * <td>
+ * <td>/xyz
* </table>
- *
- * <p>To reconstruct an URL with a scheme and host, use
+ * <p>
+ * To reconstruct an URL with a scheme and host, use
* {@link HttpUtils#getRequestURL}.
- *
- * @return a <code>String</code> containing
- * the part of the URL from the
- * protocol name up to the query string
- *
- * @see HttpUtils#getRequestURL
- *
+ *
+ * @return a <code>String</code> containing the part of the URL from the
+ * protocol name up to the query string
+ * @see HttpUtils#getRequestURL
*/
-
public String getRequestURI();
-
- /**
- *
- * Reconstructs the URL the client used to make the request.
- * The returned URL contains a protocol, server name, port
- * number, and server path, but it does not include query
- * string parameters.
- *
- * <p>Because this method returns a <code>StringBuffer</code>,
- * not a string, you can modify the URL easily, for example,
- * to append query parameters.
- *
- * <p>This method is useful for creating redirect messages
- * and for reporting errors.
- *
- * @return a <code>StringBuffer</code> object containing
- * the reconstructed URL
- *
+
+ /**
+ * Reconstructs the URL the client used to make the request. The returned
+ * URL contains a protocol, server name, port number, and server path, but
+ * it does not include query string parameters.
+ * <p>
+ * Because this method returns a <code>StringBuffer</code>, not a string,
+ * you can modify the URL easily, for example, to append query parameters.
+ * <p>
+ * This method is useful for creating redirect messages and for reporting
+ * errors.
+ *
+ * @return a <code>StringBuffer</code> object containing the reconstructed
+ * URL
*/
public StringBuffer getRequestURL();
-
-
- /**
- *
- * Returns the part of this request's URL that calls
- * the servlet. This path starts with a "/" character
- * and includes either the servlet name or a path to
- * the servlet, but does not include any extra path
- * information or a query string. Same as the value of
- * the CGI variable SCRIPT_NAME.
- *
- * <p>This method will return an empty string ("") if the
- * servlet used to process this request was matched using
- * the "/*" pattern.
- *
- * @return a <code>String</code> containing
- * the name or path of the servlet being
- * called, as specified in the request URL,
- * decoded, or an empty string if the servlet
- * used to process the request is matched
- * using the "/*" pattern.
- *
- */
- public String getServletPath();
-
-
-
-
- /**
- *
- * Returns the current <code>HttpSession</code>
- * associated with this request or, if there is no
- * current session and <code>create</code> is true, returns
- * a new session.
- *
- * <p>If <code>create</code> is <code>false</code>
- * and the request has no valid <code>HttpSession</code>,
- * this method returns <code>null</code>.
- *
- * <p>To make sure the session is properly maintained,
- * you must call this method before
- * the response is committed. If the container is using cookies
- * to maintain session integrity and is asked to create a new session
- * when the response is committed, an IllegalStateException is thrown.
- *
- *
- *
- *
- * @param create <code>true</code> to create
- * a new session for this request if necessary;
- * <code>false</code> to return <code>null</code>
- * if there's no current session
- *
- *
- * @return the <code>HttpSession</code> associated
- * with this request or <code>null</code> if
- * <code>create</code> is <code>false</code>
- * and the request has no valid session
- *
- * @see #getSession()
- *
- *
+ /**
+ * Returns the part of this request's URL that calls the servlet. This path
+ * starts with a "/" character and includes either the servlet name or a
+ * path to the servlet, but does not include any extra path information or a
+ * query string. Same as the value of the CGI variable SCRIPT_NAME.
+ * <p>
+ * This method will return an empty string ("") if the servlet used to
+ * process this request was matched using the "/*" pattern.
+ *
+ * @return a <code>String</code> containing the name or path of the servlet
+ * being called, as specified in the request URL, decoded, or an
+ * empty string if the servlet used to process the request is
+ * matched using the "/*" pattern.
*/
+ public String getServletPath();
+ /**
+ * Returns the current <code>HttpSession</code> associated with this request
+ * or, if there is no current session and <code>create</code> is true,
+ * returns a new session.
+ * <p>
+ * If <code>create</code> is <code>false</code> and the request has no valid
+ * <code>HttpSession</code>, this method returns <code>null</code>.
+ * <p>
+ * To make sure the session is properly maintained, you must call this
+ * method before the response is committed. If the container is using
+ * cookies to maintain session integrity and is asked to create a new
+ * session when the response is committed, an IllegalStateException is
+ * thrown.
+ *
+ * @param create
+ * <code>true</code> to create a new session for this request if
+ * necessary; <code>false</code> to return <code>null</code> if
+ * there's no current session
+ * @return the <code>HttpSession</code> associated with this request or
+ * <code>null</code> if <code>create</code> is <code>false</code>
+ * and the request has no valid session
+ * @see #getSession()
+ */
public HttpSession getSession(boolean create);
-
-
-
-
/**
- *
- * Returns the current session associated with this request,
- * or if the request does not have a session, creates one.
+ * Returns the current session associated with this request, or if the
+ * request does not have a session, creates one.
*
- * @return the <code>HttpSession</code> associated
- * with this request
- *
- * @see #getSession(boolean)
- *
+ * @return the <code>HttpSession</code> associated with this request
+ * @see #getSession(boolean)
*/
-
public HttpSession getSession();
-
-
-
-
-
/**
- *
* Checks whether the requested session ID is still valid.
- *
- * @return <code>true</code> if this
- * request has an id for a valid session
- * in the current session context;
- * <code>false</code> otherwise
- *
- * @see #getRequestedSessionId
- * @see #getSession
- * @see HttpSessionContext
- *
+ *
+ * @return <code>true</code> if this request has an id for a valid session
+ * in the current session context; <code>false</code> otherwise
+ * @see #getRequestedSessionId
+ * @see #getSession
+ * @see HttpSessionContext
*/
-
public boolean isRequestedSessionIdValid();
-
-
-
/**
- *
* Checks whether the requested session ID came in as a cookie.
- *
- * @return <code>true</code> if the session ID
- * came in as a
- * cookie; otherwise, <code>false</code>
- *
- *
- * @see #getSession
- *
- */
-
+ *
+ * @return <code>true</code> if the session ID came in as a cookie;
+ * otherwise, <code>false</code>
+ * @see #getSession
+ */
public boolean isRequestedSessionIdFromCookie();
-
-
-
-
- /**
- *
- * Checks whether the requested session ID came in as part of the
- * request URL.
- *
- * @return <code>true</code> if the session ID
- * came in as part of a URL; otherwise,
- * <code>false</code>
- *
- *
- * @see #getSession
- *
- */
-
+
+ /**
+ * Checks whether the requested session ID came in as part of the request
+ * URL.
+ *
+ * @return <code>true</code> if the session ID came in as part of a URL;
+ * otherwise, <code>false</code>
+ * @see #getSession
+ */
public boolean isRequestedSessionIdFromURL();
-
-
-
-
-
- /**
- *
- * @deprecated As of Version 2.1 of the Java Servlet
- * API, use {@link #isRequestedSessionIdFromURL}
- * instead.
- *
- */
- @SuppressWarnings("dep-ann") // Spec API does not use @Deprecated
- public boolean isRequestedSessionIdFromUrl();
+ /**
+ * @deprecated As of Version 2.1 of the Java Servlet API, use
+ * {@link #isRequestedSessionIdFromURL} instead.
+ */
+ @SuppressWarnings("dep-ann")
+ // Spec API does not use @Deprecated
+ public boolean isRequestedSessionIdFromUrl();
/**
- *
* @param response
* @return
* @throws IOException
* @throws ServletException
- * @since Servlet 3.0
- * TODO SERVLET3 - Add comments
+ * @since Servlet 3.0 TODO SERVLET3 - Add comments
*/
public boolean authenticate(HttpServletResponse response)
- throws IOException, ServletException;
-
-
+ throws IOException, ServletException;
+
/**
- *
* @param username
* @param password
- * @throws ServletException If any of {@link #getRemoteUser()},
- * {@link #getUserPrincipal()} or {@link #getAuthType()} are
- * non-null, if the configured authenticator does not support
- * user name and password authentication or if the authentication
- * fails
- * @since Servlet 3.0
- * TODO SERVLET3 - Add comments
+ * @throws ServletException
+ * If any of {@link #getRemoteUser()},
+ * {@link #getUserPrincipal()} or {@link #getAuthType()} are
+ * non-null, if the configured authenticator does not support
+ * user name and password authentication or if the
+ * authentication fails
+ * @since Servlet 3.0 TODO SERVLET3 - Add comments
*/
- public void login(String username, String password)
- throws ServletException;
-
-
+ public void login(String username, String password) throws ServletException;
+
/**
- *
- * @throws ServletException If the logout fails
- * @since Servlet 3.0
- * TODO SERVLET3 - Add comments
+ * @throws ServletException
+ * If the logout fails
+ * @since Servlet 3.0 TODO SERVLET3 - Add comments
*/
public void logout() throws ServletException;
-
-
+
/**
* Return a collection of all uploaded Parts.
+ *
* @return
- * @throws IOException if an I/O error occurs
- * @throws IllegalStateException if size limits are exceeded
- * @throws ServletException if the request is not multipart/form-data
+ * @throws IOException
+ * if an I/O error occurs
+ * @throws IllegalStateException
+ * if size limits are exceeded
+ * @throws ServletException
+ * if the request is not multipart/form-data
* @since Servlet 3.0
*/
public Collection<Part> getParts() throws IOException,
IllegalStateException, ServletException;
-
-
+
/**
* Gets the named Part or null if the Part does not exist. Triggers upload
- * of all Parts.
+ * of all Parts.
+ *
* @param name
* @return
- * @throws IOException if an I/O error occurs
- * @throws IllegalStateException if size limits are exceeded
- * @throws ServletException if the request is not multipart/form-data
+ * @throws IOException
+ * if an I/O error occurs
+ * @throws IllegalStateException
+ * if size limits are exceeded
+ * @throws ServletException
+ * if the request is not multipart/form-data
* @since Servlet 3.0
*/
public Part getPart(String name) throws IOException, IllegalStateException,
- ServletException;
+ ServletException;
}
/*
-* Licensed to the Apache Software Foundation (ASF) under one or more
-* contributor license agreements. See the NOTICE file distributed with
-* this work for additional information regarding copyright ownership.
-* The ASF licenses this file to You under the Apache License, Version 2.0
-* (the "License"); you may not use this file except in compliance with
-* the License. You may obtain a copy of the License at
-*
-* http://www.apache.org/licenses/LICENSE-2.0
-*
-* Unless required by applicable law or agreed to in writing, software
-* distributed under the License is distributed on an "AS IS" BASIS,
-* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-* See the License for the specific language governing permissions and
-* limitations under the License.
-*/
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
package javax.servlet.http;
import javax.servlet.ServletException;
import java.util.Enumeration;
/**
- *
* Provides a convenient implementation of the HttpServletRequest interface that
* can be subclassed by developers wishing to adapt the request to a Servlet.
* This class implements the Wrapper or Decorator pattern. Methods default to
* calling through to the wrapped request object.
*
- *
- * @see javax.servlet.http.HttpServletRequest
- * @since v 2.3
- *
+ * @see javax.servlet.http.HttpServletRequest
+ * @since v 2.3
*/
+public class HttpServletRequestWrapper extends ServletRequestWrapper implements
+ HttpServletRequest {
-
-public class HttpServletRequestWrapper extends ServletRequestWrapper implements HttpServletRequest {
-
- /**
- * Constructs a request object wrapping the given request.
- * @throws java.lang.IllegalArgumentException if the request is null
- */
+ /**
+ * Constructs a request object wrapping the given request.
+ *
+ * @throws java.lang.IllegalArgumentException
+ * if the request is null
+ */
public HttpServletRequestWrapper(HttpServletRequest request) {
- super(request);
+ super(request);
}
-
+
private HttpServletRequest _getHttpServletRequest() {
- return (HttpServletRequest) super.getRequest();
+ return (HttpServletRequest) super.getRequest();
}
/**
- * The default behavior of this method is to return getAuthType()
- * on the wrapped request object.
+ * The default behavior of this method is to return getAuthType() on the
+ * wrapped request object.
*/
-
public String getAuthType() {
- return this._getHttpServletRequest().getAuthType();
+ return this._getHttpServletRequest().getAuthType();
}
-
+
/**
- * The default behavior of this method is to return getCookies()
- * on the wrapped request object.
+ * The default behavior of this method is to return getCookies() on the
+ * wrapped request object.
*/
public Cookie[] getCookies() {
- return this._getHttpServletRequest().getCookies();
+ return this._getHttpServletRequest().getCookies();
}
/**
- * The default behavior of this method is to return getDateHeader(String name)
- * on the wrapped request object.
+ * The default behavior of this method is to return getDateHeader(String
+ * name) on the wrapped request object.
*/
public long getDateHeader(String name) {
- return this._getHttpServletRequest().getDateHeader(name);
+ return this._getHttpServletRequest().getDateHeader(name);
}
-
+
/**
* The default behavior of this method is to return getHeader(String name)
* on the wrapped request object.
*/
public String getHeader(String name) {
- return this._getHttpServletRequest().getHeader(name);
+ return this._getHttpServletRequest().getHeader(name);
}
-
+
/**
* The default behavior of this method is to return getHeaders(String name)
* on the wrapped request object.
*/
public Enumeration<String> getHeaders(String name) {
- return this._getHttpServletRequest().getHeaders(name);
- }
+ return this._getHttpServletRequest().getHeaders(name);
+ }
/**
- * The default behavior of this method is to return getHeaderNames()
- * on the wrapped request object.
+ * The default behavior of this method is to return getHeaderNames() on the
+ * wrapped request object.
*/
-
public Enumeration<String> getHeaderNames() {
- return this._getHttpServletRequest().getHeaderNames();
+ return this._getHttpServletRequest().getHeaderNames();
}
-
+
/**
- * The default behavior of this method is to return getIntHeader(String name)
- * on the wrapped request object.
+ * The default behavior of this method is to return getIntHeader(String
+ * name) on the wrapped request object.
*/
-
- public int getIntHeader(String name) {
- return this._getHttpServletRequest().getIntHeader(name);
+ public int getIntHeader(String name) {
+ return this._getHttpServletRequest().getIntHeader(name);
}
-
+
/**
- * The default behavior of this method is to return getMethod()
- * on the wrapped request object.
+ * The default behavior of this method is to return getMethod() on the
+ * wrapped request object.
*/
public String getMethod() {
- return this._getHttpServletRequest().getMethod();
+ return this._getHttpServletRequest().getMethod();
}
-
+
/**
- * The default behavior of this method is to return getPathInfo()
- * on the wrapped request object.
+ * The default behavior of this method is to return getPathInfo() on the
+ * wrapped request object.
*/
public String getPathInfo() {
- return this._getHttpServletRequest().getPathInfo();
+ return this._getHttpServletRequest().getPathInfo();
}
/**
- * The default behavior of this method is to return getPathTranslated()
- * on the wrapped request object.
+ * The default behavior of this method is to return getPathTranslated() on
+ * the wrapped request object.
*/
-
- public String getPathTranslated() {
- return this._getHttpServletRequest().getPathTranslated();
+ public String getPathTranslated() {
+ return this._getHttpServletRequest().getPathTranslated();
}
/**
- * The default behavior of this method is to return getContextPath()
- * on the wrapped request object.
+ * The default behavior of this method is to return getContextPath() on the
+ * wrapped request object.
*/
public String getContextPath() {
- return this._getHttpServletRequest().getContextPath();
+ return this._getHttpServletRequest().getContextPath();
}
-
+
/**
- * The default behavior of this method is to return getQueryString()
- * on the wrapped request object.
+ * The default behavior of this method is to return getQueryString() on the
+ * wrapped request object.
*/
public String getQueryString() {
- return this._getHttpServletRequest().getQueryString();
+ return this._getHttpServletRequest().getQueryString();
}
-
+
/**
- * The default behavior of this method is to return getRemoteUser()
- * on the wrapped request object.
+ * The default behavior of this method is to return getRemoteUser() on the
+ * wrapped request object.
*/
public String getRemoteUser() {
- return this._getHttpServletRequest().getRemoteUser();
+ return this._getHttpServletRequest().getRemoteUser();
}
-
-
+
/**
- * The default behavior of this method is to return isUserInRole(String role)
- * on the wrapped request object.
+ * The default behavior of this method is to return isUserInRole(String
+ * role) on the wrapped request object.
*/
public boolean isUserInRole(String role) {
- return this._getHttpServletRequest().isUserInRole(role);
+ return this._getHttpServletRequest().isUserInRole(role);
}
-
-
-
+
/**
- * The default behavior of this method is to return getUserPrincipal()
- * on the wrapped request object.
+ * The default behavior of this method is to return getUserPrincipal() on
+ * the wrapped request object.
*/
public java.security.Principal getUserPrincipal() {
- return this._getHttpServletRequest().getUserPrincipal();
+ return this._getHttpServletRequest().getUserPrincipal();
}
-
-
+
/**
* The default behavior of this method is to return getRequestedSessionId()
* on the wrapped request object.
*/
public String getRequestedSessionId() {
- return this._getHttpServletRequest().getRequestedSessionId();
+ return this._getHttpServletRequest().getRequestedSessionId();
}
-
+
/**
- * The default behavior of this method is to return getRequestURI()
- * on the wrapped request object.
+ * The default behavior of this method is to return getRequestURI() on the
+ * wrapped request object.
*/
public String getRequestURI() {
- return this._getHttpServletRequest().getRequestURI();
+ return this._getHttpServletRequest().getRequestURI();
}
- /**
- * The default behavior of this method is to return getRequestURL()
- * on the wrapped request object.
+
+ /**
+ * The default behavior of this method is to return getRequestURL() on the
+ * wrapped request object.
*/
public StringBuffer getRequestURL() {
- return this._getHttpServletRequest().getRequestURL();
+ return this._getHttpServletRequest().getRequestURL();
}
-
-
+
/**
- * The default behavior of this method is to return getServletPath()
- * on the wrapped request object.
+ * The default behavior of this method is to return getServletPath() on the
+ * wrapped request object.
*/
public String getServletPath() {
- return this._getHttpServletRequest().getServletPath();
+ return this._getHttpServletRequest().getServletPath();
}
-
-
+
/**
- * The default behavior of this method is to return getSession(boolean create)
- * on the wrapped request object.
+ * The default behavior of this method is to return getSession(boolean
+ * create) on the wrapped request object.
*/
public HttpSession getSession(boolean create) {
- return this._getHttpServletRequest().getSession(create);
+ return this._getHttpServletRequest().getSession(create);
}
-
+
/**
- * The default behavior of this method is to return getSession()
- * on the wrapped request object.
+ * The default behavior of this method is to return getSession() on the
+ * wrapped request object.
*/
public HttpSession getSession() {
- return this._getHttpServletRequest().getSession();
+ return this._getHttpServletRequest().getSession();
}
-
- /**
- * The default behavior of this method is to return isRequestedSessionIdValid()
- * on the wrapped request object.
- */
+ /**
+ * The default behavior of this method is to return
+ * isRequestedSessionIdValid() on the wrapped request object.
+ */
public boolean isRequestedSessionIdValid() {
- return this._getHttpServletRequest().isRequestedSessionIdValid();
+ return this._getHttpServletRequest().isRequestedSessionIdValid();
}
-
-
+
/**
- * The default behavior of this method is to return isRequestedSessionIdFromCookie()
- * on the wrapped request object.
+ * The default behavior of this method is to return
+ * isRequestedSessionIdFromCookie() on the wrapped request object.
*/
public boolean isRequestedSessionIdFromCookie() {
- return this._getHttpServletRequest().isRequestedSessionIdFromCookie();
+ return this._getHttpServletRequest().isRequestedSessionIdFromCookie();
}
-
- /**
- * The default behavior of this method is to return isRequestedSessionIdFromURL()
- * on the wrapped request object.
- */
+
+ /**
+ * The default behavior of this method is to return
+ * isRequestedSessionIdFromURL() on the wrapped request object.
+ */
public boolean isRequestedSessionIdFromURL() {
- return this._getHttpServletRequest().isRequestedSessionIdFromURL();
+ return this._getHttpServletRequest().isRequestedSessionIdFromURL();
}
-
+
/**
- * The default behavior of this method is to return isRequestedSessionIdFromUrl()
- * on the wrapped request object.
+ * The default behavior of this method is to return
+ * isRequestedSessionIdFromUrl() on the wrapped request object.
+ *
* @deprecated As of Version 3.0 of the Java Servlet API
*/
- @SuppressWarnings("dep-ann") // Spec API does not use @Deprecated
+ @SuppressWarnings("dep-ann")
+ // Spec API does not use @Deprecated
public boolean isRequestedSessionIdFromUrl() {
- return this._getHttpServletRequest().isRequestedSessionIdFromUrl();
+ return this._getHttpServletRequest().isRequestedSessionIdFromUrl();
}
/**
- * @since Servlet 3.0
- * TODO SERVLET3 - Add comments
+ * @since Servlet 3.0 TODO SERVLET3 - Add comments
*/
public boolean authenticate(HttpServletResponse response)
- throws IOException, ServletException {
+ throws IOException, ServletException {
return this._getHttpServletRequest().authenticate(response);
}
/**
- * @since Servlet 3.0
- * TODO SERVLET3 - Add comments
+ * @since Servlet 3.0 TODO SERVLET3 - Add comments
*/
public void login(String username, String password) throws ServletException {
this._getHttpServletRequest().login(username, password);
}
/**
- * @since Servlet 3.0
- * TODO SERVLET3 - Add comments
+ * @since Servlet 3.0 TODO SERVLET3 - Add comments
*/
public void logout() throws ServletException {
this._getHttpServletRequest().logout();
}
-
/**
- * @since Servlet 3.0
- * TODO SERVLET3 - Add comments
+ * @since Servlet 3.0 TODO SERVLET3 - Add comments
*/
public Collection<Part> getParts() throws IllegalStateException,
IOException, ServletException {
}
/**
- * @throws ServletException
- * @throws IOException
- * @throws IllegalStateException
- * @since Servlet 3.0
- * TODO SERVLET3 - Add comments
+ * @throws ServletException
+ * @throws IOException
+ * @throws IllegalStateException
+ * @since Servlet 3.0 TODO SERVLET3 - Add comments
*/
public Part getPart(String name) throws IllegalStateException, IOException,
ServletException {
return this._getHttpServletRequest().getPart(name);
}
-
}
/*
-* Licensed to the Apache Software Foundation (ASF) under one or more
-* contributor license agreements. See the NOTICE file distributed with
-* this work for additional information regarding copyright ownership.
-* The ASF licenses this file to You under the Apache License, Version 2.0
-* (the "License"); you may not use this file except in compliance with
-* the License. You may obtain a copy of the License at
-*
-* http://www.apache.org/licenses/LICENSE-2.0
-*
-* Unless required by applicable law or agreed to in writing, software
-* distributed under the License is distributed on an "AS IS" BASIS,
-* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-* See the License for the specific language governing permissions and
-* limitations under the License.
-*/
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
package javax.servlet.http;
import java.io.IOException;
import javax.servlet.ServletResponse;
/**
- *
* Extends the {@link ServletResponse} interface to provide HTTP-specific
- * functionality in sending a response. For example, it has methods
- * to access HTTP headers and cookies.
- *
- * <p>The servlet container creates an <code>HttpServletResponse</code> object
- * and passes it as an argument to the servlet's service methods
- * (<code>doGet</code>, <code>doPost</code>, etc).
- *
+ * functionality in sending a response. For example, it has methods to access
+ * HTTP headers and cookies.
+ * <p>
+ * The servlet container creates an <code>HttpServletResponse</code> object and
+ * passes it as an argument to the servlet's service methods (<code>doGet</code>, <code>doPost</code>, etc).
*
- * @author Various
- * @version $Version$
- *
- * @see javax.servlet.ServletResponse
- *
+ * @author Various
+ * @version $Version$
+ * @see javax.servlet.ServletResponse
*/
-
-
-
public interface HttpServletResponse extends ServletResponse {
/**
- * Adds the specified cookie to the response. This method can be called
+ * Adds the specified cookie to the response. This method can be called
* multiple times to set more than one cookie.
- *
- * @param cookie the Cookie to return to the client
- *
+ *
+ * @param cookie
+ * the Cookie to return to the client
*/
-
public void addCookie(Cookie cookie);
/**
- * Returns a boolean indicating whether the named response header
- * has already been set.
+ * Returns a boolean indicating whether the named response header has
+ * already been set.
*
- * @param name the header name
- * @return <code>true</code> if the named response header
- * has already been set;
- * <code>false</code> otherwise
+ * @param name
+ * the header name
+ * @return <code>true</code> if the named response header has already been
+ * set; <code>false</code> otherwise
*/
-
public boolean containsHeader(String name);
/**
- * Encodes the specified URL by including the session ID in it,
- * or, if encoding is not needed, returns the URL unchanged.
- * The implementation of this method includes the logic to
- * determine whether the session ID needs to be encoded in the URL.
- * For example, if the browser supports cookies, or session
- * tracking is turned off, URL encoding is unnecessary.
+ * Encodes the specified URL by including the session ID in it, or, if
+ * encoding is not needed, returns the URL unchanged. The implementation of
+ * this method includes the logic to determine whether the session ID needs
+ * to be encoded in the URL. For example, if the browser supports cookies,
+ * or session tracking is turned off, URL encoding is unnecessary.
+ * <p>
+ * For robust session tracking, all URLs emitted by a servlet should be run
+ * through this method. Otherwise, URL rewriting cannot be used with
+ * browsers which do not support cookies.
*
- * <p>For robust session tracking, all URLs emitted by a servlet
- * should be run through this
- * method. Otherwise, URL rewriting cannot be used with browsers
- * which do not support cookies.
- *
- * @param url the url to be encoded.
- * @return the encoded URL if encoding is needed;
- * the unchanged URL otherwise.
+ * @param url
+ * the url to be encoded.
+ * @return the encoded URL if encoding is needed; the unchanged URL
+ * otherwise.
*/
-
public String encodeURL(String url);
/**
- * Encodes the specified URL for use in the
- * <code>sendRedirect</code> method or, if encoding is not needed,
- * returns the URL unchanged. The implementation of this method
- * includes the logic to determine whether the session ID
- * needs to be encoded in the URL. Because the rules for making
- * this determination can differ from those used to decide whether to
- * encode a normal link, this method is separated from the
- * <code>encodeURL</code> method.
+ * Encodes the specified URL for use in the <code>sendRedirect</code> method
+ * or, if encoding is not needed, returns the URL unchanged. The
+ * implementation of this method includes the logic to determine whether the
+ * session ID needs to be encoded in the URL. Because the rules for making
+ * this determination can differ from those used to decide whether to encode
+ * a normal link, this method is separated from the <code>encodeURL</code>
+ * method.
+ * <p>
+ * All URLs sent to the <code>HttpServletResponse.sendRedirect</code> method
+ * should be run through this method. Otherwise, URL rewriting cannot be
+ * used with browsers which do not support cookies.
*
- * <p>All URLs sent to the <code>HttpServletResponse.sendRedirect</code>
- * method should be run through this method. Otherwise, URL
- * rewriting cannot be used with browsers which do not support
- * cookies.
- *
- * @param url the url to be encoded.
- * @return the encoded URL if encoding is needed;
- * the unchanged URL otherwise.
- *
+ * @param url
+ * the url to be encoded.
+ * @return the encoded URL if encoding is needed; the unchanged URL
+ * otherwise.
* @see #sendRedirect
* @see #encodeUrl
*/
-
public String encodeRedirectURL(String url);
/**
- * @param url the url to be encoded.
- * @return the encoded URL if encoding is needed;
- * the unchanged URL otherwise.
- *
- * @deprecated As of version 2.1, use encodeURL(String url) instead
+ * @param url
+ * the url to be encoded.
+ * @return the encoded URL if encoding is needed; the unchanged URL
+ * otherwise.
+ * @deprecated As of version 2.1, use encodeURL(String url) instead
*/
- @SuppressWarnings("dep-ann") // Spec API does not use @Deprecated
+ @SuppressWarnings("dep-ann")
+ // Spec API does not use @Deprecated
public String encodeUrl(String url);
-
+
/**
- * @param url the url to be encoded.
- * @return the encoded URL if encoding is needed;
- * the unchanged URL otherwise.
- *
- * @deprecated As of version 2.1, use
- * encodeRedirectURL(String url) instead
+ * @param url
+ * the url to be encoded.
+ * @return the encoded URL if encoding is needed; the unchanged URL
+ * otherwise.
+ * @deprecated As of version 2.1, use encodeRedirectURL(String url) instead
*/
- @SuppressWarnings("dep-ann") // Spec API does not use @Deprecated
+ @SuppressWarnings("dep-ann")
+ // Spec API does not use @Deprecated
public String encodeRedirectUrl(String url);
/**
- * Sends an error response to the client using the specified
- * status. The server defaults to creating the
- * response to look like an HTML-formatted server error page
- * containing the specified message, setting the content type
- * to "text/html", leaving cookies and other headers unmodified.
- *
- * If an error-page declaration has been made for the web application
- * corresponding to the status code passed in, it will be served back in
- * preference to the suggested msg parameter.
- *
- * <p>If the response has already been committed, this method throws
- * an IllegalStateException.
- * After using this method, the response should be considered
- * to be committed and should not be written to.
- *
- * @param sc the error status code
- * @param msg the descriptive message
- * @exception IOException If an input or output exception occurs
- * @exception IllegalStateException If the response was committed
- */
-
+ * Sends an error response to the client using the specified status. The
+ * server defaults to creating the response to look like an HTML-formatted
+ * server error page containing the specified message, setting the content
+ * type to "text/html", leaving cookies and other headers unmodified. If an
+ * error-page declaration has been made for the web application
+ * corresponding to the status code passed in, it will be served back in
+ * preference to the suggested msg parameter.
+ * <p>
+ * If the response has already been committed, this method throws an
+ * IllegalStateException. After using this method, the response should be
+ * considered to be committed and should not be written to.
+ *
+ * @param sc
+ * the error status code
+ * @param msg
+ * the descriptive message
+ * @exception IOException
+ * If an input or output exception occurs
+ * @exception IllegalStateException
+ * If the response was committed
+ */
public void sendError(int sc, String msg) throws IOException;
/**
- * Sends an error response to the client using the specified status
- * code and clearing the buffer.
- * <p>If the response has already been committed, this method throws
- * an IllegalStateException.
- * After using this method, the response should be considered
- * to be committed and should not be written to.
- *
- * @param sc the error status code
- * @exception IOException If an input or output exception occurs
- * @exception IllegalStateException If the response was committed
- * before this method call
+ * Sends an error response to the client using the specified status code and
+ * clearing the buffer.
+ * <p>
+ * If the response has already been committed, this method throws an
+ * IllegalStateException. After using this method, the response should be
+ * considered to be committed and should not be written to.
+ *
+ * @param sc
+ * the error status code
+ * @exception IOException
+ * If an input or output exception occurs
+ * @exception IllegalStateException
+ * If the response was committed before this method call
*/
-
public void sendError(int sc) throws IOException;
/**
- * Sends a temporary redirect response to the client using the
- * specified redirect location URL. This method can accept relative URLs;
- * the servlet container must convert the relative URL to an absolute URL
- * before sending the response to the client. If the location is relative
- * without a leading '/' the container interprets it as relative to
- * the current request URI. If the location is relative with a leading
- * '/' the container interprets it as relative to the servlet container root.
- *
- * <p>If the response has already been committed, this method throws
- * an IllegalStateException.
- * After using this method, the response should be considered
- * to be committed and should not be written to.
- *
- * @param location the redirect location URL
- * @exception IOException If an input or output exception occurs
- * @exception IllegalStateException If the response was committed or
- if a partial URL is given and cannot be converted into a valid URL
+ * Sends a temporary redirect response to the client using the specified
+ * redirect location URL. This method can accept relative URLs; the servlet
+ * container must convert the relative URL to an absolute URL before sending
+ * the response to the client. If the location is relative without a leading
+ * '/' the container interprets it as relative to the current request URI.
+ * If the location is relative with a leading '/' the container interprets
+ * it as relative to the servlet container root.
+ * <p>
+ * If the response has already been committed, this method throws an
+ * IllegalStateException. After using this method, the response should be
+ * considered to be committed and should not be written to.
+ *
+ * @param location
+ * the redirect location URL
+ * @exception IOException
+ * If an input or output exception occurs
+ * @exception IllegalStateException
+ * If the response was committed or if a partial URL is given
+ * and cannot be converted into a valid URL
*/
-
public void sendRedirect(String location) throws IOException;
-
+
/**
+ * Sets a response header with the given name and date-value. The date is
+ * specified in terms of milliseconds since the epoch. If the header had
+ * already been set, the new value overwrites the previous one. The
+ * <code>containsHeader</code> method can be used to test for the presence
+ * of a header before setting its value.
*
- * Sets a response header with the given name and
- * date-value. The date is specified in terms of
- * milliseconds since the epoch. If the header had already
- * been set, the new value overwrites the previous one. The
- * <code>containsHeader</code> method can be used to test for the
- * presence of a header before setting its value.
- *
- * @param name the name of the header to set
- * @param date the assigned date value
- *
+ * @param name
+ * the name of the header to set
+ * @param date
+ * the assigned date value
* @see #containsHeader
* @see #addDateHeader
*/
-
public void setDateHeader(String name, long date);
-
+
/**
+ * Adds a response header with the given name and date-value. The date is
+ * specified in terms of milliseconds since the epoch. This method allows
+ * response headers to have multiple values.
*
- * Adds a response header with the given name and
- * date-value. The date is specified in terms of
- * milliseconds since the epoch. This method allows response headers
- * to have multiple values.
- *
- * @param name the name of the header to set
- * @param date the additional date value
- *
+ * @param name
+ * the name of the header to set
+ * @param date
+ * the additional date value
* @see #setDateHeader
*/
-
public void addDateHeader(String name, long date);
-
- /**
- *
- * Sets a response header with the given name and value.
- * If the header had already been set, the new value overwrites the
- * previous one. The <code>containsHeader</code> method can be
- * used to test for the presence of a header before setting its
- * value.
+
+ /**
+ * Sets a response header with the given name and value. If the header had
+ * already been set, the new value overwrites the previous one. The
+ * <code>containsHeader</code> method can be used to test for the presence
+ * of a header before setting its value.
*
- * @param name the name of the header
- * @param value the header value If it contains octet string,
- * it should be encoded according to RFC 2047
- * (http://www.ietf.org/rfc/rfc2047.txt)
- *
+ * @param name
+ * the name of the header
+ * @param value
+ * the header value If it contains octet string, it should be
+ * encoded according to RFC 2047
+ * (http://www.ietf.org/rfc/rfc2047.txt)
* @see #containsHeader
* @see #addHeader
*/
-
public void setHeader(String name, String value);
-
+
/**
- * Adds a response header with the given name and value.
- * This method allows response headers to have multiple values.
+ * Adds a response header with the given name and value. This method allows
+ * response headers to have multiple values.
*
- * @param name the name of the header
- * @param value the additional header value If it contains
- * octet string, it should be encoded
- * according to RFC 2047
- * (http://www.ietf.org/rfc/rfc2047.txt)
- *
+ * @param name
+ * the name of the header
+ * @param value
+ * the additional header value If it contains octet string, it
+ * should be encoded according to RFC 2047
+ * (http://www.ietf.org/rfc/rfc2047.txt)
* @see #setHeader
*/
-
public void addHeader(String name, String value);
/**
- * Sets a response header with the given name and
- * integer value. If the header had already been set, the new value
- * overwrites the previous one. The <code>containsHeader</code>
- * method can be used to test for the presence of a header before
- * setting its value.
- *
- * @param name the name of the header
- * @param value the assigned integer value
- *
+ * Sets a response header with the given name and integer value. If the
+ * header had already been set, the new value overwrites the previous one.
+ * The <code>containsHeader</code> method can be used to test for the
+ * presence of a header before setting its value.
+ *
+ * @param name
+ * the name of the header
+ * @param value
+ * the assigned integer value
* @see #containsHeader
* @see #addIntHeader
*/
-
public void setIntHeader(String name, int value);
/**
- * Adds a response header with the given name and
- * integer value. This method allows response headers to have multiple
- * values.
- *
- * @param name the name of the header
- * @param value the assigned integer value
- *
+ * Adds a response header with the given name and integer value. This method
+ * allows response headers to have multiple values.
+ *
+ * @param name
+ * the name of the header
+ * @param value
+ * the assigned integer value
* @see #setIntHeader
*/
-
public void addIntHeader(String name, int value);
-
-
/**
- * Sets the status code for this response. This method is used to
- * set the return status code when there is no error (for example,
- * for the status codes SC_OK or SC_MOVED_TEMPORARILY). If there
- * is an error, and the caller wishes to invoke an error-page defined
- * in the web application, the <code>sendError</code> method should be used
- * instead.
- * <p> The container clears the buffer and sets the Location header, preserving
+ * Sets the status code for this response. This method is used to set the
+ * return status code when there is no error (for example, for the status
+ * codes SC_OK or SC_MOVED_TEMPORARILY). If there is an error, and the
+ * caller wishes to invoke an error-page defined in the web application, the
+ * <code>sendError</code> method should be used instead.
+ * <p>
+ * The container clears the buffer and sets the Location header, preserving
* cookies and other headers.
- *
- * @param sc the status code
- *
+ *
+ * @param sc
+ * the status code
* @see #sendError
*/
-
public void setStatus(int sc);
-
+
/**
* Sets the status code and message for this response.
*
- * @param sc the status code
- * @param sm the status message
- *
- * @deprecated As of version 2.1, due to ambiguous meaning of the
- * message parameter. To set a status code
- * use <code>setStatus(int)</code>, to send an error with a description
- * use <code>sendError(int, String)</code>.
- */
- @SuppressWarnings("dep-ann") // Spec API does not use @Deprecated
+ * @param sc
+ * the status code
+ * @param sm
+ * the status message
+ * @deprecated As of version 2.1, due to ambiguous meaning of the message
+ * parameter. To set a status code use
+ * <code>setStatus(int)</code>, to send an error with a
+ * description use <code>sendError(int, String)</code>.
+ */
+ @SuppressWarnings("dep-ann")
+ // Spec API does not use @Deprecated
public void setStatus(int sc, String sm);
-
/**
- *
* @return
- * @since Servlet 3.0
- * TODO SERVLET3 - Add comments
+ * @since Servlet 3.0 TODO SERVLET3 - Add comments
*/
public int getStatus();
-
-
+
/**
- *
* @param name
* @return
- * @since Servlet 3.0
- * TODO SERVLET3 - Add comments
+ * @since Servlet 3.0 TODO SERVLET3 - Add comments
*/
public String getHeader(String name);
-
-
+
/**
- *
* @param name
* @return
- * @since Servlet 3.0
- * TODO SERVLET3 - Add comments
+ * @since Servlet 3.0 TODO SERVLET3 - Add comments
*/
public Collection<String> getHeaders(String name);
-
/**
- *
* @return
- * @since Servlet 3.0
- * TODO SERVLET3 - Add comments
+ * @since Servlet 3.0 TODO SERVLET3 - Add comments
*/
public Collection<String> getHeaderNames();
-
/*
* Server status codes; see RFC 2068.
*/
/**
* Status code (100) indicating the client can continue.
*/
-
public static final int SC_CONTINUE = 100;
-
/**
- * Status code (101) indicating the server is switching protocols
- * according to Upgrade header.
+ * Status code (101) indicating the server is switching protocols according
+ * to Upgrade header.
*/
-
public static final int SC_SWITCHING_PROTOCOLS = 101;
/**
* Status code (200) indicating the request succeeded normally.
*/
-
public static final int SC_OK = 200;
/**
- * Status code (201) indicating the request succeeded and created
- * a new resource on the server.
+ * Status code (201) indicating the request succeeded and created a new
+ * resource on the server.
*/
-
public static final int SC_CREATED = 201;
/**
- * Status code (202) indicating that a request was accepted for
- * processing, but was not completed.
+ * Status code (202) indicating that a request was accepted for processing,
+ * but was not completed.
*/
-
public static final int SC_ACCEPTED = 202;
/**
- * Status code (203) indicating that the meta information presented
- * by the client did not originate from the server.
+ * Status code (203) indicating that the meta information presented by the
+ * client did not originate from the server.
*/
-
public static final int SC_NON_AUTHORITATIVE_INFORMATION = 203;
/**
- * Status code (204) indicating that the request succeeded but that
- * there was no new information to return.
+ * Status code (204) indicating that the request succeeded but that there
+ * was no new information to return.
*/
-
public static final int SC_NO_CONTENT = 204;
/**
- * Status code (205) indicating that the agent <em>SHOULD</em> reset
- * the document view which caused the request to be sent.
+ * Status code (205) indicating that the agent <em>SHOULD</em> reset the
+ * document view which caused the request to be sent.
*/
-
public static final int SC_RESET_CONTENT = 205;
/**
- * Status code (206) indicating that the server has fulfilled
- * the partial GET request for the resource.
+ * Status code (206) indicating that the server has fulfilled the partial
+ * GET request for the resource.
*/
-
public static final int SC_PARTIAL_CONTENT = 206;
/**
- * Status code (300) indicating that the requested resource
- * corresponds to any one of a set of representations, each with
- * its own specific location.
+ * Status code (300) indicating that the requested resource corresponds to
+ * any one of a set of representations, each with its own specific location.
*/
-
public static final int SC_MULTIPLE_CHOICES = 300;
/**
- * Status code (301) indicating that the resource has permanently
- * moved to a new location, and that future references should use a
- * new URI with their requests.
+ * Status code (301) indicating that the resource has permanently moved to a
+ * new location, and that future references should use a new URI with their
+ * requests.
*/
-
public static final int SC_MOVED_PERMANENTLY = 301;
/**
- * Status code (302) indicating that the resource has temporarily
- * moved to another location, but that future references should
- * still use the original URI to access the resource.
- *
- * This definition is being retained for backwards compatibility.
- * SC_FOUND is now the preferred definition.
+ * Status code (302) indicating that the resource has temporarily moved to
+ * another location, but that future references should still use the
+ * original URI to access the resource. This definition is being retained
+ * for backwards compatibility. SC_FOUND is now the preferred definition.
*/
-
public static final int SC_MOVED_TEMPORARILY = 302;
/**
- * Status code (302) indicating that the resource reside
- * temporarily under a different URI. Since the redirection might
- * be altered on occasion, the client should continue to use the
- * Request-URI for future requests.(HTTP/1.1) To represent the
- * status code (302), it is recommended to use this variable.
- */
-
+ * Status code (302) indicating that the resource reside temporarily under a
+ * different URI. Since the redirection might be altered on occasion, the
+ * client should continue to use the Request-URI for future
+ * requests.(HTTP/1.1) To represent the status code (302), it is recommended
+ * to use this variable.
+ */
public static final int SC_FOUND = 302;
/**
- * Status code (303) indicating that the response to the request
- * can be found under a different URI.
+ * Status code (303) indicating that the response to the request can be
+ * found under a different URI.
*/
-
public static final int SC_SEE_OTHER = 303;
/**
- * Status code (304) indicating that a conditional GET operation
- * found that the resource was available and not modified.
+ * Status code (304) indicating that a conditional GET operation found that
+ * the resource was available and not modified.
*/
-
public static final int SC_NOT_MODIFIED = 304;
/**
- * Status code (305) indicating that the requested resource
- * <em>MUST</em> be accessed through the proxy given by the
- * <code><em>Location</em></code> field.
+ * Status code (305) indicating that the requested resource <em>MUST</em> be
+ * accessed through the proxy given by the <code><em>Location</em></code>
+ * field.
*/
-
public static final int SC_USE_PROXY = 305;
- /**
- * Status code (307) indicating that the requested resource
- * resides temporarily under a different URI. The temporary URI
- * <em>SHOULD</em> be given by the <code><em>Location</em></code>
- * field in the response.
+ /**
+ * Status code (307) indicating that the requested resource resides
+ * temporarily under a different URI. The temporary URI <em>SHOULD</em> be
+ * given by the <code><em>Location</em></code> field in the response.
*/
-
- public static final int SC_TEMPORARY_REDIRECT = 307;
+ public static final int SC_TEMPORARY_REDIRECT = 307;
/**
* Status code (400) indicating the request sent by the client was
* syntactically incorrect.
*/
-
public static final int SC_BAD_REQUEST = 400;
/**
* Status code (401) indicating that the request requires HTTP
* authentication.
*/
-
public static final int SC_UNAUTHORIZED = 401;
/**
* Status code (402) reserved for future use.
*/
-
public static final int SC_PAYMENT_REQUIRED = 402;
/**
- * Status code (403) indicating the server understood the request
- * but refused to fulfill it.
+ * Status code (403) indicating the server understood the request but
+ * refused to fulfill it.
*/
-
public static final int SC_FORBIDDEN = 403;
/**
* Status code (404) indicating that the requested resource is not
* available.
*/
-
public static final int SC_NOT_FOUND = 404;
/**
* <code><em>Request-Line</em></code> is not allowed for the resource
* identified by the <code><em>Request-URI</em></code>.
*/
-
public static final int SC_METHOD_NOT_ALLOWED = 405;
/**
- * Status code (406) indicating that the resource identified by the
- * request is only capable of generating response entities which have
- * content characteristics not acceptable according to the accept
- * headers sent in the request.
+ * Status code (406) indicating that the resource identified by the request
+ * is only capable of generating response entities which have content
+ * characteristics not acceptable according to the accept headers sent in
+ * the request.
*/
-
public static final int SC_NOT_ACCEPTABLE = 406;
/**
* Status code (407) indicating that the client <em>MUST</em> first
* authenticate itself with the proxy.
*/
-
public static final int SC_PROXY_AUTHENTICATION_REQUIRED = 407;
/**
- * Status code (408) indicating that the client did not produce a
- * request within the time that the server was prepared to wait.
+ * Status code (408) indicating that the client did not produce a request
+ * within the time that the server was prepared to wait.
*/
-
public static final int SC_REQUEST_TIMEOUT = 408;
/**
- * Status code (409) indicating that the request could not be
- * completed due to a conflict with the current state of the
- * resource.
+ * Status code (409) indicating that the request could not be completed due
+ * to a conflict with the current state of the resource.
*/
-
public static final int SC_CONFLICT = 409;
/**
- * Status code (410) indicating that the resource is no longer
- * available at the server and no forwarding address is known.
- * This condition <em>SHOULD</em> be considered permanent.
+ * Status code (410) indicating that the resource is no longer available at
+ * the server and no forwarding address is known. This condition
+ * <em>SHOULD</em> be considered permanent.
*/
-
public static final int SC_GONE = 410;
/**
- * Status code (411) indicating that the request cannot be handled
- * without a defined <code><em>Content-Length</em></code>.
+ * Status code (411) indicating that the request cannot be handled without a
+ * defined <code><em>Content-Length</em></code>.
*/
-
public static final int SC_LENGTH_REQUIRED = 411;
/**
- * Status code (412) indicating that the precondition given in one
- * or more of the request-header fields evaluated to false when it
- * was tested on the server.
+ * Status code (412) indicating that the precondition given in one or more
+ * of the request-header fields evaluated to false when it was tested on the
+ * server.
*/
-
public static final int SC_PRECONDITION_FAILED = 412;
/**
- * Status code (413) indicating that the server is refusing to process
- * the request because the request entity is larger than the server is
- * willing or able to process.
+ * Status code (413) indicating that the server is refusing to process the
+ * request because the request entity is larger than the server is willing
+ * or able to process.
*/
-
public static final int SC_REQUEST_ENTITY_TOO_LARGE = 413;
/**
- * Status code (414) indicating that the server is refusing to service
- * the request because the <code><em>Request-URI</em></code> is longer
- * than the server is willing to interpret.
+ * Status code (414) indicating that the server is refusing to service the
+ * request because the <code><em>Request-URI</em></code> is longer than the
+ * server is willing to interpret.
*/
-
public static final int SC_REQUEST_URI_TOO_LONG = 414;
/**
- * Status code (415) indicating that the server is refusing to service
- * the request because the entity of the request is in a format not
- * supported by the requested resource for the requested method.
+ * Status code (415) indicating that the server is refusing to service the
+ * request because the entity of the request is in a format not supported by
+ * the requested resource for the requested method.
*/
-
public static final int SC_UNSUPPORTED_MEDIA_TYPE = 415;
/**
- * Status code (416) indicating that the server cannot serve the
- * requested byte range.
+ * Status code (416) indicating that the server cannot serve the requested
+ * byte range.
*/
-
public static final int SC_REQUESTED_RANGE_NOT_SATISFIABLE = 416;
/**
* Status code (417) indicating that the server could not meet the
* expectation given in the Expect request header.
*/
-
public static final int SC_EXPECTATION_FAILED = 417;
/**
- * Status code (500) indicating an error inside the HTTP server
- * which prevented it from fulfilling the request.
+ * Status code (500) indicating an error inside the HTTP server which
+ * prevented it from fulfilling the request.
*/
-
public static final int SC_INTERNAL_SERVER_ERROR = 500;
/**
- * Status code (501) indicating the HTTP server does not support
- * the functionality needed to fulfill the request.
+ * Status code (501) indicating the HTTP server does not support the
+ * functionality needed to fulfill the request.
*/
-
public static final int SC_NOT_IMPLEMENTED = 501;
/**
- * Status code (502) indicating that the HTTP server received an
- * invalid response from a server it consulted when acting as a
- * proxy or gateway.
+ * Status code (502) indicating that the HTTP server received an invalid
+ * response from a server it consulted when acting as a proxy or gateway.
*/
-
public static final int SC_BAD_GATEWAY = 502;
/**
- * Status code (503) indicating that the HTTP server is
- * temporarily overloaded, and unable to handle the request.
+ * Status code (503) indicating that the HTTP server is temporarily
+ * overloaded, and unable to handle the request.
*/
-
public static final int SC_SERVICE_UNAVAILABLE = 503;
/**
- * Status code (504) indicating that the server did not receive
- * a timely response from the upstream server while acting as
- * a gateway or proxy.
+ * Status code (504) indicating that the server did not receive a timely
+ * response from the upstream server while acting as a gateway or proxy.
*/
-
public static final int SC_GATEWAY_TIMEOUT = 504;
/**
- * Status code (505) indicating that the server does not support
- * or refuses to support the HTTP protocol version that was used
- * in the request message.
+ * Status code (505) indicating that the server does not support or refuses
+ * to support the HTTP protocol version that was used in the request
+ * message.
*/
-
public static final int SC_HTTP_VERSION_NOT_SUPPORTED = 505;
}
/*
-* Licensed to the Apache Software Foundation (ASF) under one or more
-* contributor license agreements. See the NOTICE file distributed with
-* this work for additional information regarding copyright ownership.
-* The ASF licenses this file to You under the Apache License, Version 2.0
-* (the "License"); you may not use this file except in compliance with
-* the License. You may obtain a copy of the License at
-*
-* http://www.apache.org/licenses/LICENSE-2.0
-*
-* Unless required by applicable law or agreed to in writing, software
-* distributed under the License is distributed on an "AS IS" BASIS,
-* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-* See the License for the specific language governing permissions and
-* limitations under the License.
-*/
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
package javax.servlet.http;
import java.io.IOException;
import javax.servlet.ServletResponseWrapper;
/**
+ * Provides a convenient implementation of the HttpServletResponse interface
+ * that can be subclassed by developers wishing to adapt the response from a
+ * Servlet. This class implements the Wrapper or Decorator pattern. Methods
+ * default to calling through to the wrapped response object.
*
- * Provides a convenient implementation of the HttpServletResponse interface that
- * can be subclassed by developers wishing to adapt the response from a Servlet.
- * This class implements the Wrapper or Decorator pattern. Methods default to
- * calling through to the wrapped response object.
- *
- * @author Various
- * @version $Version$
- * @since v 2.3
- *
- * @see javax.servlet.http.HttpServletResponse
- *
+ * @author Various
+ * @version $Version$
+ * @since v 2.3
+ * @see javax.servlet.http.HttpServletResponse
*/
+public class HttpServletResponseWrapper extends ServletResponseWrapper
+ implements HttpServletResponse {
-public class HttpServletResponseWrapper extends ServletResponseWrapper implements HttpServletResponse {
-
-
- /**
- * Constructs a response adaptor wrapping the given response.
- * @throws java.lang.IllegalArgumentException if the response is null
- */
+ /**
+ * Constructs a response adaptor wrapping the given response.
+ *
+ * @throws java.lang.IllegalArgumentException
+ * if the response is null
+ */
public HttpServletResponseWrapper(HttpServletResponse response) {
- super(response);
+ super(response);
}
-
+
private HttpServletResponse _getHttpServletResponse() {
- return (HttpServletResponse) super.getResponse();
+ return (HttpServletResponse) super.getResponse();
}
-
+
/**
* The default behavior of this method is to call addCookie(Cookie cookie)
* on the wrapped response object.
*/
public void addCookie(Cookie cookie) {
- this._getHttpServletResponse().addCookie(cookie);
+ this._getHttpServletResponse().addCookie(cookie);
}
/**
- * The default behavior of this method is to call containsHeader(String name)
- * on the wrapped response object.
+ * The default behavior of this method is to call containsHeader(String
+ * name) on the wrapped response object.
*/
-
-
public boolean containsHeader(String name) {
- return this._getHttpServletResponse().containsHeader(name);
+ return this._getHttpServletResponse().containsHeader(name);
}
-
+
/**
- * The default behavior of this method is to call encodeURL(String url)
- * on the wrapped response object.
+ * The default behavior of this method is to call encodeURL(String url) on
+ * the wrapped response object.
*/
public String encodeURL(String url) {
- return this._getHttpServletResponse().encodeURL(url);
+ return this._getHttpServletResponse().encodeURL(url);
}
/**
- * The default behavior of this method is to return encodeRedirectURL(String url)
- * on the wrapped response object.
+ * The default behavior of this method is to return encodeRedirectURL(String
+ * url) on the wrapped response object.
*/
public String encodeRedirectURL(String url) {
- return this._getHttpServletResponse().encodeRedirectURL(url);
+ return this._getHttpServletResponse().encodeRedirectURL(url);
}
/**
- * The default behavior of this method is to call encodeUrl(String url)
- * on the wrapped response object.
+ * The default behavior of this method is to call encodeUrl(String url) on
+ * the wrapped response object.
+ *
* @deprecated As of Version 3.0 of the Java Servlet API
*/
- @SuppressWarnings("dep-ann") // Spec API does not use @Deprecated
+ @SuppressWarnings("dep-ann")
+ // Spec API does not use @Deprecated
public String encodeUrl(String url) {
- return this._getHttpServletResponse().encodeUrl(url);
+ return this._getHttpServletResponse().encodeUrl(url);
}
-
+
/**
- * The default behavior of this method is to return encodeRedirectUrl(String url)
- * on the wrapped response object.
+ * The default behavior of this method is to return encodeRedirectUrl(String
+ * url) on the wrapped response object.
+ *
* @deprecated As of Version 3.0 of the Java Servlet API
*/
- @SuppressWarnings("dep-ann") // Spec API does not use @Deprecated
+ @SuppressWarnings("dep-ann")
+ // Spec API does not use @Deprecated
public String encodeRedirectUrl(String url) {
- return this._getHttpServletResponse().encodeRedirectUrl(url);
+ return this._getHttpServletResponse().encodeRedirectUrl(url);
}
-
+
/**
- * The default behavior of this method is to call sendError(int sc, String msg)
- * on the wrapped response object.
+ * The default behavior of this method is to call sendError(int sc, String
+ * msg) on the wrapped response object.
*/
public void sendError(int sc, String msg) throws IOException {
- this._getHttpServletResponse().sendError(sc, msg);
+ this._getHttpServletResponse().sendError(sc, msg);
}
/**
- * The default behavior of this method is to call sendError(int sc)
- * on the wrapped response object.
+ * The default behavior of this method is to call sendError(int sc) on the
+ * wrapped response object.
*/
-
-
public void sendError(int sc) throws IOException {
- this._getHttpServletResponse().sendError(sc);
+ this._getHttpServletResponse().sendError(sc);
}
/**
- * The default behavior of this method is to return sendRedirect(String location)
- * on the wrapped response object.
+ * The default behavior of this method is to return sendRedirect(String
+ * location) on the wrapped response object.
*/
public void sendRedirect(String location) throws IOException {
- this._getHttpServletResponse().sendRedirect(location);
+ this._getHttpServletResponse().sendRedirect(location);
}
-
+
/**
- * The default behavior of this method is to call setDateHeader(String name, long date)
- * on the wrapped response object.
+ * The default behavior of this method is to call setDateHeader(String name,
+ * long date) on the wrapped response object.
*/
public void setDateHeader(String name, long date) {
- this._getHttpServletResponse().setDateHeader(name, date);
+ this._getHttpServletResponse().setDateHeader(name, date);
}
-
+
/**
- * The default behavior of this method is to call addDateHeader(String name, long date)
- * on the wrapped response object.
+ * The default behavior of this method is to call addDateHeader(String name,
+ * long date) on the wrapped response object.
*/
- public void addDateHeader(String name, long date) {
- this._getHttpServletResponse().addDateHeader(name, date);
+ public void addDateHeader(String name, long date) {
+ this._getHttpServletResponse().addDateHeader(name, date);
}
-
+
/**
- * The default behavior of this method is to return setHeader(String name, String value)
- * on the wrapped response object.
+ * The default behavior of this method is to return setHeader(String name,
+ * String value) on the wrapped response object.
*/
public void setHeader(String name, String value) {
- this._getHttpServletResponse().setHeader(name, value);
+ this._getHttpServletResponse().setHeader(name, value);
}
-
+
/**
- * The default behavior of this method is to return addHeader(String name, String value)
- * on the wrapped response object.
+ * The default behavior of this method is to return addHeader(String name,
+ * String value) on the wrapped response object.
*/
- public void addHeader(String name, String value) {
- this._getHttpServletResponse().addHeader(name, value);
+ public void addHeader(String name, String value) {
+ this._getHttpServletResponse().addHeader(name, value);
}
-
+
/**
- * The default behavior of this method is to call setIntHeader(String name, int value)
- * on the wrapped response object.
+ * The default behavior of this method is to call setIntHeader(String name,
+ * int value) on the wrapped response object.
*/
public void setIntHeader(String name, int value) {
- this._getHttpServletResponse().setIntHeader(name, value);
+ this._getHttpServletResponse().setIntHeader(name, value);
}
-
+
/**
- * The default behavior of this method is to call addIntHeader(String name, int value)
- * on the wrapped response object.
+ * The default behavior of this method is to call addIntHeader(String name,
+ * int value) on the wrapped response object.
*/
public void addIntHeader(String name, int value) {
- this._getHttpServletResponse().addIntHeader(name, value);
+ this._getHttpServletResponse().addIntHeader(name, value);
}
/**
- * The default behavior of this method is to call setStatus(int sc)
- * on the wrapped response object.
+ * The default behavior of this method is to call setStatus(int sc) on the
+ * wrapped response object.
*/
-
-
public void setStatus(int sc) {
- this._getHttpServletResponse().setStatus(sc);
+ this._getHttpServletResponse().setStatus(sc);
}
-
+
/**
- * The default behavior of this method is to call setStatus(int sc, String sm)
- * on the wrapped response object.
+ * The default behavior of this method is to call setStatus(int sc, String
+ * sm) on the wrapped response object.
+ *
* @deprecated As of Version 3.0 of the Java Servlet API
*/
- @SuppressWarnings("dep-ann") // Spec API does not use @Deprecated
+ @SuppressWarnings("dep-ann")
+ // Spec API does not use @Deprecated
public void setStatus(int sc, String sm) {
- this._getHttpServletResponse().setStatus(sc, sm);
+ this._getHttpServletResponse().setStatus(sc, sm);
}
-
/**
- * @since Servlet 3.0
- * TODO SERVLET3 - Add comments
+ * @since Servlet 3.0 TODO SERVLET3 - Add comments
*/
public int getStatus() {
return this._getHttpServletResponse().getStatus();
}
-
/**
- * @since Servlet 3.0
- * TODO SERVLET3 - Add comments
+ * @since Servlet 3.0 TODO SERVLET3 - Add comments
*/
public String getHeader(String name) {
return this._getHttpServletResponse().getHeader(name);
}
-
/**
- * @since Servlet 3.0
- * TODO SERVLET3 - Add comments
+ * @since Servlet 3.0 TODO SERVLET3 - Add comments
*/
public Collection<String> getHeaders(String name) {
return this._getHttpServletResponse().getHeaders(name);
}
/**
- * @since Servlet 3.0
- * TODO SERVLET3 - Add comments
+ * @since Servlet 3.0 TODO SERVLET3 - Add comments
*/
public Collection<String> getHeaderNames() {
return this._getHttpServletResponse().getHeaderNames();
}
-
}
/*
-* Licensed to the Apache Software Foundation (ASF) under one or more
-* contributor license agreements. See the NOTICE file distributed with
-* this work for additional information regarding copyright ownership.
-* The ASF licenses this file to You under the Apache License, Version 2.0
-* (the "License"); you may not use this file except in compliance with
-* the License. You may obtain a copy of the License at
-*
-* http://www.apache.org/licenses/LICENSE-2.0
-*
-* Unless required by applicable law or agreed to in writing, software
-* distributed under the License is distributed on an "AS IS" BASIS,
-* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-* See the License for the specific language governing permissions and
-* limitations under the License.
-*/
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
package javax.servlet.http;
import java.util.Enumeration;
import javax.servlet.ServletContext;
/**
- *
- * Provides a way to identify a user across more than one page
- * request or visit to a Web site and to store information about that user.
- *
- * <p>The servlet container uses this interface to create a session
- * between an HTTP client and an HTTP server. The session persists
- * for a specified time period, across more than one connection or
- * page request from the user. A session usually corresponds to one
- * user, who may visit a site many times. The server can maintain a
- * session in many ways such as using cookies or rewriting URLs.
- *
- * <p>This interface allows servlets to
+ * Provides a way to identify a user across more than one page request or visit
+ * to a Web site and to store information about that user.
+ * <p>
+ * The servlet container uses this interface to create a session between an HTTP
+ * client and an HTTP server. The session persists for a specified time period,
+ * across more than one connection or page request from the user. A session
+ * usually corresponds to one user, who may visit a site many times. The server
+ * can maintain a session in many ways such as using cookies or rewriting URLs.
+ * <p>
+ * This interface allows servlets to
* <ul>
- * <li>View and manipulate information about a session, such as
- * the session identifier, creation time, and last accessed time
- * <li>Bind objects to sessions, allowing user information to persist
- * across multiple user connections
+ * <li>View and manipulate information about a session, such as the session
+ * identifier, creation time, and last accessed time
+ * <li>Bind objects to sessions, allowing user information to persist across
+ * multiple user connections
* </ul>
- *
- * <p>When an application stores an object in or removes an object from a
- * session, the session checks whether the object implements
- * {@link HttpSessionBindingListener}. If it does,
- * the servlet notifies the object that it has been bound to or unbound
- * from the session. Notifications are sent after the binding methods complete.
- * For session that are invalidated or expire, notifications are sent after
- * the session has been invalidated or expired.
- *
- * <p> When container migrates a session between VMs in a distributed container
- * setting, all session attributes implementing the {@link HttpSessionActivationListener}
- * interface are notified.
+ * <p>
+ * When an application stores an object in or removes an object from a session,
+ * the session checks whether the object implements
+ * {@link HttpSessionBindingListener}. If it does, the servlet notifies the
+ * object that it has been bound to or unbound from the session. Notifications
+ * are sent after the binding methods complete. For session that are invalidated
+ * or expire, notifications are sent after the session has been invalidated or
+ * expired.
+ * <p>
+ * When container migrates a session between VMs in a distributed container
+ * setting, all session attributes implementing the
+ * {@link HttpSessionActivationListener} interface are notified.
+ * <p>
+ * A servlet should be able to handle cases in which the client does not choose
+ * to join a session, such as when cookies are intentionally turned off. Until
+ * the client joins the session, <code>isNew</code> returns <code>true</code>.
+ * If the client chooses not to join the session, <code>getSession</code> will
+ * return a different session on each request, and <code>isNew</code> will
+ * always return <code>true</code>.
+ * <p>
+ * Session information is scoped only to the current web application (
+ * <code>ServletContext</code>), so information stored in one context will not
+ * be directly visible in another.
*
- * <p>A servlet should be able to handle cases in which
- * the client does not choose to join a session, such as when cookies are
- * intentionally turned off. Until the client joins the session,
- * <code>isNew</code> returns <code>true</code>. If the client chooses
- * not to join
- * the session, <code>getSession</code> will return a different session
- * on each request, and <code>isNew</code> will always return
- * <code>true</code>.
- *
- * <p>Session information is scoped only to the current web application
- * (<code>ServletContext</code>), so information stored in one context
- * will not be directly visible in another.
- *
- * @author Various
- * @version $Version$
- *
- *
- * @see HttpSessionBindingListener
- * @see HttpSessionContext
- *
+ * @author Various
+ * @version $Version$
+ * @see HttpSessionBindingListener
+ * @see HttpSessionContext
*/
-
public interface HttpSession {
-
-
-
/**
- *
- * Returns the time when this session was created, measured
- * in milliseconds since midnight January 1, 1970 GMT.
- *
- * @return a <code>long</code> specifying
- * when this session was created,
- * expressed in
- * milliseconds since 1/1/1970 GMT
- *
- * @exception IllegalStateException if this method is called on an
- * invalidated session
- *
+ * Returns the time when this session was created, measured in milliseconds
+ * since midnight January 1, 1970 GMT.
+ *
+ * @return a <code>long</code> specifying when this session was created,
+ * expressed in milliseconds since 1/1/1970 GMT
+ * @exception IllegalStateException
+ * if this method is called on an invalidated session
*/
-
public long getCreationTime();
-
-
-
-
+
/**
- *
- * Returns a string containing the unique identifier assigned
- * to this session. The identifier is assigned
- * by the servlet container and is implementation dependent.
+ * Returns a string containing the unique identifier assigned to this
+ * session. The identifier is assigned by the servlet container and is
+ * implementation dependent.
*
- * @return a string specifying the identifier
- * assigned to this session
- *
- * @exception IllegalStateException if this method is called on an
- * invalidated session
- *
+ * @return a string specifying the identifier assigned to this session
+ * @exception IllegalStateException
+ * if this method is called on an invalidated session
*/
-
public String getId();
-
-
-
/**
- *
- * Returns the last time the client sent a request associated with
- * this session, as the number of milliseconds since midnight
- * January 1, 1970 GMT, and marked by the time the container received the request.
- *
- * <p>Actions that your application takes, such as getting or setting
- * a value associated with the session, do not affect the access
- * time.
- *
- * @return a <code>long</code>
- * representing the last time
- * the client sent a request associated
- * with this session, expressed in
- * milliseconds since 1/1/1970 GMT
- *
- * @exception IllegalStateException if this method is called on an
- * invalidated session
- *
+ * Returns the last time the client sent a request associated with this
+ * session, as the number of milliseconds since midnight January 1, 1970
+ * GMT, and marked by the time the container received the request.
+ * <p>
+ * Actions that your application takes, such as getting or setting a value
+ * associated with the session, do not affect the access time.
+ *
+ * @return a <code>long</code> representing the last time the client sent a
+ * request associated with this session, expressed in milliseconds
+ * since 1/1/1970 GMT
+ * @exception IllegalStateException
+ * if this method is called on an invalidated session
*/
-
public long getLastAccessedTime();
-
-
- /**
- * Returns the ServletContext to which this session belongs.
- *
- * @return The ServletContext object for the web application
- * @since 2.3
- */
+ /**
+ * Returns the ServletContext to which this session belongs.
+ *
+ * @return The ServletContext object for the web application
+ * @since 2.3
+ */
public ServletContext getServletContext();
-
/**
- *
- * Specifies the time, in seconds, between client requests before the
- * servlet container will invalidate this session. A negative time
- * indicates the session should never timeout.
- *
- * @param interval An integer specifying the number
- * of seconds
- *
+ * Specifies the time, in seconds, between client requests before the
+ * servlet container will invalidate this session. A negative time indicates
+ * the session should never timeout.
+ *
+ * @param interval
+ * An integer specifying the number of seconds
*/
-
public void setMaxInactiveInterval(int interval);
-
-
-
- /**
- * Returns the maximum time interval, in seconds, that
- * the servlet container will keep this session open between
- * client accesses. After this interval, the servlet container
- * will invalidate the session. The maximum time interval can be set
- * with the <code>setMaxInactiveInterval</code> method.
- * A negative time indicates the session should never timeout.
- *
- *
- * @return an integer specifying the number of
- * seconds this session remains open
- * between client requests
- *
- * @see #setMaxInactiveInterval
- *
- *
- */
-
+ /**
+ * Returns the maximum time interval, in seconds, that the servlet container
+ * will keep this session open between client accesses. After this interval,
+ * the servlet container will invalidate the session. The maximum time
+ * interval can be set with the <code>setMaxInactiveInterval</code> method.
+ * A negative time indicates the session should never timeout.
+ *
+ * @return an integer specifying the number of seconds this session remains
+ * open between client requests
+ * @see #setMaxInactiveInterval
+ */
public int getMaxInactiveInterval();
-
-
-
- /**
- *
- * @deprecated As of Version 2.1, this method is
- * deprecated and has no replacement.
- * It will be removed in a future
- * version of the Java Servlet API.
- *
- */
- @SuppressWarnings("dep-ann") // Spec API does not use @Deprecated
+ /**
+ * @deprecated As of Version 2.1, this method is deprecated and has no
+ * replacement. It will be removed in a future version of the
+ * Java Servlet API.
+ */
+ @SuppressWarnings("dep-ann")
+ // Spec API does not use @Deprecated
public HttpSessionContext getSessionContext();
-
-
-
-
+
/**
- *
* Returns the object bound with the specified name in this session, or
* <code>null</code> if no object is bound under the name.
- *
- * @param name a string specifying the name of the object
- *
- * @return the object with the specified name
- *
- * @exception IllegalStateException if this method is called on an
- * invalidated session
- *
+ *
+ * @param name
+ * a string specifying the name of the object
+ * @return the object with the specified name
+ * @exception IllegalStateException
+ * if this method is called on an invalidated session
*/
-
public Object getAttribute(String name);
-
-
-
-
+
/**
- * @param name a string specifying the name of the object
- *
- * @return the object with the specified name
- *
- * @exception IllegalStateException if this method is called on an
- * invalidated session
- *
- * @deprecated As of Version 2.2, this method is
- * replaced by {@link #getAttribute}.
+ * @param name
+ * a string specifying the name of the object
+ * @return the object with the specified name
+ * @exception IllegalStateException
+ * if this method is called on an invalidated session
+ * @deprecated As of Version 2.2, this method is replaced by
+ * {@link #getAttribute}.
*/
- @SuppressWarnings("dep-ann") // Spec API does not use @Deprecated
+ @SuppressWarnings("dep-ann")
+ // Spec API does not use @Deprecated
public Object getValue(String name);
-
-
-
/**
- *
* Returns an <code>Enumeration</code> of <code>String</code> objects
- * containing the names of all the objects bound to this session.
- *
- * @return an <code>Enumeration</code> of
- * <code>String</code> objects specifying the
- * names of all the objects bound to
- * this session
- *
- * @exception IllegalStateException if this method is called on an
- * invalidated session
- *
+ * containing the names of all the objects bound to this session.
+ *
+ * @return an <code>Enumeration</code> of <code>String</code> objects
+ * specifying the names of all the objects bound to this session
+ * @exception IllegalStateException
+ * if this method is called on an invalidated session
*/
-
public Enumeration<String> getAttributeNames();
-
-
-
/**
- * @return an array of <code>String</code>
- * objects specifying the
- * names of all the objects bound to
- * this session
- *
- * @exception IllegalStateException if this method is called on an
- * invalidated session
- *
- * @deprecated As of Version 2.2, this method is
- * replaced by {@link #getAttributeNames}
+ * @return an array of <code>String</code> objects specifying the names of
+ * all the objects bound to this session
+ * @exception IllegalStateException
+ * if this method is called on an invalidated session
+ * @deprecated As of Version 2.2, this method is replaced by
+ * {@link #getAttributeNames}
*/
- @SuppressWarnings("dep-ann") // Spec API does not use @Deprecated
+ @SuppressWarnings("dep-ann")
+ // Spec API does not use @Deprecated
public String[] getValueNames();
-
-
-
/**
- * Binds an object to this session, using the name specified.
- * If an object of the same name is already bound to the session,
- * the object is replaced.
- *
- * <p>After this method executes, and if the new object
- * implements <code>HttpSessionBindingListener</code>,
- * the container calls
- * <code>HttpSessionBindingListener.valueBound</code>. The container then
- * notifies any <code>HttpSessionAttributeListener</code>s in the web
+ * Binds an object to this session, using the name specified. If an object
+ * of the same name is already bound to the session, the object is replaced.
+ * <p>
+ * After this method executes, and if the new object implements
+ * <code>HttpSessionBindingListener</code>, the container calls
+ * <code>HttpSessionBindingListener.valueBound</code>. The container then
+ * notifies any <code>HttpSessionAttributeListener</code>s in the web
* application.
-
- * <p>If an object was already bound to this session of this name
- * that implements <code>HttpSessionBindingListener</code>, its
+ * <p>
+ * If an object was already bound to this session of this name that
+ * implements <code>HttpSessionBindingListener</code>, its
* <code>HttpSessionBindingListener.valueUnbound</code> method is called.
- *
- * <p>If the value passed in is null, this has the same effect as calling
+ * <p>
+ * If the value passed in is null, this has the same effect as calling
* <code>removeAttribute()<code>.
- *
- *
- * @param name the name to which the object is bound;
- * cannot be null
- *
- * @param value the object to be bound
- *
- * @exception IllegalStateException if this method is called on an
- * invalidated session
- *
+ *
+ * @param name
+ * the name to which the object is bound; cannot be null
+ * @param value
+ * the object to be bound
+ * @exception IllegalStateException
+ * if this method is called on an invalidated session
*/
-
public void setAttribute(String name, Object value);
-
-
-
-
/**
- * @param name the name to which the object is bound;
- * cannot be null
- *
- * @param value the object to be bound; cannot be null
- *
- * @exception IllegalStateException if this method is called on an
- * invalidated session
- *
- * @deprecated As of Version 2.2, this method is
- * replaced by {@link #setAttribute}
+ * @param name
+ * the name to which the object is bound; cannot be null
+ * @param value
+ * the object to be bound; cannot be null
+ * @exception IllegalStateException
+ * if this method is called on an invalidated session
+ * @deprecated As of Version 2.2, this method is replaced by
+ * {@link #setAttribute}
*/
- @SuppressWarnings("dep-ann") // Spec API does not use @Deprecated
+ @SuppressWarnings("dep-ann")
+ // Spec API does not use @Deprecated
public void putValue(String name, Object value);
-
-
-
-
/**
- *
- * Removes the object bound with the specified name from
- * this session. If the session does not have an object
- * bound with the specified name, this method does nothing.
- *
- * <p>After this method executes, and if the object
- * implements <code>HttpSessionBindingListener</code>,
- * the container calls
- * <code>HttpSessionBindingListener.valueUnbound</code>. The container
- * then notifies any <code>HttpSessionAttributeListener</code>s in the web
+ * Removes the object bound with the specified name from this session. If
+ * the session does not have an object bound with the specified name, this
+ * method does nothing.
+ * <p>
+ * After this method executes, and if the object implements
+ * <code>HttpSessionBindingListener</code>, the container calls
+ * <code>HttpSessionBindingListener.valueUnbound</code>. The container then
+ * notifies any <code>HttpSessionAttributeListener</code>s in the web
* application.
*
- *
- *
- * @param name the name of the object to
- * remove from this session
- *
- * @exception IllegalStateException if this method is called on an
- * invalidated session
+ * @param name
+ * the name of the object to remove from this session
+ * @exception IllegalStateException
+ * if this method is called on an invalidated session
*/
-
public void removeAttribute(String name);
-
-
-
-
/**
- * @param name the name of the object to
- * remove from this session
- *
- * @exception IllegalStateException if this method is called on an
- * invalidated session
- *
- * @deprecated As of Version 2.2, this method is
- * replaced by {@link #removeAttribute}
+ * @param name
+ * the name of the object to remove from this session
+ * @exception IllegalStateException
+ * if this method is called on an invalidated session
+ * @deprecated As of Version 2.2, this method is replaced by
+ * {@link #removeAttribute}
*/
- @SuppressWarnings("dep-ann") // Spec API does not use @Deprecated
+ @SuppressWarnings("dep-ann")
+ // Spec API does not use @Deprecated
public void removeValue(String name);
-
-
-
/**
- *
- * Invalidates this session then unbinds any objects bound
- * to it.
- *
- * @exception IllegalStateException if this method is called on an
- * already invalidated session
- *
+ * Invalidates this session then unbinds any objects bound to it.
+ *
+ * @exception IllegalStateException
+ * if this method is called on an already invalidated session
*/
-
public void invalidate();
-
-
-
-
+
/**
- *
* Returns <code>true</code> if the client does not yet know about the
- * session or if the client chooses not to join the session. For
- * example, if the server used only cookie-based sessions, and
- * the client had disabled the use of cookies, then a session would
- * be new on each request.
- *
- * @return <code>true</code> if the
- * server has created a session,
- * but the client has not yet joined
- *
- * @exception IllegalStateException if this method is called on an
- * already invalidated session
- *
+ * session or if the client chooses not to join the session. For example, if
+ * the server used only cookie-based sessions, and the client had disabled
+ * the use of cookies, then a session would be new on each request.
+ *
+ * @return <code>true</code> if the server has created a session, but the
+ * client has not yet joined
+ * @exception IllegalStateException
+ * if this method is called on an already invalidated session
*/
-
public boolean isNew();
-
-
-
}
-
/*
-* Licensed to the Apache Software Foundation (ASF) under one or more
-* contributor license agreements. See the NOTICE file distributed with
-* this work for additional information regarding copyright ownership.
-* The ASF licenses this file to You under the Apache License, Version 2.0
-* (the "License"); you may not use this file except in compliance with
-* the License. You may obtain a copy of the License at
-*
-* http://www.apache.org/licenses/LICENSE-2.0
-*
-* Unless required by applicable law or agreed to in writing, software
-* distributed under the License is distributed on an "AS IS" BASIS,
-* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-* See the License for the specific language governing permissions and
-* limitations under the License.
-*/
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
package javax.servlet.http;
import java.util.EventListener;
- /** This listener interface can be implemented in order to
- * get notifications of changes to the attribute lists of sessions within
- * this web application.
- * @since v 2.3
-*/
-
+/**
+ * This listener interface can be implemented in order to get notifications of
+ * changes to the attribute lists of sessions within this web application.
+ *
+ * @since v 2.3
+ */
public interface HttpSessionAttributeListener extends EventListener {
- /** Notification that an attribute has been added to a session. Called after the attribute is added.*/
- public void attributeAdded ( HttpSessionBindingEvent se );
- /** Notification that an attribute has been removed from a session. Called after the attribute is removed. */
- public void attributeRemoved ( HttpSessionBindingEvent se );
- /** Notification that an attribute has been replaced in a session. Called after the attribute is replaced. */
- public void attributeReplaced ( HttpSessionBindingEvent se );
-}
+ /**
+ * Notification that an attribute has been added to a session. Called after
+ * the attribute is added.
+ */
+ public void attributeAdded(HttpSessionBindingEvent se);
+ /**
+ * Notification that an attribute has been removed from a session. Called
+ * after the attribute is removed.
+ */
+ public void attributeRemoved(HttpSessionBindingEvent se);
+
+ /**
+ * Notification that an attribute has been replaced in a session. Called
+ * after the attribute is replaced.
+ */
+ public void attributeReplaced(HttpSessionBindingEvent se);
+}
/*
-* Licensed to the Apache Software Foundation (ASF) under one or more
-* contributor license agreements. See the NOTICE file distributed with
-* this work for additional information regarding copyright ownership.
-* The ASF licenses this file to You under the Apache License, Version 2.0
-* (the "License"); you may not use this file except in compliance with
-* the License. You may obtain a copy of the License at
-*
-* http://www.apache.org/licenses/LICENSE-2.0
-*
-* Unless required by applicable law or agreed to in writing, software
-* distributed under the License is distributed on an "AS IS" BASIS,
-* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-* See the License for the specific language governing permissions and
-* limitations under the License.
-*/
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
package javax.servlet.http;
-
-
/**
- *
* Events of this type are either sent to an object that implements
- * {@link HttpSessionBindingListener} when it is bound or
- * unbound from a session, or to a {@link HttpSessionAttributeListener}
- * that has been configured in the deployment descriptor when any attribute is
- * bound, unbound or replaced in a session.
- *
- * <p>The session binds the object by a call to
- * <code>HttpSession.setAttribute</code> and unbinds the object
- * by a call to <code>HttpSession.removeAttribute</code>.
- *
- *
- *
- * @author Various
- * @version $Version$
+ * {@link HttpSessionBindingListener} when it is bound or unbound from a
+ * session, or to a {@link HttpSessionAttributeListener} that has been
+ * configured in the deployment descriptor when any attribute is bound, unbound
+ * or replaced in a session.
+ * <p>
+ * The session binds the object by a call to
+ * <code>HttpSession.setAttribute</code> and unbinds the object by a call to
+ * <code>HttpSession.removeAttribute</code>.
*
- * @see HttpSession
- * @see HttpSessionBindingListener
- * @see HttpSessionAttributeListener
+ * @author Various
+ * @version $Version$
+ * @see HttpSession
+ * @see HttpSessionBindingListener
+ * @see HttpSessionAttributeListener
*/
-
public class HttpSessionBindingEvent extends HttpSessionEvent {
-
-
-
/* The name to which the object is being bound or unbound */
private String name;
-
+
/* The object is being bound or unbound */
private Object value;
-
-
/**
- *
- * Constructs an event that notifies an object that it
- * has been bound to or unbound from a session.
- * To receive the event, the object must implement
+ * Constructs an event that notifies an object that it has been bound to or
+ * unbound from a session. To receive the event, the object must implement
* {@link HttpSessionBindingListener}.
- *
- *
- *
- * @param session the session to which the object is bound or unbound
- *
- * @param name the name with which the object is bound or unbound
- *
- * @see #getName
- * @see #getSession
- *
+ *
+ * @param session
+ * the session to which the object is bound or unbound
+ * @param name
+ * the name with which the object is bound or unbound
+ * @see #getName
+ * @see #getSession
*/
-
public HttpSessionBindingEvent(HttpSession session, String name) {
- super(session);
- this.name = name;
+ super(session);
+ this.name = name;
}
-
+
/**
- *
- * Constructs an event that notifies an object that it
- * has been bound to or unbound from a session.
- * To receive the event, the object must implement
+ * Constructs an event that notifies an object that it has been bound to or
+ * unbound from a session. To receive the event, the object must implement
* {@link HttpSessionBindingListener}.
- *
- *
- *
- * @param session the session to which the object is bound or unbound
- *
- * @param name the name with which the object is bound or unbound
- *
- * @see #getName
- * @see #getSession
- *
+ *
+ * @param session
+ * the session to which the object is bound or unbound
+ * @param name
+ * the name with which the object is bound or unbound
+ * @see #getName
+ * @see #getSession
*/
-
- public HttpSessionBindingEvent(HttpSession session, String name, Object value) {
- super(session);
- this.name = name;
- this.value = value;
+ public HttpSessionBindingEvent(HttpSession session, String name,
+ Object value) {
+ super(session);
+ this.name = name;
+ this.value = value;
}
-
-
- /** Return the session that changed. */
+
+ /** Return the session that changed. */
@Override
- public HttpSession getSession () {
- return super.getSession();
+ public HttpSession getSession() {
+ return super.getSession();
}
-
-
-
-
+
/**
- *
- * Returns the name with which the attribute is bound to or
- * unbound from the session.
- *
- *
- * @return a string specifying the name with which
- * the object is bound to or unbound from
- * the session
- *
- *
+ * Returns the name with which the attribute is bound to or unbound from the
+ * session.
+ *
+ * @return a string specifying the name with which the object is bound to or
+ * unbound from the session
*/
-
public String getName() {
- return name;
+ return name;
}
-
+
/**
- * Returns the value of the attribute that has been added, removed or replaced.
- * If the attribute was added (or bound), this is the value of the attribute. If the attribute was
- * removed (or unbound), this is the value of the removed attribute. If the attribute was replaced, this
- * is the old value of the attribute.
- *
- * @since 2.3
- */
-
- public Object getValue() {
- return this.value;
- }
-
+ * Returns the value of the attribute that has been added, removed or
+ * replaced. If the attribute was added (or bound), this is the value of the
+ * attribute. If the attribute was removed (or unbound), this is the value
+ * of the removed attribute. If the attribute was replaced, this is the old
+ * value of the attribute.
+ *
+ * @since 2.3
+ */
+ public Object getValue() {
+ return this.value;
+ }
}
-
-
-
-
-
-
-
/*
-* Licensed to the Apache Software Foundation (ASF) under one or more
-* contributor license agreements. See the NOTICE file distributed with
-* this work for additional information regarding copyright ownership.
-* The ASF licenses this file to You under the Apache License, Version 2.0
-* (the "License"); you may not use this file except in compliance with
-* the License. You may obtain a copy of the License at
-*
-* http://www.apache.org/licenses/LICENSE-2.0
-*
-* Unless required by applicable law or agreed to in writing, software
-* distributed under the License is distributed on an "AS IS" BASIS,
-* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-* See the License for the specific language governing permissions and
-* limitations under the License.
-*/
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
package javax.servlet.http;
import java.util.EventListener;
-
-
-
-
/**
- * Causes an object to be notified when it is bound to
- * or unbound from a session. The object is notified
- * by an {@link HttpSessionBindingEvent} object. This may be as a result
- * of a servlet programmer explicitly unbinding an attribute from a session,
- * due to a session being invalidated, or due to a session timing out.
- *
- *
- * @author Various
- * @version $Version$
- *
+ * Causes an object to be notified when it is bound to or unbound from a
+ * session. The object is notified by an {@link HttpSessionBindingEvent} object.
+ * This may be as a result of a servlet programmer explicitly unbinding an
+ * attribute from a session, due to a session being invalidated, or due to a
+ * session timing out.
+ *
+ * @author Various
+ * @version $Version$
* @see HttpSession
* @see HttpSessionBindingEvent
- *
*/
-
public interface HttpSessionBindingListener extends EventListener {
-
-
/**
- *
- * Notifies the object that it is being bound to
- * a session and identifies the session.
- *
- * @param event the event that identifies the
- * session
- *
+ * Notifies the object that it is being bound to a session and identifies
+ * the session.
+ *
+ * @param event
+ * the event that identifies the session
* @see #valueUnbound
- *
- */
-
+ */
public void valueBound(HttpSessionBindingEvent event);
-
-
/**
- *
- * Notifies the object that it is being unbound
- * from a session and identifies the session.
- *
- * @param event the event that identifies
- * the session
- *
+ * Notifies the object that it is being unbound from a session and
+ * identifies the session.
+ *
+ * @param event
+ * the event that identifies the session
* @see #valueBound
- *
*/
-
public void valueUnbound(HttpSessionBindingEvent event);
-
-
}
-
/*
-* Licensed to the Apache Software Foundation (ASF) under one or more
-* contributor license agreements. See the NOTICE file distributed with
-* this work for additional information regarding copyright ownership.
-* The ASF licenses this file to You under the Apache License, Version 2.0
-* (the "License"); you may not use this file except in compliance with
-* the License. You may obtain a copy of the License at
-*
-* http://www.apache.org/licenses/LICENSE-2.0
-*
-* Unless required by applicable law or agreed to in writing, software
-* distributed under the License is distributed on an "AS IS" BASIS,
-* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-* See the License for the specific language governing permissions and
-* limitations under the License.
-*/
-
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
package javax.servlet.http;
import java.util.Enumeration;
/**
- *
- * @author Various
- * @version $Version$
- *
- * @deprecated As of Java(tm) Servlet API 2.1
- * for security reasons, with no replacement.
- * This interface will be removed in a future
- * version of this API.
- *
- * @see HttpSession
- * @see HttpSessionBindingEvent
- * @see HttpSessionBindingListener
- *
+ * @author Various
+ * @version $Version$
+ * @deprecated As of Java(tm) Servlet API 2.1 for security reasons, with no
+ * replacement. This interface will be removed in a future version
+ * of this API.
+ * @see HttpSession
+ * @see HttpSessionBindingEvent
+ * @see HttpSessionBindingListener
*/
-@SuppressWarnings("dep-ann") // Spec API does not use @Deprecated
+@SuppressWarnings("dep-ann")
+// Spec API does not use @Deprecated
public interface HttpSessionContext {
/**
- *
- * @deprecated As of Java Servlet API 2.1 with
- * no replacement. This method must
- * return null and will be removed in
- * a future version of this API.
- *
+ * @deprecated As of Java Servlet API 2.1 with no replacement. This method
+ * must return null and will be removed in a future version of
+ * this API.
*/
- @SuppressWarnings("dep-ann") // Spec API does not use @Deprecated
+ @SuppressWarnings("dep-ann")
+ // Spec API does not use @Deprecated
public HttpSession getSession(String sessionId);
-
-
-
-
+
/**
- *
- * @deprecated As of Java Servlet API 2.1 with
- * no replacement. This method must return
- * an empty <code>Enumeration</code> and will be removed
- * in a future version of this API.
- *
+ * @deprecated As of Java Servlet API 2.1 with no replacement. This method
+ * must return an empty <code>Enumeration</code> and will be
+ * removed in a future version of this API.
*/
- @SuppressWarnings("dep-ann") // Spec API does not use @Deprecated
+ @SuppressWarnings("dep-ann")
+ // Spec API does not use @Deprecated
public Enumeration<String> getIds();
}
-
-
-
-
-
/*
-* Licensed to the Apache Software Foundation (ASF) under one or more
-* contributor license agreements. See the NOTICE file distributed with
-* this work for additional information regarding copyright ownership.
-* The ASF licenses this file to You under the Apache License, Version 2.0
-* (the "License"); you may not use this file except in compliance with
-* the License. You may obtain a copy of the License at
-*
-* http://www.apache.org/licenses/LICENSE-2.0
-*
-* Unless required by applicable law or agreed to in writing, software
-* distributed under the License is distributed on an "AS IS" BASIS,
-* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-* See the License for the specific language governing permissions and
-* limitations under the License.
-*/
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
package javax.servlet.http;
-
- /** This is the class representing event notifications for
- * changes to sessions within a web application.
- * @since v 2.3
- */
+/**
+ * This is the class representing event notifications for changes to sessions
+ * within a web application.
+ *
+ * @since v 2.3
+ */
public class HttpSessionEvent extends java.util.EventObject {
- /** Construct a session event from the given source.*/
- public HttpSessionEvent(HttpSession source) {
- super(source);
-}
- /** Return the session that changed.*/
- public HttpSession getSession () {
- return (HttpSession) super.getSource();
+ /** Construct a session event from the given source. */
+ public HttpSessionEvent(HttpSession source) {
+ super(source);
}
-}
+ /** Return the session that changed. */
+ public HttpSession getSession() {
+ return (HttpSession) super.getSource();
+ }
+}
/*
-* Licensed to the Apache Software Foundation (ASF) under one or more
-* contributor license agreements. See the NOTICE file distributed with
-* this work for additional information regarding copyright ownership.
-* The ASF licenses this file to You under the Apache License, Version 2.0
-* (the "License"); you may not use this file except in compliance with
-* the License. You may obtain a copy of the License at
-*
-* http://www.apache.org/licenses/LICENSE-2.0
-*
-* Unless required by applicable law or agreed to in writing, software
-* distributed under the License is distributed on an "AS IS" BASIS,
-* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-* See the License for the specific language governing permissions and
-* limitations under the License.
-*/
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
package javax.servlet.http;
import java.util.EventListener;
- /**
- * Implementations of this interface are notified of changes to the
- * list of active sessions in a web application.
- * To receive notification events, the implementation class
- * must be configured in the deployment descriptor for the web application.
- * @see HttpSessionEvent
- * @since v 2.3
- */
-
+/**
+ * Implementations of this interface are notified of changes to the list of
+ * active sessions in a web application. To receive notification events, the
+ * implementation class must be configured in the deployment descriptor for the
+ * web application.
+ *
+ * @see HttpSessionEvent
+ * @since v 2.3
+ */
public interface HttpSessionListener extends EventListener {
-
- /**
- * Notification that a session was created.
- * @param se the notification event
- */
- public void sessionCreated ( HttpSessionEvent se );
-
- /**
- * Notification that a session is about to be invalidated.
- * @param se the notification event
- */
- public void sessionDestroyed ( HttpSessionEvent se );
-
-}
+ /**
+ * Notification that a session was created.
+ *
+ * @param se
+ * the notification event
+ */
+ public void sessionCreated(HttpSessionEvent se);
+
+ /**
+ * Notification that a session is about to be invalidated.
+ *
+ * @param se
+ * the notification event
+ */
+ public void sessionDestroyed(HttpSessionEvent se);
+
+}
projects / tomcat7.0 / commitdiff