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

The GenericServlet class implements the Servlet interface and, for convenience, the ServletConfig interface. Servlet developers typically subclass GenericServlet, or its descendent HttpServlet, unless the servlet needs another class as a parent. (If a servlet does need to subclass another class, the servlet must implement the Servlet interface directly. This would be necessary when, for example, RMI or CORBA objects act as servlets.)

The GenericServlet class was created to make writing servlets easier. It provides simple versions of the life-cycle methods init and destroy, and of the methods in the ServletConfig interface. It also provides a log method, from the ServletContext interface. The servlet writer must override only the service method, which is abstract. Though not required, the servlet implementer should also override the getServletInfo method, and will want to specialize the init and destroy methods if expensive servlet-wide resources are to be managed.

See Also:

Serialized Form

Constructor Summary

GenericServlet()
The default constructor does no work.

Method Summary

void	destroy() Destroys the servlet, cleaning up whatever resources are being held, and logs the destruction in the servlet log file.
java.lang.String	getInitParameter(java.lang.String name) Returns a string containing the value of the named initialization parameter, or null if the requested parameter does not exist.
java.util.Enumeration	getInitParameterNames() Returns the names of the initialization parameters for this servlet as an enumeration of Strings, or an empty enumeration if there are no initialization parameters.
ServletConfig	getServletConfig() Returns a servletConfig object containing any startup configuration information for this servlet.
ServletContext	getServletContext() Returns a ServletContext object, which contains information about the network service in 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.
void	init() This method is provided as a convenience so that servlet writers do not have to worry about storing the ServletConfig object.
void	init(ServletConfig config) Initializes the servlet and logs the initialization.
void	log(java.lang.String msg) Writes the class name of the servlet and the given message to the servlet log file.
void	log(java.lang.String message, java.lang.Throwable t) Logs the message with the root cause
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()

The default constructor does no work.

Method Detail

destroy

public void destroy()

Destroys the servlet, cleaning up whatever resources are being held, and logs the destruction in the servlet log file. This method is called, once, automatically, by the network service each time it removes the servlet. After destroy is run, it cannot be called again until the network service reloads the servlet.

When the network service removes a servlet, it calls destroy after all service calls have been completed, or a service-specific number of seconds have passed, whichever comes first. In the case of long-running operations, there could be other threads running service requests when destroy is called. The servlet writer is responsible for making sure that any threads still in the service method complete.

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, or null if the requested parameter does not exist. Init parameters have a single string value; it is the responsibility of the servlet writer to interpret the string.

This is a convenience method; it gets the parameter's value from the ServletConfig object. (The ServletConfig object was passed into and stored by the init method.)

Specified by:

getInitParameter in interface ServletConfig

Parameters:

name - the name of the parameter whose value is requested

getInitParameterNames

public java.util.Enumeration getInitParameterNames()

Returns the names of the initialization parameters for this servlet as an enumeration of Strings, or an empty enumeration if there are no initialization parameters.

This method is supplied for convenience. It gets the parameter names from the ServletConfig object. (The ServletConfig object was passed into and stored by the init method.)

Specified by:

getInitParameterNames in interface ServletConfig

getServletConfig

public ServletConfig getServletConfig()

Returns a servletConfig object containing any startup configuration information for this servlet.

Specified by:

getServletConfig in interface Servlet

getServletContext

public ServletContext getServletContext()

Returns a ServletContext object, which contains information about the network service in which the servlet is running. This is a convenience method; it gets the ServletContext object from the ServletConfig object. (The ServletConfig object was passed into and stored by the init method.)

Specified by:

getServletContext in interface ServletConfig

getServletInfo

public java.lang.String getServletInfo()

Returns a string that contains information about the servlet, such as its author, version, and copyright. This method must be overridden in order to return this information. If it is not overridden, an empty string is returned.

Specified by:

getServletInfo in interface Servlet

init

public void init(ServletConfig config)
          throws ServletException

Initializes the servlet and logs the initialization. The init method is called once, automatically, by the network service each time it loads the servlet. It is guaranteed to finish before any service requests are accepted. On fatal initialization errors, an UnavailableException should be thrown. Do not call call the method System.exit.

The init method stores the ServletConfig object. Servlet writers who specialize this method should call either super.init, or store the ServletConfig object themselves. If an implementor decides to store the ServletConfig object in a different location, then the getServletConfig method must also be overridden.

Specified by:

init in interface Servlet

Parameters:

config - servlet configuration information

Throws:

ServletException - if a servlet exception has occurred

See Also:

UnavailableException

init

public void init()
          throws ServletException

This method is provided as a convenience so that servlet writers do not have to worry about storing the ServletConfig object. When extending this class, simply override this method and it will be called by GenericServlet.init(ServletConfig config);

log

public void log(java.lang.String msg)

Writes the class name of the servlet and the given message to the servlet log file. The name of the servlet log file is server specific; it is normally an event log.

If a servlet will have multiple instances (for example, if the network service runs the servlet for multiple virtual hosts), the servlet writer should override this method. The specialized method should log an instance identifier and possibly a thread identifier, along with the requested message. The default message prefix, the class name of the servlet, does not allow the log entries of the instances to be distinguished from one another.

Parameters:

msg - the message string to be logged

log

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

Logs the message with the root cause

service

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

Carries out a single request from the client. The request object contains parameters provided by the client, and an input stream, which can also bring data to the servlet. To return information to the client, write to the output stream of the response object.

Service requests handled after servlet initialization has completed. Any requests for service that are received during initialization block until it is complete.

Note that servlets typically run inside multi-threaded network services, which can handle multiple service requests simultaneously. It is the servlet writer's responsibility to 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 in favor of techniques that are less coarse. For more information on synchronization, see the the Java tutorial on multithreaded programming.

Specified by:

service in interface Servlet

Parameters:

req - the servlet request

res - the servlet response

Throws:

ServletException - if a servlet exception has occurred

java.io.IOException - if an I/O exception has occurred