Module org.bzdev.base

Package org.bzdev.net

Interface ServletAdapter

public interface ServletAdapter

Servlet-adapter interface. This interface is used by ServletWebMap to implement it's application-specific behavior, and can readily be used by a servlet for the same purpose. This allows code to be written for an embedded web server (EJWS) and then moved easily to a different web server that supports servlets.

The methods that ServletAdapter provides are modeled after the methods provided by HttpServlet, with HttpServerRequest replacing HttpServletRequest and HttpServerResponse replacing HttpServletResponse. ServletAdapter implements a subset of the methods that HttpServlet provides: the class EmbeddedWebServer automatically handles the HTTP TRACE method, and the FileHandler class handles the HTTP OPTIONS method. The WebMap.Info class, which implements HttpServerResponse, will provide a 'bit bucket' output stream when there is an HTTP HEAD request so that the request can be otherwise treated as an HTTP GET request. An implementation of ServletAdapter should consequently ensure that doGet(HttpServerRequest,HttpServerResponse) is both idempotent and safe.

For servlets, one can either port an implementation of ServletAdapter, or one can use the class EncapsulatingServlet to create a servlet's whose behavior is that provided by a ServletAdapter.

Porting a servlet adapter to create a servlet requires the following changes (this is not an exhaustive list):

• ServletAdapter should be replaced by HttpServlet.
• HttpServerRequest should be replaced by HttpServletRequest.
• HttpServerResponse should be replaced by HttpServletResponse.
• HttpServerResponse.sendResponseHeaders(int,long) should be replaced with HttpServletResponse.setStatus(int) and either ServletResponse.setContentLength(int) or ServletResponse.setContentLengthLong(long).
• HttpServerRequest.getMediaType() should be replaced with a method call. A suitable method is:

  
           private String getMediaType(HttpServletRequest req) {
                String mediaType = req.getHeader("content-type").trim();
                if (mediaType == null) return "application/octet-stream";
                int firstsc = mediaType.indexOf(';');
                if (firstsc == -1) {
                   return mediaType;
                } else {
                   return mediaType.substring(0, firstsc).trim();
               }
           }
         

Porting a servlet adapter, rather then using EncapsulatingServlet to create a servlet from a servlet adapter, takes more effort and results in two classes to maintain instead of one. On the other hand, porting a servlet can result in a smaller code base when an application is deployed, particularly if the servlet does not require any classes that the BZDev class library provides.

See Also:

• HttpServerRequest
• HttpServerResponse
• EncapsulatingServlet
• HttpServlet

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	ServletAdapter.ServletException	ServletAdapter Exception.

Method Summary

Modifier and Type	Method	Description
default void	destroy()	Take this servlet adapter out of service.
default void	doDelete(HttpServerRequest req, HttpServerResponse res)	Process an HTTP DELETE request.
default void	doGet(HttpServerRequest req, HttpServerResponse res)	Process an HTTP GET request.
default void	doPost(HttpServerRequest req, HttpServerResponse res)	Process an HTTP POST request.
default void	doPut(HttpServerRequest req, HttpServerResponse res)	Process an HTTP PUT request.
default void	init(Map<String,String> map)	Configure and initialize this servlet adapter This is called when the service provided by this servlet adapter starts.

Method Details

init

default void init(Map<String,String> map)
           throws ServletAdapter.ServletException

Configure and initialize this servlet adapter This is called when the service provided by this servlet adapter starts.

Parameters:

map - a map providing values for a set of keys

Throws:

ServletAdapter.ServletException - initialization failed

destroy

default void destroy()

Take this servlet adapter out of service. This will release any resources obtained when init(java.util.Map<java.lang.String,java.lang.String>) was called.

doGet

default void doGet(HttpServerRequest req,
 HttpServerResponse res)
            throws IOException,
ServletAdapter.ServletException

Process an HTTP GET request.

A ServletAdapter.ServletException should not be thrown after the method HttpServerResponse.sendResponseHeaders(int,long), HttpServerResponse.sendRedirect(String), or HttpServerResponse.sendError(int) has been called. Instead, use an IOException.

Parameters:

req - the request object

res - the response object

Throws:

ServletAdapter.ServletException - the request could not be handled

IOException - an input-output error occurred while the request was being handled

doPost

default void doPost(HttpServerRequest req,
 HttpServerResponse res)
             throws IOException,
ServletAdapter.ServletException

Process an HTTP POST request.

An ServletAdapter.ServletException should not be thrown after the method HttpServerResponse.sendResponseHeaders(int,long), HttpServerResponse.sendRedirect(String), or HttpServerResponse.sendError(int) has been called. Instead, use a IOException.

Parameters:

req - the request object

res - the response object

Throws:

ServletAdapter.ServletException - the request could not be handled

IOException - an input-output error occurred while the request was being handled

doPut

default void doPut(HttpServerRequest req,
 HttpServerResponse res)
            throws IOException,
ServletAdapter.ServletException

Process an HTTP PUT request.

An ServletAdapter.ServletException should not be thrown after the method HttpServerResponse.sendResponseHeaders(int,long), HttpServerResponse.sendRedirect(String), or HttpServerResponse.sendError(int) has been called. Instead, use a IOException.

Parameters:

req - the request object

res - the response object

Throws:

ServletAdapter.ServletException - the request could not be handled

IOException - an input-output error occurred while the request was being handled

doDelete

default void doDelete(HttpServerRequest req,
 HttpServerResponse res)
               throws IOException,
ServletAdapter.ServletException

Process an HTTP DELETE request.

An ServletAdapter.ServletException should not be thrown after the method HttpServerResponse.sendResponseHeaders(int,long), HttpServerResponse.sendRedirect(String), or HttpServerResponse.sendError(int) has been called. Instead, use a IOException.

Parameters:

req - the request object

res - the response object

Throws:

ServletAdapter.ServletException - the request could not be handled

IOException - an input-output error occurred while the request was being handled