This package contains classes and interfaces required for writing servlets. This package includes the Servlet interface, which is implemented by all servlets.
A filter object performs filtering on requests and resources. It can also filter the response from a resource. The Filter interface has three methods . Every Filter object has access to a FilterConfig object for receiving initialization parameters.
public void init(FilterConfig filterConfig) throws ServletException
init() is called by the Web container when the filter is instantiated . It is passed to a FilterConfig object containing configuration information about the filter's environment.
public void destroy()
destroy() is called when the filter is taken out of service.
public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws java.io.IOException, ServletException
doFilter() is called by the container each time a client request for which this filter is registered gets received. The FilterChain passed in to this method allows the filter to pass the request and response to the next entity in the chain.
FilterChain is an object provided by the servlet container that represents a series of filters to be invoked in a filtered resource request. Filters use the next filter in the chain to invoke the resource at the end of the chain. If this is the last filter in the chain, the filtered resource itself is invoked.
public interface FilterChain
The FilterChain interface has one method, doFilter() .
public void doFilter(ServletRequest request, ServletResponse response) throws java.io.IOException, ServletException
public interface FilterConfig
A FilterConfig object gets used by the container to pass configuration information to a filter while it is being initialized .
public String getFilterName()
getFilterName() returns the name of the filter, which corresponds to the definition in the deployment descriptor (web.xml).
public String getInitParameter(String param)
getInitParameter() returns a string containing the named initialization parameter. It returns null if there is no initialization parameter.
public java.util.Enumeration getInitParameterNames()
getInitParameterNames() returns an enumeration of the names of the initialization parameters.
getServletContext()
getServletContext() returns the servlet context in which this filter is running.
public ServletContext getServletContext()
getServletContext() returns a reference to the servlet context in which the caller is executing.
The RequestDispatcher defines an object that receives client requests and passes them to another server resource. Though it was intended to wrap servlets, this resource can be an HTML page, a JSP, or a servlet.
public void forward(ServletRequest request, ServletResponse response) throws ServletException, java.io.IOException
forward() forwards one request to another resource on the server. In this way, one resource can handle preliminary processing and another can return a response.
forward() must be called before the response is generated for the client; that is, before the response output is flushed. Otherwise, an IllegalStateException will be thrown.
The request and response must be either the same objects as were passed to the calling servlet's service() method, or be subclasses of the Servlet-RequestWrapper or ServletResponseWrapper classes that wrap them.
public void include(ServletRequest resuest, ServletResponse response) throws ServletException, java.IO.IOException
include() includes the content of another resource in the response. The resource may be an HTML page, another servlet, or a JSP.
An included servlet cannot change the response status code or change headers. Attempts to do so are ignored.
The request and response must be either the same objects as were passed to the calling servlet's service() method, or be subclasses of the Servlet-RequestWrapper or ServletResponseWrapper classes that wrap them.
public interface Servlet
All servlets must implement the Servlet interface. This interface defines the "life cycle" methods for servlets; that is, the methods that initialize a servlet, let it service requests, and then remove it.
When writing a servlet, these methods are called in the following order:
The servlet is constructed . It is initialized with the init method.
Client calls to the service() method are handled.
The servlet is removed from service. It is destroyed , garbage collected, and finalized.
There are two methods defined that are not life cycle methods. One is the getServletConfig() method. The servlet can use this method to discover initialization parameters. The other is the getServletInfo() method, with which the servlet exposes information about itself such as author and version.
public void init(ServletConfig config) throws ServletException
init() is called by the container to indicate that the servlet is being put into service.
public ServletConfig getServletConfig()
getServletConfig() returns a ServletConfig object containing the servlet's initialization parameters.
public void service(ServletRequest request, ServletResponse response) throws ServletException, java.io.IOException
service() gets called by the servlet container to allow the servlet to respond to a request. This method gets called only after the init() method is successfully completed. The code that represents the actual work of the servlet is placed inside the service() method.
public String getServletInfo()
getServletInfo() returns a string containing servlet information such as the author, copyright, and version.
public void destroy()
destroy() is called by the container when the servlet is to be removed from service. This allows the servlet to release associated resources.
public abstract interface ServletConfig
The ServletConfig object is used to pass initialization parameters to a servlet.
public String getInitParameter(String name)
getInitParameter() returns a string containing the value of the named parameter. It returns null if the parameter does not exist.
public java.util.Enumeration getInitParameterNames()
getInitParameterNames() returns an enumeration of String objects containing the names of all of the servlet's initialization parameters.
public ServletContext getServletContext()
getServletContext() returns the ServletContext associated with the calling servlet. This object contains environment information.
public String getServletName()
getServletName() returns the name of the current servlet instance. If unnamed, the method returns the servlet's class name.
public abstract interface ServletContext
The ServletContext interface declares methods that a servlet uses to communicate with its servlet container. One ServletContext per Web application per JVM exists. If a Web application's deployment descriptor describes it as "distributed," then there will be one context per JVM.
public Object getAttribute(String name)
getAttriubte() returns the servlet container attribute with the specified name. If none exists, it returns null .
public java.util.Enumeration getAttributeNames()
getAttributeNames() returns an Enumeration object containing the available attribute names within this servlet context.
public ServletContext getContext(String uripath)
getContext() returns the ServletContext object for the resource at the specified URL.
public String getInitParameter(String name)
getInitParameter() returns a string with the value of the specified initialization parameter. It returns null if the parameter does not exist.
public java.util.Enumeration getInitParameterNames()
getInitParameterNames() returns an enumeration of String objects containing the names of the context's initialization parameters. If no initialization parameters exists, it returns null .
public int getMajorVersion()
getMajorVersion() returns the version of the Java servlet API supported by this container. For Servlet version 2.3 supporting containers, this method returns 2 .
public String getMimeType(java.lang.String file)
getMimeType() returns the MIME type of the specified file. If the MIME type is not known, it returns null .
public int getMinorVersion()
getMinorVersion() returns the minor version of the Java servlet API supported by this container. For Servlet version 2.3, it returns 3 .
public RequestDispatcher getNamedDispatcher(String name)
getNamedDispatcher() returns a RequestDispatcher object that acts as a wrapper for the servlet.
public String getRealPath(String path)
getRealPath() returns the real path as a string for the specified virtual path.
public RequestDispatcher getRequestDispatcher(String path)
getRequestDispatcher() returns a RequestDispatcher object that acts as a wrapper for the resource at the specified path.
public java.net.URL getResource(String path)
getResource() returns a URL object to the resource mapped to the specified path. It returns null if there is no resource mapped to the path. The path must begin with a /. The path is interpreted as relative to the current context root.
public java.io.InputStream getResourceAsStream(String path)
getResourceAsStream() returns the resource mapped to the specified path as an InputStream object.
public java.util.Set getResourcePaths(String path)
getResourcePaths() returns all of the paths to resources in the specified subdirectory of the Web application as String prepended with a /.
public String getServerInfo()
getServerInfo() returns a String object containing the name and version number of the servlet container in which the servlet is running.
public Servlet getServlet(String name)
Deprecated; it is defined to retrieve a servlet from a servlet context.
public String getServletContextName()
getServletContextName() returns the name of the Web application as specified in the Web application's deployment descriptor in the "display-name" element.
public java.util.Enumeration getServletNames()
Deprecated; it is defined to return an enumeration of all known servlet names in this context.
public java.util.Enumeration getServlets()
Deprecated; it is defined to return an enumeration of all known servlets in this context.
public void log(Exception e, String message)
Deprecated; it is defined to write an exception's stack trace and a message to the servlet log file, and it is replaced with log(String message, Throwable throwable) .
public void log(String message, Throwable throwable)
log() writes the specified message to the servlet log file. This is generally an event log.
public void removeAttribute(String name)
removeAttribute() removes the attribute corresponding to the specified name from the servlet context.
public void setAttribute(String name, Object object)
setAttribute() binds an object to the specified attribute name in the current servlet context.
Objects that implement the ServletContextAttributeListener interface can receive notifications that their attribute lists have changed. In order to receive such notifications, a servlet must be configured in the Web application's deployment descriptor.
public void attributeAdded(ServletContextAttributeEvent scab)
attributeAdded() should be called after the attribute is added to the servlet context to make notification that the new event was added.
public void attributeRemoved(ServletContextAttributeEvent scab)
attributeRemoved() should be called after the attribute is removed from the servlet context. The specified ServletContextAttributeEvent contains information about the event.
public void attributeReplaced()
attributeReplaced() should be called after the attribute is replaced in the servlet context. The specified ServletContextAttributeEvent contains information about the event.
An object that implements the ServletContextListener interface receives notifications about changes to the servlet context of the Web application in which they reside. In order to receive notification events, the implementation class must be configured in the Web application's deployment descriptor.
public void contextDestroyed(ServletContextEvent sce)
contextDestroyed() represents notification that a Web application is about to be destroyed.
public void contextInitialized(ServletContextEvent sce)
contextInitialized() represents notification that a Web application has been initialized and can process requests.
The ServletRequest interface contains numerous methods that are useful in providing client request information to a servlet. The servlet container creates a Servlet R equest object and passes it as an argument to the servlet's service method.
public java.lang.Object getAttribute(String name)
getAttribute() returns the value of the specified attribute as an Object . It returns null if none exists.
public java.util.Enumeration getAttributeNames()
getAttributeNames() returns an Enumeration object containing the names of the attributes available to the invoking servlet request.
public String getCharacterEncoding()
getCharacterEncoding() returns the name of the character encoding type used for this request.
public int getContentLength()
getContentLength() returns the length in bytes of the input stream request body. If the length is not known, it returns -1 .
public String getContentType()
getContentType() returns the MIME type of the request. It returns null if the type is not known.
public ServletInputStream getInputStream() throws java.io.IOException
getInputStream() returns the body of the request as a ServletInputStream object containing binary data.
public java.util.Locale getLocale()
getLocale() returns the client's preferred Locale for content acceptance. This value is based on the Accept-Language header returned by the browser.
public java.util.Locale getLocales()
getLocales() returns an enumeration of acceptable locales in descending order of preference.
public String getParameter(String name)
getParameter() returns a String value of the specified request parameter. It returns null if the parameter does not exist.
public java.util.Map getParameterMap(String name)
getParameterMap() returns a java.util.Map of the current request's parameters.
public java.util.Enumeration getParameterNames()
getParameterNames() returns an enumeration of strings containing the parameter names in the current request.
public java.lang.String[] getParameterValues(String name)
getParameterValues() returns an array of strings containing all of the values of the specified parameter in the current request. It returns null if the parameter does not exist.
public String getProtocol()
getProtocol() returns the name as a string of the protocol used in the current request in this form: protocol/majorversion/minorversion. HTTP/1.1 is an example.
public java.io.BufferedReader getReader() throws java.io.IOException
getReader() returns a BufferedReader object that can read the body of the request as character data.
public String getRealPath(String path)
Deprecated; use ServletContext.getRealPath instead.
public String getRemoteAddr()
getRemoteAddr() returns the IP address of the client who sent the request.
public String getRemoteHost()
getRemoteHost() returns the fully qualified name of the client who sent the request.
public getRequestDispatcher(String path)
getRequestDispatcher() returns a RequestDispatcher object that acts as a wrapper for the resource at the specified path.
public String getScheme()
getScheme() returns the name of the scheme used for the current request. http , https , or ftp are examples.
public String getServerName()
getServerName() returns the name of the server processing the request.
public int getServerPort()
getServerPort() returns the port number of the server processing the request.
public boolean isSecure()
isSecure() returns a boolean indicating whether this request was made via a secure channel such as HTTPS.
public void removeAttribute(String name)
removeAttribute removes an attribute from the current request.
public void setAttribute(String name, Object obj)
setAttribute() binds a value to the specified attribute name. Once the request has been processed , the attribute is reset.
public void setCharacterEncoding(String enc) throws java.io.UnsupportedEncodingException
setCharacterEncoding() overrides the character encoding used in the body of the current request.
public void flushBuffer()
flushBuffer() forces any content in the buffer to be written to the client.
public int getBufferSize()
getBufferSize() returns the actual buffer size used in the response.
public String getCharacterEncoding()
getCharacterEncoding() returns the charset of the MIME type used in the response body. Default is "ISO-8859-1," which corresponds to Latin-1.
public java.util.Locale getLocale()
getLocale() returns the locale assigned to the response.
public ServletOutputStream getOutputStream() throws java.io.IOException
getOutputStream() returns a ServletOutputStream suitable for writing binary data in the response.
public java.io.PrintWriter getWriter()
getWriter() returns a PrintWriter object that can be used to return character text to the client.
public boolean isCommitted()
isCommitted() returns a boolean value indicating whether or not the response has been committed.
public void reset()
reset() clears all data in the buffer, status codes, and header.
public void resetBuffer()
resetBuffer() clears the content of the underlying buffer in the response without clearing headers or status code.
public void setBufferSize()
setBufferSize() sets the buffer size for the response body.
public void setContentLength()
setContentLength() sets the length of the content body in the response. It also sets the Content-Length HTTP header when HTTP is used.
public void setContentType(String type)
setContentType() sets the content type for the response returned to the client. The MIME type is specified in the string passed to the method. It may also include the character encoding type, such as text/plain; charset=ISO-8869-1 .
public void setLocale(java.util.Locale loc)
setLocale() sets the locale for the response by setting the HTTP headers. It will modify the Content-Type's charset.
public interface SingleThreadModel
The SingleThreadModel interface declares no methods. This interface ensures that a servlet processes only one request at a time (that is, no two threads can execute its service() method concurrently). This can happen in one of two ways: first, by synchronizing access to a single servlet instance, and second, by assigning a free servlet instance from a pool of instances to each new request.
public abstract class GenericServlet extends Object implements Servlet, ServletConfig, java.io.Serializable
The GenericServlet class defines a generic, protocol-independent servlet. To use a servlet for the Web, extend HTTPServlet . GenericServlet provides an implementation of the interfaces defined in Servlet and ServletConfig . In order to write a generic servlet, you extend the abstract service method.
public void destroy()
destroy() is called by the servlet container to indicate that the servlet is being removed from service.
public String getInitParameter(String name)
getInitParameter() returns a string containing the value of the specified initialization parameter. It returns null if the parameter does not exist.
public java.util.Enumeration getInitParameterNames()
getInitParameterNames() returns an enumeration of strings containing the names of the servlet's initialization parameters. It returns an empty enumeration if none exist.
public ServletConfig getServletConfig()
getServletConfig() returns the current servlet's ServletConfig object, which contains the initialization parameters for the servlet.
public ServletContext getServletContext()
getServletContext() returns a ServletContext object reference for the context in which the current servlet is running.
public String getServletInfo()
getServletInfo() returns a string containing information about the servlet, including author, copyright, and version.
public String getServletName()
getServletName() returns the name of this servlet instance.
public void init(ServletConfig config) throws ServletException public void init() throws ServletException
init() should get called when a servlet is first loaded. By overriding init() , you obviate calling super.init(config) . init(ServletConfig config) is called by the servlet container to indicate that a servlet is being placed into servlet.
public void log(String msg)
log() writes the specified message to the servlet's log file. The message is prepended with the name of the servlet.
public void log(String msg, java.lang.Throwable thr)
log() writes the specified message to the servlet's log file and a stack trace for the specified Throwable exception.
public abstract void service(ServletRequest req, ServletResponse res)
service() is called by the servlet container to allow the servlet to process a request. The code representing what the servlet actually does is written inside this method. As this method is abstract, a concrete subclass of GenericServlet must be implemented.
public class ServletContextAttributeEvent extends ServletContextEvent
A ServletContextEvent is the event class for notifications that an attribute has been added to, removed from, or replaced in the ServletContext of a Web application.
public ServletContextAttributeEvent(ServletContext source, String name, Object value)
The constructor accepts values for the ServletContext in which the event took place and for the name and value of the attribute.
public String getName()
getName() returns the name of the new, replaced, or removed attribute from the ServletContext .
public java.lang.Object getValue()
getValue() returns the value of the new, replaced, or removed attribute from the ServletContext .
public class ServletContextEvent extends java.util.EventObject
A ServletContextEvent is the event object used for notifications regarding changes to the servlet context of a Web application.
public ServletContextEvent(ServletContext source)
The constructor constructs a ServletContextEvent from the specified context.
public ServletContext getServletContext()
getServletContext() returns the ServletContext in which the event took place.
ServletInputStream provides an input stream to read binary data from a client request and can be used to read data sent from the client when HTTP POST and PUT methods are used. It provides one method other than those in InputStream and readLine , which read the data line by line.
protected ServletInputStream()
The constructor does nothing, as ServletInputStream is never directly created because it is an abstract class. Subclasses of this class must implement java.io.InputStream.read() .
public int readLine(byte[ ] b, int off, int len) throws java.io.IOException
readline() reads data one line at a time. It starts at the specified offset and reads bytes into an array until it reads a certain number of bytes (as specified in len ) or reaches a newline character. The newline character is also stored in the byte array. The method returns -1 if the end-of-file is reached before the maximum number of bytes is read.
ServletOutputStream provides an output stream to send binary data to the client and also provides overloaded versions of the print() and println() methods used for handling primitive and String datatypes.
protected ServletOutputStream()
The constructor does nothing, as ServletOutputStream is never directly created because it is an abstract class.
public abstract class ServletOutputStream extends java.io.OutputStream public void print(boolean b) throws java.io.IOException public void print(char c) throws java.io.IOException public void print(double d) throws java.io.IOException public void print(float f) throws java.io.IOException public void print(long l) throws java.io.IOException public void print(int i) throws java.io.IOException public void print(String s) throws java.io.IOException
print() prints the specified primitive type (or string) to the client, without appending a carriage return/line return.
public void println(boolean b) throws java.io.IOException public void println(char c) throws java.io.IOException public void println(double d) throws java.io.IOException public void println(float f) throws java.io.IOException public void println(long l) throws java.io.IOException public void println(int i) throws java.io.IOException public void println(String s) throws java.io.IOException
println() prints the specified primitive type (or string) to the client, appending a carriage return/line return.
The no argument version of println() writes only a carriage return/line feed to the client.
public class ServletRequestWrapper extends Object implements ServletRequest
The ServletRequestWrapper provides an implementation of the ServletRequest interface that can be subclassed in order to adapt the request to a servlet. It implements the Wrapper or Decorator pattern.
public ServletRequestWrapper(ServletRequest req)
The constructor creates a ServletRequest adapter that wraps the specified request object.
public ServletRequest getRequest()
getRequest() returns the wrapped ServletRequest .
public void setRequest(ServletRequest req)
setRequest() sets the ServletRequest to be wrapped.
public Object getAttribute(String name) public java.util.Enumeration getAttributeNames() public String getCharacterEncoding() public int getContentLength() public String getContentType() public ServletInputStream getInputStream() throws java.io.IOException public java.util.Locale getLocale() public java.util.Enumeration getLocales() public String getParameter(String name) public java.util.Map getParameterMap() public java.util.Enumeration getParameterNames() public String[] getParameterValues() public String getProtocol() public java.io.BufferedReader getReader() throws java.io.IOException public String getRealPath(String path) public String getRemoteAddr() public String getRemoteHost() public RequestDispatcher getRequestDispatcher(String path) public String getScheme() public String getServerName() public int getServerPort() public boolean isSecure() public void removeAttribute(String name) public void setAttribute(String name, Object obj) public void setCharacterEncoding(String enc) throws java.io.UnsupportedEncodingException
public class ServletResponseWrapper extends Object implements ServletResponse
ServletResponseWrapper provides an implementation of the ServletResponse interface that can be subclassed in order to adapt the response from a servlet. Its methods call the same methods on the wrapped response object.
public ServletResponseWrapper(ServletResponse response)
The ServletResponseWrapper constructor creates a wrapper around the specified ServletResponse object.
public ServletResponseWrapper getResponse()
getResponse() returns the wrapped ServletResponse .
public void setResponse(ServletResponse response)
setResponse() sets the ServletResponse to be wrapped.
public void flushBuffer() throws java.io.IOException public void getBufferSize() public String getCharacterEncoding() public java.util.Locale getLocale() public ServletOutputStream getOutputStream() throws java.io.IOException public java.io.PrintWriter getWriter() throws java.io.IOException public boolean isCommitted() public void reset() public void resetBuffer() public void setContentLength(int len) public void setContentType(String type) public void setLocale(java.util.Locale loc)
public class ServletException extends Exception
ServletException is a general exception thrown by servlets when processing has become ambiguous or difficult.
public ServletException() public ServletException(String message) public ServletException(String message, java.lang.Thowable rootCause) public ServletException(java.lang.Throwable rootCause)
These constructors allow a String message and/or a Throwable that represents the rootCause of the difficulty encountered .
public Throwable getRootCause()
getRootCause() returns the Throwable that caused the servlet exception.
public class UnavailableException extends ServletException
UnavailableException is thrown by a servlet to indicate that it is permanently or temporarily unavailable.
public UnavailableException(String message)
This constructor indicates that the servlet is permanently unavailable. The String parameter is a message describing the problem.
public UnavailableException(String message, int seconds)
This constructor indicates that the servlet is temporarily unavailable. It accepts a string that describes the problem and an estimate in seconds of how long the servlet will be available. Passing 0 or a negative number indicates the length of unavailability is unknown.
public boolean isPermanent()
isPermanent() returns true if the servlet is unavailable permanently.
public int getUnavailableSeconds()
getUnavailableSeconds() returns the estimated number of seconds that the servlet will be unavailable.
Top |