/*
-* 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 <code>String</code> containing the value of the
- * named initialization parameter, or <code>null</code> if
- * the parameter does not exist.
- *
- * @param name a <code>String</code> specifying the name
- * of the initialization parameter
- *
- * @return a <code>String</code> containing the value
- * of the initialization parameter
- *
+ * Returns a <code>String</code> containing the value of the named
+ * initialization parameter, or <code>null</code> if the parameter does not
+ * exist.
+ *
+ * @param name
+ * a <code>String</code> specifying the name of the
+ * initialization parameter
+ * @return a <code>String</code> containing the value of the initialization
+ * parameter
*/
-
public String getInitParameter(String name);
-
/**
- * Returns the names of the servlet's initialization parameters
- * as an <code>Enumeration</code> of <code>String</code> objects,
- * or an empty <code>Enumeration</code> if the servlet has
- * no initialization parameters.
- *
- * @return an <code>Enumeration</code> of <code>String</code>
- * objects containing the names of the servlet's
- * initialization parameters
- *
- *
- *
+ * Returns the names of the servlet's initialization parameters as an
+ * <code>Enumeration</code> of <code>String</code> objects, or an empty
+ * <code>Enumeration</code> if the servlet has no initialization parameters.
+ *
+ * @return an <code>Enumeration</code> of <code>String</code> objects
+ * containing the names of the servlet's initialization parameters
*/
-
public Enumeration<String> getInitParameterNames();
-
-
}
/*
-* 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 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.
- *
- * <p>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.
+ * <p>
+ * 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 <code>/catalog</code>
- * and possibly installed via a <code>.war</code> file.)
- *
- * <p>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.
- *
- * <p>The <code>ServletContext</code> 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 <code>.war</code> file.)
+ * <p>
+ * 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.
+ * <p>
+ * The <code>ServletContext</code> 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 <code>ServletContext</code> object that
- * corresponds to a specified URL on the server.
- *
- * <p>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 <code>ServletContext</code> object that corresponds to a
+ * specified URL on the server.
+ * <p>
+ * 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.
+ * <p>
+ * In a security conscious environment, the servlet container may return
+ * <code>null</code> for a given URL.
*
- * <p>In a security conscious environment, the servlet container may
- * return <code>null</code> for a given URL.
- *
- * @param uripath a <code>String</code> specifying the context path of
- * another web application in the container.
- * @return the <code>ServletContext</code> 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 <code>String</code> specifying the context path of another
+ * web application in the container.
+ * @return the <code>ServletContext</code> 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 <code>null</code> 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 <code>"text/html"</code> and <code>"image/gif"</code>.
- *
- *
- * @param file a <code>String</code> specifying the name
- * of a file
- *
- * @return a <code>String</code> specifying the file's MIME type
- *
+ * Returns the MIME type of the specified file, or <code>null</code> 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 <code>"text/html"</code> and
+ * <code>"image/gif"</code>.
+ *
+ * @param file
+ * a <code>String</code> specifying the name of a file
+ * @return a <code>String</code> 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<br><br>
-
- * /welcome.html<br>
- * /catalog/index.html<br>
- * /catalog/products.html<br>
- * /catalog/offers/books.html<br>
- * /catalog/offers/music.html<br>
- * /customer/login.jsp<br>
- * /WEB-INF/web.xml<br>
- * /WEB-INF/classes/com.acme.OrderServlet.class,<br><br>
- *
- * getResourcePaths("/") returns {"/welcome.html", "/catalog/", "/customer/", "/WEB-INF/"}<br>
- * getResourcePaths("/catalog/") returns {"/catalog/index.html", "/catalog/products.html", "/catalog/offers/"}.<br>
-
-
-
- *@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<br>
+ * <br>
+ * /welcome.html<br>
+ * /catalog/index.html<br>
+ * /catalog/products.html<br>
+ * /catalog/offers/books.html<br>
+ * /catalog/offers/music.html<br>
+ * /customer/login.jsp<br>
+ * /WEB-INF/web.xml<br>
+ * /WEB-INF/classes/com.acme.OrderServlet.class,<br>
+ * <br>
+ * getResourcePaths("/") returns {"/welcome.html", "/catalog/",
+ * "/customer/", "/WEB-INF/"}<br>
+ * getResourcePaths("/catalog/") returns {"/catalog/index.html",
+ * "/catalog/products.html", "/catalog/offers/"}.<br>
+ *
+ * @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<String> 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.
- *
- * <p>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 <code>.war</code> file.
- *
- * <p>The servlet container must implement the URL handlers
- * and <code>URLConnection</code> objects that are necessary
- * to access the resource.
- *
- * <p>This method returns <code>null</code>
- * if no resource is mapped to the pathname.
- *
- * <p>Some containers may allow writing to the URL returned by
- * this method using the methods of the URL class.
- *
- * <p>The resource content is returned directly, so be aware that
- * requesting a <code>.jsp</code> page returns the JSP source code.
- * Use a <code>RequestDispatcher</code> instead to include results of
- * an execution.
- *
- * <p>This method has a different purpose than
- * <code>java.lang.Class.getResource</code>,
- * 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.
+ * <p>
+ * 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 <code>.war</code> file.
+ * <p>
+ * The servlet container must implement the URL handlers and
+ * <code>URLConnection</code> objects that are necessary to access the
+ * resource.
+ * <p>
+ * This method returns <code>null</code> if no resource is mapped to the
+ * pathname.
+ * <p>
+ * Some containers may allow writing to the URL returned by this method
+ * using the methods of the URL class.
+ * <p>
+ * The resource content is returned directly, so be aware that requesting a
+ * <code>.jsp</code> page returns the JSP source code. Use a
+ * <code>RequestDispatcher</code> instead to include results of an
+ * execution.
+ * <p>
+ * This method has a different purpose than
+ * <code>java.lang.Class.getResource</code>, which looks up resources based
+ * on a class loader. This method does not use class loaders.
*
- * @param path a <code>String</code> specifying
- * the path to the resource
- *
- * @return the resource located at the named path,
- * or <code>null</code> if there is no resource
- * at that path
- *
- * @exception MalformedURLException if the pathname is not given in
- * the correct form
- *
- */
-
+ * @param path
+ * a <code>String</code> specifying the path to the resource
+ * @return the resource located at the named path, or <code>null</code> 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 <code>InputStream</code> object.
- *
- * <p>The data in the <code>InputStream</code> can be
- * of any type or length. The path must be specified according
- * to the rules given in <code>getResource</code>.
- * This method returns <code>null</code> if no resource exists at
- * the specified path.
- *
- * <p>Meta-information such as content length and content type
- * that is available via <code>getResource</code>
- * method is lost when using this method.
- *
- * <p>The servlet container must implement the URL handlers
- * and <code>URLConnection</code> objects necessary to access
- * the resource.
- *
- * <p>This method is different from
- * <code>java.lang.Class.getResourceAsStream</code>,
- * 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
+ * <code>InputStream</code> object.
+ * <p>
+ * The data in the <code>InputStream</code> can be of any type or length.
+ * The path must be specified according to the rules given in
+ * <code>getResource</code>. This method returns <code>null</code> if no
+ * resource exists at the specified path.
+ * <p>
+ * Meta-information such as content length and content type that is
+ * available via <code>getResource</code> method is lost when using this
+ * method.
+ * <p>
+ * The servlet container must implement the URL handlers and
+ * <code>URLConnection</code> objects necessary to access the resource.
+ * <p>
+ * This method is different from
+ * <code>java.lang.Class.getResourceAsStream</code>, 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 <code>String</code> specifying the path
- * to the resource
- *
- * @return the <code>InputStream</code> returned to the
- * servlet, or <code>null</code> if no resource
- * exists at the specified path
- *
- *
+ * @param path
+ * a <code>String</code> specifying the path to the resource
+ * @return the <code>InputStream</code> returned to the servlet, or
+ * <code>null</code> 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 <code>RequestDispatcher</code> 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.
- *
- * <p>The pathname must begin with a "/" and is interpreted as relative
- * to the current context root. Use <code>getContext</code> to obtain
- * a <code>RequestDispatcher</code> for resources in foreign contexts.
- * This method returns <code>null</code> if the <code>ServletContext</code>
+ * Returns a {@link RequestDispatcher} object that acts as a wrapper for the
+ * resource located at the given path. A <code>RequestDispatcher</code>
+ * 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.
+ * <p>
+ * The pathname must begin with a "/" and is interpreted as relative to the
+ * current context root. Use <code>getContext</code> to obtain a
+ * <code>RequestDispatcher</code> for resources in foreign contexts. This
+ * method returns <code>null</code> if the <code>ServletContext</code>
* cannot return a <code>RequestDispatcher</code>.
- *
- * @param path a <code>String</code> specifying the pathname
- * to the resource
- *
- * @return a <code>RequestDispatcher</code> object
- * that acts as a wrapper for the resource
- * at the specified path, or <code>null</code> if
- * the <code>ServletContext</code> cannot return
- * a <code>RequestDispatcher</code>
- *
- * @see RequestDispatcher
- * @see ServletContext#getContext
- *
+ *
+ * @param path
+ * a <code>String</code> specifying the pathname to the resource
+ * @return a <code>RequestDispatcher</code> object that acts as a wrapper for
+ * the resource at the specified path, or <code>null</code> if the
+ * <code>ServletContext</code> cannot return a
+ * <code>RequestDispatcher</code>
+ * @see RequestDispatcher
+ * @see ServletContext#getContext
*/
-
public RequestDispatcher getRequestDispatcher(String path);
-
-
/**
- * Returns a {@link RequestDispatcher} object that acts
- * as a wrapper for the named servlet.
- *
- * <p>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.
+ * <p>
+ * 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}.
- *
- * <p>This method returns <code>null</code> if the
- * <code>ServletContext</code>
+ * <p>
+ * This method returns <code>null</code> if the <code>ServletContext</code>
* cannot return a <code>RequestDispatcher</code> for any reason.
- *
- * @param name a <code>String</code> specifying the name
- * of a servlet to wrap
- *
- * @return a <code>RequestDispatcher</code> object
- * that acts as a wrapper for the named servlet,
- * or <code>null</code> if the <code>ServletContext</code>
- * cannot return a <code>RequestDispatcher</code>
- *
- * @see RequestDispatcher
- * @see ServletContext#getContext
- * @see ServletConfig#getServletName
- *
+ *
+ * @param name
+ * a <code>String</code> specifying the name of a servlet to wrap
+ * @return a <code>RequestDispatcher</code> object that acts as a wrapper for
+ * the named servlet, or <code>null</code> if the
+ * <code>ServletContext</code> cannot return a
+ * <code>RequestDispatcher</code>
+ * @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.
- *
- * <p>This method was originally defined to retrieve a servlet
- * from a <code>ServletContext</code>. In this version, this method
- * always returns <code>null</code> and remains only to preserve
- * binary compatibility. This method will be permanently removed
- * in a future version of the Java Servlet API.
- *
- * <p>In lieu of this method, servlets can share information using the
- * <code>ServletContext</code> 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.
+ * <p>
+ * This method was originally defined to retrieve a servlet from
+ * a <code>ServletContext</code>. In this version, this method
+ * always returns <code>null</code> and remains only to preserve
+ * binary compatibility. This method will be permanently removed
+ * in a future version of the Java Servlet API.
+ * <p>
+ * In lieu of this method, servlets can share information using
+ * the <code>ServletContext</code> 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.
- *
- * <p>This method was originally defined to return an <code>Enumeration</code>
- * 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.
+ * <p>
+ * This method was originally defined to return an
+ * <code>Enumeration</code> 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<Servlet> getServlets();
-
-
-
-
-
-
- /**
- * @deprecated As of Java Servlet API 2.1, with no replacement.
- *
- * <p>This method was originally defined to return an
- * <code>Enumeration</code>
- * of all the servlet names known to this context. In this version,
- * this method always returns an empty <code>Enumeration</code> 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.
+ * <p>
+ * This method was originally defined to return an
+ * <code>Enumeration</code> of all the servlet names known to
+ * this context. In this version, this method always returns an
+ * empty <code>Enumeration</code> 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<String> 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 <code>String</code> 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.
- *
- * <p>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 <code>String</code> 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.
+ * <p>
+ * 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 <code>Throwable</code> 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 <code>String</code> that
- * describes the error or exception
- *
- * @param throwable the <code>Throwable</code> error
- * or exception
- *
- */
-
- public void log(String message, Throwable throwable);
-
-
-
-
-
- /**
- * Returns a <code>String</code> 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..
- *
- * <p>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 <code>null</code>
- * 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 <code>.war</code> archive).
- *
- *
- * @param path a <code>String</code> specifying a virtual path
- *
- *
- * @return a <code>String</code> specifying the real path,
- * or null if the translation cannot be performed
- *
- *
+
+ /**
+ * Writes an explanatory message and a stack trace for a given
+ * <code>Throwable</code> 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 <code>String</code> that describes the error or exception
+ * @param throwable
+ * the <code>Throwable</code> error or exception
*/
+ public void log(String message, Throwable throwable);
+ /**
+ * Returns a <code>String</code> 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..
+ * <p>
+ * 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 <code>null</code> 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
+ * <code>.war</code> archive).
+ *
+ * @param path
+ * a <code>String</code> specifying a virtual path
+ * @return a <code>String</code> 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.
- *
- * <p>The form of the returned string is
- * <i>servername</i>/<i>versionnumber</i>.
- * 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.
+ * <p>
+ * The form of the returned string is
+ * <i>servername</i>/<i>versionnumber</i>. For example, the JavaServer Web
+ * Development Kit may return the string
* <code>JavaServer Web Dev Kit/1.0</code>.
- *
- * <p>The servlet container may return other optional information
- * after the primary string in parentheses, for example,
+ * <p>
+ * The servlet container may return other optional information after the
+ * primary string in parentheses, for example,
* <code>JavaServer Web Dev Kit/1.0 (JDK 1.1.6; Windows NT 4.0 x86)</code>.
- *
- *
- * @return a <code>String</code> containing at least the
- * servlet container name and version number
- *
+ *
+ * @return a <code>String</code> containing at least the servlet container
+ * name and version number
*/
-
public String getServerInfo();
-
-
-
/**
* Returns a <code>String</code> containing the value of the named
- * context-wide initialization parameter, or <code>null</code> if the
+ * context-wide initialization parameter, or <code>null</code> if the
* parameter does not exist.
- *
- * <p>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 <code>String</code> containing the name of the
- * parameter whose value is requested
+ * <p>
+ * 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 <code>String</code> containing at least the
- * servlet container name and version number
- *
+ * @param name
+ * a <code>String</code> containing the name of the parameter
+ * whose value is requested
+ * @return a <code>String</code> 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
- * <code>Enumeration</code> of <code>String</code> objects, or an
- * empty <code>Enumeration</code> if the context has no initialization
- * parameters.
- *
- * @return an <code>Enumeration</code> of <code>String</code>
- * objects containing the names of the context's
- * initialization parameters
- *
+ * <code>Enumeration</code> of <code>String</code> objects, or an empty
+ * <code>Enumeration</code> if the context has no initialization parameters.
+ *
+ * @return an <code>Enumeration</code> of <code>String</code> objects
+ * containing the names of the context's initialization parameters
* @see ServletConfig#getInitParameter
*/
public Enumeration<String> 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 <code>null</code> 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
- * <code>getAttributeNames</code>.
- *
- * <p>The attribute is returned as a <code>java.lang.Object</code>
- * or some subclass.
- * Attribute names should follow the same convention as package
- * names. The Java Servlet API specification reserves names
- * matching <code>java.*</code>, <code>javax.*</code>,
- * and <code>sun.*</code>.
- *
- *
- * @param name a <code>String</code> specifying the name
- * of the attribute
- *
- * @return an <code>Object</code> containing the value
- * of the attribute, or <code>null</code>
- * if no attribute exists matching the given
- * name
- *
- * @see ServletContext#getAttributeNames
- *
- */
-
- public Object getAttribute(String name);
-
-
-
/**
- * Returns an <code>Enumeration</code> 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 <code>Enumeration</code> of attribute
- * names
- *
- * @see #getAttribute
- *
+ * Returns the servlet container attribute with the given name, or
+ * <code>null</code> 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 <code>getAttributeNames</code>.
+ * <p>
+ * The attribute is returned as a <code>java.lang.Object</code> or some
+ * subclass. Attribute names should follow the same convention as package
+ * names. The Java Servlet API specification reserves names matching
+ * <code>java.*</code>, <code>javax.*</code>, and <code>sun.*</code>.
+ *
+ * @param name
+ * a <code>String</code> specifying the name of the attribute
+ * @return an <code>Object</code> containing the value of the attribute, or
+ * <code>null</code> if no attribute exists matching the given name
+ * @see ServletContext#getAttributeNames
*/
+ public Object getAttribute(String name);
+ /**
+ * Returns an <code>Enumeration</code> 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 <code>Enumeration</code> of attribute names
+ * @see #getAttribute
+ */
public Enumeration<String> 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.
- * <p>If listeners are configured on the <code>ServletContext</code> 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.
+ * <p>
+ * If listeners are configured on the <code>ServletContext</code> the
* container notifies them accordingly.
* <p>
- * 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
* <code>removeAttribute()</code>.
+ * <p>
+ * Attribute names should follow the same convention as package names. The
+ * Java Servlet API specification reserves names matching
+ * <code>java.*</code>, <code>javax.*</code>, and <code>sun.*</code>.
*
- * <p>Attribute names should follow the same convention as package
- * names. The Java Servlet API specification reserves names
- * matching <code>java.*</code>, <code>javax.*</code>, and
- * <code>sun.*</code>.
- *
- *
- * @param name a <code>String</code> specifying the name
- * of the attribute
- *
- * @param object an <code>Object</code> representing the
- * attribute to be bound
- *
- *
- *
- */
-
+ * @param name
+ * a <code>String</code> specifying the name of the attribute
+ * @param object
+ * an <code>Object</code> 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 <code>null</code>.
-
- * <p>If listeners are configured on the <code>ServletContext</code> 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 <code>null</code>.
+ * <p>
+ * If listeners are configured on the <code>ServletContext</code> the
* container notifies them accordingly.
-
- *
- *
- * @param name a <code>String</code> specifying the name
- * of the attribute to be removed
- *
+ *
+ * @param name
+ * a <code>String</code> 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<? extends Servlet> servletClass);
-
/**
- *
* @param c
* @return
* @throws ServletException
- * @since Servlet 3.0
- * TODO SERVLET3 - Add comments
+ * @since Servlet 3.0 TODO SERVLET3 - Add comments
*/
public <T extends Servlet> T createServlet(Class<T> 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<String, ? extends ServletRegistration> 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<? extends Filter> filterClass);
-
/**
- *
* @param c
* @return
* @throws ServletException
- * @since Servlet 3.0
- * TODO SERVLET3 - Add comments
+ * @since Servlet 3.0 TODO SERVLET3 - Add comments
*/
public <T extends Filter> T createFilter(Class<T> 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<String, ? extends FilterRegistration> 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<SessionTrackingMode> sessionTrackingModes)
throws IllegalStateException, IllegalArgumentException;
-
+
/**
- *
* @return
- * @since Servlet 3.0
- * TODO SERVLET3 - Add comments
+ * @since Servlet 3.0 TODO SERVLET3 - Add comments
*/
public Set<SessionTrackingMode> getDefaultSessionTrackingModes();
-
+
/**
- *
* @return
- * @since Servlet 3.0
- * TODO SERVLET3 - Add comments
+ * @since Servlet 3.0 TODO SERVLET3 - Add comments
*/
public Set<SessionTrackingMode> getEffectiveSessionTrackingModes();
-
+
/**
- *
* @param listenerClass
- * @since Servlet 3.0
- * TODO SERVLET3 - Add comments
+ * @since Servlet 3.0 TODO SERVLET3 - Add comments
*/
- public void addListener(Class <? extends EventListener> listenerClass);
-
+ public void addListener(Class<? extends EventListener> 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 <T>
* @param t
- * @since Servlet 3.0
- * TODO SERVLET3 - Add comments
+ * @since Servlet 3.0 TODO SERVLET3 - Add comments
*/
public <T extends EventListener> void addListener(T t);
-
+
/**
- *
* @param <T>
* @param c
* @return
* @throws ServletException
- * @since Servlet 3.0
- * TODO SERVLET3 - Add comments
+ * @since Servlet 3.0 TODO SERVLET3 - Add comments
*/
public <T extends EventListener> T createListener(Class<T> 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();
}
/*
-* 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;
+ }
}
-
/*
-* 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);
+}
/*
-* 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();
}
-
}
-
/*
-* 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);
}
-
/*
-* 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 {
}
/**
- * 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 <code>String</code>
- * 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 <code>String</code> 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 <code>String</code> containing
- * the text of the exception message
- *
- * @param rootCause the <code>Throwable</code> 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 <code>String</code> containing the text of the exception
+ * message
+ * @param rootCause
+ * the <code>Throwable</code> 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.
- *
- * <p>This method calls the <code>getLocalizedMessage</code> method
- * on the <code>Throwable</code> exception to get a localized exception
- * message. When subclassing <code>ServletException</code>,
- * this method can be overridden to create an exception message
- * designed for a specific locale.
- *
- * @param rootCause the <code>Throwable</code> 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.
+ * <p>
+ * This method calls the <code>getLocalizedMessage</code> method on the
+ * <code>Throwable</code> exception to get a localized exception message.
+ * When subclassing <code>ServletException</code>, this method can be
+ * overridden to create an exception message designed for a specific locale.
+ *
+ * @param rootCause
+ * the <code>Throwable</code> exception that interfered with the
+ * servlet's normal operation, making the servlet exception
+ * necessary
*/
public ServletException(Throwable rootCause) {
super(rootCause);
/**
* Returns the exception that caused this servlet exception.
- *
- * @return the <code>Throwable</code>
- * that caused this servlet exception
+ *
+ * @return the <code>Throwable</code> that caused this servlet exception
*/
public Throwable getRootCause() {
return getCause();
/*
-* 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 <code>readLine</code> method for reading data one line
+ * at a time. With some protocols, such as HTTP POST and PUT, a
+ * <code>ServletInputStream</code> object can be used to read data sent from the
+ * client.
+ * <p>
+ * A <code>ServletInputStream</code> object is normally retrieved via the
+ * {@link ServletRequest#getInputStream} method.
+ * <p>
+ * This is an abstract class that a servlet container implements. Subclasses of
+ * this class must implement the <code>java.io.InputStream.read()</code> method.
*
- * Provides an input stream for reading binary data from a client
- * request, including an efficient <code>readLine</code> method
- * for reading data one line at a time. With some protocols, such
- * as HTTP POST and PUT, a <code>ServletInputStream</code>
- * object can be used to read data sent from the client.
- *
- * <p>A <code>ServletInputStream</code> object is normally retrieved via
- * the {@link ServletRequest#getInputStream} method.
- *
- *
- * <p>This is an abstract class that a servlet container implements.
- * Subclasses of this class
- * must implement the <code>java.io.InputStream.read()</code> 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.
- *
- * <p>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.
+ * <p>
+ * 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;
}
}
-
-
-
/*
-* 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;
import java.util.ResourceBundle;
/**
- * Provides an output stream for sending binary data to the
- * client. A <code>ServletOutputStream</code> object is normally retrieved
- * via the {@link ServletResponse#getOutputStream} method.
- *
- * <p>This is an abstract class that the servlet container implements.
- * Subclasses of this class
- * must implement the <code>java.io.OutputStream.write(int)</code>
+ * Provides an output stream for sending binary data to the client. A
+ * <code>ServletOutputStream</code> object is normally retrieved via the
+ * {@link ServletResponse#getOutputStream} method.
+ * <p>
+ * This is an abstract class that the servlet container implements. Subclasses
+ * of this class must implement the <code>java.io.OutputStream.write(int)</code>
* 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 <code>String</code> to the client,
- * without a carriage return-line feed (CRLF)
- * character at the end.
- *
- *
- * @param s the <code>String</code> to send to the client
- *
- * @exception IOException if an input or output exception occurred
- *
+ * Writes a <code>String</code> to the client, without a carriage
+ * return-line feed (CRLF) character at the end.
+ *
+ * @param s
+ * the <code>String</code> 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 <code>boolean</code> value to the client,
- * with no carriage return-line feed (CRLF)
- * character at the end.
- *
- * @param b the <code>boolean</code> value
- * to send to the client
- *
- * @exception IOException if an input or output exception occurred
- *
+ * Writes a <code>boolean</code> value to the client, with no carriage
+ * return-line feed (CRLF) character at the end.
+ *
+ * @param b
+ * the <code>boolean</code> 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 <code>long</code> value to the client, with no carriage
+ * return-line feed (CRLF) at the end.
*
- * Writes a <code>long</code> value to the client,
- * with no carriage return-line feed (CRLF) at the end.
- *
- * @param l the <code>long</code> value
- * to send to the client
- *
- * @exception IOException if an input or output exception
- * occurred
- *
+ * @param l
+ * the <code>long</code> 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 <code>float</code> value to the client,
- * with no carriage return-line feed (CRLF) at the end.
- *
- * @param f the <code>float</code> value
- * to send to the client
- *
- * @exception IOException if an input or output exception occurred
- *
- *
+ * Writes a <code>float</code> value to the client, with no carriage
+ * return-line feed (CRLF) at the end.
+ *
+ * @param f
+ * the <code>float</code> 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 <code>double</code> value to the client,
- * with no carriage return-line feed (CRLF) at the end.
+ * Writes a <code>double</code> value to the client, with no carriage
+ * return-line feed (CRLF) at the end.
*
- * @param d the <code>double</code> value
- * to send to the client
- *
- * @exception IOException if an input or output exception occurred
- *
+ * @param d
+ * the <code>double</code> 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 <code>String</code> to the client,
- * followed by a carriage return-line feed (CRLF).
- *
- *
- * @param s the <code>String</code> to write to the client
- *
- * @exception IOException if an input or output exception occurred
- *
+ * Writes a <code>String</code> to the client, followed by a carriage
+ * return-line feed (CRLF).
+ *
+ * @param s
+ * the <code>String</code> 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 <code>boolean</code> value to the client,
- * followed by a
- * carriage return-line feed (CRLF).
- *
- *
- * @param b the <code>boolean</code> value
- * to write to the client
- *
- * @exception IOException if an input or output exception occurred
- *
+ * Writes a <code>boolean</code> value to the client, followed by a carriage
+ * return-line feed (CRLF).
+ *
+ * @param b
+ * the <code>boolean</code> 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 <code>long</code> value to the client, followed by a
- * carriage return-line feed (CRLF).
- *
- *
- * @param l the <code>long</code> value to write to the client
- *
- * @exception IOException if an input or output exception occurred
- *
- */
-
+ /**
+ * Writes a <code>long</code> value to the client, followed by a carriage
+ * return-line feed (CRLF).
+ *
+ * @param l
+ * the <code>long</code> 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 <code>float</code> value to the client,
- * followed by a carriage return-line feed (CRLF).
- *
- * @param f the <code>float</code> value
- * to write to the client
- *
- *
- * @exception IOException if an input or output exception
- * occurred
- *
+ * Writes a <code>float</code> value to the client, followed by a carriage
+ * return-line feed (CRLF).
+ *
+ * @param f
+ * the <code>float</code> 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 <code>double</code> value to the client,
- * followed by a carriage return-line feed (CRLF).
- *
- *
- * @param d the <code>double</code> value
- * to write to the client
- *
- * @exception IOException if an input or output exception occurred
- *
+ * Writes a <code>double</code> value to the client, followed by a carriage
+ * return-line feed (CRLF).
+ *
+ * @param d
+ * the <code>double</code> 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();
}
}
/*
-* 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;
import java.util.Locale;
import java.util.Map;
-
-
/**
- * Defines an object to provide client request information to a servlet. The
- * servlet container creates a <code>ServletRequest</code> object and passes
- * it as an argument to the servlet's <code>service</code> method.
- *
- * <p>A <code>ServletRequest</code> object provides data including
- * parameter name and values, attributes, and an input stream.
- * Interfaces that extend <code>ServletRequest</code> 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 <code>ServletRequest</code> object and passes it
+ * as an argument to the servlet's <code>service</code> method.
+ * <p>
+ * A <code>ServletRequest</code> object provides data including parameter name
+ * and values, attributes, and an input stream. Interfaces that extend
+ * <code>ServletRequest</code> 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 <code>Object</code>,
- * or <code>null</code> if no attribute of the given name exists.
- *
- * <p> 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 <code>Object</code>, or
+ * <code>null</code> if no attribute of the given name exists.
+ * <p>
+ * 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
* <code>javax.servlet.request.X509Certificate</code> 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.
- *
- * <p>Attribute names should follow the same conventions as package
- * names. This specification reserves names matching <code>java.*</code>,
- * <code>javax.*</code>, and <code>sun.*</code>.
- *
- * @param name a <code>String</code> specifying the name of
- * the attribute
- *
- * @return an <code>Object</code> containing the value
- * of the attribute, or <code>null</code> 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.
+ * <p>
+ * Attribute names should follow the same conventions as package names. This
+ * specification reserves names matching <code>java.*</code>,
+ * <code>javax.*</code>, and <code>sun.*</code>.
+ *
+ * @param name
+ * a <code>String</code> specifying the name of the attribute
+ * @return an <code>Object</code> containing the value of the attribute, or
+ * <code>null</code> if the attribute does not exist
*/
-
public Object getAttribute(String name);
-
-
/**
- * Returns an <code>Enumeration</code> containing the
- * names of the attributes available to this request.
- * This method returns an empty <code>Enumeration</code>
- * if the request has no attributes available to it.
+ * Returns an <code>Enumeration</code> containing the names of the
+ * attributes available to this request. This method returns an empty
+ * <code>Enumeration</code> if the request has no attributes available to
+ * it.
*
- *
- * @return an <code>Enumeration</code> of strings
- * containing the names
- * of the request's attributes
- *
+ * @return an <code>Enumeration</code> of strings containing the names of the
+ * request's attributes
*/
-
public Enumeration<String> getAttributeNames();
-
-
-
-
+
/**
* Returns the name of the character encoding used in the body of this
- * request. This method returns <code>null</code> if the request
- * does not specify a character encoding
+ * request. This method returns <code>null</code> if the request does not
+ * specify a character encoding
*
- *
- * @return a <code>String</code> containing the name of
- * the character encoding, or <code>null</code>
- * if the request does not specify a character encoding
- *
+ * @return a <code>String</code> containing the name of the character
+ * encoding, or <code>null</code> 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 <code>String</code> containing the name of
- * the character encoding.
- * @throws java.io.UnsupportedEncodingException if this is not a valid encoding
+ * @param env
+ * a <code>String</code> 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
- * <code>null</code> if the type is not known. For HTTP servlets,
- * same as the value of the CGI variable CONTENT_TYPE.
- *
- * @return a <code>String</code> 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 <code>null</code> if
+ * the type is not known. For HTTP servlets, same as the value of the CGI
+ * variable CONTENT_TYPE.
+ *
+ * @return a <code>String</code> 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 <code>String</code>,
- * or <code>null</code> 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.
- *
- * <p>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}.
- *
- * <p>If you use this method with a multivalued
- * parameter, the value returned is equal to the first value
- * in the array returned by <code>getParameterValues</code>.
- *
- * <p>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 <code>String</code> specifying the
- * name of the parameter
- *
- * @return a <code>String</code> 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 <code>String</code>, or
+ * <code>null</code> 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.
+ * <p>
+ * 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}.
+ * <p>
+ * If you use this method with a multivalued parameter, the value returned
+ * is equal to the first value in the array returned by
+ * <code>getParameterValues</code>.
+ * <p>
+ * 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 <code>String</code> specifying the name of the parameter
+ * @return a <code>String</code> representing the single value of the
+ * parameter
+ * @see #getParameterValues
+ */
public String getParameter(String name);
-
-
-
-
- /**
- *
- * Returns an <code>Enumeration</code> of <code>String</code>
- * objects containing the names of the parameters contained
- * in this request. If the request has
- * no parameters, the method returns an
- * empty <code>Enumeration</code>.
- *
- * @return an <code>Enumeration</code> of <code>String</code>
- * objects, each <code>String</code> containing
- * the name of a request parameter; or an
- * empty <code>Enumeration</code> if the
- * request has no parameters
- *
- */
-
- public Enumeration<String> getParameterNames();
-
-
-
-
- /**
- * Returns an array of <code>String</code> objects containing
- * all of the values the given request parameter has, or
- * <code>null</code> if the parameter does not exist.
- *
- * <p>If the parameter has a single value, the array has a length
- * of 1.
- *
- * @param name a <code>String</code> containing the name of
- * the parameter whose value is requested
- *
- * @return an array of <code>String</code> objects
- * containing the parameter's values
- *
- * @see #getParameter
- *
+
+ /**
+ * Returns an <code>Enumeration</code> of <code>String</code> objects
+ * containing the names of the parameters contained in this request. If the
+ * request has no parameters, the method returns an empty
+ * <code>Enumeration</code>.
+ *
+ * @return an <code>Enumeration</code> of <code>String</code> objects, each
+ * <code>String</code> containing the name of a request parameter;
+ * or an empty <code>Enumeration</code> if the request has no
+ * parameters
*/
+ public Enumeration<String> getParameterNames();
+ /**
+ * Returns an array of <code>String</code> objects containing all of the
+ * values the given request parameter has, or <code>null</code> if the
+ * parameter does not exist.
+ * <p>
+ * If the parameter has a single value, the array has a length of 1.
+ *
+ * @param name
+ * a <code>String</code> containing the name of the parameter
+ * whose value is requested
+ * @return an array of <code>String</code> 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<String,String[]> getParameterMap();
-
-
-
- /**
- * Returns the name and version of the protocol the request uses
- * in the form <i>protocol/majorVersion.minorVersion</i>, for
- * example, HTTP/1.1. For HTTP servlets, the value
- * returned is the same as the value of the CGI variable
- * <code>SERVER_PROTOCOL</code>.
- *
- * @return a <code>String</code> containing the protocol
- * name and version number
- *
- */
-
- public String getProtocol();
-
-
-
/**
- * Returns the name of the scheme used to make this request,
- * for example,
- * <code>http</code>, <code>https</code>, or <code>ftp</code>.
- * Different schemes have different rules for constructing URLs,
- * as noted in RFC 1738.
- *
- * @return a <code>String</code> 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<String, String[]> getParameterMap();
- public String getScheme();
-
-
-
+ /**
+ * Returns the name and version of the protocol the request uses in the form
+ * <i>protocol/majorVersion.minorVersion</i>, for example, HTTP/1.1. For
+ * HTTP servlets, the value returned is the same as the value of the CGI
+ * variable <code>SERVER_PROTOCOL</code>.
+ *
+ * @return a <code>String</code> 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 <code>Host</code>
- * header value, if any, or the resolved server name, or the server IP address.
- *
- * @return a <code>String</code> containing the name
- * of the server
+ * Returns the name of the scheme used to make this request, for example,
+ * <code>http</code>, <code>https</code>, or <code>ftp</code>. Different
+ * schemes have different rules for constructing URLs, as noted in RFC 1738.
+ *
+ * @return a <code>String</code> 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 <code>Host</code> header value,
+ * if any, or the resolved server name, or the server IP address.
+ *
+ * @return a <code>String</code> 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 <code>Host</code>
- * 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 <code>Host</code> 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 <code>BufferedReader</code>. 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
+ * <code>BufferedReader</code>. 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 <code>BufferedReader</code>
- * 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 <code>BufferedReader</code> 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 <code>REMOTE_ADDR</code>.
- *
- * @return a <code>String</code> 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 <code>REMOTE_ADDR</code>.
+ *
+ * @return a <code>String</code> 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
- * <code>REMOTE_HOST</code>.
- *
- * @return a <code>String</code> 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 <code>REMOTE_HOST</code>.
+ *
+ * @return a <code>String</code> 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}.
- *
- * <p>Attribute names should follow the same conventions as
- * package names. Names beginning with <code>java.*</code>,
- * <code>javax.*</code>, and <code>com.sun.*</code>, are
- * reserved for use by Sun Microsystems.
- *<br> If the object passed in is null, the effect is the same as
- * calling {@link #removeAttribute}.
- * <br> It is warned that when the request is dispatched from the
- * servlet resides in a different web application by
- * <code>RequestDispatcher</code>, the object set by this method
- * may not be correctly retrieved in the caller servlet.
- *
- *
- * @param name a <code>String</code> specifying
- * the name of the attribute
- *
- * @param o the <code>Object</code> 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.
- *
- * <p>Attribute names should follow the same conventions as
- * package names. Names beginning with <code>java.*</code>,
- * <code>javax.*</code>, and <code>com.sun.*</code>, are
- * reserved for use by Sun Microsystems.
- *
- *
- * @param name a <code>String</code> 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}.
+ * <p>
+ * Attribute names should follow the same conventions as package names.
+ * Names beginning with <code>java.*</code>, <code>javax.*</code>, and
+ * <code>com.sun.*</code>, are reserved for use by Sun Microsystems. <br>
+ * If the object passed in is null, the effect is the same as calling
+ * {@link #removeAttribute}. <br>
+ * It is warned that when the request is dispatched from the servlet resides
+ * in a different web application by <code>RequestDispatcher</code>, the
+ * object set by this method may not be correctly retrieved in the caller
+ * servlet.
+ *
+ * @param name
+ * a <code>String</code> specifying the name of the attribute
+ * @param o
+ * the <code>Object</code> 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.
+ * <p>
+ * Attribute names should follow the same conventions as package names.
+ * Names beginning with <code>java.*</code>, <code>javax.*</code>, and
+ * <code>com.sun.*</code>, are reserved for use by Sun Microsystems.
+ *
+ * @param name
+ * a <code>String</code> specifying the name of the attribute to
+ * remove
+ */
public void removeAttribute(String name);
-
-
-
/**
- *
- * Returns the preferred <code>Locale</code> 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 <code>Locale</code> for the client
- *
+ * Returns the preferred <code>Locale</code> 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 <code>Locale</code> for the client
*/
-
public Locale getLocale();
-
-
-
/**
- *
* Returns an <code>Enumeration</code> of <code>Locale</code> 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 <code>Enumeration</code> containing one
+ * header. If the client request doesn't provide an Accept-Language header,
+ * this method returns an <code>Enumeration</code> containing one
* <code>Locale</code>, the default locale for the server.
- *
- *
- * @return an <code>Enumeration</code> of preferred
- * <code>Locale</code> objects for the client
- *
+ *
+ * @return an <code>Enumeration</code> of preferred <code>Locale</code>
+ * objects for the client
*/
-
public Enumeration<Locale> 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 <code>RequestDispatcher</code> 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.
- *
- * <p>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 <code>null</code> if the servlet container
- * cannot return a <code>RequestDispatcher</code>.
- *
- * <p>The difference between this method and {@link
- * ServletContext#getRequestDispatcher} is that this method can take a
- * relative path.
- *
- * @param path a <code>String</code> specifying the pathname
- * to the resource. If it is relative, it must be
- * relative against the current servlet.
- *
- * @return a <code>RequestDispatcher</code> object
- * that acts as a wrapper for the resource
- * at the specified path, or <code>null</code>
- * if the servlet container cannot return a
- * <code>RequestDispatcher</code>
- *
- * @see RequestDispatcher
- * @see ServletContext#getRequestDispatcher
- *
- */
+ /**
+ * Returns a {@link RequestDispatcher} object that acts as a wrapper for the
+ * resource located at the given path. A <code>RequestDispatcher</code>
+ * 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.
+ * <p>
+ * 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
+ * <code>null</code> if the servlet container cannot return a
+ * <code>RequestDispatcher</code>.
+ * <p>
+ * The difference between this method and
+ * {@link ServletContext#getRequestDispatcher} is that this method can take
+ * a relative path.
+ *
+ * @param path
+ * a <code>String</code> specifying the pathname to the resource.
+ * If it is relative, it must be relative against the current
+ * servlet.
+ * @return a <code>RequestDispatcher</code> object that acts as a wrapper for
+ * the resource at the specified path, or <code>null</code> if the
+ * servlet container cannot return a <code>RequestDispatcher</code>
+ * @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 <code>String</code> 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 <code>String</code> 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 <code>String</code> 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 <code>String</code> 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();
}
-
/*
-* 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;
}
}
/*
-* 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();
}
}
/*
-* 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;
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<String> 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<String> 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<String,String[]> getParameterMap() {
- return this.request.getParameterMap();
+ public Map<String, String[]> 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<String> 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<Locale> 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
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
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
* @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
}
/**
- * 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
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
}
/**
- *
* @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
*/
return this.request.getDispatcherType();
}
}
-
/*
-* 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 <code>ServletResponse</code> object and
* passes it as an argument to the servlet's <code>service</code> method.
- *
- * <p>To send binary data in a MIME body response, use
- * the {@link ServletOutputStream} returned by {@link #getOutputStream}.
- * To send character data, use the <code>PrintWriter</code> object
- * returned by {@link #getWriter}. To mix binary and text data,
- * for example, to create a multipart response, use a
- * <code>ServletOutputStream</code> and manage the character sections
- * manually.
- *
- * <p>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 <code>setCharacterEncoding</code>,
- * <code>setContentType</code>, or <code>setLocale</code> method must
- * be called before <code>getWriter</code> and before committing
- * the response for the character encoding to be used.
+ * <p>
+ * To send binary data in a MIME body response, use the
+ * {@link ServletOutputStream} returned by {@link #getOutputStream}. To send
+ * character data, use the <code>PrintWriter</code> object returned by
+ * {@link #getWriter}. To mix binary and text data, for example, to create a
+ * multipart response, use a <code>ServletOutputStream</code> and manage the
+ * character sections manually.
+ * <p>
+ * 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 <code>setCharacterEncoding</code>,
+ * <code>setContentType</code>, or <code>setLocale</code> method must be called
+ * before <code>getWriter</code> and before committing the response for the
+ * character encoding to be used.
+ * <p>
+ * See the Internet RFCs such as <a href="http://www.ietf.org/rfc/rfc2045.txt">
+ * RFC 2045</a> for more information on MIME. Protocols such as SMTP and HTTP
+ * define profiles of MIME, and those standards are still evolving.
*
- * <p>See the Internet RFCs such as
- * <a href="http://www.ietf.org/rfc/rfc2045.txt">
- * RFC 2045</a> 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 <code>getWriter</code> has been
- * called or after the response has been committed have no
- * effect on the character encoding. If no character encoding
- * has been specified, <code>ISO-8859-1</code> is returned.
- * <p>See RFC 2047 (http://www.ietf.org/rfc/rfc2047.txt)
- * for more information about character encoding and MIME.
- *
- * @return a <code>String</code> specifying the
- * name of the character encoding, for
- * example, <code>UTF-8</code>
- *
+ * {@link #setLocale} method. Explicit specifications take precedence over
+ * implicit specifications. Calls made to these methods after
+ * <code>getWriter</code> has been called or after the response has been
+ * committed have no effect on the character encoding. If no character
+ * encoding has been specified, <code>ISO-8859-1</code> is returned.
+ * <p>
+ * See RFC 2047 (http://www.ietf.org/rfc/rfc2047.txt) for more information
+ * about character encoding and MIME.
+ *
+ * @return a <code>String</code> specifying the name of the character
+ * encoding, for example, <code>UTF-8</code>
*/
-
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 <code>String</code> specifying the
- * content type, for example,
- * <code>text/html; charset=UTF-8</code>,
- * 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 <code>String</code> specifying the content type, for example,
+ * <code>text/html; charset=UTF-8</code>, 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.
-
- * <p> 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 <code>getWriter</code> 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.
+ * <p>
+ * 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 <code>getWriter</code> 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 <code>PrintWriter</code> object that
- * can send character text to the client.
- * The <code>PrintWriter</code> uses the character
- * encoding returned by {@link #getCharacterEncoding}.
- * If the response's character encoding has not been
- * specified as described in <code>getCharacterEncoding</code>
- * (i.e., the method just returns the default value
- * <code>ISO-8859-1</code>), <code>getWriter</code>
- * updates it to <code>ISO-8859-1</code>.
- * <p>Calling flush() on the <code>PrintWriter</code>
- * commits the response.
- * <p>Either this method or {@link #getOutputStream} may be called
- * to write the body, not both.
- *
+ * Returns a <code>PrintWriter</code> object that can send character text to
+ * the client. The <code>PrintWriter</code> uses the character encoding
+ * returned by {@link #getCharacterEncoding}. If the response's character
+ * encoding has not been specified as described in
+ * <code>getCharacterEncoding</code> (i.e., the method just returns the
+ * default value <code>ISO-8859-1</code>), <code>getWriter</code> updates it
+ * to <code>ISO-8859-1</code>.
+ * <p>
+ * Calling flush() on the <code>PrintWriter</code> commits the response.
+ * <p>
+ * Either this method or {@link #getOutputStream} may be called to write the
+ * body, not both.
*
- * @return a <code>PrintWriter</code> object that
- * can return character data to the client
- *
+ * @return a <code>PrintWriter</code> object that can return character data
+ * to the client
* @exception UnsupportedEncodingException
- * if the character encoding returned
- * by <code>getCharacterEncoding</code> cannot be used
- *
+ * if the character encoding returned by
+ * <code>getCharacterEncoding</code> cannot be used
* @exception IllegalStateException
- * if the <code>getOutputStream</code>
- * method has already been called for this
- * response object
- *
+ * if the <code>getOutputStream</code> 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 <code>String</code>
- * of <code>text/html</code> and calling
- * this method with the <code>String</code> of <code>UTF-8</code>
- * is equivalent with calling
- * <code>setContentType</code> with the <code>String</code> 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
+ * <code>String</code> of <code>text/html</code> and calling this method
+ * with the <code>String</code> of <code>UTF-8</code> is equivalent with
+ * calling <code>setContentType</code> with the <code>String</code> of
* <code>text/html; charset=UTF-8</code>.
- * <p>This method can be called repeatedly to change the character
- * encoding.
- * This method has no effect if it is called after
- * <code>getWriter</code> has been
- * called or after the response has been committed.
- * <p>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 <code>Content-Type</code>
- * 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
- *
+ * <p>
+ * This method can be called repeatedly to change the character encoding.
+ * This method has no effect if it is called after <code>getWriter</code>
+ * has been called or after the response has been committed.
+ * <p>
+ * 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 <code>Content-Type</code> 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, <code>text/html;charset=UTF-8</code>.
- * The response's character encoding is only set from the given
- * content type if this method is called before <code>getWriter</code>
- * is called.
- * <p>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 <code>getWriter</code>
- * has been called or after the response has been committed.
- * <p>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 <code>Content-Type</code> header is used.
- *
- * @param type a <code>String</code> 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,
+ * <code>text/html;charset=UTF-8</code>. The response's character encoding
+ * is only set from the given content type if this method is called before
+ * <code>getWriter</code> is called.
+ * <p>
+ * 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 <code>getWriter</code> has been called or after the response
+ * has been committed.
+ * <p>
+ * 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
+ * <code>Content-Type</code> header is used.
+ *
+ * @param type
+ * a <code>String</code> 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 <code>getBufferSize</code>.
- *
- * <p>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 <code>getBufferSize</code>.
+ * <p>
+ * 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.
- *
- * <p>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
- * <code>IllegalStateException</code>.
- *
- * @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.
+ * <p>
+ * 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 <code>IllegalStateException</code>.
+ *
+ * @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
- * <code>IllegalStateException</code>.
- *
- * @see #setBufferSize
- * @see #getBufferSize
- * @see #isCommitted
- * @see #reset
- *
+ * clearing headers or status code. If the response has been committed, this
+ * method throws an <code>IllegalStateException</code>.
+ *
+ * @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
* <code>IllegalStateException</code>.
- *
- * @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}, <code>getWriter</code> hasn't
- * been called yet, and the response hasn't been committed yet.
- * If the deployment descriptor contains a
- * <code>locale-encoding-mapping-list</code> 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.
- * <p>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
- * <code>getWriter</code> has been called, or after the response
- * has been committed.
- * <p>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 <code>Content-Language</code> header,
- * the character encoding as part of the <code>Content-Type</code>
- * 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},
+ * <code>getWriter</code> hasn't been called yet, and the response hasn't
+ * been committed yet. If the deployment descriptor contains a
+ * <code>locale-encoding-mapping-list</code> 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.
+ * <p>
+ * 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
+ * <code>getWriter</code> has been called, or after the response has been
+ * committed.
+ * <p>
+ * 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 <code>Content-Language</code> header, the character encoding as part
+ * of the <code>Content-Type</code> 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
- * <code>setLocale</code> 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 <code>setLocale</code> 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();
-
-
}
-
-
-
-
-
/*
-* 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.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;
}
-
}
-
-
-
-
-
/*
-* 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.
- *
- * <p>If a servlet implements this interface, you are <i>guaranteed</i>
- * that no two threads will execute concurrently in the
- * servlet's <code>service</code> 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.
+ * <p>
+ * If a servlet implements this interface, you are <i>guaranteed</i> that no two
+ * threads will execute concurrently in the servlet's <code>service</code>
+ * 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.
- *
- * <p>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.
+ * <p>
+ * 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
}
/*
-* 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.
- *
- * <p>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.
+ * <p>
+ * 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.
- *
- * <p>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.
- *
- * <p>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$
- *
+ * <p>
+ * 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.
+ * <p>
+ * 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 <code>Servlet</code> instance that is
- * unavailable
- *
- * @param msg a <code>String</code> specifying the
- * descriptive message
- *
- * @deprecated As of Java Servlet API 2.2, use {@link
- * #UnavailableException(String)} instead.
+ * @param servlet
+ * the <code>Servlet</code> instance that is unavailable
+ * @param msg
+ * a <code>String</code> 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 <code>Servlet</code> that is unavailable
- *
- * @param msg a <code>String</code> 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 <code>Servlet</code> that is unavailable
+ * @param msg
+ * a <code>String</code> 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 <code>String</code> specifying the
- * descriptive message
- *
+ * @param msg
+ * a <code>String</code> 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.
+ * <p>
+ * 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 <code>seconds</code>
+ * argument.
*
- * <p>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 <code>seconds</code> argument.
- *
- * @param msg a <code>String</code> 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 <code>String</code> 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 <code>boolean</code> 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 <code>true</code> if the servlet is
- * permanently unavailable; <code>false</code>
- * if the servlet is available or temporarily
- * unavailable
- *
+ * Returns a <code>boolean</code> 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 <code>true</code> if the servlet is permanently unavailable;
+ * <code>false</code> 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 <code>Servlet</code> object that is
- * throwing the <code>UnavailableException</code>
- *
- * @deprecated As of Java Servlet API 2.2, with no replacement.
+ * @return the <code>Servlet</code> object that is throwing the
+ * <code>UnavailableException</code>
+ * @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.
- *
- * <p>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.
+ * <p>
+ * 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;
}
}
projects / tomcat7.0 / commitdiff