52
52
Every lazr.restful web service needs a root resource. The root must
53
53
implement the Zope interface
54
54
lazr.restful.interfaces.IServiceRootResource. The easiest way to do
55
this is to subclass lazr.restful.ServiceRootResource and implement
56
top_level_names, which advertises the main features of your web
57
service to your users. The service root resource must be registered as
58
a utility for IServiceRootResource (see "Utilities" below).
55
this is to subclass lazr.restful.simple.RootResource
56
and implement _build_top_level_objects(), which advertises the main
57
features of your web service to your users. The service root resource
58
must be registered as a utility for IServiceRootResource (see
60
61
Our service root resource is
61
lazr.restful.example.wsgi.root.WSGIExampleWebServiceRootResource.
63
We only have one top-level object, the collection of key-value pairs, so
64
this implementation of top_level_names ends up returning
62
lazr.restful.example.wsgi.root.WSGIExampleWebServiceRootResource. We
63
only have one top-level object, the collection of key-value pairs, so
64
this implementation of _build_top_level_objects() just returns
65
'pairs'. It maps 'pairs' to a 2-tuple (IKeyValuePair, pairset). Here,
66
"pairset" is the collection of key-value pairs itself, and
67
IKeyValuePair is a Zope interface class that explains what kind of
68
object is found in the collection. You'll see IKeyValuePair again in
69
the next section of this document.
67
71
The top-level collection
68
72
------------------------
84
88
Then we define the implementation (PairSet), which implements
87
Like all top-level collections, the collection of key-value pairs is
88
registered as a utility. In this case, PairSet is registered as the
89
utility for IPairSet (see "Utilities" below).
112
The service root, the top-level collection of key-value pairs, and the
113
the web service configuration object are all registered as Zope
114
utilities. A Zope utility is basically a singleton. These three
115
classes are registered as singletons because from time to time,
116
lazr.restful needs access to a canonical instance of one of these
112
The service root and the web service configuration object are both
113
registered as Zope utilities. A Zope utility is basically a
114
singleton. These two classes are registered as singletons because from
115
time to time, lazr.restful needs access to a canonical instance of one
119
118
Utilities are registered in lazr/restful/example/wsgi/configure.zcml,
120
119
and each one is associated with a Zope interface. So the root resource
123
122
that passes an interface class into getUtility(), that code is getting
124
123
the singleton utility registered for that interface.
126
All top-level objects published by a lazr.restful web service must be
127
registered as utilities. This is why the set of key-value pairs is
128
registered as a utility for IPairSet.
151
146
(lazr.restful.example.wsgi.root.WSGIExampleWebServiceRootResource)
153
148
2. "pairs" is passed into WSGIExampleWebServiceRootResource.get(), and
154
the result is the lazr.restful.example.wsgi.resources.PairSet object.
149
the result is the lazr.restful.example.wsgi.resources.PairSet
150
object. (The get() implementation is inherited from
151
RootResource. It works because our implementation
152
of _build_top_level_objects returned a dictionary that had a key
156
155
3. There are no more path fragments, so traversal is complete. The
157
156
PairSet object will be published as a collection resource. Why a
added
removed
src/lazr/restful/example/wsgi/README.txt
