diff --git a/Documentation.md b/Documentation.md index 992e83dc..97059757 100644 --- a/Documentation.md +++ b/Documentation.md @@ -22,9 +22,9 @@ Each incoming http request is processed by the following routine. > `{WSF_SERVICE}.execute (req: WSF_REQUEST; res: WSF_RESPONSE)` -This is the low level of the framework, at this point, `req’ provides access to the query and form parameters, input data, headers, … as specified by the Common Gateway Interface (CGI). -The response `res’ is the interface to send data back to the client. -For convenience, the framework provides richer service interface that handles the most common needs (filter, router, …). +This is the low level of the framework, at this point, `req` provides access to the query and form parameters, input data, headers, ... as specified by the Common Gateway Interface (CGI). +The response `res` is the interface to send data back to the client. +For convenience, the framework provides richer service interface that handles the most common needs (filter, router, ...). # Request and Response @@ -32,16 +32,16 @@ For convenience, the framework provides richer service interface that handles th Any incoming http request is represented by an new object of type **WSF_REQUEST**. **WSF_REQUEST** provides access to -* __meta variables__: CGI variables (coming from the request http header) -* __query parameters__: from the uri ex: ?q=abc&type=pdf -* __input data__: the message of the request, if this is a web form, this is parsed to build the form parameters. It can be retrieved once. -* __form parameters__: standard parameters from the request input data. - *typically available when a web form is sent using POST as content of type `multipart/form-data` or `application/x-www-form-urlencoded` - *(advanced usage: it is possible to write mime handler that can processed other type of content, even custom format.) -* __uploaded files__: if files are uploaded, their value will be available from the form parameters, and from the uploaded files as well. -* __cookies variable__: cookies extracted from the http header. -* path parameters: note this is related to the router and carry the semantic of the mapping (see the section on router ) -* __execution variables__: used by the application to keep value associated with the request. ++ __meta variables__: CGI variables (coming from the request http header) ++ __query parameters__: from the uri ex: `?q=abc&type=pdf` ++ __input data__: the message of the request, if this is a web form, this is parsed to build the form parameters. It can be retrieved once. ++ __form parameters__: standard parameters from the request input data. + - typically available when a web form is sent using POST as content of type `multipart/form-data` or `application/x-www-form-urlencoded` + - (advanced usage: it is possible to write mime handler that can processed other type of content, even custom format.) ++ __uploaded files__: if files are uploaded, their value will be available from the form parameters, and from the uploaded files as well. ++ __cookies variable__: cookies extracted from the http header. ++ __path parameters__: note this is related to the router and carry the semantic of the mapping (see the section on router ) ++ __execution variables__: used by the application to keep value associated with the request. The **WSF_RESPONSE** represents the communication toward the client, a service need to provide correct headers, and content. For instance the `Content-Type`, and `Content-Length`. It also allows to send data with chunked encoding. @@ -54,7 +54,7 @@ The **WSF_RESPONSE** represents the communication toward the client, a service n Using EWF, your service is built on top of underlying httpd solution/connectors. Currently 3 main connectors are available: * __CGI__: following the CGI interface, this is an easy solution to run the service on any platform. -* __libFCGI__: based on the libfcgi solution, this can be used with Apache, IIS, nginx, … +* __libFCGI__: based on the libfcgi solution, this can be used with Apache, IIS, nginx, ... * __nino__: a standalone server: Eiffel Web Nino allow you to embed a web server anywhere, on any platform without any dependencies on other httpd server. At compilation time, you can use a default connector (by using the associated default lib), but you can also use a mixed of them and choose which one to execute at runtime. @@ -69,22 +69,20 @@ A web application needs to have a clean and elegant URL scheme, and EWF provides The association between a URL pattern and the code handling the URL request is called a Router mapping in EWF. EWF provides 3 main kinds of mappings -* __URI__: any URL with path being the specified uri. - * example: “/users/” redirects any “/users/” and “/users/?query=...” -* __URI-template__: any URL matching the specified URI-template - * example: “/project/{name}/” redirects any “/project/foo” or “/project/bar” -* __Starts-with__: any URL starting with the specified path ++ __URI__: any URL with path being the specified uri. + - example: “/users/” redirects any “/users/” and “/users/?query=...” ++ __URI-template__: any URL matching the specified URI-template + - example: “/project/{name}/” redirects any “/project/foo” or “/project/bar” ++ __Starts-with__: any URL starting with the specified path Note: in the future, a Regular-Expression based kind will be added in the future, and it is possible to use custom mapping on top of EWF. Code: -` -router.map ( create {WSF_URI_TEMPLATE_MAPPING}.make ( -“/project/{name}”, project_handler) -) - -- And precising the request methods -router.map_with_request_methods ( … , router.methods_GET_POST) -` +> router.map ( create {WSF_URI_TEMPLATE_MAPPING}.make ( +> “/project/{name}”, project_handler) +> ) +> -- And precising the request methods +> router.map_with_request_methods ( … , router.methods_GET_POST) In the previous code, the `project_handler` is an object conforming to **WSF_HANDLER**, that will process the incoming requests matching URI-template “/project/{name}”. @@ -93,11 +91,11 @@ Configuring the URL scheme is done by implementing `{WSF_ROUTED_SERVICE}.setup_ To make life easier, by inheriting from WSF_URI_TEMPLATE_HELPER_FOR_ROUTED_SERVICE, a few help methods are available to `map’ URI template with agent, and so on. See -* map_uri_template (a_tpl: STRING; h: WSF_URI_TEMPLATE_HANDLER) -* map_uri_template_agent (a_tpl: READABLE_STRING_8; proc: PROCEDURE [ANY, TUPLE [req: WSF_REQUEST; res: WSF_RESPONSE]]) -* and same with request methods … -… -Check WSF_*_HELPER_FOR_ROUTED_SERVICE for other available helper classes. ++ `map_uri_template (a_tpl: STRING; h: WSF_URI_TEMPLATE_HANDLER)` ++ `map_uri_template_agent (a_tpl: READABLE_STRING_8; proc: PROCEDURE [ANY, TUPLE [req: WSF_REQUEST; res: WSF_RESPONSE]])` ++ and same with request methods ... +... +Check WSF_\*_HELPER_FOR_ROUTED_SERVICE for other available helper classes. How we do that in EWF? : Router with (or without context). Related code: wsf_router, wsf_router_context