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.

Storing the Application Location in an Attribute

One use of attributes is to take the location of an application, defined in terms of its path, and to store that information in an attribute. Such information would then travel to different resources in an application as part of the transaction, enabling those resources to generate things like hyperlinks which contain "absolute" rather than "relative" references to various parts of the application. Consider an application deployed at the following URL:

http://application.business.com/bizapp/

Inside this application, we may have other URLs which expose certain functions:

http://application.business.com/bizapp/services/finance/accounting
http://application.business.com/bizapp/services/customer/invoice

It may be interesting for these functions to know the location of the top-level or root of the application in order to, for example, generate hyperlinks to the top-level or to other established functions. Thus, we may decide to remember the top-level path which would be the following:

/bizapp/

Now, normally the get_path_without_info method will provide this information, but what if we wanted to remember the following path instead...?

/bizapp/services/

In fact, we can make use of the other path-related methods to obtain this path, provided that we ask for this information at the correct point in processing the request. Let us imagine that we have used the MapResource class to build up the path hierarchy:

resource = MapResource({
"services" : MapResource({
"finance" : finance_department,
"customer" : customer_department
})
})

We would want to define a resource to process the request and remember the path details just before choosing between the finance and customer departments. This resource would do the following:

  1. Ask for the path without info, along with the processed virtual path info (as described in "Paths To and Within Applications").
  2. Join the paths together.
  3. Store the result on an attribute (called "root", perhaps).
  4. Invoke another resource.

The advantage of doing this dynamically is that should we decide to change the location of the application or the path to services within it, we will not need to track down hard-coded path values and change them in lots of different places.

Fortunately, WebStack provides a class to do this work for us - PathSelector - and we can use it in the following way:

from WebStack.Resources.Selectors import PathSelector

resource = MapResource({
"services" : PathSelector(
MapResource({
"finance" : finance_department,
"customer" : customer_department
})
)
})

Now, once the services part of the path has been detected, the PathSelector resource will discover the path details, store them on an attribute, and then invoke the MapResource which chooses between departments, which in turn invokes other resources, and so on. However, all of the resources "below" the PathSelector resource will have an attribute called "root" which contains the selected "root path" of the application (or at least the interesting part of the application).

See the "Selectors" document for more details of the PathSelector class.