Integrating with Other Systems

This introductory guide describes the process of making a Web application using the WebStack framework.

Setting Up

Generating the API Documentation

In order to view the API documentation in conjunction with this +guide, it is necessary to generate some Web pages from the Python +source code. For this, the epydoc +application must be available on your system. Then, change into +the WebStack-0.9 directory and run the apidocs.sh +tool script as follows:

Some warnings may be generated by the script, but the result should +be a new apidocs directory within the WebStack-0.9 +directory. Of course, it is always possible to view documentation +within Python by importing modules (such as WebStack.Generic) +and using Python's built-in help function.

About WebStack Applications

Integrating with Other Systems

Most Web applications are not self-contained - instead of +providing information which is written into the application +code itself, they may often access data from other places or even +communicate with other systems. Since applications may be very +different in the way that they access external systems or the way +in which they obtain external information, WebStack does not mandate +rigid mechanisms for hooking into such systems or loading such +information. Instead, it is recommended that applications import +packages and modules which provide the functionality necessary to carry +out such integration.

Examples of Packages

Examples of packages and modules that might be used for integration +purposes include the following:

Using External Packages

In the simplest of cases, the use of external packages is as +straightforward as importing a Python module (or package) and then +using that module's contents. This can often be done in the resource code; for example:

In this case, the functionality is relatively easy to acquire and +does not require any initialisation. But what if we were connecting to +a database? There might be a need to specially initialise the database +module - only once, though - and then repeatedly use it. Consider this +highly artificial example:

What we do	Where it happens and how often
Import `urllib` +to gain access to functionality which we can then use to access a +remote service.	This happens once - when +the above code is itself imported into Python.
Use the `urlopen` +function of `urllib` to actually access a remote service.	This happens in the +resource code each time the resource decides to access the service.

What we do	Where it happens and how often
Import the `mydb` +module to gain access to database access functionality.	This happens once - when +the above code is itself imported into Python.
Initialise a database +connection using the `connect` function from the `mydb` +module.	This also happens only +once - when the above code is itself imported into Python.
Use the `query` +method on the connection object to access a database.	This happens in the +resource code each time the resource decides to access the database.

The choice of initialising the connection may seem arbitrary - why +not just obtain a connection in the resource? Usually, such decisions +are made on the basis of efficiency and on constraints outside the +control of the application - some database systems limit the number of +connections, for example, and if a large number of resources suddenly +became active, some of them would fail to obtain connections if the +connection initialisation code were in the respond +method of the resource.

Configuring Packages Globally

Of course, the above resource might not be the only resource to use +database connections. It might then be tempting to initialise a +connection for each module whose resource needs (or, since as normal +Python classes we can put many resources in a single module, whose +resources need) to access a database. But it would surely be more +convenient to define a single, central place to hold such global +resources.

One approach is to define a module which can be accessed by all +modules, and thus by all resources. Let us create such a module in the +file Properties.py which will reside alongside MyApplication.py +(or whatever the application module is called). Inside the Properties +module we can write the following code:

Now, in each module containing resources which need to access the +database, all we need to do now is to import the Properties +module and to use the connection as defined in that module:

This is a very simple approach that is technically outclassed by the +mechanisms available in some frameworks. Currently, WebStack does not +provide access to those more sophisticated mechanisms, however.

Responses and Presentation

After performing some kind of processing on input information, an -application will then want to produce some kind of response to indicate what +

After performing some kind of +processing on input information, an +application will then want to produce some kind of response to indicate +what went on. Here are some examples of responses:

Generating Responses

The procedure involved in +generating a response usually involves the following steps:

As discussed in "Character Encodings", care -must be taken generating the response so that it meets any expectations that +

As discussed in "Character Encodings", +care +must be taken generating the response so that it meets any expectations +that browsers and other Web clients may have.

WebStack API - Response-Related Methods

- -

Transaction objects have various methods that can be used in generating +

WebStack API - +Response-Related Methods

Transaction objects have +various methods that can be used in generating responses:

set_response_code: This accepts an integer value denoting the response condition as - described in the HTTP specification. If this method is not used, - WebStack sets a 200 status condition on the response, - meaning that the request was processed successfully.; This accepts an integer +value denoting the response condition as described in the HTTP +specification. If this method is not used, WebStack sets a 200 +status condition on the response, meaning that the request was +processed successfully.
set_content_type: This accepts a content type object (typically - WebStack.Generic.ContentType) which specifies both the - media type and the character encoding (if relevant) of the data sent to - the user. The media type describes the format of the data (eg. - text/html - a Web page), whereas the character encoding - describes how any character information on the page is encoded - see "Character Encodings" for more - information.; This accepts a content type +object (typically WebStack.Generic.ContentType) +which specifies both the media type and the character encoding (if +relevant) of the data sent to the user. The media type describes the +format of the data (eg. text/html +- a Web page), whereas the character encoding describes how any +character information on the page is encoded - see "Character Encodings" +for more information.
get_response_stream: This returns the output stream through which data may be sent to the - user.; This returns the output +stream through which data may be sent to the user.

Integrating with Content Generators

Just as applications might need to integrate with other systems in +order to fetch information or to perform operations on behalf of the +user, the generation of response content can also be made a lot easier +by using external libraries. In the above example code, the process of +obtaining and formatting the actual data to be written out has been +left unspecified, but for anything more complicated than "hello world" +it is usually advisable to consider using templating systems which +combine raw data and templates to produce formatted output that can be +displayed as a Web page (amongst other things).

Application Design Considerations

Examine the Transaction

WebStack API - The Transaction Object

Perform Actions

Produce a Response

Creating Web Applications with WebStack

Setting Up

Generating the API Documentation

About WebStack Applications

Integrating with Other Systems

Examples of Packages

Using External Packages

Configuring Packages Globally

Responses and Presentation

Generating Responses

WebStack API - Response-Related Methods

WebStack API - +Response-Related Methods

Integrating with Content Generators