001: /*
002: * Copyright 1998-1998 Caucho Technology -- all rights reserved
003: *
004: * Caucho Technology forbids redistribution of any part of this software
005: * in any form, including derived works and generated binaries.
006: *
007: * This Software is provided "AS IS," without a warranty of any kind.
008: * ALL EXPRESS OR IMPLIED REPRESENTATIONS AND WARRANTIES, INCLUDING ANY
009: * IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE
010: * OR NON-INFRINGEMENT, ARE HEREBY EXCLUDED.
011:
012: * CAUCHO TECHNOLOGY AND ITS LICENSORS SHALL NOT BE LIABLE FOR ANY DAMAGES
013: * SUFFERED BY LICENSEE OR ANY THIRD PARTY AS A RESULT OF USING OR
014: * DISTRIBUTING SOFTWARE. IN NO EVENT WILL CAUCHO OR ITS LICENSORS BE LIABLE
015: * FOR ANY LOST REVENUE, PROFIT OR DATA, OR FOR DIRECT, INDIRECT, SPECIAL,
016: * CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND
017: * REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF THE USE OF OR
018: * INABILITY TO USE SOFTWARE, EVEN IF HE HAS BEEN ADVISED OF THE POSSIBILITY
019: * OF SUCH DAMAGES.
020: *
021: * $Id: Servlet.java,v 1.1.1.1 2004/09/11 05:06:14 cvs Exp $
022: */
023:
024: package javax.servlet;
025:
026: import java.io.IOException;
027:
028: /**
029: * A servlet is any Java class with a null-arg constructor that
030: * implements the Servlet API.
031: *
032: * <p>Simple servlets should extend HttpServlet to create servlets.
033: *
034: * <p>Servlets that need full control should extend GenericServlet.
035: *
036: * <h4>Location</h4>
037: *
038: * Servlets are usually loaded from WEB-INF/classes under the application's
039: * root. To add a servlet test.MyServlet, create the java file:
040: * <center>/www/myweb/WEB-APP/classes/test/MyServlet.java</center>
041: *
042: * <p>Servlets can also live in the global classpath.
043: *
044: * <h4>Configuration</h4>
045: *
046: * Servlet configuration for Resin is in the resin.conf file.
047: *
048: * <pre><code>
049: * <servlet servlet-name='hello'
050: * servlet-class='test.HelloServlet'
051: * load-on-startup>
052: * <init-param param1='value1'/>
053: * <init-param param2='value2'/>
054: * </servlet>
055: * </code></pre>
056: *
057: * <h4>Dispatch</h4>
058: *
059: * The servlet engine selects servlets based on the
060: * <code>servlet-mapping</code> configuration. Servlets can use the
061: * special 'invoker' servlet or they can be configured to execute directly.
062: *
063: * <p>To get a path info, your servlet needs to use a wildcard. In the
064: * following example, /Hello will match the 'hello' servlet, but
065: * /Hello/there will match the 'defaultServlet' servlet with a pathinfo
066: * of /Hello/there.
067: *
068: * <pre><code>
069: * <servlet-mapping url-pattern='/'
070: * servlet-name='defaultServlet'/>
071: *
072: * <servlet-mapping url-pattern='/Hello'
073: * servlet-name='hello'/>
074: *
075: * <servlet-mapping url-pattern='/servlet/*'
076: * servlet-name='invoker'/>
077: *
078: * <servlet-mapping url-pattern='*.jsp'
079: * servlet-name='com.caucho.jsp.JspServlet'/>
080: * </code></pre>
081: *
082: * <h4>Life cycle</h4>
083: *
084: * Servlets are normally initialized when they are first loaded. You can
085: * force loading on startup using the 'load-on-startup' attribute to the
086: * servlet configuration. This is a useful technique for the equivalent
087: * of the global.jsa file.
088: *
089: * <p>A servlet can count on having only one instance per
090: * application (JVM) unless it implements SingleThreadedModel.
091: *
092: * <p>Servlet requests are handed by the <code>service</code> routine.
093: * Since the servlet engine is multithreaded, multiple threads may call
094: * <code>service</code> simultaneously.
095: *
096: * <p>When the application closes, the servlet engine will call
097: * <code>destroy</code>. Note, applications always close and are restarted
098: * whenever a servlet changes. So <code>init</code> and <code>destroy</code>
099: * may be called many times while the server is still up.
100: */
101: public interface Servlet {
102: /**
103: * Returns an information string about the servlet.
104: */
105: public String getServletInfo();
106:
107: /**
108: * Initialize the servlet. ServletConfig contains servlet parameters
109: * from the configuration file. GenericServlet will store the config
110: * for later use.
111: *
112: * @param config information from the configuration file.
113: */
114: public void init(ServletConfig config) throws ServletException;
115:
116: /**
117: * Returns the servlet configuration, usually the same value as passed
118: * to the init routine.
119: */
120: public ServletConfig getServletConfig();
121:
122: /**
123: * Service a request. Since the servlet engine is multithreaded,
124: * many threads may execute <code>service</code> simultaneously. Normally,
125: * <code>req</code> and <code>res</code> will actually be
126: * <code>HttpServletRequest</code> and <code>HttpServletResponse</code>
127: * classes.
128: *
129: * @param req request information. Normally servlets will cast this
130: * to <code>HttpServletRequest</code>
131: * @param res response information. Normally servlets will cast this
132: * to <code>HttpServletRequest</code>
133: */
134: public void service(ServletRequest req, ServletResponse res)
135: throws IOException, ServletException;
136:
137: /**
138: * Called when the servlet shuts down. Servlets can use this to close
139: * database connections, etc. Servlets generally only shutdown when
140: * the application closes.
141: */
142: public void destroy();
143: }
|