# Class handler for a route.
#
# **Routing** refers to determining how an application responds to a client request
# to a particular endpoint, which is a URI (or path) and a specific HTTP request
# method GET, POST, PUT or DELETE (other methods are not suported yet).
#
# Each route can have one or more handler methods, which are executed when the route is matched.
#
# Route handlers definition takes the following form:
#
# ~~~nitish
# class MyHandler
#	super Handler
#
#	redef fun METHOD(req, res) do end
# end
# ~~~
#
# Where:
# * `MyHandler` is the name of the handler you will add to the app.
# * `METHOD` can be replaced by `get`, `post`, `put` or `delete`.
#
# The following example responds with `Hello World!` to GET and POST requests:
#
# ~~~
# class MyHandler
#	super Handler
#
#	redef fun get(req, res) do res.send "Got a GET request"
#	redef fun post(req, res) do res.send "Got a POST request"
# end
# ~~~
#
# To make your handler responds to a specific route, you have to add it to the app.
#
# Respond to POST request on the root route (`/`), the application's home page:
#
# ~~~
# var app = new App
# app.use("/", new MyHandler)
# ~~~
#
# Respond to a request to the `/user` route:
#
# ~~~
# app.use("/user", new MyHandler)
# ~~~
abstract class Handler

	# Call `all(req, res)` if `route` matches `uri`.
	private fun handle(route: AppRoute, uri: String, req: HttpRequest, res: HttpResponse) do
		if route.match(uri) then
			if route isa AppParamRoute then
				req.uri_params = route.parse_uri_parameters(uri)
			end
			all(req, res)
		end
	end

	# Handler to all kind of HTTP request methods.
	#
	# `all` is a special request handler, which is not derived from any
	# HTTP method. This method is used to respond at a path for all request methods.
	#
	# In the following example, the handler will be executed for requests to "/user"
	# whether you are using GET, POST, PUT, DELETE, or any other HTTP request method.
	#
	# ~~~
	# class AllHandler
	#	super Handler
	#
	#	redef fun all(req, res) do res.send "Every request to the homepage"
	# end
	# ~~~
	#
	# Using the `all` method you can also implement other HTTP request methods.
	#
	# ~~~
	# class MergeHandler
	#	super Handler
	#
	#	redef fun all(req, res) do
	#		if req.method == "MERGE" then
	#			# handle that method
	#		else super # keep handle GET, POST, PUT and DELETE methods
	#	end
	# end
	# ~~~
	fun all(req: HttpRequest, res: HttpResponse) do
		if req.method == "GET" then
			get(req, res)
		else if req.method == "POST" then
			post(req, res)
		else if req.method == "PUT" then
			put(req, res)
		else if req.method == "DELETE" then
			delete(req, res)
		else
			res.status_code = 405
		end
	end

	# GET handler.
	#
	# Exemple of route responding to GET requests.
	# ~~~
	# class GetHandler
	#	super Handler
	#
	#	redef fun get(req, res) do res.send "GETrequest received"
	# end
	# ~~~
	fun get(req: HttpRequest, res: HttpResponse) do end

	# POST handler.
	#
	# Exemple of route responding to POST requests.
	# ~~~
	# class PostHandler
	#	super Handler
	#
	#	redef fun post(req, res) do res.send "POST request received"
	# end
	# ~~~
	fun post(req: HttpRequest, res: HttpResponse) do end

	# PUT handler.
	#
	# Exemple of route responding to PUT requests.
	# ~~~
	# class PutHandler
	#	super Handler
	#
	#	redef fun put(req, res) do res.send "PUT request received"
	# end
	# ~~~
	fun put(req: HttpRequest, res: HttpResponse) do end

	# DELETE handler.
	#
	# Exemple of route responding to PUT requests.
	# ~~~
	# class DeleteHandler
	#	super Handler
	#
	#	redef fun delete(req, res) do res.send "DELETE request received"
	# end
	# ~~~
	fun delete(req: HttpRequest, res: HttpResponse) do end
end