Servlet


1   /*
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
8   *
9   *     http://www.apache.org/licenses/LICENSE-2.0
10  *
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.
16  */
17   
18  package javax.servlet;
19  
20  import java.io.IOException  ;
21  
22  
23  /**
24   * Defines methods that all servlets must implement.
25   *
26   * <p>A servlet is a small Java program that runs within a Web server.
27   * Servlets receive and respond to requests from Web clients,
28   * usually across HTTP, the HyperText Transfer Protocol. 
29   *
30   * <p>To implement this interface, you can write a generic servlet
31   * that extends
32   * <code>javax.servlet.GenericServlet</code> or an HTTP servlet that
33   * extends <code>javax.servlet.http.HttpServlet</code>.
34   *
35   * <p>This interface defines methods to initialize a servlet,
36   * to service requests, and to remove a servlet from the server.
37   * These are known as life-cycle methods and are called in the
38   * following sequence:
39   * <ol>
40   * <li>The servlet is constructed, then initialized with the <code>init</code> method.
41   * <li>Any calls from clients to the <code>service</code> method are handled.
42   * <li>The servlet is taken out of service, then destroyed with the 
43   * <code>destroy</code> method, then garbage collected and finalized.
44   * </ol>
45   *
46   * <p>In addition to the life-cycle methods, this interface
47   * provides the <code>getServletConfig</code> method, which the servlet 
48   * can use to get any startup information, and the <code>getServletInfo</code>
49   * method, which allows the servlet to return basic information about itself,
50   * such as author, version, and copyright.
51   *
52   * @author  Various
53   * @version     $Version$
54   *
55   * @see     GenericServlet
56   * @see     javax.servlet.http.HttpServlet
57   *
58   */
59  
60  
61  public interface Servlet {
62  
63      /**
64       * Called by the servlet container to indicate to a servlet that the 
65       * servlet is being placed into service.
66       *
67       * <p>The servlet container calls the <code>init</code>
68       * method exactly once after instantiating the servlet.
69       * The <code>init</code> method must complete successfully
70       * before the servlet can receive any requests.
71       *
72       * <p>The servlet container cannot place the servlet into service
73       * if the <code>init</code> method
74       * <ol>
75       * <li>Throws a <code>ServletException</code>
76       * <li>Does not return within a time period defined by the Web server
77       * </ol>
78       *
79       *
80       * @param config            a <code>ServletConfig</code> object 
81       *                  containing the servlet's
82       *                  configuration and initialization parameters
83       *
84       * @exception ServletException  if an exception has occurred that
85       *                  interferes with the servlet's normal
86       *                  operation
87       *
88       * @see                 UnavailableException
89       * @see                 #getServletConfig
90       *
91       */
92  
93      public void init(ServletConfig   config) throws ServletException  ;
94      
95      
96  
97      /**
98       *
99       * Returns a {@link ServletConfig} object, which contains
100      * initialization and startup parameters for this servlet.
101      * The <code>ServletConfig</code> object returned is the one 
102      * passed to the <code>init</code> method. 
103      *
104      * <p>Implementations of this interface are responsible for storing the 
105      * <code>ServletConfig</code> object so that this 
106      * method can return it. The {@link GenericServlet}
107      * class, which implements this interface, already does this.
108      *
109      * @return      the <code>ServletConfig</code> object
110      *          that initializes this servlet
111      *
112      * @see         #init
113      *
114      */
115 
116     public ServletConfig   getServletConfig();
117     
118     
119 
120     /**
121      * Called by the servlet container to allow the servlet to respond to 
122      * a request.
123      *
124      * <p>This method is only called after the servlet's <code>init()</code>
125      * method has completed successfully.
126      * 
127      * <p>  The status code of the response always should be set for a servlet 
128      * that throws or sends an error.
129      *
130      * 
131      * <p>Servlets typically run inside multithreaded servlet containers
132      * that can handle multiple requests concurrently. Developers must 
133      * be aware to synchronize access to any shared resources such as files,
134      * network connections, and as well as the servlet's class and instance 
135      * variables. 
136      * More information on multithreaded programming in Java is available in 
137      * <a HREF="http://java.sun.com/Series/Tutorial/java/threads/multithreaded.html">
138      * the Java tutorial on multi-threaded programming</a>.
139      *
140      *
141      * @param req   the <code>ServletRequest</code> object that contains
142      *          the client's request
143      *
144      * @param res   the <code>ServletResponse</code> object that contains
145      *          the servlet's response
146      *
147      * @exception ServletException  if an exception occurs that interferes
148      *                  with the servlet's normal operation 
149      *
150      * @exception IOException       if an input or output exception occurs
151      *
152      */
153 
154     public void service(ServletRequest   req, ServletResponse   res)
155     throws ServletException  , IOException  ;
156     
157     
158 
159     /**
160      * Returns information about the servlet, such
161      * as author, version, and copyright.
162      * 
163      * <p>The string that this method returns should
164      * be plain text and not markup of any kind (such as HTML, XML,
165      * etc.).
166      *
167      * @return      a <code>String</code> containing servlet information
168      *
169      */
170 
171     public String   getServletInfo();
172     
173     
174 
175     /**
176      *
177      * Called by the servlet container to indicate to a servlet that the
178      * servlet is being taken out of service.  This method is
179      * only called once all threads within the servlet's
180      * <code>service</code> method have exited or after a timeout
181      * period has passed. After the servlet container calls this 
182      * method, it will not call the <code>service</code> method again
183      * on this servlet.
184      *
185      * <p>This method gives the servlet an opportunity 
186      * to clean up any resources that are being held (for example, memory,
187      * file handles, threads) and make sure that any persistent state is
188      * synchronized with the servlet's current state in memory.
189      *
190      */
191 
192     public void destroy();
193 }
194
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags