2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
9 * http://www.apache.org/licenses/LICENSE-2.0
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
18 package javax.servlet;
20 import java.io.IOException;
23 * Defines methods that all servlets must implement.
26 * A servlet is a small Java program that runs within a Web server. Servlets
27 * receive and respond to requests from Web clients, usually across HTTP, the
28 * HyperText Transfer Protocol.
31 * To implement this interface, you can write a generic servlet that extends
32 * <code>javax.servlet.GenericServlet</code> or an HTTP servlet that extends
33 * <code>javax.servlet.http.HttpServlet</code>.
36 * This interface defines methods to initialize a servlet, to service requests,
37 * and to remove a servlet from the server. These are known as life-cycle
38 * methods and are called in the following sequence:
40 * <li>The servlet is constructed, then initialized with the <code>init</code>
42 * <li>Any calls from clients to the <code>service</code> method are handled.
43 * <li>The servlet is taken out of service, then destroyed with the
44 * <code>destroy</code> method, then garbage collected and finalized.
48 * In addition to the life-cycle methods, this interface provides the
49 * <code>getServletConfig</code> method, which the servlet can use to get any
50 * startup information, and the <code>getServletInfo</code> method, which allows
51 * the servlet to return basic information about itself, such as author,
52 * version, and copyright.
55 * @see javax.servlet.http.HttpServlet
57 public interface Servlet {
60 * Called by the servlet container to indicate to a servlet that the servlet
61 * is being placed into service.
64 * The servlet container calls the <code>init</code> method exactly once
65 * after instantiating the servlet. The <code>init</code> method must
66 * complete successfully before the servlet can receive any requests.
69 * The servlet container cannot place the servlet into service if the
70 * <code>init</code> method
72 * <li>Throws a <code>ServletException</code>
73 * <li>Does not return within a time period defined by the Web server
78 * a <code>ServletConfig</code> object containing the servlet's
79 * configuration and initialization parameters
81 * @exception ServletException
82 * if an exception has occurred that interferes with the
83 * servlet's normal operation
85 * @see UnavailableException
86 * @see #getServletConfig
88 public void init(ServletConfig config) throws ServletException;
92 * Returns a {@link ServletConfig} object, which contains initialization and
93 * startup parameters for this servlet. The <code>ServletConfig</code>
94 * object returned is the one passed to the <code>init</code> method.
97 * Implementations of this interface are responsible for storing the
98 * <code>ServletConfig</code> object so that this method can return it. The
99 * {@link GenericServlet} class, which implements this interface, already
102 * @return the <code>ServletConfig</code> object that initializes this
107 public ServletConfig getServletConfig();
110 * Called by the servlet container to allow the servlet to respond to a
114 * This method is only called after the servlet's <code>init()</code> method
115 * has completed successfully.
118 * The status code of the response always should be set for a servlet that
119 * throws or sends an error.
123 * Servlets typically run inside multithreaded servlet containers that can
124 * handle multiple requests concurrently. Developers must be aware to
125 * synchronize access to any shared resources such as files, network
126 * connections, and as well as the servlet's class and instance variables.
127 * More information on multithreaded programming in Java is available in <a
129 * ="http://java.sun.com/Series/Tutorial/java/threads/multithreaded.html">
130 * the Java tutorial on multi-threaded programming</a>.
134 * the <code>ServletRequest</code> object that contains the
138 * the <code>ServletResponse</code> object that contains the
141 * @exception ServletException
142 * if an exception occurs that interferes with the servlet's
145 * @exception IOException
146 * if an input or output exception occurs
148 public void service(ServletRequest req, ServletResponse res)
149 throws ServletException, IOException;
152 * Returns information about the servlet, such as author, version, and
156 * The string that this method returns should be plain text and not markup
157 * of any kind (such as HTML, XML, etc.).
159 * @return a <code>String</code> containing servlet information
161 public String getServletInfo();
164 * Called by the servlet container to indicate to a servlet that the servlet
165 * is being taken out of service. This method is only called once all
166 * threads within the servlet's <code>service</code> method have exited or
167 * after a timeout period has passed. After the servlet container calls this
168 * method, it will not call the <code>service</code> method again on this
172 * This method gives the servlet an opportunity to clean up any resources
173 * that are being held (for example, memory, file handles, threads) and make
174 * sure that any persistent state is synchronized with the servlet's current
177 public void destroy();