rwsf::HttpServlet Class Reference

Entends rwsf::GenericServlet to define functionality for an HTTP servlet. More...

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

Inheritance diagram for rwsf::HttpServlet:

Public Member Functions
virtual	~HttpServlet ()
virtual void	service (rwsf::ServletRequest &req, rwsf::ServletResponse &resp)
Public Member Functions inherited from rwsf::GenericServlet
	GenericServlet ()
virtual	~GenericServlet ()
virtual void	destroy ()
std::string	getInitParameter (const std::string &name) const
rwsf::Enumeration< std::string >	getInitParameterNames () const
rwsf::ServletConfig	getServletConfig () const
rwsf::ServletContext	getServletContext () const
std::string	getServletInfo () const
std::string	getServletName () const
virtual void	init (const rwsf::ServletConfig &config)
virtual void	init ()
virtual void	log (const std::string &message) const
virtual void	log (const std::string &message, const rwsf::Exception &e) const
virtual void	log (rwsf::Logger::LogLevel lvl, const std::string &message) const
virtual void	log (rwsf::Logger::LogLevel lvl, const std::string &message, const rwsf::Exception &t) const
Public Member Functions inherited from rwsf::Servlet
virtual	~Servlet ()

Protected Member Functions
virtual void	doDelete (rwsf::HttpServletRequest &req, rwsf::HttpServletResponse &resp)
virtual void	doGet (rwsf::HttpServletRequest &request, rwsf::HttpServletResponse &response)
virtual void	doHead (rwsf::HttpServletRequest &req, rwsf::HttpServletResponse &resp)
virtual void	doOptions (rwsf::HttpServletRequest &req, rwsf::HttpServletResponse &resp)
virtual void	doPost (rwsf::HttpServletRequest &request, rwsf::HttpServletResponse &response)
virtual void	doPut (rwsf::HttpServletRequest &req, rwsf::HttpServletResponse &resp)
virtual void	doTrace (rwsf::HttpServletRequest &req, rwsf::HttpServletResponse &resp)
virtual rwsf::DateTime	getLastModified (rwsf::HttpServletRequest &req) const
virtual void	service (rwsf::HttpServletRequest &req, rwsf::HttpServletResponse &resp)

Detailed 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:

• doDelete()
• doGet()
• doHead()
• doOptions()
• doPost()
• doPut()
• doTrace()

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() method and releases resources in a destroy() method. 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. For more information about deployment descriptors see the Servlet Development Guide. 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, in the web.xml file, to true, as shown below:

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

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

Constructor & Destructor Documentation

virtual rwsf::HttpServlet::~HttpServlet ( )

virtual

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

Member Function Documentation

virtual void rwsf::HttpServlet::doDelete ( rwsf::HttpServletRequest &  req, rwsf::HttpServletResponse &  resp  )

protectedvirtual

Responds to a request that uses the DELETE method. The DELETE method allows a client to remove files on the server. Servlets that implement the DELETE method should override this method. The default implementation returns an rwsf::HttpServletResponse::SC_METHOD_NOT_ALLOWED status code to the client.

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

protectedvirtual

Responds to a request that uses the GET method. Servlets that implement the GET method should override this method. The default implementation returns an rwsf::HttpServletResponse::SC_METHOD_NOT_ALLOWED status code to the client.

Reimplemented in rwsf::WebServiceServlet.

virtual void rwsf::HttpServlet::doHead ( rwsf::HttpServletRequest &  req, rwsf::HttpServletResponse &  resp  )

protectedvirtual

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 method. The default implementation invokes doGet() but does not return the associated body. If the doGet() method is not overridden, the default behavior returns an rwsf::HttpServletResponse::SC_METHOD_NOT_ALLOWED status code to the client.

virtual void rwsf::HttpServlet::doOptions ( rwsf::HttpServletRequest &  req, rwsf::HttpServletResponse &  resp  )

protectedvirtual

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 method. The default implementation returns an rwsf::HttpServletResponse::SC_METHOD_NOT_ALLOWED status code to the client.

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

protectedvirtual

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 method. The default implementation returns an rwsf::HttpServletResponse::SC_METHOD_NOT_ALLOWED status code to the client.

Reimplemented in rwsf::WebServiceServlet.

virtual void rwsf::HttpServlet::doPut ( rwsf::HttpServletRequest &  req, rwsf::HttpServletResponse &  resp  )

protectedvirtual

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 method. The default implementation returns an rwsf::HttpServletResponse::SC_METHOD_NOT_ALLOWED status code to the client.

virtual void rwsf::HttpServlet::doTrace ( rwsf::HttpServletRequest &  req, rwsf::HttpServletResponse &  resp  )

protectedvirtual

Responds to a request that uses the TRACE method. The TRACE method simply returns the headers sent with the TRACE request so they can be used in debugging. Servlets that implement the TRACE method should override this method. The default implementation returns an rwsf::HttpServletResponse::SC_METHOD_NOT_ALLOWED status code to the client.

virtual rwsf::DateTime rwsf::HttpServlet::getLastModified ( rwsf::HttpServletRequest &  req ) const

protectedvirtual

Returns the time (in milliseconds) since the referenced object was last changed. If the time is unknown, this method returns a null rwsf::DateTime.

By default, this method returns a null rwsf::DateTime. If a servlet overrides the doGet() method and can effectively determine a reasonable modification time for a resource, the servlet should also override this method. Providing a last modified time improves browser and proxy caches and reduces the load on the server.

virtual void rwsf::HttpServlet::service ( rwsf::ServletRequest &  req, rwsf::ServletResponse &  resp  )

virtual

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

Implements rwsf::Servlet.

virtual void rwsf::HttpServlet::service ( rwsf::HttpServletRequest &  req, rwsf::HttpServletResponse &  resp  )

protectedvirtual

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

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