javax.servlet
Class GenericServlet

java.lang.Object
  |
  +--javax.servlet.GenericServlet

Direct Known Subclasses:

HttpServlet

public abstract class GenericServlet

extends java.lang.Object

implements Servlet, ServletConfig, java.io.Serializable

Defines a generic, protocol-independent servlet. To write an HTTP servlet to use with a Web site, you must extend HttpServlet.

GenericServlet implements the Servlet and ServletConfig interfaces. When you write a servlet, you usually extend GenericServlet or its subclass HttpServlet, unless the servlet needs another superclass. If a servlet needs to extend a class other than GenericServlet or HttpServlet, the servlet must implement the Servlet interface directly.

GenericServlet makes writing servlets easier. It provides simple versions of the lifecycle methods init and destroy and of the methods in the ServletConfig interface. GenericServlet also implements the log> method, declared in the ServletContext interface.

To write a generic servlet, you need only override the service method, which is declared as an abstract method with no body. If you are writing a servlet engine, you should override getServletInfo and specialize the init and destroy methods if the engine will manage expensive servlet-wide resources.

Version:

$Version$

Author:

Various

See Also:

Serialized Form

Constructor Summary

GenericServlet()
Does nothing, because this is an abstract class.

Method Summary

void	destroy() Destroys the servlet, cleaning up whatever resources are being held.
java.lang.String	getInitParameter(java.lang.String name) Returns a String containing the value of the named initialization parameter.
java.util.Enumeration	getInitParameterNames() Returns the names of the initialization parameters for this servlet as an enumeration of String objects.
ServletConfig	getServletConfig() Returns a ServletConfig object, which gives a servlet its initialization parameters.
ServletContext	getServletContext() Returns a ServletContext object, which contains information about the servlet engine on which the servlet is running.
java.lang.String	getServletInfo() Returns a String that contains information about the servlet such as its author, version, and copyright information.
void	init() Acts as a convenience method, so that you do not have to store a ServletConfig object to use as a parameter.
void	init(ServletConfig config) Initializes this servlet.
void	log(java.lang.String msg) Writes the servlet class name and a servlet exception message to the servlet log file.
void	log(java.lang.String message, java.lang.Throwable t) Writes a system exception message to the servlet log file.
abstract void	service(ServletRequest req, ServletResponse res) Carries out a single request from the client.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

GenericServlet

public GenericServlet()

Does nothing, because this is an abstract class. All of the servlet initialization is done by one of the init methods.

Method Detail

destroy

public void destroy()

Destroys the servlet, cleaning up whatever resources are being held.

The servlet engine calls this method once, automatically, when it removes the servlet. After the engine calls destroy, it cannot call destroy again on this instance of the servlet.

The engine calls destroy after all calls to the service method have completed or a specified amount of time has passed, whichever occurs first. In the latter case, the service method might stil be servicing requests from other threads. When you write your servlet, make sure that any threads still running in the service method complete before the servlet is destroyed.

Specified by:

destroy in interface Servlet

getInitParameter

public java.lang.String getInitParameter(java.lang.String name)

Returns a String containing the value of the named initialization parameter. If the servlet does not have a parameter of the specified name, this method returns null.

An initialization parameter has a single String value, which you must interpret.

This method is supplied for convenience. It gets the value of the named parameter from the ServletConfig object, which is passed to the servlet by the init method.

Specified by:

getInitParameter in interface ServletConfig

Parameters:

name - a String specifying the name of the initialization parameter

Returns:

String a String containing the value of the initalization parameter

getInitParameterNames

public java.util.Enumeration getInitParameterNames()

Returns the names of the initialization parameters for this servlet as an enumeration of String objects.

If the servlet has no initialization paramaters, this method returns an empty enumeration.

This method is supplied for convenience. It gets the parameter names from the ServletConfig object, which the init method passes to the servlet.

Specified by:

getInitParameterNames in interface ServletConfig

Returns:

Enumeration an enumeration of String objects containing the names of the servlet's initialization parameters

getServletConfig

public ServletConfig getServletConfig()

Returns a ServletConfig object, which gives a servlet its initialization parameters. The initialization parameters supply the initial or default values the servlet runs with.

Specified by:

getServletConfig in interface Servlet

Returns:

ServletConfig the ServletConfig object that initialized this servlet

getServletContext

public ServletContext getServletContext()

Returns a ServletContext object, which contains information about the servlet engine on which the servlet is running.

This method is supplied for convenience. The ServletContext object is contained within the ServletConfig object, which is passed to the servlet by the init method when the servlet is initialized.

Specified by:

getServletContext in interface ServletConfig

Returns:

ServletContext the ServletContext object passed to this servlet by the init method

getServletInfo

public java.lang.String getServletInfo()

Returns a String that contains information about the servlet such as its author, version, and copyright information. You must override this method before it returns this information. If you do not override this method, it returns an empty string.

Specified by:

getServletInfo in interface Servlet

Returns:

String a empty String until you override this method

init

public void init(ServletConfig config)
          throws ServletException

Initializes this servlet.

The servlet engine calls this method once, automatically, each time it loads the servlet. This method is guaranteed to finish before the servlet accepts any requests to its service method. If a fatal error occurs while the servlet is being initialized, the servlet engine should throw an UnavailableException, rather than calling the System.exit method.

The init method stores the ServletConfig object it receives from the servlet engine. If you override init, you should either call super.init or store the ServletConfig object in the new init method. If you decide to store the ServletConfig object in a different location, you should also override the getServletConfig() method.

Specified by:

init in interface Servlet

Parameters:

config - the ServletConfig object that contains initialization parameters for this servlet

Throws:

ServletException - if an exception occurs that interrupts the servlet's normal operation

See Also:

UnavailableException

init

public void init()
          throws ServletException

Acts as a convenience method, so that you do not have to store a ServletConfig object to use as a parameter.

If you extend GenericServlet, simply override this method and it will be called by GenericServlet.init(ServletConfig config).

Throws:

ServletException - if an exception occurs that interrupts the servlet's normal operation

log

public void log(java.lang.String msg)

Writes the servlet class name and a servlet exception message to the servlet log file. You should override this method if the servlet has more than one instance (for example, if the servlet engine runs the servlet for multiple virtual hosts). The specialized method should log the message, along with an instance j identifier and perhaps a thread identifier.

The default message prefix, which is the servlet class name, does not allow the servlet log entries to be distinguished from one another.

The servlet log file is an event log file whose name is specific to the server.

Parameters:

msg - a String specifying a servlet exception message

log

public void log(java.lang.String message,
                java.lang.Throwable t)

Writes a system exception message to the servlet log file. If a system exception occurs, this method adds the exception's class, name, and message to the log file.

Parameters:

message - a String containing a description of a system exception

t - an exception of type java.lang.Throwable

service

public abstract void service(ServletRequest req,
                             ServletResponse res)
                      throws ServletException,
                             java.io.IOException

Carries out a single request from the client.

Requests sent to this method are handled after servlet initialization is complete. If any requests are received while the servlet is being initializaed, they are blocked.

The ServletRequest object the client passes to this method contains parameters the client provides, as well as an input stream that gives the servlet data. The ServletResponse object contains an output stream that the servlet can use to return information to the client.

Servlets typically run inside multithreaded servlet engines, which can handle multiple service requests concurrently. Therefore, you must synchronize access to any shared resources such as database or network connections. The simplest way to do this is to synchronize the entire service call. This can have a major performance impact, however, and should be avoided whenever possible. For more information on synchronization, see the Java tutorial on multithreaded programming.

Specified by:

service in interface Servlet

Parameters:

req - the ServletRequest object that contains the client's request

res - the ServletResponse object that will contain the servlet's response

Throws:

ServletException - if an exception that interfered with the servlet's normal operation occurred

java.io.IOException - if an input or output exception occurred