mirrors/EWF
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Updated Documentation (markdown)

Browse Source
This commit is contained in:
Jocelyn Fiat
2014-01-07 03:33:37 -08:00
parent 8696681710
commit 992504a49f
1 changed files with 29 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files

60
Documentation.md
View File

@@ -22,9 +22,9 @@ Each incoming http request is processed by the following routine.
> `{WSF_SERVICE}.execute (req: WSF_REQUEST; res: WSF_RESPONSE)` > `{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). 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. 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, …). For convenience, the framework provides richer service interface that handles the most common needs (filter, router, ...).
<a name="wiki-request"/><a name="wiki-response"/><a name="wiki-request-and-response"/> <a name="wiki-request"/><a name="wiki-response"/><a name="wiki-request-and-response"/>
# Request and Response # 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**. Any incoming http request is represented by an new object of type **WSF_REQUEST**.
**WSF_REQUEST** provides access to **WSF_REQUEST** provides access to
* __meta variables__: CGI variables (coming from the request http header) + __meta variables__: CGI variables (coming from the request http header)
* __query parameters__: from the uri ex: ?q=abc&type=pdf + __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. + __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. + __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` - 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.) - (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. + __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. + __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 ) + __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. + __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. 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. Using EWF, your service is built on top of underlying httpd solution/connectors.
Currently 3 main connectors are available: Currently 3 main connectors are available:
* __CGI__: following the CGI interface, this is an easy solution to run the service on any platform. * __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. * __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. 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. 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 EWF provides 3 main kinds of mappings
* __URI__: any URL with path being the specified uri. + __URI__: any URL with path being the specified uri.
* example: “/users/” redirects any “/users/” and “/users/?query=...” - example: “/users/” redirects any “/users/” and “/users/?query=...”
* __URI-template__: any URL matching the specified URI-template + __URI-template__: any URL matching the specified URI-template
* example: “/project/{name}/” redirects any “/project/foo” or “/project/bar” - example: “/project/{name}/” redirects any “/project/foo” or “/project/bar”
* __Starts-with__: any URL starting with the specified path + __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. 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: Code:
` > router.map ( create {WSF_URI_TEMPLATE_MAPPING}.make (
router.map ( create {WSF_URI_TEMPLATE_MAPPING}.make ( > “/project/{name}”, project_handler)
“/project/{name}”, project_handler) > )
) > -- And precising the request methods
-- And precising the request methods > router.map_with_request_methods ( … , router.methods_GET_POST)
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}”. 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. 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 See
* map_uri_template (a_tpl: STRING; h: WSF_URI_TEMPLATE_HANDLER) + `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]]) + `map_uri_template_agent (a_tpl: READABLE_STRING_8; proc: PROCEDURE [ANY, TUPLE [req: WSF_REQUEST; res: WSF_RESPONSE]])`
* and same with request methods … + and same with request methods ...
… ...
Check WSF_*_HELPER_FOR_ROUTED_SERVICE for other available helper classes. Check WSF_\*_HELPER_FOR_ROUTED_SERVICE for other available helper classes.
How we do that in EWF? : Router with (or without context). How we do that in EWF? : Router with (or without context).
Related code: wsf_router, wsf_router_context Related code: wsf_router, wsf_router_context