Return-Path: Delivered-To: apmail-tomcat-dev-archive@www.apache.org Received: (qmail 36404 invoked from network); 22 Jul 2010 22:49:17 -0000 Received: from unknown (HELO mail.apache.org) (140.211.11.3) by 140.211.11.9 with SMTP; 22 Jul 2010 22:49:17 -0000 Received: (qmail 77699 invoked by uid 500); 22 Jul 2010 22:49:15 -0000 Delivered-To: apmail-tomcat-dev-archive@tomcat.apache.org Received: (qmail 77001 invoked by uid 500); 22 Jul 2010 22:49:15 -0000 Mailing-List: contact dev-help@tomcat.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: "Tomcat Developers List" Delivered-To: mailing list dev@tomcat.apache.org Received: (qmail 76584 invoked by uid 99); 22 Jul 2010 22:49:14 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 22 Jul 2010 22:49:14 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=10.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 22 Jul 2010 22:49:11 +0000 Received: by eris.apache.org (Postfix, from userid 65534) id 1CA3A23889E0; Thu, 22 Jul 2010 22:48:19 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r966888 - in /tomcat/trunk/java/javax/servlet: Filter.java FilterChain.java FilterConfig.java GenericServlet.java RequestDispatcher.java Servlet.java Date: Thu, 22 Jul 2010 22:48:18 -0000 To: dev@tomcat.apache.org From: markt@apache.org X-Mailer: svnmailer-1.0.8 Message-Id: <20100722224819.1CA3A23889E0@eris.apache.org> Author: markt Date: Thu Jul 22 22:48:18 2010 New Revision: 966888 URL: http://svn.apache.org/viewvc?rev=966888&view=rev Log: Tab police: javax.servlet (partial) Thanks to Checkstyle and Eclipse source formatting Modified: tomcat/trunk/java/javax/servlet/Filter.java tomcat/trunk/java/javax/servlet/FilterChain.java tomcat/trunk/java/javax/servlet/FilterConfig.java tomcat/trunk/java/javax/servlet/GenericServlet.java tomcat/trunk/java/javax/servlet/RequestDispatcher.java tomcat/trunk/java/javax/servlet/Servlet.java Modified: tomcat/trunk/java/javax/servlet/Filter.java URL: http://svn.apache.org/viewvc/tomcat/trunk/java/javax/servlet/Filter.java?rev=966888&r1=966887&r2=966888&view=diff ============================================================================== --- tomcat/trunk/java/javax/servlet/Filter.java (original) +++ tomcat/trunk/java/javax/servlet/Filter.java Thu Jul 22 22:48:18 2010 @@ -1,92 +1,100 @@ /* -* 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; - /** - * A filter is an object that performs filtering tasks on either the request to a resource (a servlet or static content), or on the response from a resource, or both. - *

- * Filters perform filtering in the doFilter method. Every Filter has access to - ** a FilterConfig object from which it can obtain its initialization parameters, a - ** reference to the ServletContext which it can use, for example, to load resources - ** needed for filtering tasks. - **

- ** Filters are configured in the deployment descriptor of a web application - **

- ** Examples that have been identified for this design are
- ** 1) Authentication Filters
- ** 2) Logging and Auditing Filters
- ** 3) Image conversion Filters
- ** 4) Data compression Filters
- ** 5) Encryption Filters
- ** 6) Tokenizing Filters
- ** 7) Filters that trigger resource access events
- ** 8) XSL/T filters
- ** 9) Mime-type chain Filter
- * @since Servlet 2.3 - */ - +/** + * A filter is an object that performs filtering tasks on either the request to + * a resource (a servlet or static content), or on the response from a resource, + * or both.
+ *
+ * Filters perform filtering in the doFilter method. Every Filter + * has access to a FilterConfig object from which it can obtain its + * initialization parameters, a reference to the ServletContext which it can + * use, for example, to load resources needed for filtering tasks. + *

+ * Filters are configured in the deployment descriptor of a web application + *

+ * Examples that have been identified for this design are
+ * 1) Authentication Filters
+ * 2) Logging and Auditing Filters
+ * 3) Image conversion Filters
+ * 4) Data compression Filters
+ * 5) Encryption Filters
+ * 6) Tokenizing Filters
+ * 7) Filters that trigger resource access events
+ * 8) XSL/T filters
+ * 9) Mime-type chain Filter
+ * + * @since Servlet 2.3 + */ public interface Filter { - /** - * Called by the web container to indicate to a filter that it is being placed into - * service. The servlet container calls the init method exactly once after instantiating the - * filter. The init method must complete successfully before the filter is asked to do any - * filtering work.

- - * The web container cannot place the filter into service if the init method either
- * 1.Throws a ServletException
- * 2.Does not return within a time period defined by the web container - */ - public void init(FilterConfig filterConfig) throws ServletException; - - - /** - * The doFilter method of the Filter is called by the container - * each time a request/response pair is passed through the chain due - * to a client request for a resource at the end of the chain. The FilterChain passed in to this - * method allows the Filter to pass on the request and response to the next entity in the - * chain.

- * A typical implementation of this method would follow the following pattern:-
- * 1. Examine the request
- * 2. Optionally wrap the request object with a custom implementation to - * filter content or headers for input filtering
- * 3. Optionally wrap the response object with a custom implementation to - * filter content or headers for output filtering
- * 4. a) Either invoke the next entity in the chain using the FilterChain object (chain.doFilter()),
- ** 4. b) or not pass on the request/response pair to the next entity in the filter chain to block the request processing
- ** 5. Directly set headers on the response after invocation of the next entity in the filter chain. - **/ - public void doFilter ( ServletRequest request, ServletResponse response, FilterChain chain ) throws IOException, ServletException; - - /** - * Called by the web container to indicate to a filter that it is being taken out of service. This - * method is only called once all threads within the filter's doFilter method have exited or after - * a timeout period has passed. After the web container calls this method, it will not call the - * doFilter method again on this instance of the filter.

- * - * This method gives the filter an opportunity to clean up any resources that are being held (for - * example, memory, file handles, threads) and make sure that any persistent state is synchronized - * with the filter's current state in memory. - */ - - public void destroy(); - + /** + * Called by the web container to indicate to a filter that it is being + * placed into service. The servlet container calls the init method exactly + * once after instantiating the filter. The init method must complete + * successfully before the filter is asked to do any filtering work.
+ *
+ * The web container cannot place the filter into service if the init method + * either
+ * 1.Throws a ServletException
+ * 2.Does not return within a time period defined by the web container + */ + public void init(FilterConfig filterConfig) throws ServletException; + + /** + * The doFilter method of the Filter is called by the container + * each time a request/response pair is passed through the chain due to a + * client request for a resource at the end of the chain. The FilterChain + * passed in to this method allows the Filter to pass on the request and + * response to the next entity in the chain. + *

+ * A typical implementation of this method would follow the following + * pattern:-
+ * 1. Examine the request
+ * 2. Optionally wrap the request object with a custom implementation to + * filter content or headers for input filtering
+ * 3. Optionally wrap the response object with a custom implementation to + * filter content or headers for output filtering
+ * 4. a) Either invoke the next entity in the chain using + * the FilterChain object (chain.doFilter()),
+ * 4. b) or not pass on the request/response pair to the + * next entity in the filter chain to block the request processing
+ * 5. Directly set headers on the response after invocation of the next + * entity in the filter chain. + **/ + public void doFilter(ServletRequest request, ServletResponse response, + FilterChain chain) throws IOException, ServletException; + + /** + * Called by the web container to indicate to a filter that it is being + * taken out of service. This method is only called once all threads within + * the filter's doFilter method have exited or after a timeout period has + * passed. After the web container calls this method, it will not call the + * doFilter method again on this instance of the filter.
+ *
+ * + * This method gives the filter an opportunity to clean up any resources + * that are being held (for example, memory, file handles, threads) and make + * sure that any persistent state is synchronized with the filter's current + * state in memory. + */ + public void destroy(); } - Modified: tomcat/trunk/java/javax/servlet/FilterChain.java URL: http://svn.apache.org/viewvc/tomcat/trunk/java/javax/servlet/FilterChain.java?rev=966888&r1=966887&r2=966888&view=diff ============================================================================== --- tomcat/trunk/java/javax/servlet/FilterChain.java (original) +++ tomcat/trunk/java/javax/servlet/FilterChain.java Thu Jul 22 22:48:18 2010 @@ -1,46 +1,49 @@ /* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You under the Apache License, Version 2.0 -* (the "License"); you may not use this file except in compliance with -* the License. You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ package javax.servlet; import java.io.IOException; - /** - * A FilterChain is an object provided by the servlet container to the developer - * giving a view into the invocation chain of a filtered request for a resource. Filters - * use the FilterChain to invoke the next filter in the chain, or if the calling filter - * is the last filter in the chain, to invoke the resource at the end of the chain. - * - * @see Filter - * @since Servlet 2.3 - **/ +/** + * A FilterChain is an object provided by the servlet container to the developer + * giving a view into the invocation chain of a filtered request for a resource. + * Filters use the FilterChain to invoke the next filter in the chain, or if the + * calling filter is the last filter in the chain, to invoke the resource at the + * end of the chain. + * + * @see Filter + * @since Servlet 2.3 + **/ public interface FilterChain { - - /** - * Causes the next filter in the chain to be invoked, or if the calling filter is the last filter - * in the chain, causes the resource at the end of the chain to be invoked. - * - * @param request the request to pass along the chain. - * @param response the response to pass along the chain. - * - * @since 2.3 - */ - - public void doFilter ( ServletRequest request, ServletResponse response ) throws IOException, ServletException; -} + /** + * Causes the next filter in the chain to be invoked, or if the calling + * filter is the last filter in the chain, causes the resource at the end of + * the chain to be invoked. + * + * @param request + * the request to pass along the chain. + * @param response + * the response to pass along the chain. + * + * @since 2.3 + */ + public void doFilter(ServletRequest request, ServletResponse response) + throws IOException, ServletException; +} Modified: tomcat/trunk/java/javax/servlet/FilterConfig.java URL: http://svn.apache.org/viewvc/tomcat/trunk/java/javax/servlet/FilterConfig.java?rev=966888&r1=966887&r2=966888&view=diff ============================================================================== --- tomcat/trunk/java/javax/servlet/FilterConfig.java (original) +++ tomcat/trunk/java/javax/servlet/FilterConfig.java Thu Jul 22 22:48:18 2010 @@ -1,92 +1,73 @@ /* -* 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 filter configuration object used by a servlet container - * to pass information to a filter during initialization. - * @see Filter - * @since Servlet 2.3 - * - */ - - +/** + * + * A filter configuration object used by a servlet container to pass information + * to a filter during initialization. + * + * @see Filter + * @sinceServlet 2.3 + */ public interface FilterConfig { - /** - * Returns the filter-name of this filter as defined in the deployment descriptor. - */ - - public String getFilterName(); - + /** + * Returns the filter-name of this filter as defined in the deployment + * descriptor. + */ + public String getFilterName(); - /** - * 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. + * + * @returns {@link ServletContext} object, used by the caller to interact + * with its servlet container * - * @see ServletContext - * + * @seeServletContext */ - public ServletContext getServletContext(); - + /** - * Returns a String containing the value of the - * named initialization parameter, or null if - * the parameter does not exist. - * - * @param name a String specifying the name - * of the initialization parameter - * - * @return a String containing the value - * of the initialization parameter - * + * Returns a String containing the value of the named + * initialization parameter, or null if the parameter does not + * exist. + * + * @param name + * String specifying the name of the initialization + * parameter + * + * @returns String containing the value of the initialization + * parameter */ - public String getInitParameter(String name); - /** - * Returns the names of the filter's initialization parameters - * as an Enumeration of String objects, - * or an empty Enumeration if the filter has - * no initialization parameters. - * - * @return an Enumeration of String - * objects containing the names of the filter's - * initialization parameters - * - * - * + * Returns the names of the filter's initialization parameters as an + * Enumeration of String objects, or an empty + * Enumeration if the filter has no initialization parameters. + * + * @returns Enumeration of String objects + * containing the names of the filter's initialization parameters */ - public Enumeration getInitParameterNames(); - - - } Modified: tomcat/trunk/java/javax/servlet/GenericServlet.java URL: http://svn.apache.org/viewvc/tomcat/trunk/java/javax/servlet/GenericServlet.java?rev=966888&r1=966887&r2=966888&view=diff ============================================================================== --- tomcat/trunk/java/javax/servlet/GenericServlet.java (original) +++ tomcat/trunk/java/javax/servlet/GenericServlet.java Thu Jul 22 22:48:18 2010 @@ -1,325 +1,246 @@ /* -* 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.Enumeration; /** - * - * Defines a generic, protocol-independent - * servlet. To write an HTTP servlet for use on the - * Web, extend {@link javax.servlet.http.HttpServlet} instead. - * - *

GenericServlet implements the Servlet - * and ServletConfig interfaces. GenericServlet - * may be directly extended by a servlet, although it's more common to extend - * a protocol-specific subclass such as HttpServlet. - * - *

GenericServlet makes writing servlets - * easier. It provides simple versions of the lifecycle methods - * init and destroy and of the methods - * in the ServletConfig interface. GenericServlet - * also implements the log method, declared in the - * ServletContext interface. - * - *

To write a generic servlet, you need only - * override the abstract service method. - * - * - * @author Various - * @version $Version$ - * - * - * + * + * Defines a generic, protocol-independent servlet. To write an HTTP servlet for + * use on the Web, extend {@link javax.servlet.http.HttpServlet} instead. + * + *

+ * GenericServlet implements the Servlet and + * ServletConfig interfaces. GenericServlet may be + * directly extended by a servlet, although it's more common to extend a + * protocol-specific subclass such as HttpServlet. + * + *

+ * GenericServlet makes writing servlets easier. It provides simple + * versions of the lifecycle methods init and destroy + * and of the methods in the ServletConfig interface. + * GenericServlet also implements the log method, + * declared in the ServletContext interface. + * + *

+ * To write a generic servlet, you need only override the abstract + * service method. + * + * @version $Version$ */ - - -public abstract class GenericServlet - implements Servlet, ServletConfig, java.io.Serializable -{ +public abstract class GenericServlet implements Servlet, ServletConfig, + java.io.Serializable { private transient ServletConfig config; - /** - * - * Does nothing. All of the servlet initialization - * is done by one of the init methods. - * + * Does nothing. All of the servlet initialization is done by one of the + * init methods. */ public GenericServlet() { // NOOP } - - - - /** - * Called by the servlet container to indicate to a servlet that the - * servlet is being taken out of service. See {@link Servlet#destroy}. - * - * - */ + /** + * Called by the servlet container to indicate to a servlet that the servlet + * is being taken out of service. See {@link Servlet#destroy}. + */ public void destroy() { // NOOP by default } - - - + /** * Returns a String containing the value of the named - * initialization parameter, or null if the parameter does - * not exist. See {@link ServletConfig#getInitParameter}. - * - *

This method is supplied for convenience. It gets the - * value of the named parameter from the servlet's - * ServletConfig object. - * - * @param name a String specifying the name - * of the initialization parameter - * - * @return String a String containing the value - * of the initialization parameter - * - */ - + * initialization parameter, or null if the parameter does not + * exist. See {@link ServletConfig#getInitParameter}. + * + *

+ * This method is supplied for convenience. It gets the value of the named + * parameter from the servlet's ServletConfig object. + * + * @param name + * a String specifying the name of the + * initialization parameter + * + * @return String a String containing the value of the + * initialization parameter + */ public String getInitParameter(String name) { - return getServletConfig().getInitParameter(name); + return getServletConfig().getInitParameter(name); } - - - - /** - * Returns the names of the servlet's initialization parameters - * as an Enumeration of String objects, - * or an empty Enumeration if the servlet has no - * initialization parameters. See {@link - * ServletConfig#getInitParameterNames}. - * - *

This method is supplied for convenience. It gets the - * parameter names from the servlet's ServletConfig object. - * - * - * @return Enumeration an enumeration of String - * objects containing the names of - * the servlet's initialization parameters - * - */ + /** + * Returns the names of the servlet's initialization parameters as an + * Enumeration of String objects, or an empty + * Enumeration if the servlet has no initialization parameters. + * See {@link ServletConfig#getInitParameterNames}. + * + *

+ * This method is supplied for convenience. It gets the parameter names from + * the servlet's ServletConfig object. + * + * @return Enumeration an enumeration of String objects + * containing the names of the servlet's initialization parameters + */ public Enumeration getInitParameterNames() { - return getServletConfig().getInitParameterNames(); - } - - - - + return getServletConfig().getInitParameterNames(); + } /** * Returns this servlet's {@link ServletConfig} object. - * - * @return ServletConfig the ServletConfig object - * that initialized this servlet - * + * + * @return ServletConfig the ServletConfig object that + * initialized this servlet */ - public ServletConfig getServletConfig() { - return config; + return config; } - - - - + /** * Returns a reference to the {@link ServletContext} in which this servlet - * is running. See {@link ServletConfig#getServletContext}. - * - *

This method is supplied for convenience. It gets the - * context from the servlet's ServletConfig object. - * - * - * @return ServletContext the ServletContext object - * passed to this servlet by the init - * method - * + * is running. See {@link ServletConfig#getServletContext}. + * + *

+ * This method is supplied for convenience. It gets the context from the + * servlet's ServletConfig object. + * + * + * @return ServletContext the ServletContext object passed to + * this servlet by the init method */ - public ServletContext getServletContext() { - return getServletConfig().getServletContext(); + return getServletConfig().getServletContext(); } - - - - /** - * Returns information about the servlet, such as - * author, version, and copyright. - * By default, this method returns an empty string. Override this method - * to have it return a meaningful value. See {@link - * Servlet#getServletInfo}. - * - * - * @return String information about this servlet, by default an - * empty string - * + * Returns information about the servlet, such as author, version, and + * copyright. By default, this method returns an empty string. Override this + * method to have it return a meaningful value. See + * {@link Servlet#getServletInfo}. + * + * @return String information about this servlet, by default an empty string */ - public String getServletInfo() { - return ""; + return ""; } - - - /** - * - * Called by the servlet container to indicate to a servlet that the - * servlet is being placed into service. See {@link Servlet#init}. - * - *

This implementation stores the {@link ServletConfig} - * object it receives from the servlet container for later use. - * When overriding this form of the method, call - * super.init(config). - * - * @param config the ServletConfig object - * that contains configuration - * information for this servlet - * - * @exception ServletException if an exception occurs that - * interrupts the servlet's normal - * operation - * + * Called by the servlet container to indicate to a servlet that the servlet + * is being placed into service. See {@link Servlet#init}. + * + *

+ * This implementation stores the {@link ServletConfig} object it receives + * from the servlet container for later use. When overriding this form of + * the method, call super.init(config). + * + * @param config + * the ServletConfig object that contains + * configuration information for this servlet + * + * @exception ServletException + * if an exception occurs that interrupts the servlet's + * normal operation * - * @see UnavailableException - * + * @see UnavailableException */ - public void init(ServletConfig config) throws ServletException { - this.config = config; - this.init(); + this.config = config; + this.init(); } - - - - /** - * - * A convenience method which can be overridden so that there's no need - * to call super.init(config). - * - *

Instead of overriding {@link #init(ServletConfig)}, simply override - * this method and it will be called by - * GenericServlet.init(ServletConfig config). - * The ServletConfig object can still be retrieved via {@link - * #getServletConfig}. - * - * @exception ServletException if an exception occurs that - * interrupts the servlet's - * normal operation - * + * A convenience method which can be overridden so that there's no need to + * call super.init(config). + * + *

+ * Instead of overriding {@link #init(ServletConfig)}, simply override this + * method and it will be called by + * GenericServlet.init(ServletConfig config). The + * ServletConfig object can still be retrieved via + * {@link #getServletConfig}. + * + * @exception ServletException + * if an exception occurs that interrupts the servlet's + * normal operation */ - public void init() throws ServletException { // NOOP by default } - - - /** - * * Writes the specified message to a servlet log file, prepended by the - * servlet's name. See {@link ServletContext#log(String)}. - * - * @param msg a String specifying - * the message to be written to the log file - * + * servlet's name. See {@link ServletContext#log(String)}. + * + * @param msg + * a String specifying the message to be written to + * the log file */ - public void log(String msg) { - getServletContext().log(getServletName() + ": "+ msg); + getServletContext().log(getServletName() + ": " + msg); } - - - - - /** - * Writes an explanatory message and a stack trace - * for a given Throwable exception - * to the servlet log file, prepended by the servlet's name. - * See {@link ServletContext#log(String, Throwable)}. - * - * - * @param message a String that describes - * the error or exception - * - * @param t the java.lang.Throwable error - * or exception - * - * + + /** + * Writes an explanatory message and a stack trace for a given + * Throwable exception to the servlet log file, prepended by + * the servlet's name. See {@link ServletContext#log(String, Throwable)}. + * + * @param message + * a String that describes the error or exception + * + * @param tthe + * java.lang.Throwable error or exception */ - public void log(String message, Throwable t) { - getServletContext().log(getServletName() + ": " + message, t); + getServletContext().log(getServletName() + ": " + message, t); } - - - + /** - * Called by the servlet container to allow the servlet to respond to - * a request. See {@link Servlet#service}. + * Called by the servlet container to allow the servlet to respond to a + * request. See {@link Servlet#service}. * - *

This method is declared abstract so subclasses, such as + *

+ * This method is declared abstract so subclasses, such as * HttpServlet, must override it. - * - * - * - * @param req the ServletRequest object - * that contains the client's request - * - * @param res the ServletResponse object - * that will contain the servlet's response - * - * @exception ServletException if an exception occurs that - * interferes with the servlet's - * normal operation occurred - * - * @exception IOException if an input or output - * exception occurs - * + * + * @param req + * the ServletRequest object that contains the + * client's request + * + * @param res + * the ServletResponse object that will contain the + * servlet's response + * + * @exception ServletException + * if an exception occurs that interferes with the servlet's + * normal operation occurred + * + * @exception IOException + * if an input or output exception occurs */ - public abstract void service(ServletRequest req, ServletResponse res) - throws ServletException, IOException; - - + throws ServletException, IOException; /** - * Returns the name of this servlet instance. - * See {@link ServletConfig#getServletName}. - * - * @return the name of this servlet instance - * - * - * + * Returns the name of this servlet instance. See + * {@link ServletConfig#getServletName}. + * + * @return the name of this servlet instance */ - public String getServletName() { return config.getServletName(); } Modified: tomcat/trunk/java/javax/servlet/RequestDispatcher.java URL: http://svn.apache.org/viewvc/tomcat/trunk/java/javax/servlet/RequestDispatcher.java?rev=966888&r1=966887&r2=966888&view=diff ============================================================================== --- tomcat/trunk/java/javax/servlet/RequestDispatcher.java (original) +++ tomcat/trunk/java/javax/servlet/RequestDispatcher.java Thu Jul 22 22:48:18 2010 @@ -1,170 +1,138 @@ /* -* 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; - /** - * Defines an object that receives requests from the client - * and sends them to any resource (such as a servlet, - * HTML file, or JSP file) on the server. The servlet - * container creates the RequestDispatcher object, - * which is used as a wrapper around a server resource located - * at a particular path or given by a particular name. - * - *

This interface is intended to wrap servlets, - * but a servlet container can create RequestDispatcher - * objects to wrap any type of resource. - * - * @author Various - * @version $Version$ - * - * @see ServletContext#getRequestDispatcher(java.lang.String) - * @see ServletContext#getNamedDispatcher(java.lang.String) - * @see ServletRequest#getRequestDispatcher(java.lang.String) - * + * Defines an object that receives requests from the client and sends them to + * any resource (such as a servlet, HTML file, or JSP file) on the server. The + * servlet container creates the RequestDispatcher object, which is + * used as a wrapper around a server resource located at a particular path or + * given by a particular name. + * + *

+ * This interface is intended to wrap servlets, but a servlet container can + * create RequestDispatcher objects to wrap any type of resource. + * + * @author Various + * @version $Version$ + * + * @see ServletContext#getRequestDispatcher(java.lang.String) + * @see ServletContext#getNamedDispatcher(java.lang.String) + * @see ServletRequest#getRequestDispatcher(java.lang.String) + * */ - public interface RequestDispatcher { - public static final String ERROR_EXCEPTION = - "javax.servlet.error.exception"; - public static final String ERROR_EXCEPTION_TYPE = - "javax.servlet.error.exception_type"; - public static final String ERROR_MESSAGE = - "javax.servlet.error.message"; - public static final String ERROR_REQUEST_URI = - "javax.servlet.error.request_uri"; - public static final String ERROR_SERVLET_NAME = - "javax.servlet.error.servlet_name"; - public static final String ERROR_STATUS_CODE = - "javax.servlet.error.status_code"; - public static final String FORWARD_CONTEXT_PATH = - "javax.servlet.forward.context_path"; - public static final String FORWARD_PATH_INFO = - "javax.servlet.forward.path_info"; - public static final String FORWARD_QUERY_STRING = - "javax.servlet.forward.query_string"; - public static final String FORWARD_REQUEST_URI = - "javax.servlet.forward.request_uri"; - public static final String FORWARD_SERVLET_PATH = - "javax.servlet.forward.servlet_path"; - public static final String INCLUDE_CONTEXT_PATH = - "javax.servlet.include.context_path"; - public static final String INCLUDE_PATH_INFO = - "javax.servlet.include.path_info"; - public static final String INCLUDE_QUERY_STRING = - "javax.servlet.include.query_string"; - public static final String INCLUDE_REQUEST_URI = - "javax.servlet.include.request_uri"; - public static final String INCLUDE_SERVLET_PATH = - "javax.servlet.include.servlet_path"; - - - -/** - * Forwards a request from - * a servlet to another resource (servlet, JSP file, or - * HTML file) on the server. This method allows - * one servlet to do preliminary processing of - * a request and another resource to generate - * the response. - * - *

For a RequestDispatcher obtained via - * getRequestDispatcher(), the ServletRequest - * object has its path elements and parameters adjusted to match - * the path of the target resource. - * - *

forward should be called before the response has been - * committed to the client (before response body output has been flushed). - * If the response already has been committed, this method throws - * an IllegalStateException. - * Uncommitted output in the response buffer is automatically cleared - * before the forward. - * - *

The request and response parameters must be either the same - * objects as were passed to the calling servlet's service method or be - * subclasses of the {@link ServletRequestWrapper} or {@link ServletResponseWrapper} classes - * that wrap them. - * - * - * @param request a {@link ServletRequest} object - * that represents the request the client - * makes of the servlet - * - * @param response a {@link ServletResponse} object - * that represents the response the servlet - * returns to the client - * - * @exception ServletException if the target resource throws this exception - * - * @exception IOException if the target resource throws this exception - * - * @exception IllegalStateException if the response was already committed - * - */ + public static final String ERROR_EXCEPTION = "javax.servlet.error.exception"; + public static final String ERROR_EXCEPTION_TYPE = "javax.servlet.error.exception_type"; + public static final String ERROR_MESSAGE = "javax.servlet.error.message"; + public static final String ERROR_REQUEST_URI = "javax.servlet.error.request_uri"; + public static final String ERROR_SERVLET_NAME = "javax.servlet.error.servlet_name"; + public static final String ERROR_STATUS_CODE = "javax.servlet.error.status_code"; + public static final String FORWARD_CONTEXT_PATH = "javax.servlet.forward.context_path"; + public static final String FORWARD_PATH_INFO = "javax.servlet.forward.path_info"; + public static final String FORWARD_QUERY_STRING = "javax.servlet.forward.query_string"; + public static final String FORWARD_REQUEST_URI = "javax.servlet.forward.request_uri"; + public static final String FORWARD_SERVLET_PATH = "javax.servlet.forward.servlet_path"; + public static final String INCLUDE_CONTEXT_PATH = "javax.servlet.include.context_path"; + public static final String INCLUDE_PATH_INFO = "javax.servlet.include.path_info"; + public static final String INCLUDE_QUERY_STRING = "javax.servlet.include.query_string"; + public static final String INCLUDE_REQUEST_URI = "javax.servlet.include.request_uri"; + public static final String INCLUDE_SERVLET_PATH = "javax.servlet.include.servlet_path"; + /** + * Forwards a request from a servlet to another resource (servlet, JSP file, + * or HTML file) on the server. This method allows one servlet to do + * preliminary processing of a request and another resource to generate the + * response. + * + *

+ * For a RequestDispatcher obtained via + * getRequestDispatcher(), the ServletRequest + * object has its path elements and parameters adjusted to match the path of + * the target resource. + * + *

+ * forward should be called before the response has been + * committed to the client (before response body output has been flushed). + * If the response already has been committed, this method throws an + * IllegalStateException. Uncommitted output in the response + * buffer is automatically cleared before the forward. + * + *

+ * The request and response parameters must be either the same objects as + * were passed to the calling servlet's service method or be subclasses of + * the {@link ServletRequestWrapper} or {@link ServletResponseWrapper} + * classes that wrap them. + * + * + * @param request + * a {@link ServletRequest} object that represents the request + * the client makes of the servlet + * + * @param response + * a {@link ServletResponse} object that represents the response + * the servlet returns to the client + * + * @exception ServletException + * if the target resource throws this exception + * + * @exception IOException + * if the target resource throws this exception + * + * @exception IllegalStateException + * if the response was already committed + */ public void forward(ServletRequest request, ServletResponse response) - throws ServletException, IOException; - - - + throws ServletException, IOException; /** - * - * Includes the content of a resource (servlet, JSP page, - * HTML file) in the response. In essence, this method enables - * programmatic server-side includes. - * - *

The {@link ServletResponse} object has its path elements - * and parameters remain unchanged from the caller's. The included - * servlet cannot change the response status code or set headers; - * any attempt to make a change is ignored. - * - *

The request and response parameters must be either the same - * objects as were passed to the calling servlet's service method or be - * subclasses of the {@link ServletRequestWrapper} or {@link ServletResponseWrapper} classes - * that wrap them. - * - * - * - * @param request a {@link ServletRequest} object - * that contains the client's request - * - * @param response a {@link ServletResponse} object - * that contains the servlet's response - * - * @exception ServletException if the included resource throws this exception - * - * @exception IOException if the included resource throws this exception - * - * + * Includes the content of a resource (servlet, JSP page, HTML file) in the + * response. In essence, this method enables programmatic server-side + * includes. + * + *

+ * The {@link ServletResponse} object has its path elements and parameters + * remain unchanged from the caller's. The included servlet cannot change + * the response status code or set headers; any attempt to make a change is + * ignored. + * + *

+ * The request and response parameters must be either the same objects as + * were passed to the calling servlet's service method or be subclasses of + * the {@link ServletRequestWrapper} or {@link ServletResponseWrapper} + * classes that wrap them. + * + * @param request + * a {@link ServletRequest} object that contains the client's + * request + * + * @param response + * a {@link ServletResponse} object that contains the servlet's + * response + * + * @exception ServletException + * if the included resource throws this exception + * + * @exception IOException + * if the included resource throws this exception */ - public void include(ServletRequest request, ServletResponse response) - throws ServletException, IOException; + throws ServletException, IOException; } - - - - - - - - Modified: tomcat/trunk/java/javax/servlet/Servlet.java URL: http://svn.apache.org/viewvc/tomcat/trunk/java/javax/servlet/Servlet.java?rev=966888&r1=966887&r2=966888&view=diff ============================================================================== --- tomcat/trunk/java/javax/servlet/Servlet.java (original) +++ tomcat/trunk/java/javax/servlet/Servlet.java Thu Jul 22 22:48:18 2010 @@ -1,193 +1,180 @@ /* -* 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; - /** * Defines methods that all servlets must implement. - * - *

A servlet is a small Java program that runs within a Web server. - * Servlets receive and respond to requests from Web clients, - * usually across HTTP, the HyperText Transfer Protocol. - * - *

To implement this interface, you can write a generic servlet - * that extends - * javax.servlet.GenericServlet or an HTTP servlet that - * extends javax.servlet.http.HttpServlet. - * - *

This interface defines methods to initialize a servlet, - * to service requests, and to remove a servlet from the server. - * These are known as life-cycle methods and are called in the - * following sequence: + * + *

+ * A servlet is a small Java program that runs within a Web server. Servlets + * receive and respond to requests from Web clients, usually across HTTP, the + * HyperText Transfer Protocol. + * + *

+ * To implement this interface, you can write a generic servlet that extends + * javax.servlet.GenericServlet or an HTTP servlet that extends + * javax.servlet.http.HttpServlet. + * + *

+ * This interface defines methods to initialize a servlet, to service requests, + * and to remove a servlet from the server. These are known as life-cycle + * methods and are called in the following sequence: *

    - *
  1. The servlet is constructed, then initialized with the init method. + *
  2. The servlet is constructed, then initialized with the init + * method. *
  3. Any calls from clients to the service method are handled. - *
  4. The servlet is taken out of service, then destroyed with the + *
  5. The servlet is taken out of service, then destroyed with the * destroy method, then garbage collected and finalized. *
- * - *

In addition to the life-cycle methods, this interface - * provides the getServletConfig method, which the servlet - * can use to get any startup information, and the getServletInfo - * method, which allows the servlet to return basic information about itself, - * such as author, version, and copyright. - * - * @author Various - * @version $Version$ - * - * @see GenericServlet - * @see javax.servlet.http.HttpServlet - * + * + *

+ * In addition to the life-cycle methods, this interface provides the + * getServletConfig method, which the servlet can use to get any + * startup information, and the getServletInfo method, which allows + * the servlet to return basic information about itself, such as author, + * version, and copyright. + * + * @version $Version$ + * + * @see GenericServlet + * @see javax.servlet.http.HttpServlet */ - - public interface Servlet { /** - * Called by the servlet container to indicate to a servlet that the - * servlet is being placed into service. - * - *

The servlet container calls the init - * method exactly once after instantiating the servlet. - * The init method must complete successfully - * before the servlet can receive any requests. - * - *

The servlet container cannot place the servlet into service - * if the init method + * Called by the servlet container to indicate to a servlet that the servlet + * is being placed into service. + * + *

+ * The servlet container calls the init method exactly once + * after instantiating the servlet. The init method must + * complete successfully before the servlet can receive any requests. + * + *

+ * The servlet container cannot place the servlet into service if the + * init method *

    *
  1. Throws a ServletException *
  2. Does not return within a time period defined by the Web server *
- * - * - * @param config a ServletConfig object - * containing the servlet's - * configuration and initialization parameters - * - * @exception ServletException if an exception has occurred that - * interferes with the servlet's normal - * operation - * - * @see UnavailableException - * @see #getServletConfig - * + * + * + * @param config + * a ServletConfig object containing the servlet's + * configuration and initialization parameters + * + * @exception ServletException + * if an exception has occurred that interferes with the + * servlet's normal operation + * + * @see UnavailableException + * @see #getServletConfig */ - public void init(ServletConfig config) throws ServletException; - - /** - * - * Returns a {@link ServletConfig} object, which contains - * initialization and startup parameters for this servlet. - * The ServletConfig object returned is the one - * passed to the init method. - * - *

Implementations of this interface are responsible for storing the - * ServletConfig object so that this - * method can return it. The {@link GenericServlet} - * class, which implements this interface, already does this. - * - * @return the ServletConfig object - * that initializes this servlet - * - * @see #init - * + * + * Returns a {@link ServletConfig} object, which contains initialization and + * startup parameters for this servlet. The ServletConfig + * object returned is the one passed to the init method. + * + *

+ * Implementations of this interface are responsible for storing the + * ServletConfig object so that this method can return it. The + * {@link GenericServlet} class, which implements this interface, already + * does this. + * + * @return the ServletConfig object that initializes this + * servlet + * + * @see #init */ - public ServletConfig getServletConfig(); - - /** - * Called by the servlet container to allow the servlet to respond to - * a request. - * - *

This method is only called after the servlet's init() - * method has completed successfully. - * - *

The status code of the response always should be set for a servlet - * that throws or sends an error. - * - * - *

Servlets typically run inside multithreaded servlet containers - * that can handle multiple requests concurrently. Developers must - * be aware to synchronize access to any shared resources such as files, - * network connections, and as well as the servlet's class and instance - * variables. - * More information on multithreaded programming in Java is available in - * + * Called by the servlet container to allow the servlet to respond to a + * request. + * + *

+ * This method is only called after the servlet's init() method + * has completed successfully. + * + *

+ * The status code of the response always should be set for a servlet that + * throws or sends an error. + * + * + *

+ * Servlets typically run inside multithreaded servlet containers that can + * handle multiple requests concurrently. Developers must be aware to + * synchronize access to any shared resources such as files, network + * connections, and as well as the servlet's class and instance variables. + * More information on multithreaded programming in Java is available in * the Java tutorial on multi-threaded programming. - * - * - * @param req the ServletRequest object that contains - * the client's request - * - * @param res the ServletResponse object that contains - * the servlet's response - * - * @exception ServletException if an exception occurs that interferes - * with the servlet's normal operation - * - * @exception IOException if an input or output exception occurs - * + * + * + * @param req + * the ServletRequest object that contains the + * client's request + * + * @param res + * the ServletResponse object that contains the + * servlet's response + * + * @exception ServletException + * if an exception occurs that interferes with the servlet's + * normal operation + * + * @exception IOException + * if an input or output exception occurs */ - public void service(ServletRequest req, ServletResponse res) - throws ServletException, IOException; - - + throws ServletException, IOException; /** - * Returns information about the servlet, such - * as author, version, and copyright. + * Returns information about the servlet, such as author, version, and + * copyright. * - *

The string that this method returns should - * be plain text and not markup of any kind (such as HTML, XML, - * etc.). - * - * @return a String containing servlet information - * + *

+ * The string that this method returns should be plain text and not markup + * of any kind (such as HTML, XML, etc.). + * + * @return a String containing servlet information */ - public String getServletInfo(); - - /** - * - * Called by the servlet container to indicate to a servlet that the - * servlet is being taken out of service. This method is - * only called once all threads within the servlet's - * service method have exited or after a timeout - * period has passed. After the servlet container calls this - * method, it will not call the service method again - * on this servlet. - * - *

This method gives the servlet an opportunity - * to clean up any resources that are being held (for example, memory, - * file handles, threads) and make sure that any persistent state is - * synchronized with the servlet's current state in memory. - * + * Called by the servlet container to indicate to a servlet that the servlet + * is being taken out of service. This method is only called once all + * threads within the servlet's service method have exited or + * after a timeout period has passed. After the servlet container calls this + * method, it will not call the service method again on this + * servlet. + * + *

+ * This method gives the servlet an opportunity to clean up any resources + * that are being held (for example, memory, file handles, threads) and make + * sure that any persistent state is synchronized with the servlet's current + * state in memory. */ - public void destroy(); } --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org For additional commands, e-mail: dev-help@tomcat.apache.org