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