001 /* 002 * Licensed to the Apache Software Foundation (ASF) under one 003 * or more contributor license agreements. See the NOTICE file 004 * distributed with this work for additional information 005 * regarding copyright ownership. The ASF licenses this file 006 * to you under the Apache License, Version 2.0 (the 007 * "License"); you may not use this file except in compliance 008 * with the License. You may obtain a copy of the License at 009 * 010 * http://www.apache.org/licenses/LICENSE-2.0 011 * 012 * Unless required by applicable law or agreed to in writing, 013 * software distributed under the License is distributed on an 014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 015 * KIND, either express or implied. See the License for the 016 * specific language governing permissions and limitations 017 * under the License. 018 */ 019 020 // 021 // This source code implements specifications defined by the Java 022 // Community Process. In order to remain compliant with the specification 023 // DO NOT add / change / or delete method signatures! 024 // 025 026 package javax.servlet; 027 028 import java.io.IOException; 029 030 /** 031 * Defines methods that all servlets must implement. 032 * 033 * <p>A servlet is a small Java program that runs within a Web server. 034 * Servlets receive and respond to requests from Web clients, 035 * usually across HTTP, the HyperText Transfer Protocol. 036 * 037 * <p>To implement this interface, you can write a generic servlet 038 * that extends 039 * <code>javax.servlet.GenericServlet</code> or an HTTP servlet that 040 * extends <code>javax.servlet.http.HttpServlet</code>. 041 * 042 * <p>This interface defines methods to initialize a servlet, 043 * to service requests, and to remove a servlet from the server. 044 * These are known as life-cycle methods and are called in the 045 * following sequence: 046 * <ol> 047 * <li>The servlet is constructed, then initialized with the <code>init</code> method. 048 * <li>Any calls from clients to the <code>service</code> method are handled. 049 * <li>The servlet is taken out of service, then destroyed with the 050 * <code>destroy</code> method, then garbage collected and finalized. 051 * </ol> 052 * 053 * <p>In addition to the life-cycle methods, this interface 054 * provides the <code>getServletConfig</code> method, which the servlet 055 * can use to get any startup information, and the <code>getServletInfo</code> 056 * method, which allows the servlet to return basic information about itself, 057 * such as author, version, and copyright. 058 * 059 * @see GenericServlet 060 * @see javax.servlet.http.HttpServlet 061 * 062 * @version $Rev: 467553 $ $Date: 2006-10-25 06:01:51 +0200 (Mi, 25. Okt 2006) $ 063 */ 064 public interface Servlet { 065 /** 066 * Called by the servlet container to indicate to a servlet that the 067 * servlet is being placed into service. 068 * 069 * <p>The servlet container calls the <code>init</code> 070 * method exactly once after instantiating the servlet. 071 * The <code>init</code> method must complete successfully 072 * before the servlet can receive any requests. 073 * 074 * <p>The servlet container cannot place the servlet into service 075 * if the <code>init</code> method 076 * <ol> 077 * <li>Throws a <code>ServletException</code> 078 * <li>Does not return within a time period defined by the Web server 079 * </ol> 080 * 081 * 082 * @param config a <code>ServletConfig</code> object 083 * containing the servlet's configuration and initialization parameters 084 * 085 * @exception ServletException if an exception has occurred that 086 * interferes with the servlet's normal operation 087 * 088 * @see UnavailableException 089 * @see #getServletConfig 090 */ 091 public void init(ServletConfig config) throws ServletException; 092 093 /** 094 * Returns a {@link ServletConfig} object, which contains 095 * initialization and startup parameters for this servlet. 096 * The <code>ServletConfig</code> object returned is the one 097 * passed to the <code>init</code> method. 098 * 099 * <p>Implementations of this interface are responsible for storing the 100 * <code>ServletConfig</code> object so that this 101 * method can return it. The {@link GenericServlet} 102 * class, which implements this interface, already does this. 103 * 104 * @return the <code>ServletConfig</code> object 105 * that initializes this servlet 106 * 107 * @see #init 108 */ 109 public ServletConfig getServletConfig(); 110 111 /** 112 * Called by the servlet container to allow the servlet to respond to 113 * a request. 114 * 115 * <p>This method is only called after the servlet's <code>init()</code> 116 * method has completed successfully. 117 * 118 * <p> The status code of the response always should be set for a servlet 119 * that throws or sends an error. 120 * 121 * <p>Servlets typically run inside multithreaded servlet containers 122 * that can handle multiple requests concurrently. Developers must 123 * be aware to synchronize access to any shared resources such as files, 124 * network connections, and as well as the servlet's class and instance 125 * variables. 126 * More information on multithreaded programming in Java is available in 127 * <a href="http://java.sun.com/Series/Tutorial/java/threads/multithreaded.html"> 128 * the Java tutorial on multi-threaded programming</a>. 129 * 130 * 131 * @param req the <code>ServletRequest</code> object that contains 132 * the client's request 133 * 134 * @param res the <code>ServletResponse</code> object that contains 135 * the servlet's response 136 * 137 * @exception ServletException if an exception occurs that interferes 138 * with the servlet's normal operation 139 * 140 * @exception IOException if an input or output exception occurs 141 */ 142 public void service(ServletRequest req, ServletResponse res) 143 throws ServletException, IOException; 144 145 /** 146 * Returns information about the servlet, such 147 * as author, version, and copyright. 148 * 149 * <p>The string that this method returns should 150 * be plain text and not markup of any kind (such as HTML, XML, 151 * etc.). 152 * 153 * @return a <code>String</code> containing servlet information 154 */ 155 public String getServletInfo(); 156 157 /** 158 * Called by the servlet container to indicate to a servlet that the 159 * servlet is being taken out of service. This method is 160 * only called once all threads within the servlet's 161 * <code>service</code> method have exited or after a timeout 162 * period has passed. After the servlet container calls this 163 * method, it will not call the <code>service</code> method again 164 * on this servlet. 165 * 166 * <p>This method gives the servlet an opportunity 167 * to clean up any resources that are being held (for example, memory, 168 * file handles, threads) and make sure that any persistent state is 169 * synchronized with the servlet's current state in memory. 170 */ 171 public void destroy(); 172 }