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