Transaction Attributes

Sometimes, an application will process an incoming request using a number of different resource objects. For example, in the "Treating the Path Like a Filesystem" document, an example is given which involves a number of MapResource objects arranged in a hierarchy, and whilst such objects are used merely to select other resources which are then used to provide some kind of output, there may be other situations where such objects may need to record some information about their activities, so that the output-producing resource may customise the output accordingly.

In the example mentioned above, let us consider the effect of replacing the special mapping from explicitly specified year numbers with a new resource object that recognises year numbers and dispatches requests to other resources:

news_resource = YearResource({"document.html" : document_resource, "article.html" : article_resource})
documents_resource = MapResource({"news" : news_resource})
top_resource = MapResource({"documents" : documents_resource})

What YearResource objects would do is to take the year number from the URL (see "URLs and Paths") and then to match a name in the dictionary it was initialised with, in order to dispatch the transaction to a suitable resource. However, it is likely that the year number is important to such resources: we would expect to see a different Web page for document.html in 2005 than in 2004, for example. Consequently, the YearResource needs a way to communicate such information to other resources.

Although we could provide special methods or change the parameters of the respond method in the document_resource and article_resource objects in order to create a "channel" through which year information could be passed, an alternative is to retain the existing interface and behaviour of those objects and to store such information in the transaction object itself. Since the transaction is essential in the processing of any incoming request, we can be certain that it will be available to store and to provide such information when necessary.

Using Transaction Attributes

We may obtain the attributes from the transaction by performing a method call as follows:

        # In the respond method...
attributes = trans.get_attributes()

This will provide a dictionary mapping names to attribute values. The structure of the values is not strictly defined, and it is the application's role to enforce its own rules on the data stored in the attributes dictionary.

Setting and getting values is as straightforward as using a normal dictionary:

        # Continuing from above...
attributes["year"] = year
# Later...
if attributes.has_key("year"):
year = attributes["year"]

As described in the API documentation, the attributes dictionary exists as long as the transaction object itself. Should information need to be stored beyond the lifetime of a transaction, the appropriate persistent information facilities should be used instead - see "Sessions and Persistent Information" for more details.