From 2bfe5e23a60e57f32642065f3450141df1ffb019 Mon Sep 17 00:00:00 2001 From: markt Date: Fri, 23 Jul 2010 15:48:53 +0000 Subject: [PATCH] Tab police: javax.servlet (remainder - not sub-packages) Thanks to Checkstyle and Eclipse source formatting git-svn-id: https://svn.apache.org/repos/asf/tomcat/trunk@967140 13f79535-47bb-0310-9956-ffa450edef68 --- java/javax/servlet/ServletConfig.java | 114 +- java/javax/servlet/ServletContext.java | 1117 ++++++++------------ .../servlet/ServletContextAttributeEvent.java | 103 +- .../servlet/ServletContextAttributeListener.java | 70 +- java/javax/servlet/ServletContextEvent.java | 77 +- java/javax/servlet/ServletContextListener.java | 79 +- java/javax/servlet/ServletException.java | 112 +- java/javax/servlet/ServletInputStream.java | 141 ++- java/javax/servlet/ServletOutputStream.java | 443 +++----- java/javax/servlet/ServletRequest.java | 835 ++++++--------- .../servlet/ServletRequestAttributeEvent.java | 98 +- java/javax/servlet/ServletRequestEvent.java | 78 +- java/javax/servlet/ServletRequestWrapper.java | 497 ++++----- java/javax/servlet/ServletResponse.java | 612 +++++------ java/javax/servlet/ServletResponseWrapper.java | 267 +++-- java/javax/servlet/SingleThreadModel.java | 78 +- java/javax/servlet/UnavailableException.java | 282 +++-- 17 files changed, 2096 insertions(+), 2907 deletions(-) diff --git a/java/javax/servlet/ServletConfig.java b/java/javax/servlet/ServletConfig.java index b0c385c4a..71301a0e1 100644 --- a/java/javax/servlet/ServletConfig.java +++ b/java/javax/servlet/ServletConfig.java @@ -1,95 +1,69 @@ /* -* 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; import java.util.Enumeration; - - /** - * - * A servlet configuration object used by a servlet container - * to pass information to a servlet during initialization. - * + * A servlet configuration object used by a servlet container to pass + * information to a servlet during initialization. */ - public interface ServletConfig { - /** - * Returns the name of this servlet instance. - * The name may be provided via server administration, assigned in the - * web application deployment descriptor, or for an unregistered (and thus - * unnamed) servlet instance it will be the servlet's class name. - * - * @return the name of the servlet instance - * - * - * + * Returns the name of this servlet instance. The name may be provided via + * server administration, assigned in the web application deployment + * descriptor, or for an unregistered (and thus unnamed) servlet instance it + * will be the servlet's class name. + * + * @return the name of the servlet instance */ - public String getServletName(); /** - * Returns a reference to the {@link ServletContext} in which the caller - * is executing. - * - * - * @return a {@link ServletContext} object, used - * by the caller to interact with its servlet - * container + * Returns a reference to the {@link ServletContext} in which the caller is + * executing. * - * @see ServletContext - * + * @return a {@link ServletContext} object, used by the caller to interact + * with its servlet container + * @see ServletContext */ - public ServletContext getServletContext(); - + /** - * Returns a String containing the value of the - * named initialization parameter, or null if - * the parameter does not exist. - * - * @param name a String specifying the name - * of the initialization parameter - * - * @return a String containing the value - * of the initialization parameter - * + * Returns a String containing the value of the named + * initialization parameter, or null if the parameter does not + * exist. + * + * @param name + * a String specifying the name of the + * initialization parameter + * @return a String containing the value of the initialization + * parameter */ - public String getInitParameter(String name); - /** - * Returns the names of the servlet's initialization parameters - * as an Enumeration of String objects, - * or an empty Enumeration if the servlet has - * no initialization parameters. - * - * @return an Enumeration of String - * objects containing the names of the servlet's - * initialization parameters - * - * - * + * Returns the names of the servlet's initialization parameters as an + * Enumeration of String objects, or an empty + * Enumeration if the servlet has no initialization parameters. + * + * @return an Enumeration of String objects + * containing the names of the servlet's initialization parameters */ - public Enumeration getInitParameterNames(); - - } diff --git a/java/javax/servlet/ServletContext.java b/java/javax/servlet/ServletContext.java index c6be08b6d..7f31c9208 100644 --- a/java/javax/servlet/ServletContext.java +++ b/java/javax/servlet/ServletContext.java @@ -1,19 +1,19 @@ /* -* 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; import java.io.InputStream; @@ -27,915 +27,686 @@ import java.util.Set; import javax.servlet.descriptor.JspConfigDescriptor; /** - * - * Defines a set of methods that a servlet uses to communicate with its - * servlet container, for example, to get the MIME type of a file, dispatch - * requests, or write to a log file. - * - *

There is one context per "web application" per Java Virtual Machine. (A + * Defines a set of methods that a servlet uses to communicate with its servlet + * container, for example, to get the MIME type of a file, dispatch requests, or + * write to a log file. + *

+ * There is one context per "web application" per Java Virtual Machine. (A * "web application" is a collection of servlets and content installed under a * specific subset of the server's URL namespace such as /catalog - * and possibly installed via a .war file.) - * - *

In the case of a web - * application marked "distributed" in its deployment descriptor, there will - * be one context instance for each virtual machine. In this situation, the - * context cannot be used as a location to share global information (because - * the information won't be truly global). Use an external resource like - * a database instead. - * - *

The ServletContext object is contained within - * the {@link ServletConfig} object, which the Web server provides the - * servlet when the servlet is initialized. - * - * @author Various - * @version $Version$ - * - * @see Servlet#getServletConfig - * @see ServletConfig#getServletContext - * + * and possibly installed via a .war file.) + *

+ * In the case of a web application marked "distributed" in its deployment + * descriptor, there will be one context instance for each virtual machine. In + * this situation, the context cannot be used as a location to share global + * information (because the information won't be truly global). Use an external + * resource like a database instead. + *

+ * The ServletContext object is contained within the + * {@link ServletConfig} object, which the Web server provides the servlet when + * the servlet is initialized. + * + * @author Various + * @version $Version$ + * @see Servlet#getServletConfig + * @see ServletConfig#getServletContext */ - public interface ServletContext { public static final String TEMPDIR = "javax.servlet.context.tempdir"; - + /** * @since Servlet 3.0 */ - public static final String ORDERED_LIBS = - "javax.servlet.context.orderedLibs"; + public static final String ORDERED_LIBS = "javax.servlet.context.orderedLibs"; /** - * Returns a ServletContext object that - * corresponds to a specified URL on the server. - * - *

This method allows servlets to gain - * access to the context for various parts of the server, and as - * needed obtain {@link RequestDispatcher} objects from the context. - * The given path must be begin with "/", is interpreted relative - * to the server's document root and is matched against the context roots of - * other web applications hosted on this container. + * Returns a ServletContext object that corresponds to a + * specified URL on the server. + *

+ * This method allows servlets to gain access to the context for various + * parts of the server, and as needed obtain {@link RequestDispatcher} + * objects from the context. The given path must be begin with "/", is + * interpreted relative to the server's document root and is matched against + * the context roots of other web applications hosted on this container. + *

+ * In a security conscious environment, the servlet container may return + * null for a given URL. * - *

In a security conscious environment, the servlet container may - * return null for a given URL. - * - * @param uripath a String specifying the context path of - * another web application in the container. - * @return the ServletContext object that - * corresponds to the named URL, or null if either - none exists or the container wishes to restrict - * this access. - * - * @see RequestDispatcher - * + * @param uripath + * a String specifying the context path of another + * web application in the container. + * @return the ServletContext object that corresponds to the + * named URL, or null if either none exists or the container wishes + * to restrict this access. + * @see RequestDispatcher */ - public ServletContext getContext(String uripath); - public String getContextPath(); - /** - * Returns the major version of the Java Servlet API that this - * servlet container supports. All implementations that comply - * with Version 3.0 must have this method - * return the integer 3. - * - * @return 3 - * + * Returns the major version of the Java Servlet API that this servlet + * container supports. All implementations that comply with Version 3.0 must + * have this method return the integer 3. + * + * @return 3 */ - public int getMajorVersion(); - - /** - * Returns the minor version of the Servlet API that this - * servlet container supports. All implementations that comply - * with Version 3.0 must have this method - * return the integer 0. - * - * @return 0 - * + * Returns the minor version of the Servlet API that this servlet container + * supports. All implementations that comply with Version 3.0 must have this + * method return the integer 0. + * + * @return 0 */ - public int getMinorVersion(); - + /** - * * @return * @throws UnsupportedOperationException - * @since Servlet 3.0 - * TODO SERVLET3 - Add comments + * @since Servlet 3.0 TODO SERVLET3 - Add comments */ public int getEffectiveMajorVersion(); - + /** - * * @return * @throws UnsupportedOperationException - * @since Servlet 3.0 - * TODO SERVLET3 - Add comments + * @since Servlet 3.0 TODO SERVLET3 - Add comments */ public int getEffectiveMinorVersion(); /** - * Returns the MIME type of the specified file, or null if - * the MIME type is not known. The MIME type is determined - * by the configuration of the servlet container, and may be specified - * in a web application deployment descriptor. Common MIME - * types are "text/html" and "image/gif". - * - * - * @param file a String specifying the name - * of a file - * - * @return a String specifying the file's MIME type - * + * Returns the MIME type of the specified file, or null if the + * MIME type is not known. The MIME type is determined by the configuration + * of the servlet container, and may be specified in a web application + * deployment descriptor. Common MIME types are "text/html" and + * "image/gif". + * + * @param file + * a String specifying the name of a file + * @return a String specifying the file's MIME type */ - public String getMimeType(String file); - - /** - * Returns a directory-like listing of all the paths to resources within the web application whose longest sub-path - * matches the supplied path argument. Paths indicating subdirectory paths end with a '/'. The returned paths are all - * relative to the root of the web application and have a leading '/'. For example, for a web application - * containing

- - * /welcome.html
- * /catalog/index.html
- * /catalog/products.html
- * /catalog/offers/books.html
- * /catalog/offers/music.html
- * /customer/login.jsp
- * /WEB-INF/web.xml
- * /WEB-INF/classes/com.acme.OrderServlet.class,

- * - * getResourcePaths("/") returns {"/welcome.html", "/catalog/", "/customer/", "/WEB-INF/"}
- * getResourcePaths("/catalog/") returns {"/catalog/index.html", "/catalog/products.html", "/catalog/offers/"}.
- - - - *@param path the partial path used to match the resources, - * which must start with a / - *@return a Set containing the directory listing, or null if there are no resources in the web application whose path - * begins with the supplied path. - - * @since Servlet 2.3 - */ - + + /** + * Returns a directory-like listing of all the paths to resources within the + * web application whose longest sub-path matches the supplied path + * argument. Paths indicating subdirectory paths end with a '/'. The + * returned paths are all relative to the root of the web application and + * have a leading '/'. For example, for a web application containing
+ *
+ * /welcome.html
+ * /catalog/index.html
+ * /catalog/products.html
+ * /catalog/offers/books.html
+ * /catalog/offers/music.html
+ * /customer/login.jsp
+ * /WEB-INF/web.xml
+ * /WEB-INF/classes/com.acme.OrderServlet.class,
+ *
+ * getResourcePaths("/") returns {"/welcome.html", "/catalog/", + * "/customer/", "/WEB-INF/"}
+ * getResourcePaths("/catalog/") returns {"/catalog/index.html", + * "/catalog/products.html", "/catalog/offers/"}.
+ * + * @param path + * the partial path used to match the resources, which must start + * with a / + * @return a Set containing the directory listing, or null if there are no + * resources in the web application whose path begins with the + * supplied path. + * @since Servlet 2.3 + */ public Set getResourcePaths(String path); - - - - /** - * Returns a URL to the resource that is mapped to a specified - * path. The path must begin with a "/" and is interpreted - * as relative to the current context root. - * - *

This method allows the servlet container to make a resource - * available to servlets from any source. Resources - * can be located on a local or remote - * file system, in a database, or in a .war file. - * - *

The servlet container must implement the URL handlers - * and URLConnection objects that are necessary - * to access the resource. - * - *

This method returns null - * if no resource is mapped to the pathname. - * - *

Some containers may allow writing to the URL returned by - * this method using the methods of the URL class. - * - *

The resource content is returned directly, so be aware that - * requesting a .jsp page returns the JSP source code. - * Use a RequestDispatcher instead to include results of - * an execution. - * - *

This method has a different purpose than - * java.lang.Class.getResource, - * which looks up resources based on a class loader. This - * method does not use class loaders. + + /** + * Returns a URL to the resource that is mapped to a specified path. The + * path must begin with a "/" and is interpreted as relative to the current + * context root. + *

+ * This method allows the servlet container to make a resource available to + * servlets from any source. Resources can be located on a local or remote + * file system, in a database, or in a .war file. + *

+ * The servlet container must implement the URL handlers and + * URLConnection objects that are necessary to access the + * resource. + *

+ * This method returns null if no resource is mapped to the + * pathname. + *

+ * Some containers may allow writing to the URL returned by this method + * using the methods of the URL class. + *

+ * The resource content is returned directly, so be aware that requesting a + * .jsp page returns the JSP source code. Use a + * RequestDispatcher instead to include results of an + * execution. + *

+ * This method has a different purpose than + * java.lang.Class.getResource, which looks up resources based + * on a class loader. This method does not use class loaders. * - * @param path a String specifying - * the path to the resource - * - * @return the resource located at the named path, - * or null if there is no resource - * at that path - * - * @exception MalformedURLException if the pathname is not given in - * the correct form - * - */ - + * @param path + * a String specifying the path to the resource + * @return the resource located at the named path, or null if + * there is no resource at that path + * @exception MalformedURLException + * if the pathname is not given in the correct form + */ public URL getResource(String path) throws MalformedURLException; - - - - /** - * Returns the resource located at the named path as - * an InputStream object. - * - *

The data in the InputStream can be - * of any type or length. The path must be specified according - * to the rules given in getResource. - * This method returns null if no resource exists at - * the specified path. - * - *

Meta-information such as content length and content type - * that is available via getResource - * method is lost when using this method. - * - *

The servlet container must implement the URL handlers - * and URLConnection objects necessary to access - * the resource. - * - *

This method is different from - * java.lang.Class.getResourceAsStream, - * which uses a class loader. This method allows servlet containers - * to make a resource available - * to a servlet from any location, without using a class loader. + + /** + * Returns the resource located at the named path as an + * InputStream object. + *

+ * The data in the InputStream can be of any type or length. + * The path must be specified according to the rules given in + * getResource. This method returns null if no + * resource exists at the specified path. + *

+ * Meta-information such as content length and content type that is + * available via getResource method is lost when using this + * method. + *

+ * The servlet container must implement the URL handlers and + * URLConnection objects necessary to access the resource. + *

+ * This method is different from + * java.lang.Class.getResourceAsStream, which uses a class + * loader. This method allows servlet containers to make a resource + * available to a servlet from any location, without using a class loader. * - * - * @param path a String specifying the path - * to the resource - * - * @return the InputStream returned to the - * servlet, or null if no resource - * exists at the specified path - * - * + * @param path + * a String specifying the path to the resource + * @return the InputStream returned to the servlet, or + * null if no resource exists at the specified path */ - public InputStream getResourceAsStream(String path); - - - /** - * - * Returns a {@link RequestDispatcher} object that acts - * as a wrapper for the resource located at the given path. - * A RequestDispatcher object can be used to forward - * a request to the resource or to include the resource in a response. - * The resource can be dynamic or static. - * - *

The pathname must begin with a "/" and is interpreted as relative - * to the current context root. Use getContext to obtain - * a RequestDispatcher for resources in foreign contexts. - * This method returns null if the ServletContext + * Returns a {@link RequestDispatcher} object that acts as a wrapper for the + * resource located at the given path. A RequestDispatcher + * object can be used to forward a request to the resource or to include the + * resource in a response. The resource can be dynamic or static. + *

+ * The pathname must begin with a "/" and is interpreted as relative to the + * current context root. Use getContext to obtain a + * RequestDispatcher for resources in foreign contexts. This + * method returns null if the ServletContext * cannot return a RequestDispatcher. - * - * @param path a String specifying the pathname - * to the resource - * - * @return a RequestDispatcher object - * that acts as a wrapper for the resource - * at the specified path, or null if - * the ServletContext cannot return - * a RequestDispatcher - * - * @see RequestDispatcher - * @see ServletContext#getContext - * + * + * @param path + * a String specifying the pathname to the resource + * @return a RequestDispatcher object that acts as a wrapper for + * the resource at the specified path, or null if the + * ServletContext cannot return a + * RequestDispatcher + * @see RequestDispatcher + * @see ServletContext#getContext */ - public RequestDispatcher getRequestDispatcher(String path); - - /** - * Returns a {@link RequestDispatcher} object that acts - * as a wrapper for the named servlet. - * - *

Servlets (and JSP pages also) may be given names via server - * administration or via a web application deployment descriptor. - * A servlet instance can determine its name using + * Returns a {@link RequestDispatcher} object that acts as a wrapper for the + * named servlet. + *

+ * Servlets (and JSP pages also) may be given names via server + * administration or via a web application deployment descriptor. A servlet + * instance can determine its name using * {@link ServletConfig#getServletName}. - * - *

This method returns null if the - * ServletContext + *

+ * This method returns null if the ServletContext * cannot return a RequestDispatcher for any reason. - * - * @param name a String specifying the name - * of a servlet to wrap - * - * @return a RequestDispatcher object - * that acts as a wrapper for the named servlet, - * or null if the ServletContext - * cannot return a RequestDispatcher - * - * @see RequestDispatcher - * @see ServletContext#getContext - * @see ServletConfig#getServletName - * + * + * @param name + * a String specifying the name of a servlet to wrap + * @return a RequestDispatcher object that acts as a wrapper for + * the named servlet, or null if the + * ServletContext cannot return a + * RequestDispatcher + * @see RequestDispatcher + * @see ServletContext#getContext + * @see ServletConfig#getServletName */ - public RequestDispatcher getNamedDispatcher(String name); - - - - - /** - * - * @deprecated As of Java Servlet API 2.1, with no direct replacement. - * - *

This method was originally defined to retrieve a servlet - * from a ServletContext. In this version, this method - * always returns null and remains only to preserve - * binary compatibility. This method will be permanently removed - * in a future version of the Java Servlet API. - * - *

In lieu of this method, servlets can share information using the - * ServletContext class and can perform shared business logic - * by invoking methods on common non-servlet classes. - * + + /** + * @deprecated As of Java Servlet API 2.1, with no direct replacement. + *

+ * This method was originally defined to retrieve a servlet from + * a ServletContext. In this version, this method + * always returns null and remains only to preserve + * binary compatibility. This method will be permanently removed + * in a future version of the Java Servlet API. + *

+ * In lieu of this method, servlets can share information using + * the ServletContext class and can perform shared + * business logic by invoking methods on common non-servlet + * classes. * @deprecated */ - @SuppressWarnings("dep-ann") // Spec API does not use @Deprecated + @SuppressWarnings("dep-ann") + // Spec API does not use @Deprecated public Servlet getServlet(String name) throws ServletException; - - - - - - - /** - * - * @deprecated As of Java Servlet API 2.0, with no replacement. - * - *

This method was originally defined to return an Enumeration - * of all the servlets known to this servlet context. In this - * version, this method always returns an empty enumeration and - * remains only to preserve binary compatibility. This method - * will be permanently removed in a future version of the Java - * Servlet API. - * + + /** + * @deprecated As of Java Servlet API 2.0, with no replacement. + *

+ * This method was originally defined to return an + * Enumeration of all the servlets known to this + * servlet context. In this version, this method always returns + * an empty enumeration and remains only to preserve binary + * compatibility. This method will be permanently removed in a + * future version of the Java Servlet API. * @deprecated */ - @SuppressWarnings("dep-ann") // Spec API does not use @Deprecated + @SuppressWarnings("dep-ann") + // Spec API does not use @Deprecated public Enumeration getServlets(); - - - - - - - /** - * @deprecated As of Java Servlet API 2.1, with no replacement. - * - *

This method was originally defined to return an - * Enumeration - * of all the servlet names known to this context. In this version, - * this method always returns an empty Enumeration and - * remains only to preserve binary compatibility. This method will - * be permanently removed in a future version of the Java Servlet API. - * + + /** + * @deprecated As of Java Servlet API 2.1, with no replacement. + *

+ * This method was originally defined to return an + * Enumeration of all the servlet names known to + * this context. In this version, this method always returns an + * empty Enumeration and remains only to preserve + * binary compatibility. This method will be permanently removed + * in a future version of the Java Servlet API. * @deprecated */ - @SuppressWarnings("dep-ann") // Spec API does not use @Deprecated + @SuppressWarnings("dep-ann") + // Spec API does not use @Deprecated public Enumeration getServletNames(); - - - - - - /** - * - * Writes the specified message to a servlet log file, usually - * an event log. The name and type of the servlet log file is - * specific to the servlet container. - * - * - * @param msg a String specifying the - * message to be written to the log file - * - */ - - public void log(String msg); - - - - - - /** - * @deprecated As of Java Servlet API 2.1, use - * {@link #log(String message, Throwable throwable)} - * instead. - * - *

This method was originally defined to write an - * exception's stack trace and an explanatory error message - * to the servlet log file. + + /** + * Writes the specified message to a servlet log file, usually an event log. + * The name and type of the servlet log file is specific to the servlet + * container. * + * @param msg + * a String specifying the message to be written to + * the log file + */ + public void log(String msg); + + /** + * @deprecated As of Java Servlet API 2.1, use + * {@link #log(String message, Throwable throwable)} instead. + *

+ * This method was originally defined to write an exception's + * stack trace and an explanatory error message to the servlet + * log file. * @deprecated */ - @SuppressWarnings("dep-ann") // Spec API does not use @Deprecated + @SuppressWarnings("dep-ann") + // Spec API does not use @Deprecated public void log(Exception exception, String msg); - - - - - - /** - * Writes an explanatory message and a stack trace - * for a given Throwable exception - * to the servlet log file. The name and type of the servlet log - * file is specific to the servlet container, usually an event log. - * - * - * @param message a String that - * describes the error or exception - * - * @param throwable the Throwable error - * or exception - * - */ - - public void log(String message, Throwable throwable); - - - - - - /** - * Returns a String containing the real path - * for a given virtual path. For example, the path "/index.html" - * returns the absolute file path on the server's filesystem would be - * served by a request for "http://host/contextPath/index.html", - * where contextPath is the context path of this ServletContext.. - * - *

The real path returned will be in a form - * appropriate to the computer and operating system on - * which the servlet container is running, including the - * proper path separators. This method returns null - * if the servlet container cannot translate the virtual path - * to a real path for any reason (such as when the content is - * being made available from a .war archive). - * - * - * @param path a String specifying a virtual path - * - * - * @return a String specifying the real path, - * or null if the translation cannot be performed - * - * + + /** + * Writes an explanatory message and a stack trace for a given + * Throwable exception to the servlet log file. The name and + * type of the servlet log file is specific to the servlet container, + * usually an event log. + * + * @param message + * a String that describes the error or exception + * @param throwable + * the Throwable error or exception */ + public void log(String message, Throwable throwable); + /** + * Returns a String containing the real path for a given + * virtual path. For example, the path "/index.html" returns the absolute + * file path on the server's filesystem would be served by a request for + * "http://host/contextPath/index.html", where contextPath is the context + * path of this ServletContext.. + *

+ * The real path returned will be in a form appropriate to the computer and + * operating system on which the servlet container is running, including the + * proper path separators. This method returns null if the + * servlet container cannot translate the virtual path to a real path for + * any reason (such as when the content is being made available from a + * .war archive). + * + * @param path + * a String specifying a virtual path + * @return a String specifying the real path, or null if the + * translation cannot be performed + */ public String getRealPath(String path); - - - /** - * Returns the name and version of the servlet container on which - * the servlet is running. - * - *

The form of the returned string is - * servername/versionnumber. - * For example, the JavaServer Web Development Kit may return the string + * Returns the name and version of the servlet container on which the + * servlet is running. + *

+ * The form of the returned string is + * servername/versionnumber. For example, the JavaServer Web + * Development Kit may return the string * JavaServer Web Dev Kit/1.0. - * - *

The servlet container may return other optional information - * after the primary string in parentheses, for example, + *

+ * The servlet container may return other optional information after the + * primary string in parentheses, for example, * JavaServer Web Dev Kit/1.0 (JDK 1.1.6; Windows NT 4.0 x86). - * - * - * @return a String containing at least the - * servlet container name and version number - * + * + * @return a String containing at least the servlet container + * name and version number */ - public String getServerInfo(); - - - /** * Returns a String containing the value of the named - * context-wide initialization parameter, or null if the + * context-wide initialization parameter, or null if the * parameter does not exist. - * - *

This method can make available configuration information useful - * to an entire "web application". For example, it can provide a - * webmaster's email address or the name of a system that holds - * critical data. - * - * @param name a String containing the name of the - * parameter whose value is requested + *

+ * This method can make available configuration information useful to an + * entire "web application". For example, it can provide a webmaster's email + * address or the name of a system that holds critical data. * - * @return a String containing at least the - * servlet container name and version number - * + * @param name + * a String containing the name of the parameter + * whose value is requested + * @return a String containing at least the servlet container + * name and version number * @see ServletConfig#getInitParameter */ - public String getInitParameter(String name); - - - /** * Returns the names of the context's initialization parameters as an - * Enumeration of String objects, or an - * empty Enumeration if the context has no initialization - * parameters. - * - * @return an Enumeration of String - * objects containing the names of the context's - * initialization parameters - * + * Enumeration of String objects, or an empty + * Enumeration if the context has no initialization parameters. + * + * @return an Enumeration of String objects + * containing the names of the context's initialization parameters * @see ServletConfig#getInitParameter */ public Enumeration getInitParameterNames(); - - + /** - * * @param name * @param value * @return * @throws IllegalStateException * @throws UnsupportedOperationException - * @since Servlet 3.0 - * TODO SERVLET3 - Add comments + * @since Servlet 3.0 TODO SERVLET3 - Add comments */ public boolean setInitParameter(String name, String value); - - - /** - * Returns the servlet container attribute with the given name, - * or null if there is no attribute by that name. - * An attribute allows a servlet container to give the - * servlet additional information not - * already provided by this interface. See your - * server documentation for information about its attributes. - * A list of supported attributes can be retrieved using - * getAttributeNames. - * - *

The attribute is returned as a java.lang.Object - * or some subclass. - * Attribute names should follow the same convention as package - * names. The Java Servlet API specification reserves names - * matching java.*, javax.*, - * and sun.*. - * - * - * @param name a String specifying the name - * of the attribute - * - * @return an Object containing the value - * of the attribute, or null - * if no attribute exists matching the given - * name - * - * @see ServletContext#getAttributeNames - * - */ - - public Object getAttribute(String name); - - - /** - * Returns an Enumeration containing the - * attribute names available - * within this servlet context. Use the - * {@link #getAttribute} method with an attribute name - * to get the value of an attribute. - * - * @return an Enumeration of attribute - * names - * - * @see #getAttribute - * + * Returns the servlet container attribute with the given name, or + * null if there is no attribute by that name. An attribute + * allows a servlet container to give the servlet additional information not + * already provided by this interface. See your server documentation for + * information about its attributes. A list of supported attributes can be + * retrieved using getAttributeNames. + *

+ * The attribute is returned as a java.lang.Object or some + * subclass. Attribute names should follow the same convention as package + * names. The Java Servlet API specification reserves names matching + * java.*, javax.*, and sun.*. + * + * @param name + * a String specifying the name of the attribute + * @return an Object containing the value of the attribute, or + * null if no attribute exists matching the given name + * @see ServletContext#getAttributeNames */ + public Object getAttribute(String name); + /** + * Returns an Enumeration containing the attribute names + * available within this servlet context. Use the {@link #getAttribute} + * method with an attribute name to get the value of an attribute. + * + * @return an Enumeration of attribute names + * @see #getAttribute + */ public Enumeration getAttributeNames(); - - - - - /** - * - * Binds an object to a given attribute name in this servlet context. If - * the name specified is already used for an attribute, this - * method will replace the attribute with the new to the new attribute. - *

If listeners are configured on the ServletContext the + + /** + * Binds an object to a given attribute name in this servlet context. If the + * name specified is already used for an attribute, this method will replace + * the attribute with the new to the new attribute. + *

+ * If listeners are configured on the ServletContext the * container notifies them accordingly. *

- * If a null value is passed, the effect is the same as calling + * If a null value is passed, the effect is the same as calling * removeAttribute(). + *

+ * Attribute names should follow the same convention as package names. The + * Java Servlet API specification reserves names matching + * java.*, javax.*, and sun.*. * - *

Attribute names should follow the same convention as package - * names. The Java Servlet API specification reserves names - * matching java.*, javax.*, and - * sun.*. - * - * - * @param name a String specifying the name - * of the attribute - * - * @param object an Object representing the - * attribute to be bound - * - * - * - */ - + * @param name + * a String specifying the name of the attribute + * @param object + * an Object representing the attribute to be bound + */ public void setAttribute(String name, Object object); - - - - /** - * Removes the attribute with the given name from - * the servlet context. After removal, subsequent calls to - * {@link #getAttribute} to retrieve the attribute's value - * will return null. - - *

If listeners are configured on the ServletContext the + * Removes the attribute with the given name from the servlet context. After + * removal, subsequent calls to {@link #getAttribute} to retrieve the + * attribute's value will return null. + *

+ * If listeners are configured on the ServletContext the * container notifies them accordingly. - - * - * - * @param name a String specifying the name - * of the attribute to be removed - * + * + * @param name + * a String specifying the name of the attribute to + * be removed */ - public void removeAttribute(String name); - + /** - * Returns the name of this web application corresponding to this ServletContext as specified in the deployment - * descriptor for this web application by the display-name element. - * - * - * @return The name of the web application or null if no name has been declared in the deployment descriptor. + * Returns the name of this web application corresponding to this + * ServletContext as specified in the deployment descriptor for this web + * application by the display-name element. + * + * @return The name of the web application or null if no name has been + * declared in the deployment descriptor. * @since Servlet 2.3 */ - public String getServletContextName(); - /** - * * @param servletName * @param className - * @throws IllegalStateException If the context has already been - * initialised - * @since Servlet 3.0 - * TODO SERVLET3 - Add comments + * @throws IllegalStateException + * If the context has already been initialised + * @since Servlet 3.0 TODO SERVLET3 - Add comments */ public ServletRegistration.Dynamic addServlet(String servletName, String className); - - + /** - * * @param servletName * @param servlet - * @throws IllegalStateException If the context has already been - * initialised - * @since Servlet 3.0 - * TODO SERVLET3 - Add comments + * @throws IllegalStateException + * If the context has already been initialised + * @since Servlet 3.0 TODO SERVLET3 - Add comments */ public ServletRegistration.Dynamic addServlet(String servletName, Servlet servlet); - - + /** - * * @param servletName * @param servletClass - * @throws IllegalStateException If the context has already been - * initialised - * @since Servlet 3.0 - * TODO SERVLET3 - Add comments + * @throws IllegalStateException + * If the context has already been initialised + * @since Servlet 3.0 TODO SERVLET3 - Add comments */ public ServletRegistration.Dynamic addServlet(String servletName, Class servletClass); - /** - * * @param c * @return * @throws ServletException - * @since Servlet 3.0 - * TODO SERVLET3 - Add comments + * @since Servlet 3.0 TODO SERVLET3 - Add comments */ public T createServlet(Class c) - throws ServletException; + throws ServletException; - /** - * * @param servletName * @return * @throws UnsupportedOperationException - * @since Servlet 3.0 - * TODO SERVLET3 - Add comments + * @since Servlet 3.0 TODO SERVLET3 - Add comments */ public ServletRegistration getServletRegistration(String servletName); - - + /** - * * @return * @throws UnsupportedOperationException - * @since Servlet 3.0 - * TODO SERVLET3 - Add comments + * @since Servlet 3.0 TODO SERVLET3 - Add comments */ public Map getServletRegistrations(); - /** - * * @param filterName * @param className - * @throws IllegalStateException If the context has already been - * initialised - * - * @since Servlet 3.0 - * TODO SERVLET3 - Add comments + * @throws IllegalStateException + * If the context has already been initialised + * @since Servlet 3.0 TODO SERVLET3 - Add comments */ - public FilterRegistration.Dynamic addFilter(String filterName, + public FilterRegistration.Dynamic addFilter(String filterName, String className); - - + /** - * * @param filterName * @param filter - * @throws IllegalStateException If the context has already been - * initialised - * - * @since Servlet 3.0 - * TODO SERVLET3 - Add comments + * @throws IllegalStateException + * If the context has already been initialised + * @since Servlet 3.0 TODO SERVLET3 - Add comments */ - public FilterRegistration.Dynamic addFilter(String filterName, - Filter filter); + public FilterRegistration.Dynamic addFilter(String filterName, Filter filter); - /** - * * @param filterName * @param filterClass - * @throws IllegalStateException If the context has already been - * initialised - * - * @since Servlet 3.0 - * TODO SERVLET3 - Add comments + * @throws IllegalStateException + * If the context has already been initialised + * @since Servlet 3.0 TODO SERVLET3 - Add comments */ - public FilterRegistration.Dynamic addFilter(String filterName, + public FilterRegistration.Dynamic addFilter(String filterName, Class filterClass); - /** - * * @param c * @return * @throws ServletException - * @since Servlet 3.0 - * TODO SERVLET3 - Add comments + * @since Servlet 3.0 TODO SERVLET3 - Add comments */ public T createFilter(Class c) - throws ServletException; + throws ServletException; - /** - * * @param filterName * @return * @throws UnsupportedOperationException - * @since Servlet 3.0 - * TODO SERVLET3 - Add comments + * @since Servlet 3.0 TODO SERVLET3 - Add comments */ public FilterRegistration getFilterRegistration(String filterName); /** - * * @return * @throws UnsupportedOperationException - * @since Servlet 3.0 - * TODO SERVLET3 - Add comments + * @since Servlet 3.0 TODO SERVLET3 - Add comments */ public Map getFilterRegistrations(); /** - * * @return * @throws UnsupportedOperationException - * @since Servlet 3.0 - * TODO SERVLET3 - Add comments + * @since Servlet 3.0 TODO SERVLET3 - Add comments */ public SessionCookieConfig getSessionCookieConfig(); /** - * * @param sessionTrackingModes - * @throws IllegalArgumentException If sessionTrackingModes specifies - * {@link SessionTrackingMode#SSL} in - * combination with any other - * {@link SessionTrackingMode} - * @throws IllegalStateException If the context has already been - * initialised + * @throws IllegalArgumentException + * If sessionTrackingModes specifies + * {@link SessionTrackingMode#SSL} in combination with any other + * {@link SessionTrackingMode} + * @throws IllegalStateException + * If the context has already been initialised * @throws UnsupportedOperationException - * @since Servlet 3.0 - * TODO SERVLET3 - Add comments + * @since Servlet 3.0 TODO SERVLET3 - Add comments */ public void setSessionTrackingModes( Set sessionTrackingModes) throws IllegalStateException, IllegalArgumentException; - + /** - * * @return - * @since Servlet 3.0 - * TODO SERVLET3 - Add comments + * @since Servlet 3.0 TODO SERVLET3 - Add comments */ public Set getDefaultSessionTrackingModes(); - + /** - * * @return - * @since Servlet 3.0 - * TODO SERVLET3 - Add comments + * @since Servlet 3.0 TODO SERVLET3 - Add comments */ public Set getEffectiveSessionTrackingModes(); - + /** - * * @param listenerClass - * @since Servlet 3.0 - * TODO SERVLET3 - Add comments + * @since Servlet 3.0 TODO SERVLET3 - Add comments */ - public void addListener(Class listenerClass); - + public void addListener(Class listenerClass); + /** - * * @param className - * @since Servlet 3.0 - * TODO SERVLET3 - Add comments + * @since Servlet 3.0 TODO SERVLET3 - Add comments */ public void addListener(String className); /** - * * @param * @param t - * @since Servlet 3.0 - * TODO SERVLET3 - Add comments + * @since Servlet 3.0 TODO SERVLET3 - Add comments */ public void addListener(T t); - + /** - * * @param * @param c * @return * @throws ServletException - * @since Servlet 3.0 - * TODO SERVLET3 - Add comments + * @since Servlet 3.0 TODO SERVLET3 - Add comments */ public T createListener(Class c) - throws ServletException; - + throws ServletException; + /** - * * @param roleNames * @throws UnsupportedOperationException * @throws IllegalArgumentException * @throws IllegalStateException - * @since Servlet 3.0 - * TODO SERVLET3 - Add comments + * @since Servlet 3.0 TODO SERVLET3 - Add comments */ public void declareRoles(String... roleNames); - + /** - * * @return * @throws UnsupportedOperationException * @throws SecurityException - * @since Servlet 3.0 - * TODO SERVLET3 - Add comments + * @since Servlet 3.0 TODO SERVLET3 - Add comments */ public ClassLoader getClassLoader(); - + /** - * * @return * @throws UnsupportedOperationException - * @since Servlet 3.0 - * TODO SERVLET3 - Add comments + * @since Servlet 3.0 TODO SERVLET3 - Add comments */ public JspConfigDescriptor getJspConfigDescriptor(); } diff --git a/java/javax/servlet/ServletContextAttributeEvent.java b/java/javax/servlet/ServletContextAttributeEvent.java index 2ae493674..2660602b1 100644 --- a/java/javax/servlet/ServletContextAttributeEvent.java +++ b/java/javax/servlet/ServletContextAttributeEvent.java @@ -1,60 +1,57 @@ /* -* 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; +/** + * This is the event class for notifications about changes to the attributes of + * the servlet context of a web application. + * + * @see ServletContextAttributeListener + * @since v 2.3 + */ +public class ServletContextAttributeEvent extends ServletContextEvent { + private String name; + private Object value; - /** - * This is the event class for notifications about changes to the attributes of the - * servlet context of a web application. - * @see ServletContextAttributeListener - * @since v 2.3 - */ + /** + * Construct a ServletContextAttributeEvent from the given context for the + * given attribute name and attribute value. + */ + public ServletContextAttributeEvent(ServletContext source, String name, + Object value) { + super(source); + this.name = name; + this.value = value; + } -public class ServletContextAttributeEvent extends ServletContextEvent { - private String name; - private Object value; + /** + * Return the name of the attribute that changed on the ServletContext. + */ + public String getName() { + return this.name; + } - /** Construct a ServletContextAttributeEvent from the given context for the - ** given attribute name and attribute value. - */ - public ServletContextAttributeEvent(ServletContext source, String name, Object value) { - super(source); - this.name = name; - this.value = value; - } - - /** - * Return the name of the attribute that changed on the ServletContext. - * - */ - public String getName() { - return this.name; - } - - /** - * Returns the value of the attribute that has been added, removed, or replaced. - * If the attribute was added, this is the value of the attribute. If the attribute was - * removed, this is the value of the removed attribute. If the attribute was replaced, this - * is the old value of the attribute. - * - */ - - public Object getValue() { - return this.value; - } + /** + * Returns the value of the attribute that has been added, removed, or + * replaced. If the attribute was added, this is the value of the attribute. + * If the attribute was removed, this is the value of the removed attribute. + * If the attribute was replaced, this is the old value of the attribute. + */ + public Object getValue() { + return this.value; + } } - diff --git a/java/javax/servlet/ServletContextAttributeListener.java b/java/javax/servlet/ServletContextAttributeListener.java index fcb5575f0..886413559 100644 --- a/java/javax/servlet/ServletContextAttributeListener.java +++ b/java/javax/servlet/ServletContextAttributeListener.java @@ -1,37 +1,49 @@ /* -* 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; import java.util.EventListener; - /** Implementations of this interface receive notifications of - ** changes to the attribute list on the servlet context of a web application. - * To receive notification events, the implementation class - * must be configured in the deployment descriptor for the web application. - * @see ServletContextAttributeEvent - * @since v 2.3 - */ +/** + * Implementations of this interface receive notifications of changes to the + * attribute list on the servlet context of a web application. To receive + * notification events, the implementation class must be configured in the + * deployment descriptor for the web application. + * + * @see ServletContextAttributeEvent + * @since v 2.3 + */ public interface ServletContextAttributeListener extends EventListener { - /** Notification that a new attribute was added to the servlet context. Called after the attribute is added.*/ -public void attributeAdded(ServletContextAttributeEvent scab); - /** Notification that an existing attribute has been removed from the servlet context. Called after the attribute is removed.*/ -public void attributeRemoved(ServletContextAttributeEvent scab); - /** Notification that an attribute on the servlet context has been replaced. Called after the attribute is replaced. */ -public void attributeReplaced(ServletContextAttributeEvent scab); -} + /** + * Notification that a new attribute was added to the servlet context. + * Called after the attribute is added. + */ + public void attributeAdded(ServletContextAttributeEvent scab); + + /** + * Notification that an existing attribute has been removed from the servlet + * context. Called after the attribute is removed. + */ + public void attributeRemoved(ServletContextAttributeEvent scab); + /** + * Notification that an attribute on the servlet context has been replaced. + * Called after the attribute is replaced. + */ + public void attributeReplaced(ServletContextAttributeEvent scab); +} diff --git a/java/javax/servlet/ServletContextEvent.java b/java/javax/servlet/ServletContextEvent.java index 713759656..9793f2f82 100644 --- a/java/javax/servlet/ServletContextEvent.java +++ b/java/javax/servlet/ServletContextEvent.java @@ -1,47 +1,46 @@ /* -* 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; +/** + * This is the event class for notifications about changes to the servlet + * context of a web application. + * + * @see ServletContextListener + * @since v 2.3 + */ +public class ServletContextEvent extends java.util.EventObject { - /** - * This is the event class for notifications about changes to - * the servlet context of a web application. - * @see ServletContextListener - * @since v 2.3 - */ - -public class ServletContextEvent extends java.util.EventObject { - - /** Construct a ServletContextEvent from the given context. - * - * @param source - the ServletContext that is sending the event. - */ + /** + * Construct a ServletContextEvent from the given context. + * + * @param source + * - the ServletContext that is sending the event. + */ public ServletContextEvent(ServletContext source) { - super(source); + super(source); } - - /** - * Return the ServletContext that changed. - * - * @return the ServletContext that sent the event. - */ - public ServletContext getServletContext () { - return (ServletContext) super.getSource(); + + /** + * Return the ServletContext that changed. + * + * @return the ServletContext that sent the event. + */ + public ServletContext getServletContext() { + return (ServletContext) super.getSource(); } - } - diff --git a/java/javax/servlet/ServletContextListener.java b/java/javax/servlet/ServletContextListener.java index e4b01641c..e78019923 100644 --- a/java/javax/servlet/ServletContextListener.java +++ b/java/javax/servlet/ServletContextListener.java @@ -1,51 +1,46 @@ /* -* 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; import java.util.EventListener; - /** - * Implementations of this interface receive notifications about - * changes to the servlet context of the web application they are - * part of. - * To receive notification events, the implementation class - * must be configured in the deployment descriptor for the web - * application. - * @see ServletContextEvent - * @since v 2.3 - */ +/** + * Implementations of this interface receive notifications about changes to the + * servlet context of the web application they are part of. To receive + * notification events, the implementation class must be configured in the + * deployment descriptor for the web application. + * + * @see ServletContextEvent + * @since v 2.3 + */ public interface ServletContextListener extends EventListener { - /** - ** Notification that the web application initialization - ** process is starting. - ** All ServletContextListeners are notified of context - ** initialization before any filter or servlet in the web - ** application is initialized. - */ + + /** + ** Notification that the web application initialization process is starting. + * All ServletContextListeners are notified of context initialization before + * any filter or servlet in the web application is initialized. + */ + public void contextInitialized(ServletContextEvent sce); - public void contextInitialized ( ServletContextEvent sce ); - - /** - ** Notification that the servlet context is about to be shut down. - ** All servlets and filters have been destroy()ed before any - ** ServletContextListeners are notified of context - ** destruction. - */ - public void contextDestroyed ( ServletContextEvent sce ); + /** + ** Notification that the servlet context is about to be shut down. All + * servlets and filters have been destroy()ed before any + * ServletContextListeners are notified of context destruction. + */ + public void contextDestroyed(ServletContextEvent sce); } - diff --git a/java/javax/servlet/ServletException.java b/java/javax/servlet/ServletException.java index 5de0d1bb6..cf35694fa 100644 --- a/java/javax/servlet/ServletException.java +++ b/java/javax/servlet/ServletException.java @@ -1,28 +1,27 @@ /* -* 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; - /** - * Defines a general exception a servlet can throw when it - * encounters difficulty. - * - * @author Various - * @version $Version$ + * Defines a general exception a servlet can throw when it encounters + * difficulty. + * + * @author Various + * @version $Version$ */ public class ServletException extends Exception { @@ -34,53 +33,49 @@ public class ServletException extends Exception { } /** - * Constructs a new servlet exception with the - * specified message. The message can be written - * to the server log and/or displayed for the user. - * - * @param message a String - * specifying the text of - * the exception message + * Constructs a new servlet exception with the specified message. The + * message can be written to the server log and/or displayed for the user. + * + * @param message + * a String specifying the text of the exception + * message */ public ServletException(String message) { super(message); } /** - * Constructs a new servlet exception when the servlet - * needs to throw an exception and include a message - * about the "root cause" exception that interfered with its - * normal operation, including a description message. - * - * @param message a String containing - * the text of the exception message - * - * @param rootCause the Throwable exception - * that interfered with the servlet's - * normal operation, making this servlet - * exception necessary + * Constructs a new servlet exception when the servlet needs to throw an + * exception and include a message about the "root cause" exception that + * interfered with its normal operation, including a description message. + * + * @param message + * a String containing the text of the exception + * message + * @param rootCause + * the Throwable exception that interfered with the + * servlet's normal operation, making this servlet exception + * necessary */ public ServletException(String message, Throwable rootCause) { super(message, rootCause); } /** - * Constructs a new servlet exception when the servlet - * needs to throw an exception and include a message - * about the "root cause" exception that interfered with its - * normal operation. The exception's message is based on the localized - * message of the underlying exception. - * - *

This method calls the getLocalizedMessage method - * on the Throwable exception to get a localized exception - * message. When subclassing ServletException, - * this method can be overridden to create an exception message - * designed for a specific locale. - * - * @param rootCause the Throwable exception - * that interfered with the servlet's - * normal operation, making the servlet exception - * necessary + * Constructs a new servlet exception when the servlet needs to throw an + * exception and include a message about the "root cause" exception that + * interfered with its normal operation. The exception's message is based on + * the localized message of the underlying exception. + *

+ * This method calls the getLocalizedMessage method on the + * Throwable exception to get a localized exception message. + * When subclassing ServletException, this method can be + * overridden to create an exception message designed for a specific locale. + * + * @param rootCause + * the Throwable exception that interfered with the + * servlet's normal operation, making the servlet exception + * necessary */ public ServletException(Throwable rootCause) { super(rootCause); @@ -88,9 +83,8 @@ public class ServletException extends Exception { /** * Returns the exception that caused this servlet exception. - * - * @return the Throwable - * that caused this servlet exception + * + * @return the Throwable that caused this servlet exception */ public Throwable getRootCause() { return getCause(); diff --git a/java/javax/servlet/ServletInputStream.java b/java/javax/servlet/ServletInputStream.java index d004a3a24..e54543094 100644 --- a/java/javax/servlet/ServletInputStream.java +++ b/java/javax/servlet/ServletInputStream.java @@ -1,107 +1,84 @@ /* -* 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; import java.io.InputStream; import java.io.IOException; /** + * Provides an input stream for reading binary data from a client request, + * including an efficient readLine method for reading data one line + * at a time. With some protocols, such as HTTP POST and PUT, a + * ServletInputStream object can be used to read data sent from the + * client. + *

+ * A ServletInputStream object is normally retrieved via the + * {@link ServletRequest#getInputStream} method. + *

+ * This is an abstract class that a servlet container implements. Subclasses of + * this class must implement the java.io.InputStream.read() method. * - * Provides an input stream for reading binary data from a client - * request, including an efficient readLine method - * for reading data one line at a time. With some protocols, such - * as HTTP POST and PUT, a ServletInputStream - * object can be used to read data sent from the client. - * - *

A ServletInputStream object is normally retrieved via - * the {@link ServletRequest#getInputStream} method. - * - * - *

This is an abstract class that a servlet container implements. - * Subclasses of this class - * must implement the java.io.InputStream.read() method. - * - * - * @author Various - * @version $Version$ - * - * @see ServletRequest - * + * @author Various + * @version $Version$ + * @see ServletRequest */ - public abstract class ServletInputStream extends InputStream { - - /** * Does nothing, because this is an abstract class. - * */ protected ServletInputStream() { // NOOP } - - - /** - * - * Reads the input stream, one line at a time. Starting at an - * offset, reads bytes into an array, until it reads a certain number - * of bytes or reaches a newline character, which it reads into the - * array as well. - * - *

This method returns -1 if it reaches the end of the input - * stream before reading the maximum number of bytes. - * - * - * - * @param b an array of bytes into which data is read - * - * @param off an integer specifying the character at which - * this method begins reading - * - * @param len an integer specifying the maximum number of - * bytes to read - * - * @return an integer specifying the actual number of bytes - * read, or -1 if the end of the stream is reached - * - * @exception IOException if an input or output exception has occurred - * + * Reads the input stream, one line at a time. Starting at an offset, reads + * bytes into an array, until it reads a certain number of bytes or reaches + * a newline character, which it reads into the array as well. + *

+ * This method returns -1 if it reaches the end of the input stream before + * reading the maximum number of bytes. + * + * @param b + * an array of bytes into which data is read + * @param off + * an integer specifying the character at which this method + * begins reading + * @param len + * an integer specifying the maximum number of bytes to read + * @return an integer specifying the actual number of bytes read, or -1 if + * the end of the stream is reached + * @exception IOException + * if an input or output exception has occurred */ - public int readLine(byte[] b, int off, int len) throws IOException { - if (len <= 0) { - return 0; - } - int count = 0, c; + if (len <= 0) { + return 0; + } + int count = 0, c; - while ((c = read()) != -1) { - b[off++] = (byte)c; - count++; - if (c == '\n' || count == len) { - break; - } - } - return count > 0 ? count : -1; + while ((c = read()) != -1) { + b[off++] = (byte) c; + count++; + if (c == '\n' || count == len) { + break; + } + } + return count > 0 ? count : -1; } } - - - diff --git a/java/javax/servlet/ServletOutputStream.java b/java/javax/servlet/ServletOutputStream.java index 6d8fb18c2..c000eb729 100644 --- a/java/javax/servlet/ServletOutputStream.java +++ b/java/javax/servlet/ServletOutputStream.java @@ -1,19 +1,19 @@ /* -* 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; import java.io.OutputStream; @@ -23,343 +23,252 @@ import java.text.MessageFormat; import java.util.ResourceBundle; /** - * Provides an output stream for sending binary data to the - * client. A ServletOutputStream object is normally retrieved - * via the {@link ServletResponse#getOutputStream} method. - * - *

This is an abstract class that the servlet container implements. - * Subclasses of this class - * must implement the java.io.OutputStream.write(int) + * Provides an output stream for sending binary data to the client. A + * ServletOutputStream object is normally retrieved via the + * {@link ServletResponse#getOutputStream} method. + *

+ * This is an abstract class that the servlet container implements. Subclasses + * of this class must implement the java.io.OutputStream.write(int) * method. - * * - * @author Various - * @version $Version$ - * - * @see ServletResponse - * + * @author Various + * @version $Version$ + * @see ServletResponse */ - public abstract class ServletOutputStream extends OutputStream { private static final String LSTRING_FILE = "javax.servlet.LocalStrings"; - private static final ResourceBundle lStrings = - ResourceBundle.getBundle(LSTRING_FILE); + private static final ResourceBundle lStrings = ResourceBundle.getBundle(LSTRING_FILE); - - /** - * * Does nothing, because this is an abstract class. - * */ protected ServletOutputStream() { // NOOP } - /** - * Writes a String to the client, - * without a carriage return-line feed (CRLF) - * character at the end. - * - * - * @param s the String to send to the client - * - * @exception IOException if an input or output exception occurred - * + * Writes a String to the client, without a carriage + * return-line feed (CRLF) character at the end. + * + * @param s + * the String to send to the client + * @exception IOException + * if an input or output exception occurred */ - public void print(String s) throws IOException { - if (s==null) s="null"; - int len = s.length(); - for (int i = 0; i < len; i++) { - char c = s.charAt (i); - - // - // XXX NOTE: This is clearly incorrect for many strings, - // but is the only consistent approach within the current - // servlet framework. It must suffice until servlet output - // streams properly encode their output. - // - if ((c & 0xff00) != 0) { // high order byte must be zero - String errMsg = lStrings.getString("err.not_iso8859_1"); - Object[] errArgs = new Object[1]; - errArgs[0] = new Character(c); - errMsg = MessageFormat.format(errMsg, errArgs); - throw new CharConversionException(errMsg); - } - write (c); - } + if (s == null) + s = "null"; + int len = s.length(); + for (int i = 0; i < len; i++) { + char c = s.charAt(i); + + // + // XXX NOTE: This is clearly incorrect for many strings, + // but is the only consistent approach within the current + // servlet framework. It must suffice until servlet output + // streams properly encode their output. + // + if ((c & 0xff00) != 0) { // high order byte must be zero + String errMsg = lStrings.getString("err.not_iso8859_1"); + Object[] errArgs = new Object[1]; + errArgs[0] = new Character(c); + errMsg = MessageFormat.format(errMsg, errArgs); + throw new CharConversionException(errMsg); + } + write(c); + } } - - /** - * Writes a boolean value to the client, - * with no carriage return-line feed (CRLF) - * character at the end. - * - * @param b the boolean value - * to send to the client - * - * @exception IOException if an input or output exception occurred - * + * Writes a boolean value to the client, with no carriage + * return-line feed (CRLF) character at the end. + * + * @param b + * the boolean value to send to the client + * @exception IOException + * if an input or output exception occurred */ - public void print(boolean b) throws IOException { - String msg; - if (b) { - msg = lStrings.getString("value.true"); - } else { - msg = lStrings.getString("value.false"); - } - print(msg); + String msg; + if (b) { + msg = lStrings.getString("value.true"); + } else { + msg = lStrings.getString("value.false"); + } + print(msg); } - - /** - * Writes a character to the client, - * with no carriage return-line feed (CRLF) - * at the end. - * - * @param c the character to send to the client - * - * @exception IOException if an input or output exception occurred - * + * Writes a character to the client, with no carriage return-line feed + * (CRLF) at the end. + * + * @param c + * the character to send to the client + * @exception IOException + * if an input or output exception occurred */ - public void print(char c) throws IOException { - print(String.valueOf(c)); + print(String.valueOf(c)); } - - - /** - * - * Writes an int to the client, - * with no carriage return-line feed (CRLF) - * at the end. - * - * @param i the int to send to the client - * - * @exception IOException if an input or output exception occurred - * - */ - + * Writes an int to the client, with no carriage return-line feed (CRLF) at + * the end. + * + * @param i + * the int to send to the client + * @exception IOException + * if an input or output exception occurred + */ public void print(int i) throws IOException { - print(String.valueOf(i)); + print(String.valueOf(i)); } - - - /** + * Writes a long value to the client, with no carriage + * return-line feed (CRLF) at the end. * - * Writes a long value to the client, - * with no carriage return-line feed (CRLF) at the end. - * - * @param l the long value - * to send to the client - * - * @exception IOException if an input or output exception - * occurred - * + * @param l + * the long value to send to the client + * @exception IOException + * if an input or output exception occurred */ - public void print(long l) throws IOException { - print(String.valueOf(l)); + print(String.valueOf(l)); } - - /** - * - * Writes a float value to the client, - * with no carriage return-line feed (CRLF) at the end. - * - * @param f the float value - * to send to the client - * - * @exception IOException if an input or output exception occurred - * - * + * Writes a float value to the client, with no carriage + * return-line feed (CRLF) at the end. + * + * @param f + * the float value to send to the client + * @exception IOException + * if an input or output exception occurred */ - public void print(float f) throws IOException { - print(String.valueOf(f)); + print(String.valueOf(f)); } - - /** - * - * Writes a double value to the client, - * with no carriage return-line feed (CRLF) at the end. + * Writes a double value to the client, with no carriage + * return-line feed (CRLF) at the end. * - * @param d the double value - * to send to the client - * - * @exception IOException if an input or output exception occurred - * + * @param d + * the double value to send to the client + * @exception IOException + * if an input or output exception occurred */ - public void print(double d) throws IOException { - print(String.valueOf(d)); + print(String.valueOf(d)); } - - /** - * Writes a carriage return-line feed (CRLF) - * to the client. - * - * - * - * @exception IOException if an input or output exception occurred - * + * Writes a carriage return-line feed (CRLF) to the client. + * + * @exception IOException + * if an input or output exception occurred */ - public void println() throws IOException { - print("\r\n"); + print("\r\n"); } - - /** - * Writes a String to the client, - * followed by a carriage return-line feed (CRLF). - * - * - * @param s the String to write to the client - * - * @exception IOException if an input or output exception occurred - * + * Writes a String to the client, followed by a carriage + * return-line feed (CRLF). + * + * @param s + * the String to write to the client + * @exception IOException + * if an input or output exception occurred */ - public void println(String s) throws IOException { - print(s); - println(); + print(s); + println(); } - - - /** - * - * Writes a boolean value to the client, - * followed by a - * carriage return-line feed (CRLF). - * - * - * @param b the boolean value - * to write to the client - * - * @exception IOException if an input or output exception occurred - * + * Writes a boolean value to the client, followed by a carriage + * return-line feed (CRLF). + * + * @param b + * the boolean value to write to the client + * @exception IOException + * if an input or output exception occurred */ - public void println(boolean b) throws IOException { - print(b); - println(); + print(b); + println(); } - - /** - * - * Writes a character to the client, followed by a carriage - * return-line feed (CRLF). - * - * @param c the character to write to the client - * - * @exception IOException if an input or output exception occurred - * + * Writes a character to the client, followed by a carriage return-line feed + * (CRLF). + * + * @param c + * the character to write to the client + * @exception IOException + * if an input or output exception occurred */ - public void println(char c) throws IOException { - print(c); - println(); + print(c); + println(); } - - /** - * - * Writes an int to the client, followed by a - * carriage return-line feed (CRLF) character. - * - * - * @param i the int to write to the client - * - * @exception IOException if an input or output exception occurred - * + * Writes an int to the client, followed by a carriage return-line feed + * (CRLF) character. + * + * @param i + * the int to write to the client + * @exception IOException + * if an input or output exception occurred */ - public void println(int i) throws IOException { - print(i); - println(); + print(i); + println(); } - - - /** - * - * Writes a long value to the client, followed by a - * carriage return-line feed (CRLF). - * - * - * @param l the long value to write to the client - * - * @exception IOException if an input or output exception occurred - * - */ - + /** + * Writes a long value to the client, followed by a carriage + * return-line feed (CRLF). + * + * @param l + * the long value to write to the client + * @exception IOException + * if an input or output exception occurred + */ public void println(long l) throws IOException { - print(l); - println(); + print(l); + println(); } - - /** - * - * Writes a float value to the client, - * followed by a carriage return-line feed (CRLF). - * - * @param f the float value - * to write to the client - * - * - * @exception IOException if an input or output exception - * occurred - * + * Writes a float value to the client, followed by a carriage + * return-line feed (CRLF). + * + * @param f + * the float value to write to the client + * @exception IOException + * if an input or output exception occurred */ - public void println(float f) throws IOException { - print(f); - println(); + print(f); + println(); } - - /** - * - * Writes a double value to the client, - * followed by a carriage return-line feed (CRLF). - * - * - * @param d the double value - * to write to the client - * - * @exception IOException if an input or output exception occurred - * + * Writes a double value to the client, followed by a carriage + * return-line feed (CRLF). + * + * @param d + * the double value to write to the client + * @exception IOException + * if an input or output exception occurred */ - public void println(double d) throws IOException { - print(d); - println(); + print(d); + println(); } } diff --git a/java/javax/servlet/ServletRequest.java b/java/javax/servlet/ServletRequest.java index 6f3c63348..0a2ff5f9c 100644 --- a/java/javax/servlet/ServletRequest.java +++ b/java/javax/servlet/ServletRequest.java @@ -1,19 +1,19 @@ /* -* 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; import java.io.BufferedReader; @@ -22,637 +22,456 @@ import java.util.Enumeration; import java.util.Locale; import java.util.Map; - - /** - * Defines an object to provide client request information to a servlet. The - * servlet container creates a ServletRequest object and passes - * it as an argument to the servlet's service method. - * - *

A ServletRequest object provides data including - * parameter name and values, attributes, and an input stream. - * Interfaces that extend ServletRequest can provide - * additional protocol-specific data (for example, HTTP data is - * provided by {@link javax.servlet.http.HttpServletRequest}. + * Defines an object to provide client request information to a servlet. The + * servlet container creates a ServletRequest object and passes it + * as an argument to the servlet's service method. + *

+ * A ServletRequest object provides data including parameter name + * and values, attributes, and an input stream. Interfaces that extend + * ServletRequest can provide additional protocol-specific data + * (for example, HTTP data is provided by + * {@link javax.servlet.http.HttpServletRequest}. * - * @author Various - * @version $Version$ - * - * @see javax.servlet.http.HttpServletRequest - * + * @author Various + * @version $Version$ + * @see javax.servlet.http.HttpServletRequest */ - public interface ServletRequest { - - - /** - * - * Returns the value of the named attribute as an Object, - * or null if no attribute of the given name exists. - * - *

Attributes can be set two ways. The servlet container may set - * attributes to make available custom information about a request. - * For example, for requests made using HTTPS, the attribute + * Returns the value of the named attribute as an Object, or + * null if no attribute of the given name exists. + *

+ * Attributes can be set two ways. The servlet container may set attributes + * to make available custom information about a request. For example, for + * requests made using HTTPS, the attribute * javax.servlet.request.X509Certificate can be used to - * retrieve information on the certificate of the client. Attributes - * can also be set programatically using - * {@link ServletRequest#setAttribute}. This allows information to be - * embedded into a request before a {@link RequestDispatcher} call. - * - *

Attribute names should follow the same conventions as package - * names. This specification reserves names matching java.*, - * javax.*, and sun.*. - * - * @param name a String specifying the name of - * the attribute - * - * @return an Object containing the value - * of the attribute, or null if - * the attribute does not exist - * + * retrieve information on the certificate of the client. Attributes can + * also be set programatically using {@link ServletRequest#setAttribute}. + * This allows information to be embedded into a request before a + * {@link RequestDispatcher} call. + *

+ * Attribute names should follow the same conventions as package names. This + * specification reserves names matching java.*, + * javax.*, and sun.*. + * + * @param name + * a String specifying the name of the attribute + * @return an Object containing the value of the attribute, or + * null if the attribute does not exist */ - public Object getAttribute(String name); - - /** - * Returns an Enumeration containing the - * names of the attributes available to this request. - * This method returns an empty Enumeration - * if the request has no attributes available to it. + * Returns an Enumeration containing the names of the + * attributes available to this request. This method returns an empty + * Enumeration if the request has no attributes available to + * it. * - * - * @return an Enumeration of strings - * containing the names - * of the request's attributes - * + * @return an Enumeration of strings containing the names of the + * request's attributes */ - public Enumeration getAttributeNames(); - - - - + /** * Returns the name of the character encoding used in the body of this - * request. This method returns null if the request - * does not specify a character encoding + * request. This method returns null if the request does not + * specify a character encoding * - * - * @return a String containing the name of - * the character encoding, or null - * if the request does not specify a character encoding - * + * @return a String containing the name of the character + * encoding, or null if the request does not specify a + * character encoding */ - public String getCharacterEncoding(); - /** + /** * Overrides the name of the character encoding used in the body of this * request. This method must be called prior to reading request parameters * or reading input using getReader(). * - * - * @param env a String containing the name of - * the character encoding. - * @throws java.io.UnsupportedEncodingException if this is not a valid encoding + * @param env + * a String containing the name of the character + * encoding. + * @throws java.io.UnsupportedEncodingException + * if this is not a valid encoding */ + public void setCharacterEncoding(String env) + throws java.io.UnsupportedEncodingException; - public void setCharacterEncoding(String env) throws java.io.UnsupportedEncodingException; - - - - - /** - * Returns the length, in bytes, of the request body - * and made available by the input stream, or -1 if the - * length is not known. For HTTP servlets, same as the value - * of the CGI variable CONTENT_LENGTH. - * - * @return an integer containing the length of the - * request body or -1 if the length is not known - * + * Returns the length, in bytes, of the request body and made available by + * the input stream, or -1 if the length is not known. For HTTP servlets, + * same as the value of the CGI variable CONTENT_LENGTH. + * + * @return an integer containing the length of the request body or -1 if the + * length is not known */ - public int getContentLength(); - - - /** - * Returns the MIME type of the body of the request, or - * null if the type is not known. For HTTP servlets, - * same as the value of the CGI variable CONTENT_TYPE. - * - * @return a String containing the name - * of the MIME type of - * the request, or null if the type is not known - * + * Returns the MIME type of the body of the request, or null if + * the type is not known. For HTTP servlets, same as the value of the CGI + * variable CONTENT_TYPE. + * + * @return a String containing the name of the MIME type of the + * request, or null if the type is not known */ - public String getContentType(); - - - - - /** - * Retrieves the body of the request as binary data using - * a {@link ServletInputStream}. Either this method or - * {@link #getReader} may be called to read the body, not both. - * - * @return a {@link ServletInputStream} object containing - * the body of the request - * - * @exception IllegalStateException if the {@link #getReader} method - * has already been called for this request - * - * @exception IOException if an input or output exception occurred - * - */ - - public ServletInputStream getInputStream() throws IOException; - - - - - /** - * Returns the value of a request parameter as a String, - * or null if the parameter does not exist. Request parameters - * are extra information sent with the request. For HTTP servlets, - * parameters are contained in the query string or posted form data. - * - *

You should only use this method when you are sure the - * parameter has only one value. If the parameter might have - * more than one value, use {@link #getParameterValues}. - * - *

If you use this method with a multivalued - * parameter, the value returned is equal to the first value - * in the array returned by getParameterValues. - * - *

If the parameter data was sent in the request body, such as occurs - * with an HTTP POST request, then reading the body directly via {@link - * #getInputStream} or {@link #getReader} can interfere - * with the execution of this method. - * - * @param name a String specifying the - * name of the parameter - * - * @return a String representing the - * single value of the parameter - * - * @see #getParameterValues - * - */ + /** + * Retrieves the body of the request as binary data using a + * {@link ServletInputStream}. Either this method or {@link #getReader} may + * be called to read the body, not both. + * + * @return a {@link ServletInputStream} object containing the body of the + * request + * @exception IllegalStateException + * if the {@link #getReader} method has already been called + * for this request + * @exception IOException + * if an input or output exception occurred + */ + public ServletInputStream getInputStream() throws IOException; + + /** + * Returns the value of a request parameter as a String, or + * null if the parameter does not exist. Request parameters are + * extra information sent with the request. For HTTP servlets, parameters + * are contained in the query string or posted form data. + *

+ * You should only use this method when you are sure the parameter has only + * one value. If the parameter might have more than one value, use + * {@link #getParameterValues}. + *

+ * If you use this method with a multivalued parameter, the value returned + * is equal to the first value in the array returned by + * getParameterValues. + *

+ * If the parameter data was sent in the request body, such as occurs with + * an HTTP POST request, then reading the body directly via + * {@link #getInputStream} or {@link #getReader} can interfere with the + * execution of this method. + * + * @param name + * a String specifying the name of the parameter + * @return a String representing the single value of the + * parameter + * @see #getParameterValues + */ public String getParameter(String name); - - - - - /** - * - * Returns an Enumeration of String - * objects containing the names of the parameters contained - * in this request. If the request has - * no parameters, the method returns an - * empty Enumeration. - * - * @return an Enumeration of String - * objects, each String containing - * the name of a request parameter; or an - * empty Enumeration if the - * request has no parameters - * - */ - - public Enumeration getParameterNames(); - - - - - /** - * Returns an array of String objects containing - * all of the values the given request parameter has, or - * null if the parameter does not exist. - * - *

If the parameter has a single value, the array has a length - * of 1. - * - * @param name a String containing the name of - * the parameter whose value is requested - * - * @return an array of String objects - * containing the parameter's values - * - * @see #getParameter - * + + /** + * Returns an Enumeration of String objects + * containing the names of the parameters contained in this request. If the + * request has no parameters, the method returns an empty + * Enumeration. + * + * @return an Enumeration of String objects, each + * String containing the name of a request parameter; + * or an empty Enumeration if the request has no + * parameters */ + public Enumeration getParameterNames(); + /** + * Returns an array of String objects containing all of the + * values the given request parameter has, or null if the + * parameter does not exist. + *

+ * If the parameter has a single value, the array has a length of 1. + * + * @param name + * a String containing the name of the parameter + * whose value is requested + * @return an array of String objects containing the parameter's + * values + * @see #getParameter + */ public String[] getParameterValues(String name); - - /** Returns a java.util.Map of the parameters of this request. - * Request parameters - * are extra information sent with the request. For HTTP servlets, - * parameters are contained in the query string or posted form data. - * - * @return an immutable java.util.Map containing parameter names as - * keys and parameter values as map values. The keys in the parameter - * map are of type String. The values in the parameter map are of type - * String array. - * - */ - - public Map getParameterMap(); - - - - /** - * Returns the name and version of the protocol the request uses - * in the form protocol/majorVersion.minorVersion, for - * example, HTTP/1.1. For HTTP servlets, the value - * returned is the same as the value of the CGI variable - * SERVER_PROTOCOL. - * - * @return a String containing the protocol - * name and version number - * - */ - - public String getProtocol(); - - - /** - * Returns the name of the scheme used to make this request, - * for example, - * http, https, or ftp. - * Different schemes have different rules for constructing URLs, - * as noted in RFC 1738. - * - * @return a String containing the name - * of the scheme used to make this request - * + * Returns a java.util.Map of the parameters of this request. Request + * parameters are extra information sent with the request. For HTTP + * servlets, parameters are contained in the query string or posted form + * data. + * + * @return an immutable java.util.Map containing parameter names as keys and + * parameter values as map values. The keys in the parameter map are + * of type String. The values in the parameter map are of type + * String array. */ + public Map getParameterMap(); - public String getScheme(); - - - + /** + * Returns the name and version of the protocol the request uses in the form + * protocol/majorVersion.minorVersion, for example, HTTP/1.1. For + * HTTP servlets, the value returned is the same as the value of the CGI + * variable SERVER_PROTOCOL. + * + * @return a String containing the protocol name and version + * number + */ + public String getProtocol(); /** - * Returns the host name of the server to which the request was sent. - * It is the value of the part before ":" in the Host - * header value, if any, or the resolved server name, or the server IP address. - * - * @return a String containing the name - * of the server + * Returns the name of the scheme used to make this request, for example, + * http, https, or ftp. Different + * schemes have different rules for constructing URLs, as noted in RFC 1738. + * + * @return a String containing the name of the scheme used to + * make this request */ + public String getScheme(); + /** + * Returns the host name of the server to which the request was sent. It is + * the value of the part before ":" in the Host header value, + * if any, or the resolved server name, or the server IP address. + * + * @return a String containing the name of the server + */ public String getServerName(); - - - /** - * Returns the port number to which the request was sent. - * It is the value of the part after ":" in the Host - * header value, if any, or the server port where the client connection - * was accepted on. - * - * @return an integer specifying the port number - * + * Returns the port number to which the request was sent. It is the value of + * the part after ":" in the Host header value, if any, or the + * server port where the client connection was accepted on. + * + * @return an integer specifying the port number */ - public int getServerPort(); - - - - /** - * Retrieves the body of the request as character data using - * a BufferedReader. The reader translates the character - * data according to the character encoding used on the body. - * Either this method or {@link #getInputStream} may be called to read the - * body, not both. + + /** + * Retrieves the body of the request as character data using a + * BufferedReader. The reader translates the character data + * according to the character encoding used on the body. Either this method + * or {@link #getInputStream} may be called to read the body, not both. * - * - * @return a BufferedReader - * containing the body of the request - * - * @exception UnsupportedEncodingException if the character set encoding - * used is not supported and the - * text cannot be decoded - * - * @exception IllegalStateException if {@link #getInputStream} method - * has been called on this request - * - * @exception IOException if an input or output exception occurred - * - * @see #getInputStream - * + * @return a BufferedReader containing the body of the request + * @exception UnsupportedEncodingException + * if the character set encoding used is not supported and + * the text cannot be decoded + * @exception IllegalStateException + * if {@link #getInputStream} method has been called on this + * request + * @exception IOException + * if an input or output exception occurred + * @see #getInputStream */ - public BufferedReader getReader() throws IOException; - - - /** - * Returns the Internet Protocol (IP) address of the client - * or last proxy that sent the request. - * For HTTP servlets, same as the value of the - * CGI variable REMOTE_ADDR. - * - * @return a String containing the - * IP address of the client that sent the request - * + * Returns the Internet Protocol (IP) address of the client or last proxy + * that sent the request. For HTTP servlets, same as the value of the CGI + * variable REMOTE_ADDR. + * + * @return a String containing the IP address of the client + * that sent the request */ - public String getRemoteAddr(); - - - /** - * Returns the fully qualified name of the client - * or the last proxy that sent the request. - * If the engine cannot or chooses not to resolve the hostname - * (to improve performance), this method returns the dotted-string form of - * the IP address. For HTTP servlets, same as the value of the CGI variable - * REMOTE_HOST. - * - * @return a String containing the fully - * qualified name of the client - * + * Returns the fully qualified name of the client or the last proxy that + * sent the request. If the engine cannot or chooses not to resolve the + * hostname (to improve performance), this method returns the dotted-string + * form of the IP address. For HTTP servlets, same as the value of the CGI + * variable REMOTE_HOST. + * + * @return a String containing the fully qualified name of the + * client */ - public String getRemoteHost(); - - - - - /** - * - * Stores an attribute in this request. - * Attributes are reset between requests. This method is most - * often used in conjunction with {@link RequestDispatcher}. - * - *

Attribute names should follow the same conventions as - * package names. Names beginning with java.*, - * javax.*, and com.sun.*, are - * reserved for use by Sun Microsystems. - *
If the object passed in is null, the effect is the same as - * calling {@link #removeAttribute}. - *
It is warned that when the request is dispatched from the - * servlet resides in a different web application by - * RequestDispatcher, the object set by this method - * may not be correctly retrieved in the caller servlet. - * - * - * @param name a String specifying - * the name of the attribute - * - * @param o the Object to be stored - * - */ - public void setAttribute(String name, Object o); - - - - - /** - * - * Removes an attribute from this request. This method is not - * generally needed as attributes only persist as long as the request - * is being handled. - * - *

Attribute names should follow the same conventions as - * package names. Names beginning with java.*, - * javax.*, and com.sun.*, are - * reserved for use by Sun Microsystems. - * - * - * @param name a String specifying - * the name of the attribute to remove - * + /** + * Stores an attribute in this request. Attributes are reset between + * requests. This method is most often used in conjunction with + * {@link RequestDispatcher}. + *

+ * Attribute names should follow the same conventions as package names. + * Names beginning with java.*, javax.*, and + * com.sun.*, are reserved for use by Sun Microsystems.
+ * If the object passed in is null, the effect is the same as calling + * {@link #removeAttribute}.
+ * It is warned that when the request is dispatched from the servlet resides + * in a different web application by RequestDispatcher, the + * object set by this method may not be correctly retrieved in the caller + * servlet. + * + * @param name + * a String specifying the name of the attribute + * @param o + * the Object to be stored */ + public void setAttribute(String name, Object o); + /** + * Removes an attribute from this request. This method is not generally + * needed as attributes only persist as long as the request is being + * handled. + *

+ * Attribute names should follow the same conventions as package names. + * Names beginning with java.*, javax.*, and + * com.sun.*, are reserved for use by Sun Microsystems. + * + * @param name + * a String specifying the name of the attribute to + * remove + */ public void removeAttribute(String name); - - - /** - * - * Returns the preferred Locale that the client will - * accept content in, based on the Accept-Language header. - * If the client request doesn't provide an Accept-Language header, - * this method returns the default locale for the server. - * - * - * @return the preferred Locale for the client - * + * Returns the preferred Locale that the client will accept + * content in, based on the Accept-Language header. If the client request + * doesn't provide an Accept-Language header, this method returns the + * default locale for the server. + * + * @return the preferred Locale for the client */ - public Locale getLocale(); - - - /** - * * Returns an Enumeration of Locale objects * indicating, in decreasing order starting with the preferred locale, the * locales that are acceptable to the client based on the Accept-Language - * header. - * If the client request doesn't provide an Accept-Language header, - * this method returns an Enumeration containing one + * header. If the client request doesn't provide an Accept-Language header, + * this method returns an Enumeration containing one * Locale, the default locale for the server. - * - * - * @return an Enumeration of preferred - * Locale objects for the client - * + * + * @return an Enumeration of preferred Locale + * objects for the client */ - public Enumeration getLocales(); - - - /** - * - * Returns a boolean indicating whether this request was made using a - * secure channel, such as HTTPS. - * - * - * @return a boolean indicating if the request was made using a - * secure channel - * + * Returns a boolean indicating whether this request was made using a secure + * channel, such as HTTPS. + * + * @return a boolean indicating if the request was made using a secure + * channel */ - public boolean isSecure(); - - - - - /** - * - * Returns a {@link RequestDispatcher} object that acts as a wrapper for - * the resource located at the given path. - * A RequestDispatcher object can be used to forward - * a request to the resource or to include the resource in a response. - * The resource can be dynamic or static. - * - *

The pathname specified may be relative, although it cannot extend - * outside the current servlet context. If the path begins with - * a "/" it is interpreted as relative to the current context root. - * This method returns null if the servlet container - * cannot return a RequestDispatcher. - * - *

The difference between this method and {@link - * ServletContext#getRequestDispatcher} is that this method can take a - * relative path. - * - * @param path a String specifying the pathname - * to the resource. If it is relative, it must be - * relative against the current servlet. - * - * @return a RequestDispatcher object - * that acts as a wrapper for the resource - * at the specified path, or null - * if the servlet container cannot return a - * RequestDispatcher - * - * @see RequestDispatcher - * @see ServletContext#getRequestDispatcher - * - */ + /** + * Returns a {@link RequestDispatcher} object that acts as a wrapper for the + * resource located at the given path. A RequestDispatcher + * object can be used to forward a request to the resource or to include the + * resource in a response. The resource can be dynamic or static. + *

+ * The pathname specified may be relative, although it cannot extend outside + * the current servlet context. If the path begins with a "/" it is + * interpreted as relative to the current context root. This method returns + * null if the servlet container cannot return a + * RequestDispatcher. + *

+ * The difference between this method and + * {@link ServletContext#getRequestDispatcher} is that this method can take + * a relative path. + * + * @param path + * a String specifying the pathname to the resource. + * If it is relative, it must be relative against the current + * servlet. + * @return a RequestDispatcher object that acts as a wrapper for + * the resource at the specified path, or null if the + * servlet container cannot return a RequestDispatcher + * @see RequestDispatcher + * @see ServletContext#getRequestDispatcher + */ public RequestDispatcher getRequestDispatcher(String path); - - - /** - * @deprecated As of Version 2.1 of the Java Servlet API, - * use {@link ServletContext#getRealPath} instead. + * @deprecated As of Version 2.1 of the Java Servlet API, use + * {@link ServletContext#getRealPath} instead. */ - @SuppressWarnings("dep-ann") // Spec API does not use @Deprecated + @SuppressWarnings("dep-ann") + // Spec API does not use @Deprecated public String getRealPath(String path); - - - /** - * Returns the Internet Protocol (IP) source port of the client - * or last proxy that sent the request. - * - * @return an integer specifying the port number - * + + /** + * Returns the Internet Protocol (IP) source port of the client or last + * proxy that sent the request. + * + * @return an integer specifying the port number * @since 2.4 - */ + */ public int getRemotePort(); - /** - * Returns the host name of the Internet Protocol (IP) interface on - * which the request was received. - * - * @return a String containing the host - * name of the IP on which the request was received. - * + * Returns the host name of the Internet Protocol (IP) interface on which + * the request was received. + * + * @return a String containing the host name of the IP on which + * the request was received. * @since 2.4 */ public String getLocalName(); /** - * Returns the Internet Protocol (IP) address of the interface on - * which the request was received. - * - * @return a String containing the - * IP address on which the request was received. - * + * Returns the Internet Protocol (IP) address of the interface on which the + * request was received. + * + * @return a String containing the IP address on which the + * request was received. * @since 2.4 - * - */ + */ public String getLocalAddr(); - /** - * Returns the Internet Protocol (IP) port number of the interface - * on which the request was received. - * + * Returns the Internet Protocol (IP) port number of the interface on which + * the request was received. + * * @return an integer specifying the port number - * * @since 2.4 */ public int getLocalPort(); /** - * * @return - * @since Servlet 3.0 - * TODO SERVLET3 - Add comments + * @since Servlet 3.0 TODO SERVLET3 - Add comments */ public ServletContext getServletContext(); - + /** - * * @return - * @throws java.lang.IllegalStateException If async is not supported for - * this request - * @since Servlet 3.0 - * TODO SERVLET3 - Add comments + * @throws java.lang.IllegalStateException + * If async is not supported for this request + * @since Servlet 3.0 TODO SERVLET3 - Add comments */ public AsyncContext startAsync(); - + /** - * * @param servletRequest * @param servletResponse * @return * @throws java.lang.IllegalStateException - * @since Servlet 3.0 - * TODO SERVLET3 - Add comments + * @since Servlet 3.0 TODO SERVLET3 - Add comments */ public AsyncContext startAsync(ServletRequest servletRequest, ServletResponse servletResponse); - + /** - * * @return - * @since Servlet 3.0 - * TODO SERVLET3 - Add comments + * @since Servlet 3.0 TODO SERVLET3 - Add comments */ public boolean isAsyncStarted(); - + /** - * * @return - * @since Servlet 3.0 - * TODO SERVLET3 - Add comments + * @since Servlet 3.0 TODO SERVLET3 - Add comments */ public boolean isAsyncSupported(); - + /** - * * @return * @throws java.lang.IllegalStateException - * @since Servlet 3.0 - * TODO SERVLET3 - Add comments + * @since Servlet 3.0 TODO SERVLET3 - Add comments */ public AsyncContext getAsyncContext(); /** - * * @return - * @since Servlet 3.0 - * TODO SERVLET3 - Add comments + * @since Servlet 3.0 TODO SERVLET3 - Add comments */ public DispatcherType getDispatcherType(); } - diff --git a/java/javax/servlet/ServletRequestAttributeEvent.java b/java/javax/servlet/ServletRequestAttributeEvent.java index 98a5861ff..9f5527730 100644 --- a/java/javax/servlet/ServletRequestAttributeEvent.java +++ b/java/javax/servlet/ServletRequestAttributeEvent.java @@ -1,67 +1,71 @@ /* -* 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; - - /** - * This is the event class for notifications of changes to the - * attributes of the servlet request in an application. - * @see ServletRequestAttributeListener - * @since Servlet 2.4 - */ - -public class ServletRequestAttributeEvent extends ServletRequestEvent { +/** + * This is the event class for notifications of changes to the attributes of the + * servlet request in an application. + * + * @see ServletRequestAttributeListener + * @since Servlet 2.4 + */ +public class ServletRequestAttributeEvent extends ServletRequestEvent { private String name; private Object value; - /** Construct a ServletRequestAttributeEvent giving the servlet context - * of this web application, the ServletRequest whose attributes are - * changing and the name and value of the attribute. - * - * @param sc the ServletContext that is sending the event. - * @param request the ServletRequest that is sending the event. - * @param name the name of the request attribute. - * @param value the value of the request attribute. - */ - public ServletRequestAttributeEvent(ServletContext sc, ServletRequest request, String name, Object value) { + /** + * Construct a ServletRequestAttributeEvent giving the servlet context of + * this web application, the ServletRequest whose attributes are changing + * and the name and value of the attribute. + * + * @param sc + * the ServletContext that is sending the event. + * @param request + * the ServletRequest that is sending the event. + * @param name + * the name of the request attribute. + * @param value + * the value of the request attribute. + */ + public ServletRequestAttributeEvent(ServletContext sc, + ServletRequest request, String name, Object value) { super(sc, request); this.name = name; this.value = value; } /** - * Return the name of the attribute that changed on the ServletRequest. - * - * @return the name of the changed request attribute - */ + * Return the name of the attribute that changed on the ServletRequest. + * + * @return the name of the changed request attribute + */ public String getName() { return this.name; } /** - * Returns the value of the attribute that has been added, removed or - * replaced. If the attribute was added, this is the value of the - * attribute. If the attribute was removed, this is the value of the - * removed attribute. If the attribute was replaced, this is the old - * value of the attribute. - * - * @return the value of the changed request attribute - */ + * Returns the value of the attribute that has been added, removed or + * replaced. If the attribute was added, this is the value of the attribute. + * If the attribute was removed, this is the value of the removed attribute. + * If the attribute was replaced, this is the old value of the attribute. + * + * @return the value of the changed request attribute + */ public Object getValue() { - return this.value; + return this.value; } } diff --git a/java/javax/servlet/ServletRequestEvent.java b/java/javax/servlet/ServletRequestEvent.java index d39502907..fb42a0fc9 100644 --- a/java/javax/servlet/ServletRequestEvent.java +++ b/java/javax/servlet/ServletRequestEvent.java @@ -1,56 +1,56 @@ /* -* 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; - - /** - * Events of this kind indicate lifecycle - * events for a ServletRequest. - * The source of the event - * is the ServletContext of this web application. - * @see ServletRequestListener - * @since Servlet 2.4 - */ - -public class ServletRequestEvent extends java.util.EventObject { +/** + * Events of this kind indicate lifecycle events for a ServletRequest. The + * source of the event is the ServletContext of this web application. + * + * @see ServletRequestListener + * @since Servlet 2.4 + */ +public class ServletRequestEvent extends java.util.EventObject { private ServletRequest request; - /** Construct a ServletRequestEvent for the given ServletContext - * and ServletRequest. - * - * @param sc the ServletContext of the web application. - * @param request the ServletRequest that is sending the event. - */ + /** + * Construct a ServletRequestEvent for the given ServletContext and + * ServletRequest. + * + * @param sc + * the ServletContext of the web application. + * @param request + * the ServletRequest that is sending the event. + */ public ServletRequestEvent(ServletContext sc, ServletRequest request) { super(sc); this.request = request; } - + /** - * Returns the ServletRequest that is changing. - */ - public ServletRequest getServletRequest () { + * Returns the ServletRequest that is changing. + */ + public ServletRequest getServletRequest() { return this.request; } /** - * Returns the ServletContext of this web application. - */ - public ServletContext getServletContext () { + * Returns the ServletContext of this web application. + */ + public ServletContext getServletContext() { return (ServletContext) super.getSource(); } } diff --git a/java/javax/servlet/ServletRequestWrapper.java b/java/javax/servlet/ServletRequestWrapper.java index a0e133e6f..3c468bd44 100644 --- a/java/javax/servlet/ServletRequestWrapper.java +++ b/java/javax/servlet/ServletRequestWrapper.java @@ -1,19 +1,19 @@ /* -* 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; import java.io.BufferedReader; @@ -22,385 +22,299 @@ import java.util.Enumeration; import java.util.Locale; import java.util.Map; - - /** + * Provides a convenient implementation of the ServletRequest 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. * - * Provides a convenient implementation of the ServletRequest 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. - * @since v 2.3 - * - * - * - * @see javax.servlet.ServletRequest - * + * @since v 2.3 + * @see javax.servlet.ServletRequest */ - public class ServletRequestWrapper implements ServletRequest { private ServletRequest request; - /** - * Creates a ServletRequest adaptor wrapping the given request object. - * @throws java.lang.IllegalArgumentException if the request is null - */ - + /** + * Creates a ServletRequest adaptor wrapping the given request object. + * + * @throws java.lang.IllegalArgumentException + * if the request is null + */ public ServletRequestWrapper(ServletRequest request) { - if (request == null) { - throw new IllegalArgumentException("Request cannot be null"); - } - this.request = request; - } - - /** - * Return the wrapped request object. - */ - public ServletRequest getRequest() { - return this.request; - } - - /** - * Sets the request object being wrapped. - * @throws java.lang.IllegalArgumentException if the request is null. - */ - - public void setRequest(ServletRequest request) { - if (request == null) { - throw new IllegalArgumentException("Request cannot be null"); - } - this.request = request; - } - - /** - * - * The default behavior of this method is to call getAttribute(String name) - * on the wrapped request object. + if (request == null) { + throw new IllegalArgumentException("Request cannot be null"); + } + this.request = request; + } + + /** + * Return the wrapped request object. */ + public ServletRequest getRequest() { + return this.request; + } - public Object getAttribute(String name) { - return this.request.getAttribute(name); - } - - + /** + * Sets the request object being wrapped. + * + * @throws java.lang.IllegalArgumentException + * if the request is null. + */ + public void setRequest(ServletRequest request) { + if (request == null) { + throw new IllegalArgumentException("Request cannot be null"); + } + this.request = request; + } /** - * The default behavior of this method is to return getAttributeNames() + * The default behavior of this method is to call getAttribute(String name) * on the wrapped request object. */ + public Object getAttribute(String name) { + return this.request.getAttribute(name); + } - public Enumeration getAttributeNames() { - return this.request.getAttributeNames(); - } - - - /** - * The default behavior of this method is to return getCharacterEncoding() - * on the wrapped request object. + * The default behavior of this method is to return getAttributeNames() on + * the wrapped request object. */ + public Enumeration getAttributeNames() { + return this.request.getAttributeNames(); + } - public String getCharacterEncoding() { - return this.request.getCharacterEncoding(); - } - /** - * The default behavior of this method is to set the character encoding + * The default behavior of this method is to return getCharacterEncoding() * on the wrapped request object. */ + public String getCharacterEncoding() { + return this.request.getCharacterEncoding(); + } - public void setCharacterEncoding(String enc) throws java.io.UnsupportedEncodingException { - this.request.setCharacterEncoding(enc); - } - - /** - * The default behavior of this method is to return getContentLength() - * on the wrapped request object. + * The default behavior of this method is to set the character encoding on + * the wrapped request object. */ + public void setCharacterEncoding(String enc) + throws java.io.UnsupportedEncodingException { + this.request.setCharacterEncoding(enc); + } + /** + * The default behavior of this method is to return getContentLength() on + * the wrapped request object. + */ public int getContentLength() { - return this.request.getContentLength(); + return this.request.getContentLength(); } - - - - /** - * The default behavior of this method is to return getContentType() - * on the wrapped request object. + /** + * The default behavior of this method is to return getContentType() on the + * wrapped request object. */ public String getContentType() { - return this.request.getContentType(); + return this.request.getContentType(); } - - - - /** - * The default behavior of this method is to return getInputStream() - * on the wrapped request object. + /** + * The default behavior of this method is to return getInputStream() on the + * wrapped request object. */ - public ServletInputStream getInputStream() throws IOException { - return this.request.getInputStream(); - } - - - + return this.request.getInputStream(); + } /** - * The default behavior of this method is to return getParameter(String name) - * on the wrapped request object. + * The default behavior of this method is to return getParameter(String + * name) on the wrapped request object. */ - public String getParameter(String name) { - return this.request.getParameter(name); + return this.request.getParameter(name); } - + /** - * The default behavior of this method is to return getParameterMap() - * on the wrapped request object. + * The default behavior of this method is to return getParameterMap() on the + * wrapped request object. */ - public Map getParameterMap() { - return this.request.getParameterMap(); + public Map getParameterMap() { + return this.request.getParameterMap(); } - - - /** - * The default behavior of this method is to return getParameterNames() - * on the wrapped request object. + * The default behavior of this method is to return getParameterNames() on + * the wrapped request object. */ - public Enumeration getParameterNames() { - return this.request.getParameterNames(); + return this.request.getParameterNames(); } - - - - /** - * The default behavior of this method is to return getParameterValues(String name) - * on the wrapped request object. + /** + * The default behavior of this method is to return + * getParameterValues(String name) on the wrapped request object. */ public String[] getParameterValues(String name) { - return this.request.getParameterValues(name); - } - - - - - /** - * The default behavior of this method is to return getProtocol() - * on the wrapped request object. + return this.request.getParameterValues(name); + } + + /** + * The default behavior of this method is to return getProtocol() on the + * wrapped request object. */ - public String getProtocol() { - return this.request.getProtocol(); - } - - - + return this.request.getProtocol(); + } /** - * The default behavior of this method is to return getScheme() - * on the wrapped request object. + * The default behavior of this method is to return getScheme() on the + * wrapped request object. */ - - public String getScheme() { - return this.request.getScheme(); - } - - - + return this.request.getScheme(); + } /** - * The default behavior of this method is to return getServerName() - * on the wrapped request object. + * The default behavior of this method is to return getServerName() on the + * wrapped request object. */ public String getServerName() { - return this.request.getServerName(); - } - - - - - /** - * The default behavior of this method is to return getServerPort() - * on the wrapped request object. - */ + return this.request.getServerName(); + } - public int getServerPort() { - return this.request.getServerPort(); - } - - - - /** - * The default behavior of this method is to return getReader() - * on the wrapped request object. + /** + * The default behavior of this method is to return getServerPort() on the + * wrapped request object. */ + public int getServerPort() { + return this.request.getServerPort(); + } + /** + * The default behavior of this method is to return getReader() on the + * wrapped request object. + */ public BufferedReader getReader() throws IOException { - return this.request.getReader(); - } - - - + return this.request.getReader(); + } /** - * The default behavior of this method is to return getRemoteAddr() - * on the wrapped request object. + * The default behavior of this method is to return getRemoteAddr() on the + * wrapped request object. */ - public String getRemoteAddr() { - return this.request.getRemoteAddr(); + return this.request.getRemoteAddr(); } - - - - /** - * The default behavior of this method is to return getRemoteHost() - * on the wrapped request object. + /** + * The default behavior of this method is to return getRemoteHost() on the + * wrapped request object. */ - public String getRemoteHost() { - return this.request.getRemoteHost(); + return this.request.getRemoteHost(); } - - - /** - * The default behavior of this method is to return setAttribute(String name, Object o) - * on the wrapped request object. + * The default behavior of this method is to return setAttribute(String + * name, Object o) on the wrapped request object. */ - public void setAttribute(String name, Object o) { - this.request.setAttribute(name, o); + this.request.setAttribute(name, o); } - - - /** - * The default behavior of this method is to call removeAttribute(String name) - * on the wrapped request object. + * The default behavior of this method is to call removeAttribute(String + * name) on the wrapped request object. */ public void removeAttribute(String name) { - this.request.removeAttribute(name); + this.request.removeAttribute(name); } - - - - /** - * The default behavior of this method is to return getLocale() - * on the wrapped request object. + /** + * The default behavior of this method is to return getLocale() on the + * wrapped request object. */ - public Locale getLocale() { - return this.request.getLocale(); + return this.request.getLocale(); } - - - - /** - * The default behavior of this method is to return getLocales() - * on the wrapped request object. + /** + * The default behavior of this method is to return getLocales() on the + * wrapped request object. */ - public Enumeration getLocales() { - return this.request.getLocales(); + return this.request.getLocales(); } - - - /** - * The default behavior of this method is to return isSecure() - * on the wrapped request object. + * The default behavior of this method is to return isSecure() on the + * wrapped request object. */ - public boolean isSecure() { - return this.request.isSecure(); + return this.request.isSecure(); } - - - /** - * The default behavior of this method is to return getRequestDispatcher(String path) - * on the wrapped request object. + * The default behavior of this method is to return + * getRequestDispatcher(String path) on the wrapped request object. */ - public RequestDispatcher getRequestDispatcher(String path) { - return this.request.getRequestDispatcher(path); + return this.request.getRequestDispatcher(path); } - - - /** - * The default behavior of this method is to return getRealPath(String path) + * The default behavior of this method is to return getRealPath(String path) * 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 String getRealPath(String path) { - return this.request.getRealPath(path); + return this.request.getRealPath(path); } - + /** - * The default behavior of this method is to return - * getRemotePort() on the wrapped request object. - * + * The default behavior of this method is to return getRemotePort() on the + * wrapped request object. + * * @since 2.4 - */ - public int getRemotePort(){ + */ + public int getRemotePort() { return this.request.getRemotePort(); } - /** - * The default behavior of this method is to return - * getLocalName() on the wrapped request object. - * + * The default behavior of this method is to return getLocalName() on the + * wrapped request object. + * * @since 2.4 */ - public String getLocalName(){ + public String getLocalName() { return this.request.getLocalName(); } /** - * The default behavior of this method is to return - * getLocalAddr() on the wrapped request object. - * + * The default behavior of this method is to return getLocalAddr() on the + * wrapped request object. + * * @since 2.4 - */ - public String getLocalAddr(){ + */ + public String getLocalAddr() { return this.request.getLocalAddr(); } - /** - * The default behavior of this method is to return - * getLocalPort() on the wrapped request object. - * + * The default behavior of this method is to return getLocalPort() on the + * wrapped request object. + * * @since 2.4 */ - public int getLocalPort(){ + public int getLocalPort() { return this.request.getLocalPort(); } /** - * The default behavior of this method is to return - * getServletContext() on the wrapped request object. + * The default behavior of this method is to return getServletContext() on + * the wrapped request object. * * @return * @since Servlet 3.0 @@ -408,10 +322,10 @@ public class ServletRequestWrapper implements ServletRequest { public ServletContext getServletContext() { return request.getServletContext(); } - + /** - * The default behavior of this method is to return - * startAsync() on the wrapped request object. + * The default behavior of this method is to return startAsync() on the + * wrapped request object. * * @return * @throws java.lang.IllegalStateException @@ -420,10 +334,10 @@ public class ServletRequestWrapper implements ServletRequest { public AsyncContext startAsync() { return request.startAsync(); } - + /** - * The default behavior of this method is to return - * startAsync(Runnable) on the wrapped request object. + * The default behavior of this method is to return startAsync(Runnable) on + * the wrapped request object. * * @param servletRequest * @param servletResponse @@ -432,14 +346,13 @@ public class ServletRequestWrapper implements ServletRequest { * @since Servlet 3.0 */ public AsyncContext startAsync(ServletRequest servletRequest, - ServletResponse servletResponse) - throws IllegalStateException { + ServletResponse servletResponse) throws IllegalStateException { return request.startAsync(servletRequest, servletResponse); } - + /** - * The default behavior of this method is to return - * isAsyncStarted() on the wrapped request object. + * The default behavior of this method is to return isAsyncStarted() on the + * wrapped request object. * * @return * @since Servlet 3.0 @@ -449,8 +362,8 @@ public class ServletRequestWrapper implements ServletRequest { } /** - * The default behavior of this method is to return - * isAsyncSupported() on the wrapped request object. + * The default behavior of this method is to return isAsyncSupported() on + * the wrapped request object. * * @return * @since Servlet 3.0 @@ -458,10 +371,10 @@ public class ServletRequestWrapper implements ServletRequest { public boolean isAsyncSupported() { return request.isAsyncSupported(); } - + /** - * The default behavior of this method is to return - * getAsyncContext() on the wrapped request object. + * The default behavior of this method is to return getAsyncContext() on the + * wrapped request object. * * @return * @since Servlet 3.0 @@ -471,41 +384,38 @@ public class ServletRequestWrapper implements ServletRequest { } /** - * * @param wrapped - * @since Servlet 3.0 - * TODO SERVLET3 - Add comments + * @since Servlet 3.0 TODO SERVLET3 - Add comments */ public boolean isWrapperFor(ServletRequest wrapped) { if (request == wrapped) { return true; } if (request instanceof ServletRequestWrapper) { - return ((ServletRequestWrapper)request).isWrapperFor(wrapped); + return ((ServletRequestWrapper) request).isWrapperFor(wrapped); } return false; } - + /** - * * @param wrappedType - * @since Servlet 3.0 - * TODO SERVLET3 - Add comments + * @since Servlet 3.0 TODO SERVLET3 - Add comments */ - @SuppressWarnings("unchecked") // Spec API does not use generics + @SuppressWarnings("unchecked") + // Spec API does not use generics public boolean isWrapperFor(Class wrappedType) { if (wrappedType.isAssignableFrom(request.getClass())) { return true; } if (request instanceof ServletRequestWrapper) { - return ((ServletRequestWrapper)request).isWrapperFor(wrappedType); + return ((ServletRequestWrapper) request).isWrapperFor(wrappedType); } return false; } - + /** - * The default behavior of this method is to call - * getDispatcherType() on the wrapped request object. + * The default behavior of this method is to call getDispatcherType() on the + * wrapped request object. * * @since Servlet 3.0 */ @@ -513,4 +423,3 @@ public class ServletRequestWrapper implements ServletRequest { return this.request.getDispatcherType(); } } - diff --git a/java/javax/servlet/ServletResponse.java b/java/javax/servlet/ServletResponse.java index b9427d7a3..7859fc401 100644 --- a/java/javax/servlet/ServletResponse.java +++ b/java/javax/servlet/ServletResponse.java @@ -1,453 +1,339 @@ /* -* 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; import java.io.IOException; import java.io.PrintWriter; import java.util.Locale; - /** * Defines an object to assist a servlet in sending a response to the client. * The servlet container creates a ServletResponse object and * passes it as an argument to the servlet's service method. - * - *

To send binary data in a MIME body response, use - * the {@link ServletOutputStream} returned by {@link #getOutputStream}. - * To send character data, use the PrintWriter object - * returned by {@link #getWriter}. To mix binary and text data, - * for example, to create a multipart response, use a - * ServletOutputStream and manage the character sections - * manually. - * - *

The charset for the MIME body response can be specified - * explicitly using the {@link #setCharacterEncoding} and - * {@link #setContentType} methods, or implicitly - * using the {@link #setLocale} method. - * Explicit specifications take precedence over - * implicit specifications. If no charset is specified, ISO-8859-1 will be - * used. The setCharacterEncoding, - * setContentType, or setLocale method must - * be called before getWriter and before committing - * the response for the character encoding to be used. + *

+ * To send binary data in a MIME body response, use the + * {@link ServletOutputStream} returned by {@link #getOutputStream}. To send + * character data, use the PrintWriter object returned by + * {@link #getWriter}. To mix binary and text data, for example, to create a + * multipart response, use a ServletOutputStream and manage the + * character sections manually. + *

+ * The charset for the MIME body response can be specified explicitly using the + * {@link #setCharacterEncoding} and {@link #setContentType} methods, or + * implicitly using the {@link #setLocale} method. Explicit specifications take + * precedence over implicit specifications. If no charset is specified, + * ISO-8859-1 will be used. The setCharacterEncoding, + * setContentType, or setLocale method must be called + * before getWriter and before committing the response for the + * character encoding to be used. + *

+ * See the Internet RFCs such as + * RFC 2045 for more information on MIME. Protocols such as SMTP and HTTP + * define profiles of MIME, and those standards are still evolving. * - *

See the Internet RFCs such as - * - * RFC 2045 for more information on MIME. Protocols such as SMTP - * and HTTP define profiles of MIME, and those standards - * are still evolving. - * - * @author Various - * @version $Version$ - * - * @see ServletOutputStream - * + * @author Various + * @version $Version$ + * @see ServletOutputStream */ - public interface ServletResponse { - - /** - * Returns the name of the character encoding (MIME charset) - * used for the body sent in this response. - * The character encoding may have been specified explicitly - * using the {@link #setCharacterEncoding} or + * Returns the name of the character encoding (MIME charset) used for the + * body sent in this response. The character encoding may have been + * specified explicitly using the {@link #setCharacterEncoding} or * {@link #setContentType} methods, or implicitly using the - * {@link #setLocale} method. Explicit specifications take - * precedence over implicit specifications. Calls made - * to these methods after getWriter has been - * called or after the response has been committed have no - * effect on the character encoding. If no character encoding - * has been specified, ISO-8859-1 is returned. - *

See RFC 2047 (http://www.ietf.org/rfc/rfc2047.txt) - * for more information about character encoding and MIME. - * - * @return a String specifying the - * name of the character encoding, for - * example, UTF-8 - * + * {@link #setLocale} method. Explicit specifications take precedence over + * implicit specifications. Calls made to these methods after + * getWriter has been called or after the response has been + * committed have no effect on the character encoding. If no character + * encoding has been specified, ISO-8859-1 is returned. + *

+ * See RFC 2047 (http://www.ietf.org/rfc/rfc2047.txt) for more information + * about character encoding and MIME. + * + * @return a String specifying the name of the character + * encoding, for example, UTF-8 */ - public String getCharacterEncoding(); - - /** - * Returns the content type used for the MIME body - * sent in this response. The content type proper must - * have been specified using {@link #setContentType} - * before the response is committed. If no content type - * has been specified, this method returns null. - * If a content type has been specified and a - * character encoding has been explicitly or implicitly - * specified as described in {@link #getCharacterEncoding}, - * the charset parameter is included in the string returned. - * If no character encoding has been specified, the - * charset parameter is omitted. - * - * @return a String specifying the - * content type, for example, - * text/html; charset=UTF-8, - * or null - * + * Returns the content type used for the MIME body sent in this response. + * The content type proper must have been specified using + * {@link #setContentType} before the response is committed. If no content + * type has been specified, this method returns null. If a content type has + * been specified and a character encoding has been explicitly or implicitly + * specified as described in {@link #getCharacterEncoding}, the charset + * parameter is included in the string returned. If no character encoding + * has been specified, the charset parameter is omitted. + * + * @return a String specifying the content type, for example, + * text/html; charset=UTF-8, or null * @since 2.4 */ - public String getContentType(); - - /** - * Returns a {@link ServletOutputStream} suitable for writing binary - * data in the response. The servlet container does not encode the - * binary data. - - *

Calling flush() on the ServletOutputStream commits the response. - - * Either this method or {@link #getWriter} may - * be called to write the body, not both. - * - * @return a {@link ServletOutputStream} for writing binary data - * - * @exception IllegalStateException if the getWriter method - * has been called on this response - * - * @exception IOException if an input or output exception occurred - * - * @see #getWriter - * + * Returns a {@link ServletOutputStream} suitable for writing binary data in + * the response. The servlet container does not encode the binary data. + *

+ * Calling flush() on the ServletOutputStream commits the response. Either + * this method or {@link #getWriter} may be called to write the body, not + * both. + * + * @return a {@link ServletOutputStream} for writing binary data + * @exception IllegalStateException + * if the getWriter method has been called on + * this response + * @exception IOException + * if an input or output exception occurred + * @see #getWriter */ - public ServletOutputStream getOutputStream() throws IOException; - - /** - * Returns a PrintWriter object that - * can send character text to the client. - * The PrintWriter uses the character - * encoding returned by {@link #getCharacterEncoding}. - * If the response's character encoding has not been - * specified as described in getCharacterEncoding - * (i.e., the method just returns the default value - * ISO-8859-1), getWriter - * updates it to ISO-8859-1. - *

Calling flush() on the PrintWriter - * commits the response. - *

Either this method or {@link #getOutputStream} may be called - * to write the body, not both. - * + * Returns a PrintWriter object that can send character text to + * the client. The PrintWriter uses the character encoding + * returned by {@link #getCharacterEncoding}. If the response's character + * encoding has not been specified as described in + * getCharacterEncoding (i.e., the method just returns the + * default value ISO-8859-1), getWriter updates it + * to ISO-8859-1. + *

+ * Calling flush() on the PrintWriter commits the response. + *

+ * Either this method or {@link #getOutputStream} may be called to write the + * body, not both. * - * @return a PrintWriter object that - * can return character data to the client - * + * @return a PrintWriter object that can return character data + * to the client * @exception UnsupportedEncodingException - * if the character encoding returned - * by getCharacterEncoding cannot be used - * + * if the character encoding returned by + * getCharacterEncoding cannot be used * @exception IllegalStateException - * if the getOutputStream - * method has already been called for this - * response object - * + * if the getOutputStream method has already + * been called for this response object * @exception IOException - * if an input or output exception occurred - * - * @see #getOutputStream - * @see #setCharacterEncoding - * + * if an input or output exception occurred + * @see #getOutputStream + * @see #setCharacterEncoding */ - public PrintWriter getWriter() throws IOException; - - - - + /** - * Sets the character encoding (MIME charset) of the response - * being sent to the client, for example, to UTF-8. - * If the character encoding has already been set by - * {@link #setContentType} or {@link #setLocale}, - * this method overrides it. - * Calling {@link #setContentType} with the String - * of text/html and calling - * this method with the String of UTF-8 - * is equivalent with calling - * setContentType with the String of + * Sets the character encoding (MIME charset) of the response being sent to + * the client, for example, to UTF-8. If the character encoding has already + * been set by {@link #setContentType} or {@link #setLocale}, this method + * overrides it. Calling {@link #setContentType} with the + * String of text/html and calling this method + * with the String of UTF-8 is equivalent with + * calling setContentType with the String of * text/html; charset=UTF-8. - *

This method can be called repeatedly to change the character - * encoding. - * This method has no effect if it is called after - * getWriter has been - * called or after the response has been committed. - *

Containers must communicate the character encoding used for - * the servlet response's writer to the client if the protocol - * provides a way for doing so. In the case of HTTP, the character - * encoding is communicated as part of the Content-Type - * header for text media types. Note that the character encoding - * cannot be communicated via HTTP headers if the servlet does not - * specify a content type; however, it is still used to encode text - * written via the servlet response's writer. - * - * @param charset a String specifying only the character set - * defined by IANA Character Sets - * (http://www.iana.org/assignments/character-sets) - * - * @see #setContentType - * #setLocale - * + *

+ * This method can be called repeatedly to change the character encoding. + * This method has no effect if it is called after getWriter + * has been called or after the response has been committed. + *

+ * Containers must communicate the character encoding used for the servlet + * response's writer to the client if the protocol provides a way for doing + * so. In the case of HTTP, the character encoding is communicated as part + * of the Content-Type header for text media types. Note that + * the character encoding cannot be communicated via HTTP headers if the + * servlet does not specify a content type; however, it is still used to + * encode text written via the servlet response's writer. + * + * @param charset + * a String specifying only the character set defined by IANA + * Character Sets + * (http://www.iana.org/assignments/character-sets) + * @see #setContentType #setLocale * @since 2.4 - * */ - public void setCharacterEncoding(String charset); - - - /** - * Sets the length of the content body in the response - * In HTTP servlets, this method sets the HTTP Content-Length header. - * - * - * @param len an integer specifying the length of the - * content being returned to the client; sets - * the Content-Length header - * + * Sets the length of the content body in the response In HTTP servlets, + * this method sets the HTTP Content-Length header. + * + * @param len + * an integer specifying the length of the content being returned + * to the client; sets the Content-Length header */ - public void setContentLength(int len); - - /** - * Sets the content type of the response being sent to - * the client, if the response has not been committed yet. - * The given content type may include a character encoding - * specification, for example, text/html;charset=UTF-8. - * The response's character encoding is only set from the given - * content type if this method is called before getWriter - * is called. - *

This method may be called repeatedly to change content type and - * character encoding. - * This method has no effect if called after the response - * has been committed. It does not set the response's character - * encoding if it is called after getWriter - * has been called or after the response has been committed. - *

Containers must communicate the content type and the character - * encoding used for the servlet response's writer to the client if - * the protocol provides a way for doing so. In the case of HTTP, - * the Content-Type header is used. - * - * @param type a String specifying the MIME - * type of the content - * - * @see #setLocale - * @see #setCharacterEncoding - * @see #getOutputStream - * @see #getWriter - * + * Sets the content type of the response being sent to the client, if the + * response has not been committed yet. The given content type may include a + * character encoding specification, for example, + * text/html;charset=UTF-8. The response's character encoding + * is only set from the given content type if this method is called before + * getWriter is called. + *

+ * This method may be called repeatedly to change content type and character + * encoding. This method has no effect if called after the response has been + * committed. It does not set the response's character encoding if it is + * called after getWriter has been called or after the response + * has been committed. + *

+ * Containers must communicate the content type and the character encoding + * used for the servlet response's writer to the client if the protocol + * provides a way for doing so. In the case of HTTP, the + * Content-Type header is used. + * + * @param type + * a String specifying the MIME type of the content + * @see #setLocale + * @see #setCharacterEncoding + * @see #getOutputStream + * @see #getWriter */ - public void setContentType(String type); - /** - * Sets the preferred buffer size for the body of the response. - * The servlet container will use a buffer at least as large as - * the size requested. The actual buffer size used can be found - * using getBufferSize. - * - *

A larger buffer allows more content to be written before anything is + * Sets the preferred buffer size for the body of the response. The servlet + * container will use a buffer at least as large as the size requested. The + * actual buffer size used can be found using getBufferSize. + *

+ * A larger buffer allows more content to be written before anything is * actually sent, thus providing the servlet with more time to set - * appropriate status codes and headers. A smaller buffer decreases - * server memory load and allows the client to start receiving data more - * quickly. - * - *

This method must be called before any response body content is - * written; if content has been written or the response object has - * been committed, this method throws an - * IllegalStateException. - * - * @param size the preferred buffer size - * - * @exception IllegalStateException if this method is called after - * content has been written - * - * @see #getBufferSize - * @see #flushBuffer - * @see #isCommitted - * @see #reset - * + * appropriate status codes and headers. A smaller buffer decreases server + * memory load and allows the client to start receiving data more quickly. + *

+ * This method must be called before any response body content is written; + * if content has been written or the response object has been committed, + * this method throws an IllegalStateException. + * + * @param size + * the preferred buffer size + * @exception IllegalStateException + * if this method is called after content has been written + * @see #getBufferSize + * @see #flushBuffer + * @see #isCommitted + * @see #reset */ - public void setBufferSize(int size); - - /** - * Returns the actual buffer size used for the response. If no buffering - * is used, this method returns 0. - * - * @return the actual buffer size used - * - * @see #setBufferSize - * @see #flushBuffer - * @see #isCommitted - * @see #reset - * + * Returns the actual buffer size used for the response. If no buffering is + * used, this method returns 0. + * + * @return the actual buffer size used + * @see #setBufferSize + * @see #flushBuffer + * @see #isCommitted + * @see #reset */ - public int getBufferSize(); - - /** - * Forces any content in the buffer to be written to the client. A call - * to this method automatically commits the response, meaning the status - * code and headers will be written. - * - * @see #setBufferSize - * @see #getBufferSize - * @see #isCommitted - * @see #reset - * + * Forces any content in the buffer to be written to the client. A call to + * this method automatically commits the response, meaning the status code + * and headers will be written. + * + * @see #setBufferSize + * @see #getBufferSize + * @see #isCommitted + * @see #reset */ - public void flushBuffer() throws IOException; - - - + /** * Clears the content of the underlying buffer in the response without - * clearing headers or status code. If the - * response has been committed, this method throws an - * IllegalStateException. - * - * @see #setBufferSize - * @see #getBufferSize - * @see #isCommitted - * @see #reset - * + * clearing headers or status code. If the response has been committed, this + * method throws an IllegalStateException. + * + * @see #setBufferSize + * @see #getBufferSize + * @see #isCommitted + * @see #reset * @since 2.3 */ - public void resetBuffer(); - /** - * Returns a boolean indicating if the response has been - * committed. A committed response has already had its status - * code and headers written. - * - * @return a boolean indicating if the response has been - * committed - * - * @see #setBufferSize - * @see #getBufferSize - * @see #flushBuffer - * @see #reset - * + * Returns a boolean indicating if the response has been committed. A + * committed response has already had its status code and headers written. + * + * @return a boolean indicating if the response has been committed + * @see #setBufferSize + * @see #getBufferSize + * @see #flushBuffer + * @see #reset */ - public boolean isCommitted(); - - /** * Clears any data that exists in the buffer as well as the status code and - * headers. If the response has been committed, this method throws an + * headers. If the response has been committed, this method throws an * IllegalStateException. - * - * @exception IllegalStateException if the response has already been - * committed - * - * @see #setBufferSize - * @see #getBufferSize - * @see #flushBuffer - * @see #isCommitted - * + * + * @exception IllegalStateException + * if the response has already been committed + * @see #setBufferSize + * @see #getBufferSize + * @see #flushBuffer + * @see #isCommitted */ - public void reset(); - - /** - * Sets the locale of the response, if the response has not been - * committed yet. It also sets the response's character encoding - * appropriately for the locale, if the character encoding has not - * been explicitly set using {@link #setContentType} or - * {@link #setCharacterEncoding}, getWriter hasn't - * been called yet, and the response hasn't been committed yet. - * If the deployment descriptor contains a - * locale-encoding-mapping-list element, and that - * element provides a mapping for the given locale, that mapping - * is used. Otherwise, the mapping from locale to character - * encoding is container dependent. - *

This method may be called repeatedly to change locale and - * character encoding. The method has no effect if called after the - * response has been committed. It does not set the response's - * character encoding if it is called after {@link #setContentType} - * has been called with a charset specification, after - * {@link #setCharacterEncoding} has been called, after - * getWriter has been called, or after the response - * has been committed. - *

Containers must communicate the locale and the character encoding - * used for the servlet response's writer to the client if the protocol - * provides a way for doing so. In the case of HTTP, the locale is - * communicated via the Content-Language header, - * the character encoding as part of the Content-Type - * header for text media types. Note that the character encoding - * cannot be communicated via HTTP headers if the servlet does not - * specify a content type; however, it is still used to encode text - * written via the servlet response's writer. + * Sets the locale of the response, if the response has not been committed + * yet. It also sets the response's character encoding appropriately for the + * locale, if the character encoding has not been explicitly set using + * {@link #setContentType} or {@link #setCharacterEncoding}, + * getWriter hasn't been called yet, and the response hasn't + * been committed yet. If the deployment descriptor contains a + * locale-encoding-mapping-list element, and that element + * provides a mapping for the given locale, that mapping is used. Otherwise, + * the mapping from locale to character encoding is container dependent. + *

+ * This method may be called repeatedly to change locale and character + * encoding. The method has no effect if called after the response has been + * committed. It does not set the response's character encoding if it is + * called after {@link #setContentType} has been called with a charset + * specification, after {@link #setCharacterEncoding} has been called, after + * getWriter has been called, or after the response has been + * committed. + *

+ * Containers must communicate the locale and the character encoding used + * for the servlet response's writer to the client if the protocol provides + * a way for doing so. In the case of HTTP, the locale is communicated via + * the Content-Language header, the character encoding as part + * of the Content-Type header for text media types. Note that + * the character encoding cannot be communicated via HTTP headers if the + * servlet does not specify a content type; however, it is still used to + * encode text written via the servlet response's writer. * - * @param loc the locale of the response - * - * @see #getLocale - * @see #setContentType - * @see #setCharacterEncoding - * + * @param loc + * the locale of the response + * @see #getLocale + * @see #setContentType + * @see #setCharacterEncoding */ - public void setLocale(Locale loc); - - /** - * Returns the locale specified for this response - * using the {@link #setLocale} method. Calls made to - * setLocale after the response is committed - * have no effect. If no locale has been specified, + * Returns the locale specified for this response using the + * {@link #setLocale} method. Calls made to setLocale after the + * response is committed have no effect. If no locale has been specified, * the container's default locale is returned. * - * @see #setLocale - * + * @see #setLocale */ - public Locale getLocale(); - - } - - - - - diff --git a/java/javax/servlet/ServletResponseWrapper.java b/java/javax/servlet/ServletResponseWrapper.java index 47230e76d..81ea47c57 100644 --- a/java/javax/servlet/ServletResponseWrapper.java +++ b/java/javax/servlet/ServletResponseWrapper.java @@ -1,19 +1,19 @@ /* -* 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; import java.io.IOException; @@ -21,231 +21,204 @@ import java.io.PrintWriter; import java.util.Locale; /** - * * Provides a convenient implementation of the ServletResponse 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.ServletResponse - * + * @author Various + * @version $Version$ + * @since v 2.3 + * @see javax.servlet.ServletResponse */ - - public class ServletResponseWrapper implements ServletResponse { - private ServletResponse response; - /** - * Creates a ServletResponse adaptor wrapping the given response object. - * @throws java.lang.IllegalArgumentException if the response is null. - */ - - - public ServletResponseWrapper(ServletResponse response) { - if (response == null) { - throw new IllegalArgumentException("Response cannot be null"); - } - this.response = response; - } - - /** - * Return the wrapped ServletResponse object. - */ - - public ServletResponse getResponse() { - return this.response; - } - - - /** - * Sets the response being wrapped. - * @throws java.lang.IllegalArgumentException if the response is null. - */ - - public void setResponse(ServletResponse response) { - if (response == null) { - throw new IllegalArgumentException("Response cannot be null"); - } - this.response = response; - } - - /** - * The default behavior of this method is to call setCharacterEncoding(String charset) - * on the wrapped response object. - * - * @since 2.4 + private ServletResponse response; + + /** + * Creates a ServletResponse adaptor wrapping the given response object. + * + * @throws java.lang.IllegalArgumentException + * if the response is null. */ + public ServletResponseWrapper(ServletResponse response) { + if (response == null) { + throw new IllegalArgumentException("Response cannot be null"); + } + this.response = response; + } - public void setCharacterEncoding(String charset) { - this.response.setCharacterEncoding(charset); + /** + * Return the wrapped ServletResponse object. + */ + public ServletResponse getResponse() { + return this.response; } /** - * The default behavior of this method is to return getCharacterEncoding() - * on the wrapped response object. + * Sets the response being wrapped. + * + * @throws java.lang.IllegalArgumentException + * if the response is null. */ + public void setResponse(ServletResponse response) { + if (response == null) { + throw new IllegalArgumentException("Response cannot be null"); + } + this.response = response; + } - public String getCharacterEncoding() { - return this.response.getCharacterEncoding(); - } - - - /** - * The default behavior of this method is to return getOutputStream() - * on the wrapped response object. + /** + * The default behavior of this method is to call + * setCharacterEncoding(String charset) on the wrapped response object. + * + * @since 2.4 */ + public void setCharacterEncoding(String charset) { + this.response.setCharacterEncoding(charset); + } - public ServletOutputStream getOutputStream() throws IOException { - return this.response.getOutputStream(); - } - - /** - * The default behavior of this method is to return getWriter() + /** + * The default behavior of this method is to return getCharacterEncoding() * on the wrapped response object. */ + public String getCharacterEncoding() { + return this.response.getCharacterEncoding(); + } + /** + * The default behavior of this method is to return getOutputStream() on the + * wrapped response object. + */ + public ServletOutputStream getOutputStream() throws IOException { + return this.response.getOutputStream(); + } + /** + * The default behavior of this method is to return getWriter() on the + * wrapped response object. + */ public PrintWriter getWriter() throws IOException { - return this.response.getWriter(); - } - + return this.response.getWriter(); + } + /** * The default behavior of this method is to call setContentLength(int len) * on the wrapped response object. */ - public void setContentLength(int len) { - this.response.setContentLength(len); + this.response.setContentLength(len); } - + /** - * The default behavior of this method is to call setContentType(String type) - * on the wrapped response object. + * The default behavior of this method is to call setContentType(String + * type) on the wrapped response object. */ - public void setContentType(String type) { - this.response.setContentType(type); + this.response.setContentType(type); } /** - * The default behavior of this method is to return getContentType() - * on the wrapped response object. - * + * The default behavior of this method is to return getContentType() on the + * wrapped response object. + * * @since 2.4 */ - public String getContentType() { - return this.response.getContentType(); + return this.response.getContentType(); } - + /** - * The default behavior of this method is to call setBufferSize(int size) - * on the wrapped response object. + * The default behavior of this method is to call setBufferSize(int size) on + * the wrapped response object. */ public void setBufferSize(int size) { - this.response.setBufferSize(size); + this.response.setBufferSize(size); } - + /** - * The default behavior of this method is to return getBufferSize() - * on the wrapped response object. + * The default behavior of this method is to return getBufferSize() on the + * wrapped response object. */ public int getBufferSize() { - return this.response.getBufferSize(); + return this.response.getBufferSize(); } /** - * The default behavior of this method is to call flushBuffer() - * on the wrapped response object. + * The default behavior of this method is to call flushBuffer() on the + * wrapped response object. */ - public void flushBuffer() throws IOException { - this.response.flushBuffer(); + this.response.flushBuffer(); } - + /** - * The default behavior of this method is to return isCommitted() - * on the wrapped response object. + * The default behavior of this method is to return isCommitted() on the + * wrapped response object. */ public boolean isCommitted() { - return this.response.isCommitted(); + return this.response.isCommitted(); } /** - * The default behavior of this method is to call reset() - * on the wrapped response object. + * The default behavior of this method is to call reset() on the wrapped + * response object. */ - public void reset() { - this.response.reset(); + this.response.reset(); } - + /** - * The default behavior of this method is to call resetBuffer() - * on the wrapped response object. + * The default behavior of this method is to call resetBuffer() on the + * wrapped response object. */ - public void resetBuffer() { - this.response.resetBuffer(); + this.response.resetBuffer(); } - + /** - * The default behavior of this method is to call setLocale(Locale loc) - * on the wrapped response object. + * The default behavior of this method is to call setLocale(Locale loc) on + * the wrapped response object. */ - public void setLocale(Locale loc) { - this.response.setLocale(loc); + this.response.setLocale(loc); } - + /** - * The default behavior of this method is to return getLocale() - * on the wrapped response object. + * The default behavior of this method is to return getLocale() on the + * wrapped response object. */ public Locale getLocale() { - return this.response.getLocale(); + return this.response.getLocale(); } /** - * * @param wrapped - * @since Servlet 3.0 - * TODO SERVLET3 - Add comments + * @since Servlet 3.0 TODO SERVLET3 - Add comments */ public boolean isWrapperFor(ServletResponse wrapped) { if (response == wrapped) { return true; } if (response instanceof ServletResponseWrapper) { - return ((ServletResponseWrapper)response).isWrapperFor(wrapped); + return ((ServletResponseWrapper) response).isWrapperFor(wrapped); } return false; } - + /** - * * @param wrappedType - * @since Servlet 3.0 - * TODO SERVLET3 - Add comments + * @since Servlet 3.0 TODO SERVLET3 - Add comments */ - @SuppressWarnings("unchecked") // Spec API does not use generics + @SuppressWarnings("unchecked") + // Spec API does not use generics public boolean isWrapperFor(Class wrappedType) { if (wrappedType.isAssignableFrom(response.getClass())) { return true; } if (response instanceof ServletResponseWrapper) { - return ((ServletResponseWrapper)response).isWrapperFor(wrappedType); + return ((ServletResponseWrapper) response).isWrapperFor(wrappedType); } return false; } - } - - - - - diff --git a/java/javax/servlet/SingleThreadModel.java b/java/javax/servlet/SingleThreadModel.java index 60ac99f46..4f2bb8e12 100644 --- a/java/javax/servlet/SingleThreadModel.java +++ b/java/javax/servlet/SingleThreadModel.java @@ -1,50 +1,46 @@ /* -* 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; /** - * Ensures that servlets handle - * only one request at a time. This interface has no methods. - * - *

If a servlet implements this interface, you are guaranteed - * that no two threads will execute concurrently in the - * servlet's service method. The servlet container - * can make this guarantee by synchronizing access to a single - * instance of the servlet, or by maintaining a pool of servlet + * Ensures that servlets handle only one request at a time. This interface has + * no methods. + *

+ * If a servlet implements this interface, you are guaranteed that no two + * threads will execute concurrently in the servlet's service + * method. The servlet container can make this guarantee by synchronizing access + * to a single instance of the servlet, or by maintaining a pool of servlet * instances and dispatching each new request to a free servlet. - * - *

Note that SingleThreadModel does not solve all thread safety - * issues. For example, session attributes and static variables can - * still be accessed by multiple requests on multiple threads - * at the same time, even when SingleThreadModel servlets are used. - * It is recommended that a developer take other means to resolve - * those issues instead of implementing this interface, such as - * avoiding the usage of an instance variable or synchronizing - * the block of the code accessing those resources. - * This interface is deprecated in Servlet API version 2.4. - * - * - * @author Various - * @version $Version$ - * - * @deprecated As of Java Servlet API 2.4, with no direct - * replacement. + *

+ * Note that SingleThreadModel does not solve all thread safety issues. For + * example, session attributes and static variables can still be accessed by + * multiple requests on multiple threads at the same time, even when + * SingleThreadModel servlets are used. It is recommended that a developer take + * other means to resolve those issues instead of implementing this interface, + * such as avoiding the usage of an instance variable or synchronizing the block + * of the code accessing those resources. This interface is deprecated in + * Servlet API version 2.4. + * + * @author Various + * @version $Version$ + * @deprecated As of Java Servlet API 2.4, with no direct replacement. */ -@SuppressWarnings("dep-ann") // Spec API does not use @Deprecated +@SuppressWarnings("dep-ann") +// Spec API does not use @Deprecated public interface SingleThreadModel { // No methods } diff --git a/java/javax/servlet/UnavailableException.java b/java/javax/servlet/UnavailableException.java index 88efff761..6e1a979ea 100644 --- a/java/javax/servlet/UnavailableException.java +++ b/java/javax/servlet/UnavailableException.java @@ -1,203 +1,177 @@ /* -* 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; - /** - * Defines an exception that a servlet or filter throws to indicate - * that it is permanently or temporarily unavailable. - * - *

When a servlet or filter is permanently unavailable, something is wrong - * with it, and it cannot handle - * requests until some action is taken. For example, a servlet - * might be configured incorrectly, or a filter's state may be corrupted. - * The component should log both the error and the corrective action + * Defines an exception that a servlet or filter throws to indicate that it is + * permanently or temporarily unavailable. + *

+ * When a servlet or filter is permanently unavailable, something is wrong with + * it, and it cannot handle requests until some action is taken. For example, a + * servlet might be configured incorrectly, or a filter's state may be + * corrupted. The component should log both the error and the corrective action * that is needed. - * - *

A servlet or filter is temporarily unavailable if it cannot handle - * requests momentarily due to some system-wide problem. For example, - * a third-tier server might not be accessible, or there may be - * insufficient memory or disk storage to handle requests. A system - * administrator may need to take corrective action. - * - *

Servlet containers can safely treat both types of unavailable - * exceptions in the same way. However, treating temporary unavailability - * effectively makes the servlet container more robust. Specifically, - * the servlet container might block requests to the servlet or filter for a period - * of time suggested by the exception, rather than rejecting them until - * the servlet container restarts. - * - * - * @author Various - * @version $Version$ - * + *

+ * A servlet or filter is temporarily unavailable if it cannot handle requests + * momentarily due to some system-wide problem. For example, a third-tier server + * might not be accessible, or there may be insufficient memory or disk storage + * to handle requests. A system administrator may need to take corrective + * action. + *

+ * Servlet containers can safely treat both types of unavailable exceptions in + * the same way. However, treating temporary unavailability effectively makes + * the servlet container more robust. Specifically, the servlet container might + * block requests to the servlet or filter for a period of time suggested by the + * exception, rather than rejecting them until the servlet container restarts. + * + * @author Various + * @version $Version$ */ +public class UnavailableException extends ServletException { -public class UnavailableException -extends ServletException { - - private Servlet servlet; // what's unavailable - private boolean permanent; // needs admin action? - private int seconds; // unavailability estimate + private Servlet servlet; // what's unavailable + private boolean permanent; // needs admin action? + private int seconds; // unavailability estimate /** - * @param servlet the Servlet instance that is - * unavailable - * - * @param msg a String specifying the - * descriptive message - * - * @deprecated As of Java Servlet API 2.2, use {@link - * #UnavailableException(String)} instead. + * @param servlet + * the Servlet instance that is unavailable + * @param msg + * a String specifying the descriptive message + * @deprecated As of Java Servlet API 2.2, use + * {@link #UnavailableException(String)} instead. */ - @SuppressWarnings("dep-ann") // Spec API does not use @Deprecated + @SuppressWarnings("dep-ann") + // Spec API does not use @Deprecated public UnavailableException(Servlet servlet, String msg) { - super(msg); - this.servlet = servlet; - permanent = true; + super(msg); + this.servlet = servlet; + permanent = true; } - + /** - * - * @param seconds an integer specifying the number of seconds - * the servlet expects to be unavailable; if - * zero or negative, indicates that the servlet - * can't make an estimate - * - * @param servlet the Servlet that is unavailable - * - * @param msg a String specifying the descriptive - * message, which can be written to a log file or - * displayed for the user. - * - * @deprecated As of Java Servlet API 2.2, use {@link - * #UnavailableException(String, int)} instead. + * @param seconds + * an integer specifying the number of seconds the servlet + * expects to be unavailable; if zero or negative, indicates that + * the servlet can't make an estimate + * @param servlet + * the Servlet that is unavailable + * @param msg + * a String specifying the descriptive message, + * which can be written to a log file or displayed for the user. + * @deprecated As of Java Servlet API 2.2, use + * {@link #UnavailableException(String, int)} instead. */ - @SuppressWarnings("dep-ann") // Spec API does not use @Deprecated + @SuppressWarnings("dep-ann") + // Spec API does not use @Deprecated public UnavailableException(int seconds, Servlet servlet, String msg) { - super(msg); - this.servlet = servlet; - if (seconds <= 0) - this.seconds = -1; - else - this.seconds = seconds; - permanent = false; + super(msg); + this.servlet = servlet; + if (seconds <= 0) + this.seconds = -1; + else + this.seconds = seconds; + permanent = false; } /** + * Constructs a new exception with a descriptive message indicating that the + * servlet is permanently unavailable. * - * Constructs a new exception with a descriptive - * message indicating that the servlet is permanently - * unavailable. - * - * @param msg a String specifying the - * descriptive message - * + * @param msg + * a String specifying the descriptive message */ - public UnavailableException(String msg) { - super(msg); + super(msg); - permanent = true; + permanent = true; } /** - * Constructs a new exception with a descriptive message - * indicating that the servlet is temporarily unavailable - * and giving an estimate of how long it will be unavailable. + * Constructs a new exception with a descriptive message indicating that the + * servlet is temporarily unavailable and giving an estimate of how long it + * will be unavailable. + *

+ * In some cases, the servlet cannot make an estimate. For example, the + * servlet might know that a server it needs is not running, but not be able + * to report how long it will take to be restored to functionality. This can + * be indicated with a negative or zero value for the seconds + * argument. * - *

In some cases, the servlet cannot make an estimate. For - * example, the servlet might know that a server it needs is - * not running, but not be able to report how long it will take - * to be restored to functionality. This can be indicated with - * a negative or zero value for the seconds argument. - * - * @param msg a String specifying the - * descriptive message, which can be written - * to a log file or displayed for the user. - * - * @param seconds an integer specifying the number of seconds - * the servlet expects to be unavailable; if - * zero or negative, indicates that the servlet - * can't make an estimate - * + * @param msg + * a String specifying the descriptive message, + * which can be written to a log file or displayed for the user. + * @param seconds + * an integer specifying the number of seconds the servlet + * expects to be unavailable; if zero or negative, indicates that + * the servlet can't make an estimate */ - public UnavailableException(String msg, int seconds) { - super(msg); + super(msg); - if (seconds <= 0) - this.seconds = -1; - else - this.seconds = seconds; + if (seconds <= 0) + this.seconds = -1; + else + this.seconds = seconds; - permanent = false; + permanent = false; } /** - * - * Returns a boolean indicating - * whether the servlet is permanently unavailable. - * If so, something is wrong with the servlet, and the - * system administrator must take some corrective action. - * - * @return true if the servlet is - * permanently unavailable; false - * if the servlet is available or temporarily - * unavailable - * + * Returns a boolean indicating whether the servlet is + * permanently unavailable. If so, something is wrong with the servlet, and + * the system administrator must take some corrective action. + * + * @return true if the servlet is permanently unavailable; + * false if the servlet is available or temporarily + * unavailable */ - public boolean isPermanent() { - return permanent; + return permanent; } - + /** * Returns the servlet that is reporting its unavailability. * - * @return the Servlet object that is - * throwing the UnavailableException - * - * @deprecated As of Java Servlet API 2.2, with no replacement. + * @return the Servlet object that is throwing the + * UnavailableException + * @deprecated As of Java Servlet API 2.2, with no replacement. */ - @SuppressWarnings("dep-ann") // Spec API does not use @Deprecated + @SuppressWarnings("dep-ann") + // Spec API does not use @Deprecated public Servlet getServlet() { - return servlet; + return servlet; } /** - * Returns the number of seconds the servlet expects to - * be temporarily unavailable. - * - *

If this method returns a negative number, the servlet - * is permanently unavailable or cannot provide an estimate of - * how long it will be unavailable. No effort is - * made to correct for the time elapsed since the exception was - * first reported. - * - * @return an integer specifying the number of seconds - * the servlet will be temporarily unavailable, - * or a negative number if the servlet is permanently - * unavailable or cannot make an estimate - * + * Returns the number of seconds the servlet expects to be temporarily + * unavailable. + *

+ * If this method returns a negative number, the servlet is permanently + * unavailable or cannot provide an estimate of how long it will be + * unavailable. No effort is made to correct for the time elapsed since the + * exception was first reported. + * + * @return an integer specifying the number of seconds the servlet will be + * temporarily unavailable, or a negative number if the servlet is + * permanently unavailable or cannot make an estimate */ - public int getUnavailableSeconds() { - return permanent ? -1 : seconds; + return permanent ? -1 : seconds; } } -- 2.11.0