1 2 3 /* 4 * The contents of this file are subject to the terms 5 * of the Common Development and Distribution License 6 * (the "License"). You may not use this file except 7 * in compliance with the License. 8 * 9 * You can obtain a copy of the license at 10 * glassfish/bootstrap/legal/CDDLv1.0.txt or 11 * https://glassfish.dev.java.net/public/CDDLv1.0.html. 12 * See the License for the specific language governing 13 * permissions and limitations under the License. 14 * 15 * When distributing Covered Code, include this CDDL 16 * HEADER in each file and include the License file at 17 * glassfish/bootstrap/legal/CDDLv1.0.txt. If applicable, 18 * add the following below this CDDL HEADER, with the 19 * fields enclosed by brackets "[]" replaced with your 20 * own identifying information: Portions Copyright [yyyy] 21 * [name of copyright owner] 22 * 23 * Copyright 2005 Sun Microsystems, Inc. All rights reserved. 24 * 25 * Portions Copyright Apache Software Foundation. 26 */ 27 28 package javax.servlet; 29 30 import java.io.IOException; 31 32 33 /** 34 * Defines methods that all servlets must implement. 35 * 36 * <p>A servlet is a small Java program that runs within a Web server. 37 * Servlets receive and respond to requests from Web clients, 38 * usually across HTTP, the HyperText Transfer Protocol. 39 * 40 * <p>To implement this interface, you can write a generic servlet 41 * that extends 42 * <code>javax.servlet.GenericServlet</code> or an HTTP servlet that 43 * extends <code>javax.servlet.http.HttpServlet</code>. 44 * 45 * <p>This interface defines methods to initialize a servlet, 46 * to service requests, and to remove a servlet from the server. 47 * These are known as life-cycle methods and are called in the 48 * following sequence: 49 * <ol> 50 * <li>The servlet is constructed, then initialized with the <code>init</code> method. 51 * <li>Any calls from clients to the <code>service</code> method are handled. 52 * <li>The servlet is taken out of service, then destroyed with the 53 * <code>destroy</code> method, then garbage collected and finalized. 54 * </ol> 55 * 56 * <p>In addition to the life-cycle methods, this interface 57 * provides the <code>getServletConfig</code> method, which the servlet 58 * can use to get any startup information, and the <code>getServletInfo</code> 59 * method, which allows the servlet to return basic information about itself, 60 * such as author, version, and copyright. 61 * 62 * @author Various 63 * 64 * @see GenericServlet 65 * @see javax.servlet.http.HttpServlet 66 * 67 */ 68 69 70 public interface Servlet { 71 72 /** 73 * Called by the servlet container to indicate to a servlet that the 74 * servlet is being placed into service. 75 * 76 * <p>The servlet container calls the <code>init</code> 77 * method exactly once after instantiating the servlet. 78 * The <code>init</code> method must complete successfully 79 * before the servlet can receive any requests. 80 * 81 * <p>The servlet container cannot place the servlet into service 82 * if the <code>init</code> method 83 * <ol> 84 * <li>Throws a <code>ServletException</code> 85 * <li>Does not return within a time period defined by the Web server 86 * </ol> 87 * 88 * 89 * @param config a <code>ServletConfig</code> object 90 * containing the servlet's 91 * configuration and initialization parameters 92 * 93 * @exception ServletException if an exception has occurred that 94 * interferes with the servlet's normal 95 * operation 96 * 97 * @see UnavailableException 98 * @see #getServletConfig 99 * 100 */ 101 102 public void init(ServletConfig config) throws ServletException; 103 104 105 106 /** 107 * 108 * Returns a {@link ServletConfig} object, which contains 109 * initialization and startup parameters for this servlet. 110 * The <code>ServletConfig</code> object returned is the one 111 * passed to the <code>init</code> method. 112 * 113 * <p>Implementations of this interface are responsible for storing the 114 * <code>ServletConfig</code> object so that this 115 * method can return it. The {@link GenericServlet} 116 * class, which implements this interface, already does this. 117 * 118 * @return the <code>ServletConfig</code> object 119 * that initializes this servlet 120 * 121 * @see #init 122 * 123 */ 124 125 public ServletConfig getServletConfig(); 126 127 128 129 /** 130 * Called by the servlet container to allow the servlet to respond to 131 * a request. 132 * 133 * <p>This method is only called after the servlet's <code>init()</code> 134 * method has completed successfully. 135 * 136 * <p> The status code of the response always should be set for a servlet 137 * that throws or sends an error. 138 * 139 * 140 * <p>Servlets typically run inside multithreaded servlet containers 141 * that can handle multiple requests concurrently. Developers must 142 * be aware to synchronize access to any shared resources such as files, 143 * network connections, and as well as the servlet's class and instance 144 * variables. 145 * More information on multithreaded programming in Java is available in 146 * <a href="http://java.sun.com/Series/Tutorial/java/threads/multithreaded.html"> 147 * the Java tutorial on multi-threaded programming</a>. 148 * 149 * 150 * @param req the <code>ServletRequest</code> object that contains 151 * the client's request 152 * 153 * @param res the <code>ServletResponse</code> object that contains 154 * the servlet's response 155 * 156 * @exception ServletException if an exception occurs that interferes 157 * with the servlet's normal operation 158 * 159 * @exception IOException if an input or output exception occurs 160 * 161 */ 162 163 public void service(ServletRequest req, ServletResponse res) 164 throws ServletException, IOException; 165 166 167 168 /** 169 * Returns information about the servlet, such 170 * as author, version, and copyright. 171 * 172 * <p>The string that this method returns should 173 * be plain text and not markup of any kind (such as HTML, XML, 174 * etc.). 175 * 176 * @return a <code>String</code> containing servlet information 177 * 178 */ 179 180 public String getServletInfo(); 181 182 183 184 /** 185 * 186 * Called by the servlet container to indicate to a servlet that the 187 * servlet is being taken out of service. This method is 188 * only called once all threads within the servlet's 189 * <code>service</code> method have exited or after a timeout 190 * period has passed. After the servlet container calls this 191 * method, it will not call the <code>service</code> method again 192 * on this servlet. 193 * 194 * <p>This method gives the servlet an opportunity 195 * to clean up any resources that are being held (for example, memory, 196 * file handles, threads) and make sure that any persistent state is 197 * synchronized with the servlet's current state in memory. 198 * 199 */ 200 201 public void destroy(); 202 }