Save This Page
Home » glassfish-v2ur2-b04-src » javax » servlet » [javadoc | source]
    1   
    2   
    3   /*
    4    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
    5    * 
    6    * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
    7    * 
    8    * Portions Copyright Apache Software Foundation.
    9    * 
   10    * The contents of this file are subject to the terms of either the GNU
   11    * General Public License Version 2 only ("GPL") or the Common Development
   12    * and Distribution License("CDDL") (collectively, the "License").  You
   13    * may not use this file except in compliance with the License. You can obtain
   14    * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
   15    * or glassfish/bootstrap/legal/LICENSE.txt.  See the License for the specific
   16    * language governing permissions and limitations under the License.
   17    * 
   18    * When distributing the software, include this License Header Notice in each
   19    * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt.
   20    * Sun designates this particular file as subject to the "Classpath" exception
   21    * as provided by Sun in the GPL Version 2 section of the License file that
   22    * accompanied this code.  If applicable, add the following below the License
   23    * Header, with the fields enclosed by brackets [] replaced by your own
   24    * identifying information: "Portions Copyrighted [year]
   25    * [name of copyright owner]"
   26    * 
   27    * Contributor(s):
   28    * 
   29    * If you wish your version of this file to be governed by only the CDDL or
   30    * only the GPL Version 2, indicate your decision by adding "[Contributor]
   31    * elects to include this software in this distribution under the [CDDL or GPL
   32    * Version 2] license."  If you don't indicate a single choice of license, a
   33    * recipient has the option to distribute your version of this file under
   34    * either the CDDL, the GPL Version 2 or to extend the choice of license to
   35    * its licensees as provided above.  However, if you add GPL Version 2 code
   36    * and therefore, elected the GPL Version 2 license, then the option applies
   37    * only if the new code is made subject to such option by the copyright
   38    * holder.
   39    */
   40   
   41   
   42   package javax.servlet;
   43   
   44   import java.io.IOException;
   45   
   46   
   47   /**
   48    * Defines an object that receives requests from the client
   49    * and sends them to any resource (such as a servlet, 
   50    * HTML file, or JSP file) on the server. The servlet
   51    * container creates the <code>RequestDispatcher</code> object,
   52    * which is used as a wrapper around a server resource located
   53    * at a particular path or given by a particular name.
   54    *
   55    * <p>This interface is intended to wrap servlets,
   56    * but a servlet container can create <code>RequestDispatcher</code>
   57    * objects to wrap any type of resource.
   58    *
   59    * @author 	Various
   60    *
   61    * @see 	ServletContext#getRequestDispatcher(java.lang.String)
   62    * @see 	ServletContext#getNamedDispatcher(java.lang.String)
   63    * @see 	ServletRequest#getRequestDispatcher(java.lang.String)
   64    *
   65    */
   66    
   67   public interface RequestDispatcher {
   68   
   69   
   70   
   71   
   72   
   73   /**
   74    * Forwards a request from
   75    * a servlet to another resource (servlet, JSP file, or
   76    * HTML file) on the server. This method allows
   77    * one servlet to do preliminary processing of
   78    * a request and another resource to generate
   79    * the response.
   80    *
   81    * <p>For a <code>RequestDispatcher</code> obtained via 
   82    * <code>getRequestDispatcher()</code>, the <code>ServletRequest</code> 
   83    * object has its path elements and parameters adjusted to match
   84    * the path of the target resource.
   85    *
   86    * <p><code>forward</code> should be called before the response has been 
   87    * committed to the client (before response body output has been flushed).  
   88    * If the response already has been committed, this method throws
   89    * an <code>IllegalStateException</code>.
   90    * Uncommitted output in the response buffer is automatically cleared 
   91    * before the forward.
   92    *
   93    * <p>The request and response parameters must be either the same
   94    * objects as were passed to the calling servlet's service method or be
   95    * subclasses of the {@link ServletRequestWrapper} or {@link ServletResponseWrapper} classes
   96    * that wrap them.
   97    *
   98    *
   99    * @param request		a {@link ServletRequest} object
  100    *				that represents the request the client
  101    * 				makes of the servlet
  102    *
  103    * @param response		a {@link ServletResponse} object
  104    *				that represents the response the servlet
  105    *				returns to the client
  106    *
  107    * @exception ServletException	if the target resource throws this exception
  108    *
  109    * @exception IOException	if the target resource throws this exception
  110    *
  111    * @exception IllegalStateException	if the response was already committed
  112    *
  113    */
  114   
  115       public void forward(ServletRequest request, ServletResponse response)
  116   	throws ServletException, IOException;
  117   
  118   
  119   
  120   
  121       /**
  122        *
  123        * Includes the content of a resource (servlet, JSP page,
  124        * HTML file) in the response. In essence, this method enables 
  125        * programmatic server-side includes.
  126        *
  127        * <p>The {@link ServletResponse} object has its path elements
  128        * and parameters remain unchanged from the caller's. The included
  129        * servlet cannot change the response status code or set headers;
  130        * any attempt to make a change is ignored.
  131        *
  132        * <p>The request and response parameters must be either the same
  133        * objects as were passed to the calling servlet's service method or be
  134        * subclasses of the {@link ServletRequestWrapper} or {@link ServletResponseWrapper} classes
  135        * that wrap them.
  136        * 
  137        *
  138        *
  139        * @param request 			a {@link ServletRequest} object 
  140        *					that contains the client's request
  141        *
  142        * @param response 			a {@link ServletResponse} object 
  143        * 					that contains the servlet's response
  144        *
  145        * @exception ServletException 	if the included resource throws this exception
  146        *
  147        * @exception IOException 		if the included resource throws this exception
  148        *
  149        *
  150        */
  151        
  152       public void include(ServletRequest request, ServletResponse response)
  153   	throws ServletException, IOException;
  154   }
  155   
  156   
  157   
  158   
  159   
  160   
  161   
  162   

Save This Page
Home » glassfish-v2ur2-b04-src » javax » servlet » [javadoc | source]