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.
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.
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:
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.