rwsf::HttpServlet

HydraExpress Servlet Reference Guide
Rogue Wave web site: Home Page | Main Documentation Page

rwsf::HttpServlet

Package: Servlet


rwsf::HttpServlet  rwsf::GenericServlet  rwsf::Servlet

Local Index
Header File
Description
Public Constructors
Public Destructor
Public Member Functions
Protected Member Functions
See Also

Local Index

Members

doDelete()
doGet()
doHead()

doOptions()
doPost()
doPut()

doTrace()
getLastModified()
HttpServlet()

service()
~HttpServlet()

Header File

#include <rwsf/servlet/http/HttpServlet.h>

Description

rwsf::HttpServlet is a base class for servlets that use the HTTP protocol. A typical servlet derives from this class and overrides one or more of the do...() methods. A derived class should override at least one of the following methods:

doGet(), to implement the HTTP GET method.
doPost(), to implement the HTTP POST method. The POST method is used to send large or unstructured data to the servlet and is very useful when sending XML encoded data.
doPut(), to implement the HTTP PUT method. The PUT method allows a client to store files on the server similar to sending a file with FTP.
doDelete(), to implement the HTTP DELETE method.

A servlet differs from most C++ classes in that the servlet should not acquire resources in the constructor and should not release resources in the destructor. Instead, a servlet acquires resources in an init() function and releases resources in a destroy() function. The Agent always calls init() before forwarding requests to the servlet and always calls destroy() when the servlet is removed from service. However, the Agent may construct the servlet before the servlet is needed, and may take the servlet out of service long before the servlet is destroyed. A servlet can take advantage of this situation by deferring resource acquisition until the Agent calls init() and releasing resources as soon as the Agent calls destroy().

By default, multiple threads may execute inside the servlet at the same time. A multithreaded servlet must guard shared resources.

The servlet deployment descriptor can state that the servlet only allows access to one thread at a time. In this case, the Agent guards access to the servlet to guarantee that only one thread enters the servlet at a time. To only allow one thread at a time to execute within a servlet, set the single-threaded attribute on the servlet element to true, as shown below:

<servlet single-threaded="true">
   ....
</servlet>

Note that the servlet is still a multithreaded process. Even though only one thread enters the servlet at a time, other threads in the Agent will still be able to service requests in other servlets.

Public Constructors

HttpServlet();

Default constructor. Constructs a new, uninitialized servlet. A servlet constructor should not acquire resources or contain initialization code. Instead, the servlet should implement an init() method.

Public Destructor

virtual
~HttpServlet();

Destructor. A servlet should not rely on the destructor to perform cleanup or release resources. Instead, the servlet should implement a destroy() method.

Public Member Functions

virtual void 
service(rwsf::ServletRequest& request, 
        rwsf::ServletResponse& response);

Services a client request. The Agent calls this function when a request arrives for this servlet. The function converts the provided request and response to an rwsf::HttpServletRequest and an rwsf::HttpServletResponse, then calls self's protected service() function with the converted parameters. A servlet should not override this function. Instead, a servlet should override the do...() functions and/or the protected service() function.

Protected Member Functions

virtual void 
doDelete(rwsf::HttpServletRequest& request, 
         rwsf::HttpServletResponse& response);

Responds to a request that uses the DELETE method. Servlets that implement the DELETE method should override this function. The default implementation of this method is to return a "not supported" message to the client. The default implementation returns a METHOD_NOT_ALLOWED status code to the client.

virtual void 
doGet(rwsf::HttpServletRequest& request, 
      rwsf::HttpServletResponse& response);

Responds to a request that uses the GET method. Servlets that implement the GET method should override this function. The default implementation returns a METHOD_NOT_ALLOWED status code to the client.

virtual void 
doHead(rwsf::HttpServletRequest& request, 
       rwsf::HttpServletResponse& response);

Responds to a request that uses the HEAD method. The HTTP HEAD method simply returns the HTTP headers from the response. Servlets that implement the HEAD method should override this function. The default implementation invokes doGet() but does not return the associated body.

virtual void 
doOptions(rwsf::HttpServletRequest& request,
          rwsf::HttpServletResponse& response);

Responds to a request that uses the OPTIONS method. The HTTP OPTIONS method returns information about which methods are supported by this servlet. The servlet should return a list of supported methods in the Allow HTTP header. Servlets that implement the OPTION method should override this function. The default implementation returns a METHOD_NOT_ALLOWED status code to the client.

virtual void 
doPost(rwsf::HttpServletRequest& request,
       rwsf::HttpServletResponse& response);

Responds to a request that uses the POST method. The POST method is used to send large or unstructured data to the servlet and is very useful when sending XML encoded data. Servlets that implement the POST method should override this function. The default implementation returns a METHOD_NOT_ALLOWED status code to the client.

virtual void 
doPut(rwsf::HttpServletRequest& request,
      rwsf::HttpServletResponse& response);

Responds to a request that uses the PUT method. The PUT method allows a client to store files on the server in a manner similar to sending a file with FTP. Servlets that implement the PUT method should override this function. The default implementation returns a METHOD_NOT_ALLOWED status code to the client.

virtual void 
doTrace(rwsf::HttpServletRequest& request,
        rwsf::HttpServletResponse& response);

Responds to a request that uses the TRACE method. The TRACE method simply returns the headers sent with the TRACE request so that they can be used in debugging. This method currently returns a METHOD_NOT_ALLOWED status code to the client.

virtual rwsf::DateTime
getLastModified(rwsf::HttpServletRequest& request) const;

Returns the time (in milliseconds) since the object that is requested has changed. If the time is unknown, this method returns a null rwsf::DateTime.

In rwsf::HttpServlet, this method always returns a null rwsf::DateTime. If a servlet overrides the doGet() method and can efficiently determine a reasonable modification time for a resource, the servlet should also override this method. Providing a last modified time will improve browser and proxy caches and reduce the load on the server.

virtual void 
service(rwsf::HttpServletRequest& request,
        rwsf::HttpServletResponse& response);

Services a client request by calling the do...() function for the HTTP method specified in request. If the request is a conditional GET, this function may check the modification time of the resource by calling getLastModified() before calling doGet().

A servlet may override this function to respond to HTTP methods not specified by HTTP 1.1. Typically, servlets that override this function also call the service method of rwsf::HttpServlet to handle dispatch to the standard HTTP methods.