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