Provides an abstract class to be subclassed to create an HTTP servlet suitable for a Web site. More...

#include <servlet.h>

Public Member Functions
virtual void	init (servlet_config &config)
	Called by the servlet container to indicate to a servlet that the servlet is being placed into service. More...

virtual void	init ()
	A convenience method which can be overridden so that there's no need to call `init(config)`. More...

virtual void	service (http_request &req, http_response &resp)
	Receives standard HTTP requests from the public `service` method and dispatches them to the `do_`method methods defined in this class.There's no need to override this method. More...

const servlet_config &	get_servlet_config () const
	Returns a `servlet_config` object, which contains initialization and startup parameters for this servlet. More...

const std::string &	get_servlet_name () const
	Returns the name of this servlet instance. More...

const std::map< std::string, std::string, std::less<> > &	get_init_parameters () const
	Returns the all of the servlet's initialization parameters as an `tree_map` of `std::string` objects, or an empty `tree_map` if the servlet has no initialization parameters. More...

template<typename KeyType >
optional_ref< const std::string >	get_init_parameter (const KeyType &name) const
	Returns an optional `std::string` containing the value of the named initialization parameter, or `null` if the parameter does not exist. More...

Protected Member Functions
virtual void	do_get (http_request &req, http_response &resp)
	Called by the server (via the `service` method) to allow a servlet to handle a GET request. More...

virtual void	do_post (http_request &req, http_response &resp)
	Called by the server (via the `service` method) to allow a servlet to handle a POST request. More...

virtual void	do_put (http_request &req, http_response &resp)
	Called by the server (via the `service` method) to allow a servlet to handle a PUT request. More...

virtual void	do_delete (http_request &req, http_response &resp)
	Called by the server (via the `service` method) to allow a servlet to handle a DELETE request. More...

virtual void	do_head (http_request &req, http_response &resp)

virtual void	do_trace (http_request &req, http_response &resp)
	Called by the server (via the `service` method) to allow a servlet to handle a TRACE request. More...

virtual void	do_options (http_request &req, http_response &resp)
	Called by the server (via the `service` method) to allow a servlet to handle a OPTIONS request. More...

virtual long	get_last_modified (http_request &req)
	Returns the time the `http_request` object was last modified, in milliseconds since midnight January 1, 1970 GMT. More...

virtual int	get_allowed_methods ()
	This method is needed by do_options, which adds all allowed by the servlet methods. More...

Static Protected Attributes
static constexpr int	GET_ALLOWED = 1
	Constant to indicate that GET method is allowed. More...

static constexpr int	POST_ALLOWED = 1 << 1
	Constant to indicate that POST method is allowed. More...

static constexpr int	PUT_ALLOWED = 1 << 2
	Constant to indicate that PUT method is allowed. More...

static constexpr int	DELETE_ALLOWED = 1 << 3
	Constant to indicate that DELETE method is allowed. More...

static constexpr int	HEAD_ALLOWED = 1 << 4
	Constant to indicate that HEAD method is allowed. More...

static constexpr int	TRACE_ALLOWED = 1 << 5
	Constant to indicate that TRACE method is allowed. More...

static constexpr int	OPTIONS_ALLOWED = 1 << 6
	Constant to indicate that OPTIONS method is allowed. More...

Detailed Description

Provides an abstract class to be subclassed to create an HTTP servlet suitable for a Web site.

A subclass of http_servlet must override at least one method, usually one of these:

do_get, if the servlet supports HTTP GET requests
do_post, for HTTP POST requests
do_put, for HTTP PUT requests
do_delete, for HTTP DELETE requests
init, to manage resources that are held for the life of the servlet
get_servlet_config, which the servlet uses to provide information about itself

There's almost no reason to override the service * method. service handles standard HTTP requests by dispatching them to the handler methods for each HTTP request type (the do_method methods listed above).

Likewise, there's almost no reason to override the do_options and do_trace methods.

Servlets typically run on multithreaded servers, so be aware that a servlet must handle concurrent requests and be careful to synchronize access to shared resources. Shared resources include in-memory data such as instance or class variables and external objects such as files, database connections, and network connections.

In order to make the servlet available to mod_servlet a factory method should be provided and exported. The easiest way to do this is to use SERVLET_EXPORT like this:

class my_servlet : public servlet::http_servlet
{
  ...
};
SERVLET_EXPORT(myServletFac, my_servlet);

If the servlet cannot be trivially created or requires special preparation before it is available to mod_servlet container than factory method should be coded manually:

class my_servlet : public servlet::http_servlet
{
  ...
};
extern "C" servlet::http_servlet* myServletFac()
{
    my_servlet* servlet = nullptr;
    // Create and prepare the servlet instance
    return servlet;
}

Member Function Documentation

virtual void servlet::http_servlet::do_delete	(	http_request &	req,
		http_response &	resp
	)

protectedvirtual

Called by the server (via the service method) to allow a servlet to handle a DELETE request.

The DELETE operation allows a client to remove a document or Web page from the server.

This method does not need to be either safe or idempotent. Operations requested through DELETE can have side effects for which users can be held accountable. When using this method, it may be useful to save a copy of the affected URL in temporary storage.

If the HTTP DELETE request is incorrectly formatted, do_delete returns an HTTP "Bad Request" message.

Parameters

req	the http_request object that contains the request the client made of the servlet
resp	the http_response object that contains the response the servlet returns to the client

virtual void servlet::http_servlet::do_get	(	http_request &	req,
		http_response &	resp
	)

protectedvirtual

Called by the server (via the service method) to allow a servlet to handle a GET request.

Overriding this method to support a GET request also automatically supports an HTTP HEAD request. A HEAD request is a GET request that returns no body in the response, only the request header fields.

When overriding this method, read the request data, write the response headers, get the response's writer or output stream object, and finally, write the response data. It's best to include content type and encoding. When using a std::ostream object to return the response, set the content type before accessing the std::ostream object.

The servlet container must write the headers before committing the response, because in HTTP the headers must be sent before the response body.

Where possible, set the Content-Length header (with the http_response::set_content_length(std::size_t) method), to allow the servlet container to use a persistent connection to return its response to the client, improving performance. The content length is automatically set if the entire response fits inside the response buffer.

When using HTTP 1.1 chunked encoding (which means that the response has a Transfer-Encoding header), do not set the Content-Length header.

The GET method should be safe, that is, without any side effects for which users are held responsible. For example, most form queries have no side effects. If a client request is intended to change stored data, the request should use some other HTTP method.

The GET method should also be idempotent, meaning that it can be safely repeated. Sometimes making a method safe also makes it idempotent. For example, repeating queries is both safe and idempotent, but buying a product online or modifying data is neither safe nor idempotent.

If the request is incorrectly formatted, do_get returns an HTTP "Bad Request" message.

Parameters

req	an http_request object that contains the request the client has made of the servlet
resp	an http_response object that contains the response the servlet sends to the client

See Also: servlet::http_response::set_content_type

virtual void servlet::http_servlet::do_head	(	http_request &	req,
		http_response &	resp
	)

protectedvirtual

Receives an HTTP HEAD request from the protected service method and handles the request. The client sends a HEAD request when it wants to see only the headers of a response, such as Content-Type or Content-Length. The HTTP HEAD method counts the output bytes in the response to set the Content-Length header accurately.

If you override this method, you can avoid computing the response body and just set the response headers directly to improve performance. Make sure that the do_head method you write is both safe and idempotent (that is, protects itself from being called multiple times for one HTTP HEAD request).

If the HTTP HEAD request is incorrectly formatted, do_head returns an HTTP "Bad Request" message.

Parameters

req	the http_request object that is passed to the servlet
resp	the http_response object that the servlet uses to return the headers to the client

virtual void servlet::http_servlet::do_options	(	http_request &	req,
		http_response &	resp
	)

protectedvirtual

Called by the server (via the service method) to allow a servlet to handle a OPTIONS request.

The OPTIONS request determines which HTTP methods the server supports and returns an appropriate header. For example, if a servlet overrides do_get, this method returns the following header:

Allow: GET, HEAD, TRACE, OPTIONS

There's no need to override this method unless the servlet implements new HTTP methods, beyond those implemented by HTTP 1.1.

Parameters

req	the http_request object that contains the request the client made of the servlet
resp	the http_response object that contains the response the servlet returns to the client

virtual void servlet::http_servlet::do_post	(	http_request &	req,
		http_response &	resp
	)

protectedvirtual

Called by the server (via the service method) to allow a servlet to handle a POST request.

The HTTP POST method allows the client to send data of unlimited length to the Web server a single time and is useful when posting information such as credit card numbers.

When overriding this method, read the request data, write the response headers, get the response's writer or output stream object, and finally, write the response data. It's best to include content type and encoding. When using a std::ostream object to return the response, set the content type before accessing the std::ostream object.

The servlet container must write the headers before committing the response, because in HTTP the headers must be sent before the response body.

Where possible, set the Content-Length header (with the http_response::set_content_length method), to allow the servlet container to use a persistent connection to return its response to the client, improving performance. The content length is automatically set if the entire response fits inside the response buffer.

When using HTTP 1.1 chunked encoding (which means that the response has a Transfer-Encoding header), do not set the Content-Length header.

This method does not need to be either safe or idempotent. Operations requested through POST can have side effects for which the user can be held accountable, for example, updating stored data or buying items online.

If the HTTP POST request is incorrectly formatted, do_post returns an HTTP "Bad Request" message.

Parameters

req	an http_request object that contains the request the client has made of the servlet
resp	an http_response object that contains the response the servlet sends to the client

See Also: servlet::http_response::set_content_type

virtual void servlet::http_servlet::do_put	(	http_request &	req,
		http_response &	resp
	)

protectedvirtual

Called by the server (via the service method) to allow a servlet to handle a PUT request.

The PUT operation allows a client to place a file on the server and is similar to sending a file by FTP.

When overriding this method, leave intact any content headers sent with the request (including Content-Length, Content-Type, Content-Transfer-Encoding, Content-Encoding, Content-Base, Content-Language, Content-Location, Content-MD5, and Content-Range). If your method cannot handle a content header, it must issue an error message (HTTP 501 - Not Implemented) and discard the request. For more information on HTTP 1.1, see RFC 2616 .

This method does not need to be either safe or idempotent. Operations that do_put performs can have side effects for which the user can be held accountable. When using this method, it may be useful to save a copy of the affected URL in temporary storage.

If the HTTP PUT request is incorrectly formatted, do_put returns an HTTP "Bad Request" message.

Parameters

req	the http_request object that contains the request the client made of the servlet
resp	the http_response object that contains the response the servlet returns to the client

virtual void servlet::http_servlet::do_trace	(	http_request &	req,
		http_response &	resp
	)

protectedvirtual

Called by the server (via the service method) to allow a servlet to handle a TRACE request.

A TRACE returns the headers sent with the TRACE request to the client, so that they can be used in debugging. There's no need to override this method.

Parameters

req	the http_request object that contains the request the client made of the servlet
resp	the http_response object that contains the response the servlet returns to the client

virtual int servlet::http_servlet::get_allowed_methods ( )

protectedvirtual

This method is needed by do_options, which adds all allowed by the servlet methods.

This method is needed by do_options, which adds all allowed by the servlet methods. By default it reports all methods to be allowed.

There is no such method in Java Servlet API, because getOptions there reports only those methods allowed which were overridden in the running servlet class. In C++ unfortunately it is impossible to find which virtual methods were overridden, as comparison ov virtual method pointers are not supported. There is a proposal to C++ stardatization commitee to allow virtual function pointers comparison (see document P0191R1 )

Returns: int mask of all allowed to this servlet methods.

See Also: get_options()

template<typename KeyType >

optional_ref<const std::string> servlet::http_servlet::get_init_parameter ( const KeyType & name ) const

inline

Returns an optional std::string containing the value of the named initialization parameter, or null if the parameter does not exist.

This method is supplied for convenience. It gets the value of the named parameter from the servlet's servlet_config object.

Template Parameters

KeyType a type comparable to std::string

Parameters

name	a `string` specifying the name of the initialization parameter

Returns: String an optional reference to std::string containing the value of the initialization parameter

See Also: servlet_config::get_init_parameter

const std::map<std::string, std::string, std::less<> >& servlet::http_servlet::get_init_parameters ( ) const

inline

Returns the all of the servlet's initialization parameters as an tree_map of std::string objects, or an empty tree_map if the servlet has no initialization parameters.

See servlet_config::get_init_parameters.

This method is supplied for convenience. It gets the parameter names from the servlet's servlet_config object.

Returns: tree_map a tree_map of std::string objects containing all of the servlet's initialization parameters

See Also: servlet_config::get_init_parameters

virtual long servlet::http_servlet::get_last_modified ( http_request & req )

protectedvirtual

Returns the time the http_request object was last modified, in milliseconds since midnight January 1, 1970 GMT.

If the time is unknown, this method returns a negative number (the default).

Servlets that support HTTP GET requests and can quickly determine their last modification time should override this method. This makes browser and proxy caches work more effectively, reducing the load on server and network resources.

Parameters

req	the http_request object that is sent to the servlet

Returns: a long integer specifying the time the http_request object was last modified, in milliseconds since midnight, January 1, 1970 GMT, or -1 if the time is not known

const servlet_config& servlet::http_servlet::get_servlet_config ( ) const

inline

Returns a servlet_config object, which contains initialization and startup parameters for this servlet.

The servlet_config object returned is the one passed to the init method.

Method init is responsible for storing the servlet_config object so that this method can return it.

Returns: the servlet_config object that initializes this servlet

See Also: init

const std::string& servlet::http_servlet::get_servlet_name ( ) const

inline

Returns the name of this servlet instance.

The name may be provided via server administration, assigned in the web application deployment descriptor, or for an unregistered (and thus unnamed) servlet instance it will be the servlet's class name.

Returns: the name of the servlet instance

virtual void servlet::http_servlet::init ( servlet_config & config )

virtual

Called by the servlet container to indicate to a servlet that the servlet is being placed into service.

The servlet container calls the init method exactly once after instantiating the servlet. The init method must complete successfully before the servlet can receive any requests.

The servlet container cannot place the servlet into service if the init method

Throws a servlet_exception
Does not return within a time period defined by the Web server

Parameters

config a servlet_config object containing the servlet's configuration and initialization parameters

See Also: get_servlet_config

virtual void servlet::http_servlet::init ( )

inlinevirtual

A convenience method which can be overridden so that there's no need to call init(config).

Instead of overriding init(servlet_config&), simply override this method and it will be called by init(config). The servlet_config object can still be retrieved via get_servlet_config().

virtual void servlet::http_servlet::service	(	http_request &	req,
		http_response &	resp
	)

virtual

Receives standard HTTP requests from the public service method and dispatches them to the do_method methods defined in this class.There's no need to override this method.

Parameters

req	the http_request object that contains the request the client made of the servlet
resp	the http_response object that contains the response the servlet returns to the client