Merge lp:~leonardr/lazr.restful/multiversion-collection into lp:lazr.restful

[Leonard Richardson]

[Leonard Richardson (leonardr)]

This branch makes it possible to serve multiple versions of a web service from the same underlying dataset. The multiversion.txt test shows how it's done. Everything else in this branch is code to make existing lazr.restful code version-aware without breaking the existing tests.

As per the 'version-specific-request-interface' branch, every incoming request is associated with some version of the web service using a marker interface. To make lazr.restful code version-aware I made it request-aware. Instead of ILocation I now use IRequestAwareLocation. IEntry and ICollection lookups are now multi-adapter lookups: previously you could just write "IEntry(data_model_object)". Now you must write "getMultiAdapter((data_model_object, request), IEntry)" -- depending on the marker interface attached to the request object, you may get a different IEntry implementation back.

I had to add some more setup to the unit tests. Previously they got along without defining any configuration or request objects. Now that IEntry lookups require a request object, I had to define fake requests and minimal configuration objects for the unit tests.

There are a few TK places I need to look into. I also use code like this several times:

+ request_interface = getUtility(
+ IVersionedClientRequestImplementation,
+ name=self.request.version)
+ return getGlobalSiteManager().adapters.lookup(
+ (model_schema, request_interface), IEntry).schema

It might be worth writing a helper function.

I'm going through the code now and I'll comment on anything else strange I find.

[Leonard Richardson (leonardr)]

I fixed all but one of the XXX sections (the remaining XXX can't be removed until we can generate multiple versions from declarations) and removed some useless code.

[Francis J. Lacoste (flacoste)]

On January 7, 2010, Leonard Richardson wrote:
> I fixed all but one of the XXX sections (the remaining XXX can't be removed
> until we can generate multiple versions from declarations) and removed
> some useless code.
>
Hi Leonard,

This is really taking shape! I have a few questions and suggestions, so
setting this to

    review needsfixing code

> === modified file 'src/lazr/restful/_resource.py'
> class EntryFieldURL(AbsoluteURL):
> """An IAbsoluteURL adapter for EntryField objects."""
> component.adapts(EntryField, IHTTPRequest)
> @@ -1243,7 +1246,7 @@
> def __init__(self, context, request):
> """Associate this resource with a specific object and request."""
> super(EntryResource, self).__init__(context, request)
> - self.entry = IEntry(context)
> + self.entry = getMultiAdapter((context, request), IEntry)
>

Not that if context is already providing IEntry, you'll get an error. I don't
know if this is a plausible case, but if it is, you'll want to only query the
adapter, if context doesn't provide IEntry.

> # We are given a model schema (IFoo). Look up the
> # corresponding entry schema (IFooEntry).
> model_schema = self.relationship.value_type.schema
> - return getGlobalSiteManager().adapters.lookup1(
> - model_schema, IEntry).schema
> + request_interface = getUtility(
> + IVersionedClientRequestImplementation,
> + name=self.request.version)
> + return getGlobalSiteManager().adapters.lookup(
> + (model_schema, request_interface), IEntry).schema

In my previous review, I suggested I...Factory instead of
IVersionedClientRequestImplementation, here I see that it's not a factory.
Sine you are using the name, why do you need a separate interface. Why not
simply ask for the IWebClientRequest with the specific name? Since all
versioned interface should extend that one, it should work.

> === modified file 'src/lazr/restful/directives/__init__.py'

> + utility = cls()
> + sm = getSiteManager()
> + sm.registerUtility(utility, IWebServiceConfiguration)
> +
> + # Create and register marker interfaces for request objects.
> + for version in set(
> + utility.active_versions + [utility.latest_version_uri_prefix]):
> + classname = ("IWebServiceClientRequestVersion" +
> + version.replace('.', '_'))

There are probably other characters that need to be squashed '-' is likely to
be used.

> + marker_interface = InterfaceClass(
> + classname, (IWebServiceClientRequest,), {})
> + alsoProvides(
> + marker_interface, IVersionedClientRequestImplementation)
> + sm.registerUtility(
> + marker_interface, IVersionedClientRequestImplementation,
> + name=version)
> return True

I suggest writing a unit test for that part that would cover the mangling.

> === modified file 'src/lazr/restful/docs/multiversion.txt'
> +URL generation
> +--------------
> +
> + >>> from zope.component import getSiteManager
> + >>> from zope.traversing.browser...

review: Needs Fixing (code)

[Leonard Richardson (leonardr)]

Thanks for your thorough review. I'm going through it slowly. I'll probably have many comments in reply.

> > # We are given a model schema (IFoo). Look up the
> > # corresponding entry schema (IFooEntry).
> > model_schema = self.relationship.value_type.schema
> > - return getGlobalSiteManager().adapters.lookup1(
> > - model_schema, IEntry).schema
> > + request_interface = getUtility(
> > + IVersionedClientRequestImplementation,
> > + name=self.request.version)
> > + return getGlobalSiteManager().adapters.lookup(
> > + (model_schema, request_interface), IEntry).schema
>
> In my previous review, I suggested I...Factory instead of
> IVersionedClientRequestImplementation, here I see that it's not a factory.
> Sine you are using the name, why do you need a separate interface. Why not
> simply ask for the IWebClientRequest with the specific name? Since all
> versioned interface should extend that one, it should work.

I don't do that because request objects shouldn't be utilities. There's not one request object for every version, but one object for every request. I could create a dummy request object and register that as a utility, but I think that would be really confusing. What I have is also confusing, but it can be explained in an internally consistent way:

1. We need a way to look up a web service description given a version number.
2. These lookups don't operate by version number; they take a marker interface that's different for every version.
3. So we create a way to look up the marker interface given the version number.
4. We implement this by registering the marker interface objects as named utilities.

Does this make sense?

I believe in all these cases we have a specific request object whose .version we look up. If there was some way of extracting from the request object the marker interface that identified the version, we could write a property method WebServiceClientRequest.marker_interface. Is that what you meant? (I could write this property method now, with the utility lookup, and it would clean up the code a bit.)

[Francis J. Lacoste (flacoste)]

On January 11, 2010, Leonard Richardson wrote:
> Thanks for your thorough review. I'm going through it slowly. I'll probably
> have many comments in reply.
>
> > > # We are given a model schema (IFoo). Look up the
> > > # corresponding entry schema (IFooEntry).
> > > model_schema = self.relationship.value_type.schema
> > > - return getGlobalSiteManager().adapters.lookup1(
> > > - model_schema, IEntry).schema
> > > + request_interface = getUtility(
> > > + IVersionedClientRequestImplementation,
> > > + name=self.request.version)
> > > + return getGlobalSiteManager().adapters.lookup(
> > > + (model_schema, request_interface), IEntry).schema
> >
> > In my previous review, I suggested I...Factory instead of
> > IVersionedClientRequestImplementation, here I see that it's not a
> > factory. Sine you are using the name, why do you need a separate
> > interface. Why not simply ask for the IWebClientRequest with the specific
> > name? Since all versioned interface should extend that one, it should
> > work.
>
> I don't do that because request objects shouldn't be utilities. There's not
> one request object for every version, but one object for every request. I
> could create a dummy request object and register that as a utility, but I
> think that would be really confusing. What I have is also confusing, but
> it can be explained in an internally consistent way:
>
> 1. We need a way to look up a web service description given a version
> number. 2. These lookups don't operate by version number; they take a
> marker interface that's different for every version. 3. So we create a way
> to look up the marker interface given the version number. 4. We implement
> this by registering the marker interface objects as named utilities.
>
> Does this make sense?

Yes, this does make sense. And I do think you should be registering the marker
interface themselve. Remember that a class (or an interface) is an object in
itself. It's already a pattern in zope, the ZCA registers all interfaces as
utility already.

You are also right that what I suggest doesn't work, since the
IWebServiceRequest subclass don't provide IWebServiceRequest themselves. So
what you are doing is the proper way to do. I think I just don't like the name
(it's too long, and the utility you are retrieving isn't an implementation.)
How about IWebServiceVersion ?

>
> I believe in all these cases we have a specific request object whose
> .version we look up. If there was some way of extracting from the request
> object the marker interface that identified the version, we could write a
> property method WebServiceClientRequest.marker_interface. Is that what you
> meant? (I could write this property method now, with the utility lookup,
> and it would clean up the code a bit.)
>

--
Francis J. Lacoste
<email address hidden>

[Leonard Richardson (leonardr)]

> > === modified file 'src/lazr/restful/_resource.py'
> > class EntryFieldURL(AbsoluteURL):
> > """An IAbsoluteURL adapter for EntryField objects."""
> > component.adapts(EntryField, IHTTPRequest)
> > @@ -1243,7 +1246,7 @@
> > def __init__(self, context, request):
> > """Associate this resource with a specific object and request."""
> > super(EntryResource, self).__init__(context, request)
> > - self.entry = IEntry(context)
> > + self.entry = getMultiAdapter((context, request), IEntry)
> >
>
> Not that if context is already providing IEntry, you'll get an error. I don't
> know if this is a plausible case, but if it is, you'll want to only query the
> adapter, if context doesn't provide IEntry.

I could go either way on this, but I kind of consider it an error to pass an Entry object directly into EntryResource. I think allowing that would encourage sloppy thinking and cause lazr.restful developers to confuse entries and data model objects. What do you think?

> > + # Create and register marker interfaces for request objects.
> > + for version in set(
> > + utility.active_versions + [utility.latest_version_uri_prefix]):
> > + classname = ("IWebServiceClientRequestVersion" +
> > + version.replace('.', '_'))
>
> There are probably other characters that need to be squashed '-' is likely to
> be used.

I was lazy. I've added a make_identifier_safe function to lazr.restful.utils and a doctest for it.

> > === modified file 'src/lazr/restful/docs/multiversion.txt'
> > +URL generation
> > +--------------
> > +
> > + >>> from zope.component import getSiteManager
> > + >>> from zope.traversing.browser.interfaces import IAbsoluteURL
> > + >>> from lazr.restful.interfaces import (
> > + ... IRequestAwareLocation, IWebServiceLayer)
> > + >>> from lazr.restful.simple import AbsoluteURL
> > + >>> sm = getSiteManager()
> > + >>> sm.registerAdapter(
> > + ... AbsoluteURL, (IRequestAwareLocation, IWebServiceLayer),
> > + ... provided=IAbsoluteURL)
>
> Can you add a paragraph explaining what the above does?

OK.

> > Here's the interface for the 'set' object that manages the contacts.
> >
> > + >>> from zope.interface import implements
> > >>> from lazr.restful.interfaces import ITraverseWithGet
> > >>> class IContactSet(ITestDataObject, ITraverseWithGet):
> > - ... def getAll(self):
> > + ... def getAllContacts():
> > ... "Get all contacts."
> > ...
> > - ... def get(self, name):
> > + ... def get(request, name):
> > ... "Retrieve a single contact by name."
>
> Why is request part of the interface signature?

That method doesn't need to be defined in IContactSet at all, because it's inherited from ITraverseWithGet. ITraverseWithGet.get() needs to take a request as an argument because the traversal rules can change from one version to another. But they don't change in this case. I've removed the redundant definition.

> > Here's a simple ContactSet with a predefined list of contacts.
> >
> > + >>> from zope.publisher.interfaces.browser...

[Leonard Richardson (leonardr)]

> You are also right that what I suggest doesn't work, since the
> IWebServiceRequest subclass don't provide IWebServiceRequest themselves. So
> what you are doing is the proper way to do. I think I just don't like the name
> (it's too long, and the utility you are retrieving isn't an implementation.)
> How about IWebServiceVersion ?

OK, I've renamed it to IWebServiceVersion.

[Leonard Richardson (leonardr)]

Apropos getting rid of IRequestAwareLocation: I think you were envisioning some code like this:

    >>> class ContactSetLocation(object):
    ... """An ILocation implementation for ContactSet objects."""
    ... implements(ILocation)
    ...
    ... def __init__(self, context, request):
    ... self.context = contact_set
    ... self.request = request
    ...
    ... def __parent__(self, request):
    ... return getUtility(IServiceRootResource, name=request.version)
    ...
    ... def __name__(self, request):
    ... if request.version == 'beta':
    ... return 'contact_list'
    ... return 'contacts'

    >>> from zope.traversing.browser import AbsoluteURL as ZopeAbsoluteURL
    >>> sm.registerAdapter(
    ... ZopeAbsoluteURL, (ILocation, IWebServiceLayer),
    ... provided=IAbsoluteURL)

    >>> sm.registerAdapter(
    ... ContactSetLocation, (IContactSet, IWebServiceLayer),
    ... provided=ILocation)

Unfortunately this doesn't work with Zope's AbsoluteURL implementation, which contains this line:

        context = ILocation(context)

I never get a chance to convert ContactSet into a ContactSetLocation.

I can modify my alternate implementation of AbsoluteURL to try a multi-adapter lookup before trying a simple cast to ILocation. I'll still need the alternate AbsoluteURL but I'd be able to get rid of the IRequestAwareLocation interface. Does this make sense? Am I missing something?

[Francis J. Lacoste (flacoste)]

On January 11, 2010, Leonard Richardson wrote:
> > > === modified file 'src/lazr/restful/_resource.py'
> > > class EntryFieldURL(AbsoluteURL):
> > > """An IAbsoluteURL adapter for EntryField objects."""
> > > component.adapts(EntryField, IHTTPRequest)
> > > @@ -1243,7 +1246,7 @@
> > > def __init__(self, context, request):
> > > """Associate this resource with a specific object and
> > > request.""" super(EntryResource, self).__init__(context, request) -
> > > self.entry = IEntry(context)
> > > + self.entry = getMultiAdapter((context, request), IEntry)
> >
> > Not that if context is already providing IEntry, you'll get an error. I
> > don't know if this is a plausible case, but if it is, you'll want to only
> > query the adapter, if context doesn't provide IEntry.
>
> I could go either way on this, but I kind of consider it an error to pass
> an Entry object directly into EntryResource. I think allowing that would
> encourage sloppy thinking and cause lazr.restful developers to confuse
> entries and data model objects. What do you think?

Sure.

> > > Here's a simple ContactSet with a predefined list of contacts.
> > >
> > > + >>> from zope.publisher.interfaces.browser import IBrowserRequest
> > > + >>> from lazr.restful.interfaces import IServiceRootResource
> > >
> > > >>> from lazr.restful.simple import TraverseWithGet
> > >
> > > - >>> from zope.publisher.interfaces.browser import IBrowserRequest
> > >
> > > >>> class ContactSet(TraverseWithGet):
> > >
> > > ... implements(IContactSet)
> > > - ... path = "contacts"
> > > ...
> > > ... def __init__(self):
> > > ... self.contacts = CONTACTS
> > > ...
> > > - ... def get(self, name):
> > > - ... contacts = [contact for contacts in self.contacts
> > > - ... if pair.name == name]
> > > + ... def get(self, request, name):
> > > + ... contacts = [contact for contact in self.contacts
> > > + ... if contact.name == name]
> > > ... if len(contacts) == 1:
> > > ... return contacts[0]
> > > ... return None
> >
> > From the implementation, I don't see why request is required?
>
> As before, it's inherited from ITraverseWithGet.

Ok.

--
Francis J. Lacoste
<email address hidden>

[Francis J. Lacoste (flacoste)]

On January 11, 2010, Leonard Richardson wrote:
> Apropos getting rid of IRequestAwareLocation: I think you were envisioning
some code like this:
> >>> class ContactSetLocation(object):
>
> ... """An ILocation implementation for ContactSet objects."""
> ... implements(ILocation)
> ...
> ... def __init__(self, context, request):
> ... self.context = contact_set
> ... self.request = request
> ...
> ... def __parent__(self, request):
> ... return getUtility(IServiceRootResource,
> name=request.version) ...
> ... def __name__(self, request):
> ... if request.version == 'beta':
> ... return 'contact_list'
> ... return 'contacts'
>

I'd expect __parent__ and __name__ to be property. You don't need the request
parameter since you have it from the constructor.

> >>> from zope.traversing.browser import AbsoluteURL as ZopeAbsoluteURL
> >>> sm.registerAdapter(
>
> ... ZopeAbsoluteURL, (ILocation, IWebServiceLayer),
> ... provided=IAbsoluteURL)
>
> >>> sm.registerAdapter(
>
> ... ContactSetLocation, (IContactSet, IWebServiceLayer),
> ... provided=ILocation)
>
> Unfortunately this doesn't work with Zope's AbsoluteURL implementation,
> which contains this line:
>
> context = ILocation(context)
>
> I never get a chance to convert ContactSet into a ContactSetLocation.

I see. I suggest then that you simply provide an ILocation adapter and use
get_current_browser_request() to get the request parameter.

>
> I can modify my alternate implementation of AbsoluteURL to try a
> multi-adapter lookup before trying a simple cast to ILocation. I'll still
> need the alternate AbsoluteURL but I'd be able to get rid of the
> IRequestAwareLocation interface. Does this make sense? Am I missing
> something?
>

--
Francis J. Lacoste
<email address hidden>

[Leonard Richardson (leonardr)]

If I use get_current_browser_request() I shouldn't need an ILocation adapter at all. (Though one is still possible.) I might as well make the data model objects implement ILocation directly.

On that note, I remember what I was doing with the IRequestAwareLocation thing. We can always implement a standard ILocation adapter that grabs the request and branches based on request.version. But with IRequestAwareLocation we can define totally different adapters for different versions. BetaContactLocation can provide the location for version 'beta' and DevContactLocation can provide the location for version 'dev'.

We don't really need that to get a basic system working, but it might be useful in the future. What do you think? I'll work on taking the code out for now.

[Francis J. Lacoste (flacoste)]

On January 12, 2010, Leonard Richardson wrote:
> If I use get_current_browser_request() I shouldn't need an ILocation
> adapter at all. (Though one is still possible.) I might as well make the
> data model objects implement ILocation directly.
>
> On that note, I remember what I was doing with the IRequestAwareLocation
> thing. We can always implement a standard ILocation adapter that grabs the
> request and branches based on request.version. But with
> IRequestAwareLocation we can define totally different adapters for
> different versions. BetaContactLocation can provide the location for
> version 'beta' and DevContactLocation can provide the location for version
> 'dev'.
>
> We don't really need that to get a basic system working, but it might be
> useful in the future. What do you think? I'll work on taking the code out
> for now.
>

We shouldn't introduce other abstraction layers until they are needed :-) I
call YAGNI for now.

--
Francis J. Lacoste
<email address hidden>

[Leonard Richardson (leonardr)]

OK, I've made all the changes you requested. The complete diff of my changes since your review is here:

http://pastebin.ubuntu.com/355558/

[Francis J. Lacoste (flacoste)]

On January 12, 2010, Leonard Richardson wrote:
> OK, I've made all the changes you requested. The complete diff of my
> changes since your review is here:
>
> http://pastebin.ubuntu.com/355558/
>

That's great, thanks. My only comment is about the NEWS.txt file:

> === modified file 'src/lazr/restful/NEWS.txt'
> --- src/lazr/restful/NEWS.txt 2009-11-16 14:49:53 +0000
> +++ src/lazr/restful/NEWS.txt 2010-01-12 15:17:51 +0000
> @@ -9,10 +9,11 @@
> changes. You *must* change your configuration object to get your code
> to work in this version! See "active_versions" below.
>
> -Added the precursor of a versioning system for web services. Clients
> -can now request the "trunk" of a web service as well as one published
> -version. Apart from the URIs served, the two web services are exactly
> -the same.
> +Added a versioning system for web services. Clients can now request
> +the "trunk" of a web service as well as one published version. Apart
> +from the URIs served, the two web services are exactly the same. There
> +is no way to serve two different versions of a web service without
> +defining both versions from scratch.

You might want to make this less harsh by stating that a next version will add
annotations to make that easy to do.

  review approve code
  status approved

--
Francis J. Lacoste
<email address hidden>

review: Approve (code)

[lp:~leonardr/lazr.restful/multiversion-collection]

95. By Leonard Richardson on 2010-01-12

[r=flacoste] It's now possible to define two distinct web services based on the same data model.

=== modified file 'src/lazr/restful/NEWS.txt'
--- src/lazr/restful/NEWS.txt	2009-11-16 14:49:53 +0000
+++ src/lazr/restful/NEWS.txt	2010-01-12 15:21:22 +0000
@@ -9,10 +9,11 @@
 changes. You *must* change your configuration object to get your code
 to work in this version! See "active_versions" below.
 
-Added the precursor of a versioning system for web services. Clients
-can now request the "trunk" of a web service as well as one published
-version. Apart from the URIs served, the two web services are exactly
-the same.
+Added a versioning system for web services. Clients can now request
+the "trunk" of a web service as well as one published version. Apart
+from the URIs served, the two web services are exactly the same. There
+is no way to serve two different versions of a web service without
+defining both versions from scratch.
 
 This release introduces a new field to IWebServiceConfiguration:
 latest_version_uri_prefix. If you are rolling your own

=== modified file 'src/lazr/restful/_operation.py'
--- src/lazr/restful/_operation.py	2009-03-31 17:58:53 +0000
+++ src/lazr/restful/_operation.py	2010-01-12 15:21:22 +0000
@@ -4,7 +4,7 @@
 
 import simplejson
 
-from zope.component import getMultiAdapter, queryAdapter
+from zope.component import getMultiAdapter, queryMultiAdapter
 from zope.event import notify
 from zope.interface import Attribute, implements, providedBy
 from zope.interface.interfaces import IInterface
@@ -80,11 +80,11 @@
             # this object served to the client.
             return result
 
-        if queryAdapter(result, ICollection):
+        if queryMultiAdapter((result, self.request), ICollection):
             # If the result is a web service collection, serve only one
             # batch of the collection.
-            result = CollectionResource(
-                ICollection(result), self.request).batch()
+            collection = getMultiAdapter((result, self.request), ICollection)
+            result = CollectionResource(collection, self.request).batch()
         elif self.should_batch(result):
             result = self.batch(result, self.request)
 
@@ -93,7 +93,7 @@
         try:
             json_representation = simplejson.dumps(
                 result, cls=ResourceJSONEncoder)
-        except TypeError:
+        except TypeError, e:
             raise TypeError("Could not serialize object %s to JSON." %
                             result)
 

=== modified file 'src/lazr/restful/_resource.py'
--- src/lazr/restful/_resource.py	2009-10-27 17:45:53 +0000
+++ src/lazr/restful/_resource.py	2010-01-12 15:21:22 +0000
@@ -18,6 +18,7 @@
     'JSONItem',
     'ReadOnlyResource',
     'RedirectResource',
+    'register_versioned_request_utility',
     'render_field_to_html',
     'ResourceJSONEncoder',
     'RESTUtilityBase',
@@ -47,13 +48,15 @@
 from zope.app.pagetemplate.engine import TrustedAppPT
 from zope import component
 from zope.component import (
-    adapts, getAdapters, getAllUtilitiesRegisteredFor, getMultiAdapter,
-    getUtility, queryAdapter, getGlobalSiteManager)
+    adapts, getAdapters, getAllUtilitiesRegisteredFor,
+    getGlobalSiteManager, getMultiAdapter, getSiteManager, getUtility,
+    queryMultiAdapter)
 from zope.component.interfaces import ComponentLookupError
 from zope.event import notify
 from zope.publisher.http import init_status_codes, status_reasons
 from zope.interface import (
-    implementer, implements, implementedBy, providedBy, Interface)
+    alsoProvides, implementer, implements, implementedBy, providedBy,
+    Interface)
 from zope.interface.common.sequence import IFiniteSequence
 from zope.interface.interfaces import IInterface
 from zope.location.interfaces import ILocation
@@ -82,7 +85,8 @@
     IResourceDELETEOperation, IResourceGETOperation, IResourcePOSTOperation,
     IScopedCollection, IServiceRootResource, ITopLevelEntryLink,
     IUnmarshallingDoesntNeedValue, IWebServiceClientRequest,
-    IWebServiceConfiguration, LAZR_WEBSERVICE_NAME)
+    IWebServiceConfiguration, IWebServiceLayer, IWebServiceVersion,
+    LAZR_WEBSERVICE_NAME)
 from lazr.restful.utils import get_current_browser_request
 
 
@@ -112,6 +116,17 @@
         return unicode(value)
 
 
+def register_versioned_request_utility(interface, version):
+    """Registers a marker interface as a utility for version lookup.
+
+    This function registers the given interface class as the
+    IWebServiceVersion utility for the given version string.
+    """
+    alsoProvides(interface, IWebServiceVersion)
+    getSiteManager().registerUtility(
+        interface, IWebServiceVersion, name=version)
+
+
 class LazrPageTemplateFile(TrustedAppPT, PageTemplateFile):
     "A page template class for generating web service-related documents."
     pass
@@ -143,8 +158,9 @@
                 return tuple(obj)
             if isinstance(underlying_object, dict):
                 return dict(obj)
-        if queryAdapter(obj, IEntry):
-            obj = EntryResource(obj, get_current_browser_request())
+        request = get_current_browser_request()
+        if queryMultiAdapter((obj, request), IEntry):
+            obj = EntryResource(obj, request)
 
         return IJSONPublishable(obj).toDataForJSON()
 
@@ -1220,6 +1236,7 @@
         self.__parent__ = self.entry.context
         self.__name__ = self.name
 
+
 class EntryFieldURL(AbsoluteURL):
     """An IAbsoluteURL adapter for EntryField objects."""
     component.adapts(EntryField, IHTTPRequest)
@@ -1243,7 +1260,7 @@
     def __init__(self, context, request):
         """Associate this resource with a specific object and request."""
         super(EntryResource, self).__init__(context, request)
-        self.entry = IEntry(context)
+        self.entry = getMultiAdapter((context, request), IEntry)
 
     def _getETagCore(self, unmarshalled_field_values=None):
         """Calculate the ETag for an entry.
@@ -1442,7 +1459,10 @@
     def __init__(self, context, request):
         """Associate this resource with a specific object and request."""
         super(CollectionResource, self).__init__(context, request)
-        self.collection = ICollection(context)
+        if ICollection.providedBy(context):
+            self.collection = context
+        else:
+            self.collection = getMultiAdapter((context, request), ICollection)
 
     def do_GET(self):
         """Fetch a collection and render it as JSON."""
@@ -1492,12 +1512,14 @@
             # Scoped collection. The type URL depends on what type of
             # entry the collection holds.
             schema = self.context.relationship.value_type.schema
-            adapter = EntryAdapterUtility.forSchemaInterface(schema)
+            adapter = EntryAdapterUtility.forSchemaInterface(
+                schema, self.request)
             return adapter.entry_page_type_link
         else:
             # Top-level collection.
             schema = self.collection.entry_schema
-            adapter = EntryAdapterUtility.forEntryInterface(schema)
+            adapter = EntryAdapterUtility.forEntryInterface(
+                schema, self.request)
             return adapter.collection_type_link
 
 
@@ -1588,7 +1610,7 @@
                     # class's singular or plural names.
                     schema = registration.required[0]
                     adapter = EntryAdapterUtility.forSchemaInterface(
-                        schema)
+                        schema, self.request)
 
                     singular = adapter.singular_type
                     assert not singular_names.has_key(singular), (
@@ -1662,7 +1684,7 @@
                         # It's not a top-level resource.
                         continue
                     adapter = EntryAdapterUtility.forEntryInterface(
-                        entry_schema)
+                        entry_schema, self.request)
                     link_name = ("%s_collection_link" % adapter.plural_type)
                     top_level_resources[link_name] = utility
         # Now, collect the top-level entries.
@@ -1687,26 +1709,28 @@
     """An individual entry."""
     implements(IEntry)
 
-    def __init__(self, context):
+    def __init__(self, context, request):
         """Associate the entry with some database model object."""
         self.context = context
+        self.request = request
 
 
 class Collection:
     """A collection of entries."""
     implements(ICollection)
 
-    def __init__(self, context):
+    def __init__(self, context, request):
         """Associate the entry with some database model object."""
         self.context = context
+        self.request = request
 
 
 class ScopedCollection:
     """A collection associated with some parent object."""
     implements(IScopedCollection)
-    adapts(Interface, Interface)
+    adapts(Interface, Interface, IWebServiceLayer)
 
-    def __init__(self, context, collection):
+    def __init__(self, context, collection, request):
         """Initialize the scoped collection.
 
         :param context: The object to which the collection is scoped.
@@ -1714,6 +1738,7 @@
         """
         self.context = context
         self.collection = collection
+        self.request = request
         # Unknown at this time. Should be set by our call-site.
         self.relationship = None
 
@@ -1723,8 +1748,11 @@
         # We are given a model schema (IFoo). Look up the
         # corresponding entry schema (IFooEntry).
         model_schema = self.relationship.value_type.schema
-        return getGlobalSiteManager().adapters.lookup1(
-            model_schema, IEntry).schema
+        request_interface = getUtility(
+            IWebServiceVersion,
+            name=self.request.version)
+        return getGlobalSiteManager().adapters.lookup(
+            (model_schema, request_interface), IEntry).schema
 
     def find(self):
         """See `ICollection`."""
@@ -1748,33 +1776,42 @@
     """
 
     @classmethod
-    def forSchemaInterface(cls, entry_interface):
+    def forSchemaInterface(cls, entry_interface, request):
         """Create an entry adapter utility, given a schema interface.
 
         A schema interface is one that can be annotated to produce a
         subclass of IEntry.
         """
+        request_interface = getUtility(
+            IWebServiceVersion, name=request.version)
         entry_class = getGlobalSiteManager().adapters.lookup(
-            (entry_interface,), IEntry)
+            (entry_interface, request_interface), IEntry)
         assert entry_class is not None, (
-            "No IEntry adapter found for %s." % entry_interface.__name__)
+            ("No IEntry adapter found for %s (web service version: %s)."
+             % (entry_interface.__name__, request.version)))
         return EntryAdapterUtility(entry_class)
 
     @classmethod
-    def forEntryInterface(cls, entry_interface):
+    def forEntryInterface(cls, entry_interface, request):
         """Create an entry adapter utility, given a subclass of IEntry."""
         registrations = getGlobalSiteManager().registeredAdapters()
+        # There should be one IEntry subclass registered for every
+        # version of the web service. We'll go through the appropriate
+        # IEntry registrations looking for one associated with the
+        # same IWebServiceVersion interface we find on the 'request'
+        # object.
         entry_classes = [
             registration.factory for registration in registrations
             if (IInterface.providedBy(registration.provided)
                 and registration.provided.isOrExtends(IEntry)
-                and entry_interface.implementedBy(registration.factory))]
+                and entry_interface.implementedBy(registration.factory)
+                and registration.required[1].providedBy(request))]
         assert not len(entry_classes) > 1, (
-            "%s provides more than one IEntry subclass." %
-            entry_interface.__name__)
+            "%s provides more than one IEntry subclass for version %s." %
+            entry_interface.__name__, request.version)
         assert not len(entry_classes) < 1, (
-            "%s does not provide any IEntry subclass." %
-            entry_interface.__name__)
+            "%s does not provide any IEntry subclass for version %s." %
+            entry_interface.__name__, request.version)
         return EntryAdapterUtility(entry_classes[0])
 
     def __init__(self, entry_class):

=== modified file 'src/lazr/restful/declarations.py'
--- src/lazr/restful/declarations.py	2009-08-14 16:11:34 +0000
+++ src/lazr/restful/declarations.py	2010-01-12 15:21:22 +0000
@@ -51,12 +51,12 @@
 from lazr.restful.interface import copy_field
 from lazr.restful.interfaces import (
     ICollection, IEntry, IResourceDELETEOperation, IResourceGETOperation,
-    IResourcePOSTOperation, IWebServiceConfiguration, LAZR_WEBSERVICE_NAME,
-    LAZR_WEBSERVICE_NS)
+    IResourcePOSTOperation, IWebServiceConfiguration, IWebServiceVersion,
+    LAZR_WEBSERVICE_NAME, LAZR_WEBSERVICE_NS)
 from lazr.restful import (
     Collection, Entry, EntryAdapterUtility, ResourceOperation, ObjectLink)
 from lazr.restful.security import protect_schema
-from lazr.restful.utils import camelcase_to_underscore_separated
+from lazr.restful.utils import camelcase_to_underscore_separated, get_current_browser_request
 
 LAZR_WEBSERVICE_EXPORTED = '%s.exported' % LAZR_WEBSERVICE_NS
 COLLECTION_TYPE = 'collection'
@@ -780,8 +780,14 @@
 
     def __get__(self, instance, owner):
         """Look up the entry schema that adapts the model schema."""
-        entry_class = getGlobalSiteManager().adapters.lookup1(
-            self.model_schema, IEntry)
+        if instance is None or instance.request is None:
+            request = get_current_browser_request()
+        else:
+            request = instance.request
+        request_interface = getUtility(
+            IWebServiceVersion, name=request.version)
+        entry_class = getGlobalSiteManager().adapters.lookup(
+            (self.model_schema, request_interface), IEntry)
         if entry_class is None:
             return None
         return EntryAdapterUtility(entry_class).entry_interface

=== modified file 'src/lazr/restful/directives/__init__.py'
--- src/lazr/restful/directives/__init__.py	2009-11-19 15:33:49 +0000
+++ src/lazr/restful/directives/__init__.py	2010-01-12 15:21:22 +0000
@@ -10,15 +10,20 @@
 import martian
 from zope.component import getSiteManager, getUtility
 from zope.location.interfaces import ILocation
+from zope.interface import alsoProvides
+from zope.interface.interface import InterfaceClass
 from zope.traversing.browser import AbsoluteURL
 from zope.traversing.browser.interfaces import IAbsoluteURL
 
 from lazr.restful.interfaces import (
-    IServiceRootResource, IWebServiceConfiguration, IWebServiceLayer)
-from lazr.restful import ServiceRootResource
+    IServiceRootResource, IWebServiceClientRequest, IWebServiceConfiguration,
+    IWebServiceLayer, IWebServiceVersion)
+from lazr.restful import (
+    register_versioned_request_utility, ServiceRootResource)
 from lazr.restful.simple import (
     BaseWebServiceConfiguration, Publication, Request,
     RootResourceAbsoluteURL)
+from lazr.restful.utils import make_identifier_safe
 
 
 class request_class(martian.Directive):
@@ -57,6 +62,10 @@
 
     This grokker then registers an instance of your subclass as the
     singleton configuration object.
+
+    This grokker also creates marker interfaces for every web service
+    version defined in the configuration, and registers each as an
+    IWebServiceVersion utility.
     """
     martian.component(BaseWebServiceConfiguration)
     martian.directive(request_class)
@@ -84,7 +93,18 @@
             cls.get_request_user = get_request_user
 
         # Register as utility.
-        getSiteManager().registerUtility(cls(), IWebServiceConfiguration)
+        utility = cls()
+        sm = getSiteManager()
+        sm.registerUtility(utility, IWebServiceConfiguration)
+
+        # Create and register marker interfaces for request objects.
+        for version in set(
+            utility.active_versions + [utility.latest_version_uri_prefix]):
+            classname = ("IWebServiceClientRequestVersion" +
+                         make_identifier_safe(version))
+            marker_interface = InterfaceClass(
+                classname, (IWebServiceClientRequest,), {})
+            register_versioned_request_utility(marker_interface, version)
         return True
 
 

=== modified file 'src/lazr/restful/docs/multiversion.txt'
--- src/lazr/restful/docs/multiversion.txt	2009-11-19 16:43:08 +0000
+++ src/lazr/restful/docs/multiversion.txt	2010-01-12 15:21:22 +0000
@@ -5,10 +5,121 @@
 services. Typically these different services represent successive
 versions of a single web service, improved over time.
 
+This test defines three different versions of a web service ('beta',
+'1.0', and 'dev'), all based on the same underlying data model.
+
+Setup
+=====
+
+First, let's set up the web service infrastructure. Doing this first
+will let us create HTTP requests for different versions of the web
+service. The first step is to install the common ZCML used by all
+lazr.restful web services.
+
+    >>> from zope.configuration import xmlconfig
+    >>> zcmlcontext = xmlconfig.string("""
+    ... <configure xmlns="http://namespaces.zope.org/zope">
+    ...   <include package="lazr.restful" file="basic-site.zcml"/>
+    ...   <utility
+    ...       factory="lazr.restful.example.base.filemanager.FileManager" />
+    ... </configure>
+    ... """)
+
+Web service configuration object
+--------------------------------
+
+Here's the web service configuration, which defines the three
+versions: 'beta', '1.0', and 'dev'.
+
+    >>> from lazr.restful import directives
+    >>> from lazr.restful.interfaces import IWebServiceConfiguration
+    >>> from lazr.restful.simple import BaseWebServiceConfiguration
+    >>> from lazr.restful.testing.webservice import WebServiceTestPublication
+
+    >>> class WebServiceConfiguration(BaseWebServiceConfiguration):
+    ...     hostname = 'api.multiversion.dev'
+    ...     use_https = False
+    ...     active_versions = ['beta', '1.0']
+    ...     latest_version_uri_prefix = 'dev'
+    ...     code_revision = 'test'
+    ...     max_batch_size = 100
+    ...     view_permission = None
+    ...     directives.publication_class(WebServiceTestPublication)
+
+    >>> from grokcore.component.testing import grok_component
+    >>> ignore = grok_component(
+    ...     'WebServiceConfiguration', WebServiceConfiguration)
+
+    >>> from zope.component import getUtility
+    >>> config = getUtility(IWebServiceConfiguration)
+
+URL generation
+--------------
+
+The URL to an entry or collection is different in different versions
+of web service. Not only does every URL includes the version number as
+a path element ("http://api.multiversion.dev/1.0/..."), the name or
+location of an object might change from one version to another.
+
+We implement this in this example web service by defining ILocation
+implementations that retrieve the current browser request and branch
+based on the value of request.version. You'll see this in the
+ContactSet class.
+
+Here, we tell Zope to use Zope's default AbsoluteURL class for
+generating the URLs of objects that implement ILocation. There's no
+multiversion-specific code here.
+
+    >>> from zope.component import getSiteManager
+    >>> from zope.traversing.browser import AbsoluteURL
+    >>> from zope.traversing.browser.interfaces import IAbsoluteURL
+    >>> from zope.location.interfaces import ILocation
+    >>> from lazr.restful.interfaces import IWebServiceLayer
+
+    >>> sm = getSiteManager()
+    >>> sm.registerAdapter(
+    ...     AbsoluteURL, (ILocation, IWebServiceLayer),
+    ...     provided=IAbsoluteURL)
+
+Defining the request marker interfaces
+--------------------------------------
+
+Every version must have a corresponding subclass of
+IWebServiceClientRequest. Each interface class is registered as a
+named utility implementing IWebServiceVersion. For instance, in the
+example below, the IWebServiceRequest10 class will be registered as
+the IWebServiceVersion utility with the name "1.0".
+
+When a request comes in, lazr.restful figures out which version the
+client is asking for, and tags the request with the appropriate marker
+interface. The utility registrations make it easy to get the marker
+interface for a version, given the version string.
+
+In a real application, these interfaces will be generated and
+registered automatically.
+
+    >>> from lazr.restful.interfaces import IWebServiceClientRequest
+    >>> class IWebServiceRequestBeta(IWebServiceClientRequest):
+    ...     pass
+
+    >>> class IWebServiceRequest10(IWebServiceClientRequest):
+    ...     pass
+
+    >>> class IWebServiceRequestDev(IWebServiceClientRequest):
+    ...     pass
+
+    >>> versions = ((IWebServiceRequestBeta, 'beta'),
+    ...             (IWebServiceRequest10, '1.0'),
+    ...             (IWebServiceRequestDev, 'dev'))
+
+    >>> from lazr.restful import register_versioned_request_utility
+    >>> for cls, version in versions:
+    ...     register_versioned_request_utility(cls, version)
+
 Example model objects
 =====================
 
-First let's define the data model. The model in webservice.txt is
+Now let's define the data model. The model in webservice.txt is
 pretty complicated; this model will be just complicated enough to
 illustrate how to publish multiple versions of a web service.
 
@@ -18,40 +129,21 @@
     >>> from zope.interface import Interface, Attribute
     >>> from zope.schema import Bool, Bytes, Int, Text, TextLine, Object
 
-    >>> class ITestDataObject(Interface):
-    ...     """A marker interface for data objects."""
-    ...     path = Attribute("The path portion of this object's URL. "
-    ...                      "Defined here for simplicity of testing.")
-
-    >>> class IContact(ITestDataObject):
+    >>> class IContact(Interface):
     ...     name = TextLine(title=u"Name", required=True)
     ...     phone = TextLine(title=u"Phone number", required=True)
     ...     fax = TextLine(title=u"Fax number", required=False)
 
-Here's the interface for the 'set' object that manages the contacts.
+Here's an interface for the 'set' object that manages the
+contacts.
 
     >>> from lazr.restful.interfaces import ITraverseWithGet
-    >>> class IContactSet(ITestDataObject, ITraverseWithGet):
-    ...     def getAll(self):
+    >>> class IContactSet(ITraverseWithGet):
+    ...     def getAllContacts():
     ...         "Get all contacts."
     ...
-    ...     def get(self, name):
-    ...         "Retrieve a single contact by name."
-
-Before we can define any classes, a bit of web service setup. Let's
-make all component lookups use the global site manager.
-
-    >>> from zope.component import getSiteManager
-    >>> sm = getSiteManager()
-
-    >>> from zope.component import adapter
-    >>> from zope.component.interfaces import IComponentLookup
-    >>> from zope.interface import implementer, Interface
-    >>> @implementer(IComponentLookup)
-    ... @adapter(Interface)
-    ... def everything_uses_the_global_site_manager(context):
-    ...     return sm
-    >>> sm.registerAdapter(everything_uses_the_global_site_manager)
+    ...     def findContacts(self, string, search_fax):
+    ...         """Find contacts by name, phone number, or fax number."""
 
 Here's a simple implementation of IContact.
 
@@ -59,40 +151,64 @@
     >>> from zope.interface import implements
     >>> from lazr.restful.security import protect_schema
     >>> class Contact:
-    ...     implements(IContact)
+    ...     implements(IContact, ILocation)
     ...     def __init__(self, name, phone, fax):
     ...         self.name = name
     ...         self.phone = phone
     ...         self.fax = fax
     ...
     ...     @property
-    ...     def path(self):
-    ...         return 'contacts/' + quote(self.name)
+    ...     def __parent__(self):
+    ...         return ContactSet()
+    ...
+    ...     @property
+    ...     def __name__(self):
+    ...         return self.name
     >>> protect_schema(Contact, IContact)
 
 Here's a simple ContactSet with a predefined list of contacts.
 
+    >>> from zope.publisher.interfaces.browser import IBrowserRequest
+    >>> from lazr.restful.interfaces import IServiceRootResource
     >>> from lazr.restful.simple import TraverseWithGet
-    >>> from zope.publisher.interfaces.browser import IBrowserRequest
+    >>> from lazr.restful.utils import get_current_browser_request
     >>> class ContactSet(TraverseWithGet):
-    ...     implements(IContactSet)
-    ...     path = "contacts"
+    ...     implements(IContactSet, ILocation)
     ...
     ...     def __init__(self):
     ...         self.contacts = CONTACTS
     ...
-    ...     def get(self, name):
-    ...         contacts = [contact for contacts in self.contacts
-    ...                     if pair.name == name]
+    ...     def get(self, request, name):
+    ...         contacts = [contact for contact in self.contacts
+    ...                     if contact.name == name]
     ...         if len(contacts) == 1:
     ...             return contacts[0]
     ...         return None
     ...
     ...     def getAllContacts(self):
     ...         return self.contacts
+    ...
+    ...     def findContacts(self, string, search_fax=True):
+    ...          return [contact for contact in self.contacts
+    ...                  if (string in contact.name
+    ...                      or string in contact.phone
+    ...                      or (search_fax and string in contact.fax))]
+    ...
+    ...     @property
+    ...     def __parent__(self):
+    ...         request = get_current_browser_request()
+    ...         return getUtility(
+    ...             IServiceRootResource, name=request.version)
+    ...
+    ...     @property
+    ...     def __name__(self):
+    ...         request = get_current_browser_request()
+    ...         if request.version == 'beta':
+    ...             return 'contact_list'
+    ...         return 'contacts'
 
-    >>> sm.registerAdapter(
-    ...     TraverseWithGet, [ITestDataObject, IBrowserRequest])
+    >>> from lazr.restful.security import protect_schema
+    >>> protect_schema(ContactSet, IContactSet)
 
 Here are the "model objects" themselves:
 
@@ -118,7 +234,7 @@
     ...     """Marker for a contact published through the web service."""
 
     >>> from zope.interface import taggedValue
-    >>> from lazr.restful.interfaces import IEntry, LAZR_WEBSERVICE_NAME
+    >>> from lazr.restful.interfaces import LAZR_WEBSERVICE_NAME
     >>> class IContactEntryBeta(IContactEntry, IContact):
     ...     """The part of an author we expose through the web service."""
     ...     taggedValue(LAZR_WEBSERVICE_NAME,
@@ -169,14 +285,18 @@
     ...     implements(IContactEntryBeta)
     ...     delegates(IContactEntryBeta)
     ...     schema = IContactEntryBeta
+    ...     def __init__(self, context, request):
+    ...         self.context = context
+
     >>> sm.registerAdapter(
-    ...     ContactEntryBeta, provided=IContactEntry, name="beta")
+    ...     ContactEntryBeta, [IContact, IWebServiceRequestBeta],
+    ...     provided=IContactEntry)
 
 By wrapping one of our predefined Contacts in a ContactEntryBeta
 object, we can verify that it implements IContactEntryBeta and
 IContactEntry.
 
-    >>> entry = ContactEntryBeta(C1)
+    >>> entry = ContactEntryBeta(C1, None)
     >>> IContactEntry.validateInvariants(entry)
     >>> IContactEntryBeta.validateInvariants(entry)
 
@@ -184,24 +304,26 @@
 properties to implement the different field names.
 
     >>> class ContactEntry10(Entry):
-    ...    adapts(IContact)
-    ...    implements(IContactEntry10)
-    ...    schema = IContactEntry10
-    ...
-    ...    def __init__(self, contact):
-    ...        self.contact = contact
-    ...
-    ...    @property
-    ...    def phone_number(self):
-    ...        return self.contact.phone
-    ...
-    ...    @property
-    ...    def fax_number(self):
-    ...        return self.contact.fax
+    ...     adapts(IContact)
+    ...     implements(IContactEntry10)
+    ...     delegates(IContactEntry10)
+    ...     schema = IContactEntry10
+    ...
+    ...     def __init__(self, context, request):
+    ...         self.context = context
+    ...
+    ...     @property
+    ...     def phone_number(self):
+    ...         return self.context.phone
+    ...
+    ...     @property
+    ...     def fax_number(self):
+    ...         return self.context.fax
     >>> sm.registerAdapter(
-    ...     ContactEntry10, provided=IContactEntry, name="1.0")
+    ...     ContactEntry10, [IContact, IWebServiceRequest10],
+    ...     provided=IContactEntry)
 
-    >>> entry = ContactEntry10(C1)
+    >>> entry = ContactEntry10(C1, None)
     >>> IContactEntry.validateInvariants(entry)
     >>> IContactEntry10.validateInvariants(entry)
 
@@ -209,20 +331,22 @@
 the web service.
 
     >>> class ContactEntryDev(Entry):
-    ...    adapts(IContact)
-    ...    implements(IContactEntryDev)
-    ...    schema = IContactEntryDev
-    ...
-    ...    def __init__(self, contact):
-    ...        self.contact = contact
-    ...
-    ...    @property
-    ...    def phone_number(self):
-    ...        return self.contact.phone
+    ...     adapts(IContact)
+    ...     implements(IContactEntryDev)
+    ...     delegates(IContactEntryDev)
+    ...     schema = IContactEntryDev
+    ...
+    ...     def __init__(self, context, request):
+    ...         self.context = context
+    ...
+    ...     @property
+    ...     def phone_number(self):
+    ...         return self.context.phone
     >>> sm.registerAdapter(
-    ...     ContactEntryDev, provided=IContactEntry, name="dev")
+    ...     ContactEntryDev, [IContact, IWebServiceRequestDev],
+    ...     provided=IContactEntry)
 
-    >>> entry = ContactEntryDev(C1)
+    >>> entry = ContactEntryDev(C1, None)
     >>> IContactEntry.validateInvariants(entry)
     >>> IContactEntryDev.validateInvariants(entry)
 
@@ -239,19 +363,35 @@
     ...
     ComponentLookupError: ...
 
-When adapting Contact to IEntry you must specify a version number as
-the name of the adapter. The object you get back will implement the
-appropriate version of the web service.
-
-    >>> beta_entry = getAdapter(C1, IEntry, name="beta")
+When adapting Contact to IEntry you must provide a versioned request
+object. The IEntry object you get back will implement the appropriate
+version of the web service.
+
+To test this we'll need to manually create some versioned request
+objects. The traversal process would take care of this for us (see
+"Request lifecycle" below), but it won't work yet because we have yet
+to define a service root resource.
+
+    >>> from lazr.restful.testing.webservice import (
+    ...     create_web_service_request)
+    >>> from zope.interface import alsoProvides
+
+    >>> from zope.component import getMultiAdapter
+    >>> request_beta = create_web_service_request('/beta/')
+    >>> alsoProvides(request_beta, IWebServiceRequestBeta)
+    >>> beta_entry = getMultiAdapter((C1, request_beta), IEntry)
     >>> print beta_entry.fax
     111-2121
 
-    >>> one_oh_entry = getAdapter(C1, IEntry, name="1.0")
+    >>> request_10 = create_web_service_request('/1.0/')
+    >>> alsoProvides(request_10, IWebServiceRequest10)
+    >>> one_oh_entry = getMultiAdapter((C1, request_10), IEntry)
     >>> print one_oh_entry.fax_number
     111-2121
 
-    >>> dev_entry = getAdapter(C1, IEntry, name="dev")
+    >>> request_dev = create_web_service_request('/dev/')
+    >>> alsoProvides(request_dev, IWebServiceRequestDev)
+    >>> dev_entry = getMultiAdapter((C1, request_dev), IEntry)
     >>> print dev_entry.fax
     Traceback (most recent call last):
     ...
@@ -260,9 +400,13 @@
 Implementing the collection resource
 ====================================
 
-The contact collection itself doesn't change between versions (though
-it could). We'll define it once and register it for every version of
-the web service.
+The set of contacts publishes a slightly different named operation in
+every version of the web service, so in a little bit we'll be
+implementing three different versions of the same named operation. But
+the contact set itself doesn't change between versions (although it
+could). So it's sufficient to implement one ICollection implementation
+and register it as the implementation for every version of the web
+service.
 
     >>> from lazr.restful import Collection
     >>> from lazr.restful.interfaces import ICollection
@@ -277,67 +421,87 @@
     ...        """Find all the contacts."""
     ...        return self.context.getAllContacts()
 
-Let's make sure ContactCollection implements ICollection.
+Let's make sure it implements ICollection.
 
     >>> from zope.interface.verify import verifyObject
     >>> contact_set = ContactSet()
-    >>> verifyObject(ICollection, ContactCollection(contact_set))
+    >>> verifyObject(ICollection, ContactCollection(contact_set, None))
     True
 
-Once we register ContactCollection as the ICollection implementation,
-we can adapt the ContactSet object to a web service ICollection.
-
-    >>> for version in ['beta', 'dev', '1.0']:
-    ...     sm.registerAdapter(
-    ...         ContactCollection, provided=ICollection, name=version)
-
-    >>> dev_collection = getAdapter(contact_set, ICollection, name="dev")
-    >>> len(dev_collection.find())
-    2
-
-    >>> dev_collection = getAdapter(contact_set, ICollection, name="dev")
-    >>> len(dev_collection.find())
-    2
-
-Web service infrastructure initialization
-=========================================
-
-Now that we've defined the data model, it's time to set up the web
-service infrastructure.
-
-    >>> from zope.configuration import xmlconfig
-    >>> zcmlcontext = xmlconfig.string("""
-    ... <configure xmlns="http://namespaces.zope.org/zope">
-    ...   <include package="lazr.restful" file="basic-site.zcml"/>
-    ...   <utility
-    ...       factory="lazr.restful.example.base.filemanager.FileManager" />
-    ... </configure>
-    ... """)
-
-Here's the configuration, which defines the three versions: 'beta',
-'1.0', and 'dev'.
-
-    >>> from lazr.restful import directives
-    >>> from lazr.restful.interfaces import IWebServiceConfiguration
-    >>> from lazr.restful.simple import BaseWebServiceConfiguration
-    >>> from lazr.restful.testing.webservice import WebServiceTestPublication
-
-    >>> class WebServiceConfiguration(BaseWebServiceConfiguration):
-    ...     hostname = 'api.multiversion.dev'
-    ...     use_https = False
-    ...     active_versions = ['beta', '1.0']
-    ...     latest_version_uri_prefix = 'dev'
-    ...     code_revision = 'test'
-    ...     max_batch_size = 100
-    ...     directives.publication_class(WebServiceTestPublication)
-
-    >>> from grokcore.component.testing import grok_component
-    >>> ignore = grok_component(
-    ...     'WebServiceConfiguration', WebServiceConfiguration)
-
-    >>> from zope.component import getUtility
-    >>> config = getUtility(IWebServiceConfiguration)
-
+Register it as the ICollection adapter for IContactSet. We use a
+generic request interface (IWebServiceClientRequest) rather than a
+specific one like IWebServiceRequestBeta, so that the same
+implementation will be used for every version of the web service.
+
+    >>> sm.registerAdapter(
+    ...     ContactCollection, [IContactSet, IWebServiceClientRequest],
+    ...     provided=ICollection)
+
+Make sure the functionality works properly.
+
+    >>> collection = getMultiAdapter(
+    ...     (contact_set, request_beta), ICollection)
+    >>> len(collection.find())
+    2
+
+Implementing the named operations
+---------------------------------
+
+All three versions of the web service publish a named operation for
+searching for contacts, but they publish it in slightly different
+ways. In 'beta' it publishes a named operation called 'findContacts',
+which does a search based on name, phone number, and fax number. In
+'1.0' it publishes the same operation, but the name is
+'find'. In 'dev' the contact set publishes 'find',
+but the functionality is changed to search only the name and phone
+number.
+
+Here's the named operation as implemented in versions 'beta' and '1.0'.
+
+    >>> from lazr.restful import ResourceGETOperation
+    >>> from lazr.restful.fields import CollectionField, Reference
+    >>> from lazr.restful.interfaces import IResourceGETOperation
+    >>> class FindContactsOperationBase(ResourceGETOperation):
+    ...    """An operation that searches for contacts."""
+    ...    implements(IResourceGETOperation)
+    ...
+    ...    params = [ TextLine(__name__='string') ]
+    ...    return_type = CollectionField(value_type=Reference(schema=IContact))
+    ...
+    ...    def call(self, string):
+    ...        try:
+    ...            return self.context.findContacts(string)
+    ...        except ValueError, e:
+    ...            self.request.response.setStatus(400)
+    ...            return str(e)
+
+This operation is registered as the "findContacts" operation in the
+'beta' service, and the 'find' operation in the '1.0' service.
+
+    >>> sm.registerAdapter(
+    ...     FindContactsOperationBase, [IContactSet, IWebServiceRequestBeta],
+    ...     provided=IResourceGETOperation, name="findContacts")
+
+    >>> sm.registerAdapter(
+    ...     FindContactsOperationBase, [IContactSet, IWebServiceRequest10],
+    ...     provided=IResourceGETOperation, name="find")
+
+Here's the slightly different named operation as implemented in
+version 'dev'.
+
+    >>> class FindContactsOperationNoFax(FindContactsOperationBase):
+    ...    """An operation that searches for contacts."""
+    ...
+    ...    def call(self, string):
+    ...        try:
+    ...            return self.context.findContacts(string, False)
+    ...        except ValueError, e:
+    ...            self.request.response.setStatus(400)
+    ...            return str(e)
+
+    >>> sm.registerAdapter(
+    ...     FindContactsOperationNoFax, [IContactSet, IWebServiceRequestDev],
+    ...     provided=IResourceGETOperation, name="find")
 
 The service root resource
 =========================
@@ -346,19 +510,20 @@
 roots. The 'beta' web service will publish the contact set as
 'contact_list', and subsequent versions will publish it as 'contacts'.
 
-    >>> from lazr.restful.interfaces import IServiceRootResource
     >>> from lazr.restful.simple import RootResource
     >>> from zope.traversing.browser.interfaces import IAbsoluteURL
 
     >>> class BetaServiceRootResource(RootResource):
     ...     implements(IAbsoluteURL)
     ...
-    ...     top_level_objects = { 'contact_list': ContactSet() }
+    ...     top_level_collections = {
+    ...         'contact_list': (IContact, ContactSet()) }
 
     >>> class PostBetaServiceRootResource(RootResource):
     ...     implements(IAbsoluteURL)
     ...
-    ...     top_level_objects = { 'contacts': ContactSet() }
+    ...     top_level_collections = {
+    ...         'contacts': (IContact, ContactSet()) }
 
     >>> for version, cls in (('beta', BetaServiceRootResource),
     ...                      ('1.0', PostBetaServiceRootResource),
@@ -378,22 +543,338 @@
 Both classes will use the default lazr.restful code to generate their
 URLs.
 
+    >>> from zope.traversing.browser import absoluteURL
     >>> from lazr.restful.simple import RootResourceAbsoluteURL
     >>> for cls in (BetaServiceRootResource, PostBetaServiceRootResource):
     ...     sm.registerAdapter(
     ...         RootResourceAbsoluteURL, [cls, IBrowserRequest])
 
-    >>> from zope.traversing.browser import absoluteURL
-    >>> from lazr.restful.testing.webservice import (
-    ...     create_web_service_request)
-
     >>> beta_request = create_web_service_request('/beta/')
-    >>> ignore = beta_request.traverse(None)
+    >>> print beta_request.traverse(None)
+    <BetaServiceRootResource object...>
+
     >>> print absoluteURL(beta_app, beta_request)
     http://api.multiversion.dev/beta/
 
     >>> dev_request = create_web_service_request('/dev/')
-    >>> ignore = dev_request.traverse(None)
+    >>> print dev_request.traverse(None)
+    <PostBetaServiceRootResource object...>
+
     >>> print absoluteURL(dev_app, dev_request)
     http://api.multiversion.dev/dev/
 
+Request lifecycle
+=================
+
+When a request first comes in, there's no way to tell which version
+it's associated with.
+
+    >>> from lazr.restful.testing.webservice import (
+    ...     create_web_service_request)
+
+    >>> request_beta = create_web_service_request('/beta/')
+    >>> IWebServiceRequestBeta.providedBy(request_beta)
+    False
+
+The traversal process associates the request with a particular version.
+
+    >>> request_beta.traverse(None)
+    <BetaServiceRootResource object ...>
+    >>> IWebServiceRequestBeta.providedBy(request_beta)
+    True
+    >>> print request_beta.version
+    beta
+
+Using the web service
+=====================
+
+Now that we can create versioned web service requests, let's try out
+the different versions of the web service.
+
+Beta
+----
+
+Here's the service root resource.
+
+    >>> import simplejson
+    >>> request = create_web_service_request('/beta/')
+    >>> resource = request.traverse(None)
+    >>> body = simplejson.loads(resource())
+    >>> print sorted(body.keys())
+    ['contacts_collection_link', 'resource_type_link']
+
+    >>> print body['contacts_collection_link']
+    http://api.multiversion.dev/beta/contact_list
+
+Here's the contact list.
+
+    >>> request = create_web_service_request('/beta/contact_list')
+    >>> resource = request.traverse(None)
+
+We can't access the underlying data model object through the request,
+but since we happen to know which object it is, we can pass it into
+absoluteURL along with the request object, and get the correct URL.
+
+    >>> print absoluteURL(contact_set, request)
+    http://api.multiversion.dev/beta/contact_list
+
+    >>> body = simplejson.loads(resource())
+    >>> body['total_size']
+    2
+    >>> for link in sorted(
+    ...     [contact['self_link'] for contact in body['entries']]):
+    ...     print link
+    http://api.multiversion.dev/beta/contact_list/Cleo%20Python
+    http://api.multiversion.dev/beta/contact_list/Oliver%20Bluth
+
+We can traverse through the collection to an entry.
+
+    >>> request_beta = create_web_service_request(
+    ...     '/beta/contact_list/Cleo Python')
+    >>> resource = request_beta.traverse(None)
+
+Again, we can't access the underlying data model object through the
+request, but since we know which object represents Cleo Python, we can
+pass it into absoluteURL along with this request object, and get the
+object's URL.
+
+    >>> print C1.name
+    Cleo Python
+    >>> print absoluteURL(C1, request_beta)
+    http://api.multiversion.dev/beta/contact_list/Cleo%20Python
+
+    >>> body = simplejson.loads(resource())
+    >>> sorted(body.keys())
+    ['fax', 'http_etag', 'name', 'phone', 'resource_type_link', 'self_link']
+    >>> print body['name']
+    Cleo Python
+
+We can traverse through an entry to one of its fields.
+
+    >>> request_beta = create_web_service_request(
+    ...     '/beta/contact_list/Cleo Python/fax')
+    >>> field = request_beta.traverse(None)
+    >>> print simplejson.loads(field())
+    111-2121
+
+We can invoke a named operation.
+
+    >>> import simplejson
+    >>> request_beta = create_web_service_request(
+    ...     '/beta/contact_list',
+    ...     environ={'QUERY_STRING' : 'ws.op=findContacts&string=Cleo'})
+    >>> operation = request_beta.traverse(None)
+    >>> result = simplejson.loads(operation())
+    >>> [contact['name'] for contact in result['entries']]
+    ['Cleo Python']
+
+    >>> request_beta = create_web_service_request(
+    ...     '/beta/contact_list',
+    ...     environ={'QUERY_STRING' : 'ws.op=findContacts&string=111'})
+
+    >>> operation = request_beta.traverse(None)
+    >>> result = simplejson.loads(operation())
+    >>> [contact['fax'] for contact in result['entries']]
+    ['111-2121']
+
+1.0
+---
+
+Here's the service root resource.
+
+    >>> import simplejson
+    >>> request = create_web_service_request('/1.0/')
+    >>> resource = request.traverse(None)
+    >>> body = simplejson.loads(resource())
+    >>> print sorted(body.keys())
+    ['contacts_collection_link', 'resource_type_link']
+
+Note that 'contacts_collection_link' points to a different URL in
+'1.0' than in 'dev'.
+
+    >>> print body['contacts_collection_link']
+    http://api.multiversion.dev/1.0/contacts
+
+An attempt to use the 'beta' name of the contact list in the '1.0' web
+service will fail.
+
+    >>> request = create_web_service_request('/1.0/contact_list')
+    >>> resource = request.traverse(None)
+    Traceback (most recent call last):
+    ...
+    NotFound: Object: <PostBetaServiceRootResource...>, name: u'contact_list'
+
+Here's the contact list under its correct URL.
+
+    >>> request = create_web_service_request('/1.0/contacts')
+    >>> resource = request.traverse(None)
+    >>> print absoluteURL(contact_set, request)
+    http://api.multiversion.dev/1.0/contacts
+
+    >>> body = simplejson.loads(resource())
+    >>> body['total_size']
+    2
+    >>> for link in sorted(
+    ...     [contact['self_link'] for contact in body['entries']]):
+    ...     print link
+    http://api.multiversion.dev/1.0/contacts/Cleo%20Python
+    http://api.multiversion.dev/1.0/contacts/Oliver%20Bluth
+
+We can traverse through the collection to an entry.
+
+    >>> request_10 = create_web_service_request(
+    ...     '/1.0/contacts/Cleo Python')
+    >>> resource = request_10.traverse(None)
+    >>> print absoluteURL(C1, request_10)
+    http://api.multiversion.dev/1.0/contacts/Cleo%20Python
+
+Note that the 'fax' and 'phone' fields are now called 'fax_number' and
+'phone_number'.
+
+    >>> body = simplejson.loads(resource())
+    >>> sorted(body.keys())
+    ['fax_number', 'http_etag', 'name', 'phone_number',
+     'resource_type_link', 'self_link']
+    >>> print body['name']
+    Cleo Python
+
+We can traverse through an entry to one of its fields.
+
+    >>> request_10 = create_web_service_request(
+    ...     '/1.0/contacts/Cleo Python/fax_number')
+    >>> field = request_10.traverse(None)
+    >>> print simplejson.loads(field())
+    111-2121
+
+The fax field in '1.0' is called 'fax_number', and attempting
+to traverse to its 'beta' name ('fax') will fail.
+
+    >>> request_10 = create_web_service_request(
+    ...     '/1.0/contacts/Cleo Python/fax')
+    >>> field = request_10.traverse(None)
+    Traceback (most recent call last):
+    ...
+    NotFound: Object: <Contact object...>, name: u'fax'
+
+We can invoke a named operation. Note that the name of the operation
+is now 'find' (it was 'findContacts' in 'beta').
+
+    >>> request_10 = create_web_service_request(
+    ...     '/1.0/contacts',
+    ...     environ={'QUERY_STRING' : 'ws.op=find&string=Cleo'})
+    >>> operation = request_10.traverse(None)
+    >>> result = simplejson.loads(operation())
+    >>> [contact['name'] for contact in result['entries']]
+    ['Cleo Python']
+
+    >>> request_10 = create_web_service_request(
+    ...     '/1.0/contacts',
+    ...     environ={'QUERY_STRING' : 'ws.op=find&string=111'})
+    >>> operation = request_10.traverse(None)
+    >>> result = simplejson.loads(operation())
+    >>> [contact['fax_number'] for contact in result['entries']]
+    ['111-2121']
+
+Attempting to invoke the operation using its 'beta' name won't work.
+
+    >>> request_10 = create_web_service_request(
+    ...     '/1.0/contacts',
+    ...     environ={'QUERY_STRING' : 'ws.op=findContacts&string=Cleo'})
+    >>> operation = request_10.traverse(None)
+    >>> print operation()
+    No such operation: findContacts
+
+Dev
+---
+
+Here's the service root resource.
+
+    >>> request = create_web_service_request('/dev/')
+    >>> resource = request.traverse(None)
+    >>> body = simplejson.loads(resource())
+    >>> print sorted(body.keys())
+    ['contacts_collection_link', 'resource_type_link']
+
+    >>> print body['contacts_collection_link']
+    http://api.multiversion.dev/dev/contacts
+
+Here's the contact list.
+
+    >>> request_dev = create_web_service_request('/dev/contacts')
+    >>> resource = request_dev.traverse(None)
+    >>> print absoluteURL(contact_set, request_dev)
+    http://api.multiversion.dev/dev/contacts
+
+    >>> body = simplejson.loads(resource())
+    >>> body['total_size']
+    2
+    >>> for link in sorted(
+    ...     [contact['self_link'] for contact in body['entries']]):
+    ...     print link
+    http://api.multiversion.dev/dev/contacts/Cleo%20Python
+    http://api.multiversion.dev/dev/contacts/Oliver%20Bluth
+
+We can traverse through the collection to an entry.
+
+    >>> request_dev = create_web_service_request(
+    ...     '/dev/contacts/Cleo Python')
+    >>> resource = request_dev.traverse(None)
+    >>> print absoluteURL(C1, request_dev)
+    http://api.multiversion.dev/dev/contacts/Cleo%20Python
+
+Note that the published field names have changed between 'dev' and
+'1.0'. The phone field is still 'phone_number', but the 'fax_number'
+field is gone.
+
+    >>> body = simplejson.loads(resource())
+    >>> sorted(body.keys())
+    ['http_etag', 'name', 'phone_number', 'resource_type_link', 'self_link']
+    >>> print body['name']
+    Cleo Python
+
+We can traverse through an entry to one of its fields.
+
+    >>> request_dev = create_web_service_request(
+    ...     '/dev/contacts/Cleo Python/name')
+    >>> field = request_dev.traverse(None)
+    >>> print simplejson.loads(field())
+    Cleo Python
+
+We cannot use 'dev' to traverse to a field not published in the 'dev'
+version.
+
+    >>> request_beta = create_web_service_request(
+    ...     '/dev/contacts/Cleo Python/fax')
+    >>> field = request_beta.traverse(None)
+    Traceback (most recent call last):
+    ...
+    NotFound: Object: <Contact object...>, name: u'fax'
+
+    >>> request_beta = create_web_service_request(
+    ...     '/dev/contacts/Cleo Python/fax_number')
+    >>> field = request_beta.traverse(None)
+    Traceback (most recent call last):
+    ...
+    NotFound: Object: <Contact object...>, name: u'fax_number'
+
+We can invoke a named operation.
+
+    >>> request_dev = create_web_service_request(
+    ...     '/dev/contacts',
+    ...     environ={'QUERY_STRING' : 'ws.op=find&string=Cleo'})
+    >>> operation = request_dev.traverse(None)
+    >>> result = simplejson.loads(operation())
+    >>> [contact['name'] for contact in result['entries']]
+    ['Cleo Python']
+
+Note that a search for Cleo's fax number no longer finds anything,
+because the named operation published as 'find' in the 'dev' web
+service doesn't search the fax field.
+
+    >>> request_dev = create_web_service_request(
+    ...     '/dev/contacts',
+    ...     environ={'QUERY_STRING' : 'ws.op=find&string=111'})
+    >>> operation = request_dev.traverse(None)
+    >>> result = simplejson.loads(operation())
+    >>> result['total_size']
+    0

=== modified file 'src/lazr/restful/docs/utils.txt'
--- src/lazr/restful/docs/utils.txt	2009-08-27 15:50:55 +0000
+++ src/lazr/restful/docs/utils.txt	2010-01-12 15:21:22 +0000
@@ -75,8 +75,33 @@
     >>> print implementation().a_method()
     superclass result
 
-
-=================================
+make_identifier_safe
+====================
+
+LAZR provides a way of converting an arbitrary string into a similar
+string that can be used as a Python identifier.
+
+    >>> from lazr.restful.utils import make_identifier_safe
+    >>> print make_identifier_safe("already_a_valid_IDENTIFIER_444")
+    already_a_valid_IDENTIFIER_444
+
+    >>> print make_identifier_safe("!starts_with_punctuation")
+    _starts_with_punctuation
+
+    >>> print make_identifier_safe("_!contains!pu-nc.tuation")
+    __contains_pu_nc_tuation
+
+    >>> print make_identifier_safe("contains\nnewline")
+    contains_newline
+
+    >>> print make_identifier_safe("")
+    _
+
+    >>> print make_identifier_safe(None)
+    Traceback (most recent call last):
+    ...
+    ValueError: Cannot make None value identifier-safe.
+
 camelcase_to_underscore_separated
 =================================
 
@@ -97,7 +122,6 @@
     >>> camelcase_to_underscore_separated('_StartsWithUnderscore')
     '__starts_with_underscore'
 
-==============
 safe_hasattr()
 ==============
 
@@ -130,7 +154,6 @@
     >>> safe_hasattr(oracle, 'weather')
     False
 
-============
 smartquote()
 ============
 
@@ -155,7 +178,6 @@
     >>> smartquote('a lot of "foo"?')
     u'a lot of \u201cfoo\u201d?'
 
-================
 safe_js_escape()
 ================
 

=== modified file 'src/lazr/restful/docs/webservice-declarations.txt'
--- src/lazr/restful/docs/webservice-declarations.txt	2009-11-16 14:49:53 +0000
+++ src/lazr/restful/docs/webservice-declarations.txt	2010-01-12 15:21:22 +0000
@@ -867,8 +867,50 @@
     ...         self.base_price = base_price
     ...         self.inventory_number = inventory_number
 
+Before we can continue, we must define a web service configuration
+object. Each web service needs to have one of these registered
+utilities providing basic information about the web service. This one
+is just a dummy.
+
+    >>> from zope.component import provideUtility
+    >>> from lazr.restful.interfaces import IWebServiceConfiguration
+    >>> class MyWebServiceConfiguration:
+    ...     implements(IWebServiceConfiguration)
+    ...     view_permission = "lazr.View"
+    ...     active_versions = ["beta"]
+    ...     code_revision = "1.0b"
+    ...     default_batch_size = 50
+    ...     latest_version_uri_prefix = 'beta'
+    ...
+    ...     def get_request_user(self):
+    ...         return 'A user'
+    >>> provideUtility(MyWebServiceConfiguration(), IWebServiceConfiguration)
+
+
+We must also set up the ability to create versioned requests.  We only
+have one version of the web service ('beta'), but lazr.restful
+requires every request to be marked with a version string and to
+implement an appropriate marker interface. Here, we define the marker
+interface for the 'beta' version of the web service.
+
+    >>> from zope.component import getSiteManager
+    >>> from lazr.restful.interfaces import IWebServiceVersion
+    >>> class ITestServiceRequestBeta(IWebServiceVersion):
+    ...     pass
+    >>> sm = getSiteManager()
+    >>> sm.registerUtility(
+    ...     ITestServiceRequestBeta, IWebServiceVersion,
+    ...     name='beta')
+
+    >>> from lazr.restful.testing.webservice import FakeRequest
+    >>> request = FakeRequest()
+
+Now we can turn a Book object into something that implements
+IBookEntry.
+
     >>> entry_adapter = entry_adapter_factory(
-    ...     Book(u'Aldous Huxley', u'Island', 10.0, '12345'))
+    ...     Book(u'Aldous Huxley', u'Island', 10.0, '12345'),
+    ...     request)
 
     >>> entry_adapter.schema is entry_interface
     True
@@ -926,7 +968,7 @@
     ...         return self.books
 
     >>> collection_adapter = collection_adapter_factory(
-    ...     BookSet(['A book', 'Another book']))
+    ...     BookSet(['A book', 'Another book']), request)
 
     >>> verifyObject(ICollection, collection_adapter)
     True
@@ -943,24 +985,6 @@
 find(). The REQUEST_USER marker value will be replaced by the logged in
 user.
 
-To get this to work we must define a web service configuration
-object. Each web service needs to have one of these registered
-utilities providing basic information about the web service. This one
-is just a dummy.
-
-    >>> from zope.component import provideUtility
-    >>> from lazr.restful.interfaces import IWebServiceConfiguration
-    >>> class MyWebServiceConfiguration:
-    ...     implements(IWebServiceConfiguration)
-    ...     view_permission = "lazr.View"
-    ...     active_versions = ["beta"]
-    ...     code_revision = "1.0b"
-    ...     default_batch_size = 50
-    ...
-    ...     def get_request_user(self):
-    ...         return 'A user'
-    >>> provideUtility(MyWebServiceConfiguration(), IWebServiceConfiguration)
-
     >>> class CheckedOutBookSet(object):
     ...     """Simple ICheckedOutBookSet implementation."""
     ...     implements(ICheckedOutBookSet)
@@ -970,7 +994,7 @@
     ...             user, title)
 
     >>> checked_out_adapter = generate_collection_adapter(
-    ...     ICheckedOutBookSet)(CheckedOutBookSet())
+    ...     ICheckedOutBookSet)(CheckedOutBookSet(), request)
 
     >>> checked_out_adapter.find()
     A user searched for checked out book matching "".
@@ -1046,7 +1070,6 @@
 
 Now we can create a fake request that invokes the named operation.
 
-    >>> from lazr.restful.testing.webservice import FakeRequest
     >>> request = FakeRequest()
     >>> read_method_adapter = read_method_adapter_factory(
     ...     BookSetOnSteroids(), request)
@@ -1298,7 +1321,7 @@
     ...     IHasText, hastext_entry_interface)
 
     >>> obj = HasText()
-    >>> hastext_entry_adapter = hastext_entry_adapter_factory(obj)
+    >>> hastext_entry_adapter = hastext_entry_adapter_factory(obj, request)
 
 ...and you'll have an object that invokes set_text() when you set the
 'text' attribute.
@@ -1531,11 +1554,11 @@
 After the registration, adapters from IBook to IEntry, and IBookSet to
 ICollection are available:
 
-    >>> from zope.component import getAdapter
+    >>> from zope.component import getMultiAdapter
     >>> book = Book(u'George Orwell', u'1984', 10.0, u'12345-1984')
     >>> bookset = BookSet([book])
 
-    >>> entry_adapter = getAdapter(book, IEntry)
+    >>> entry_adapter = getMultiAdapter((book, request), IEntry)
     >>> verifyObject(IEntry, entry_adapter)
     True
 
@@ -1544,7 +1567,7 @@
     >>> verifyObject(entry_adapter.schema, entry_adapter)
     True
 
-    >>> collection_adapter = getAdapter(bookset, ICollection)
+    >>> collection_adapter = getMultiAdapter((bookset, request), ICollection)
     >>> verifyObject(ICollection, collection_adapter)
     True
 

=== modified file 'src/lazr/restful/docs/webservice-error.txt'
--- src/lazr/restful/docs/webservice-error.txt	2009-08-04 19:27:13 +0000
+++ src/lazr/restful/docs/webservice-error.txt	2010-01-12 15:21:22 +0000
@@ -15,6 +15,7 @@
     >>> class SimpleWebServiceConfiguration:
     ...     implements(IWebServiceConfiguration)
     ...     show_tracebacks = False
+    ...     latest_version_uri_prefix = 'trunk'
     >>> webservice_configuration = SimpleWebServiceConfiguration()
     >>> getSiteManager().registerUtility(webservice_configuration)
 

=== modified file 'src/lazr/restful/docs/webservice.txt'
--- src/lazr/restful/docs/webservice.txt	2009-11-19 16:28:38 +0000
+++ src/lazr/restful/docs/webservice.txt	2010-01-12 15:21:22 +0000
@@ -114,23 +114,14 @@
 
     >>> from urllib import quote
     >>> from zope.component import (
-    ...     adapts, adapter, getSiteManager, getMultiAdapter)
-    >>> from zope.interface import implements, implementer, Interface
+    ...     adapts, getSiteManager, getMultiAdapter)
+    >>> from zope.interface import implements
     >>> from zope.publisher.interfaces import IPublishTraverse, NotFound
     >>> from zope.publisher.interfaces.browser import IBrowserRequest
     >>> from zope.security.checker import CheckerPublic
     >>> from zope.traversing.browser.interfaces import IAbsoluteURL
     >>> from lazr.restful.security import protect_schema
 
-    >>> from zope.component.interfaces import IComponentLookup
-    >>> sm = getSiteManager()
-
-    >>> @implementer(IComponentLookup)
-    ... @adapter(Interface)
-    ... def everything_uses_the_global_site_manager(context):
-    ...     return sm
-    >>> sm.registerAdapter(everything_uses_the_global_site_manager)
-
     >>> class BaseAbsoluteURL:
     ...     """A basic, extensible implementation of IAbsoluteURL."""
     ...     implements(IAbsoluteURL)
@@ -143,6 +134,8 @@
     ...         return "http://api.cookbooks.dev/beta/" + self.context.path
     ...
     ...     __call__ = __str__
+
+    >>> sm = getSiteManager()
     >>> sm.registerAdapter(
     ...     BaseAbsoluteURL, [ITestDataObject, IBrowserRequest],
     ...     IAbsoluteURL)
@@ -520,6 +513,26 @@
     >>> from zope.component import getUtility
     >>> webservice_configuration = getUtility(IWebServiceConfiguration)
 
+We also need to define a marker interface for each version of the web
+service, so that incoming requests can be marked with the appropriate
+version string. The configuration above defines two versions, 'beta'
+and 'devel'.
+
+    >>> from lazr.restful.interfaces import IWebServiceClientRequest
+    >>> class IWebServiceRequestBeta(IWebServiceClientRequest):
+    ...     pass
+
+    >>> class IWebServiceRequestDevel(IWebServiceClientRequest):
+    ...     pass
+
+    >>> versions = ((IWebServiceRequestBeta, 'beta'),
+    ...             (IWebServiceRequestDevel, 'devel'))
+
+    >>> from lazr.restful import register_versioned_request_utility
+    >>> for cls, version in versions:
+    ...     register_versioned_request_utility(cls, version)
+
+
 ======================
 Defining the resources
 ======================
@@ -625,6 +638,7 @@
     >>> from zope.interface.verify import verifyObject
     >>> from lazr.delegates import delegates
     >>> from lazr.restful import Entry
+    >>> from lazr.restful.testing.webservice import FakeRequest
 
     >>> class AuthorEntry(Entry):
     ...     """An author, as exposed through the web service."""
@@ -632,7 +646,8 @@
     ...     delegates(IAuthorEntry)
     ...     schema = IAuthorEntry
 
-    >>> verifyObject(IAuthorEntry, AuthorEntry(A1))
+    >>> request = FakeRequest()
+    >>> verifyObject(IAuthorEntry, AuthorEntry(A1, request))
     True
 
 The ``schema`` attribute points to the interface class that defines the
@@ -643,18 +658,17 @@
 the interface defined in the schema attribute. This is usually not a problem,
 since the schema is usually the interface itself.
 
-    >>> IAuthorEntry.validateInvariants(AuthorEntry(A1))
+    >>> IAuthorEntry.validateInvariants(AuthorEntry(A1, request))
 
 But the invariant will complain if that isn't true.
 
     >>> class InvalidAuthorEntry(Entry):
-    ...     adapts(IAuthor)
     ...     delegates(IAuthorEntry)
     ...     schema = ICookbookEntry
 
-    >>> verifyObject(IAuthorEntry, InvalidAuthorEntry(A1))
+    >>> verifyObject(IAuthorEntry, InvalidAuthorEntry(A1, request))
     True
-    >>> IAuthorEntry.validateInvariants(InvalidAuthorEntry(A1))
+    >>> IAuthorEntry.validateInvariants(InvalidAuthorEntry(A1, request))
     Traceback (most recent call last):
       ...
     Invalid: InvalidAuthorEntry doesn't provide its ICookbookEntry schema.
@@ -663,40 +677,43 @@
 
     >>> class CookbookEntry(Entry):
     ...     """A cookbook, as exposed through the web service."""
-    ...     adapts(ICookbook)
     ...     delegates(ICookbookEntry)
     ...     schema = ICookbookEntry
 
     >>> class DishEntry(Entry):
     ...     """A dish, as exposed through the web service."""
-    ...     adapts(IDish)
     ...     delegates(IDishEntry)
     ...     schema = IDishEntry
 
     >>> class CommentEntry(Entry):
     ...     """A comment, as exposed through the web service."""
-    ...     adapts(IComment)
     ...     delegates(ICommentEntry)
     ...     schema = ICommentEntry
 
     >>> class RecipeEntry(Entry):
-    ...     adapts(IRecipe)
     ...     delegates(IRecipeEntry)
     ...     schema = IRecipeEntry
 
-We need to register these entries as an adapter from (e.g.) ``IAuthor`` to
-(e.g.) ``IAuthorEntry``. In ZCML a registration would look like this.
+We need to register these entries as a multiadapter adapter from
+(e.g.) ``IAuthor`` and ``IWebServiceClientRequest`` to (e.g.)
+``IAuthorEntry``. In ZCML a registration would look like this.
 
-    <adapter factory="my.app.rest.AuthorEntry" />
+    <adapter for="my.app.rest.IAuthor
+                  lazr.restful.interfaces.IWebServiceClientRequest"
+             factory="my.app.rest.AuthorEntry" />
 
 Since we're in the middle of a Python example we can do the equivalent
-in Python code:
+in Python code for each entry class:
 
-    >>> sm.registerAdapter(AuthorEntry, provided=IAuthorEntry)
-    >>> sm.registerAdapter(CookbookEntry, provided=ICookbookEntry)
-    >>> sm.registerAdapter(DishEntry, provided=IDishEntry)
-    >>> sm.registerAdapter(CommentEntry, provided=ICommentEntry)
-    >>> sm.registerAdapter(RecipeEntry, provided=IRecipeEntry)
+    >>> for entry_class, adapts_interface, provided_interface in [
+    ...     [AuthorEntry, IAuthor, IAuthorEntry],
+    ...     [CookbookEntry, ICookbook, ICookbookEntry],
+    ...     [DishEntry, IDish, IDishEntry],
+    ...     [CommentEntry, IComment, ICommentEntry],
+    ...     [RecipeEntry, IRecipe, IRecipeEntry]]:
+    ...         sm.registerAdapter(
+    ...             entry_class, [adapts_interface, IWebServiceClientRequest],
+    ...             provided=provided_interface)
 
 lazr.restful also defines an interface and a base class for collections of
 objects. I'll use it to expose the ``AuthorSet`` collection and other
@@ -708,7 +725,6 @@
 
     >>> class AuthorCollection(Collection):
     ...     """A collection of authors, as exposed through the web service."""
-    ...     adapts(IAuthorSet)
     ...
     ...     entry_schema = IAuthorEntry
     ...
@@ -716,9 +732,11 @@
     ...        """Find all the authors."""
     ...        return self.context.getAllAuthors()
 
-    >>> sm.registerAdapter(AuthorCollection)
+    >>> sm.registerAdapter(AuthorCollection,
+    ...                   (IAuthorSet, IWebServiceClientRequest),
+    ...                   provided=ICollection)
 
-    >>> verifyObject(ICollection, AuthorCollection(AuthorSet()))
+    >>> verifyObject(ICollection, AuthorCollection(AuthorSet(), request))
     True
 
     >>> class CookbookCollection(Collection):
@@ -731,7 +749,9 @@
     ...     def find(self):
     ...        """Find all the cookbooks."""
     ...        return self.context.getAll()
-    >>> sm.registerAdapter(CookbookCollection)
+    >>> sm.registerAdapter(CookbookCollection,
+    ...                   (ICookbookSet, IWebServiceClientRequest),
+    ...                   provided=ICollection)
 
     >>> class DishCollection(Collection):
     ...     """A collection of dishes, as exposed through the web service."""
@@ -742,7 +762,10 @@
     ...     def find(self):
     ...        """Find all the dishes."""
     ...        return self.context.getAll()
-    >>> sm.registerAdapter(DishCollection)
+
+    >>> sm.registerAdapter(DishCollection,
+    ...                   (IDishSet, IWebServiceClientRequest),
+    ...                   provided=ICollection)
 
 Like ``Entry``, ``Collection`` is a simple base class that defines a
 constructor. The ``entry_schema`` attribute gives a ``Collection`` class
@@ -762,8 +785,9 @@
 
     >>> def scope_collection(parent, child, name):
     ...     """A helper method that simulates a scoped collection lookup."""
-    ...     parent_entry = IEntry(parent)
-    ...     scoped = getMultiAdapter((parent_entry, IEntry(child)),
+    ...     parent_entry = getMultiAdapter((parent, request), IEntry)
+    ...     child_entry = getMultiAdapter((child, request), IEntry)
+    ...     scoped = getMultiAdapter((parent_entry, child_entry, request),
     ...                               IScopedCollection)
     ...     scoped.relationship = parent_entry.schema.get(name)
     ...     return scoped

=== modified file 'src/lazr/restful/example/base/root.py'
--- src/lazr/restful/example/base/root.py	2009-11-12 19:08:10 +0000
+++ src/lazr/restful/example/base/root.py	2010-01-12 15:21:22 +0000
@@ -16,12 +16,11 @@
 
 from zope.interface import implements
 from zope.location.interfaces import ILocation
-from zope.component import adapts, getUtility
+from zope.component import adapts, getMultiAdapter, getUtility
 from zope.schema.interfaces import IBytes
 
-from lazr.restful import ServiceRootResource
+from lazr.restful import directives, ServiceRootResource
 
-from lazr.restful import directives
 from lazr.restful.interfaces import (
     IByteStorage, IEntry, IServiceRootResource, ITopLevelEntryLink,
     IWebServiceConfiguration)
@@ -30,6 +29,7 @@
     IFileManager, IRecipe, IRecipeSet, IHasGet, NameAlreadyTaken)
 from lazr.restful.simple import BaseWebServiceConfiguration
 from lazr.restful.testing.webservice import WebServiceTestPublication
+from lazr.restful.utils import get_current_browser_request
 
 
 #Entry classes.
@@ -148,7 +148,8 @@
         self.recipes.remove(recipe)
 
     def replace_cover(self, cover):
-        storage = SimpleByteStorage(IEntry(self), ICookbook['cover'])
+        entry = getMultiAdapter((self, get_current_browser_request()), IEntry)
+        storage = SimpleByteStorage(entry, ICookbook['cover'])
         storage.createStored('application/octet-stream', cover, 'cover')
 
 

=== modified file 'src/lazr/restful/interfaces/_rest.py'
--- src/lazr/restful/interfaces/_rest.py	2009-11-18 17:33:20 +0000
+++ src/lazr/restful/interfaces/_rest.py	2010-01-12 15:21:22 +0000
@@ -49,6 +49,7 @@
     'LAZR_WEBSERVICE_NS',
     'IWebServiceClientRequest',
     'IWebServiceLayer',
+    'IWebServiceVersion',
     ]
 
 from zope.schema import Bool, Int, List, TextLine
@@ -251,13 +252,27 @@
 
 
 class IWebServiceClientRequest(IBrowserRequest):
-    """Marker interface requests to the web service."""
+    """Interface for requests to the web service."""
+    version = Attribute("The version of the web service that the client "
+                        "requested.")
 
 
 class IWebServiceLayer(IWebServiceClientRequest, IDefaultBrowserLayer):
     """Marker interface for registering views on the web service."""
 
 
+class IWebServiceVersion(Interface):
+    """Used to register IWebServiceClientRequest subclasses as utilities.
+
+    Every version of a web service must register a subclass of
+    IWebServiceClientRequest as an IWebServiceVersion utility, with a
+    name that's the web service version name. For instance:
+
+    registerUtility(IWebServiceClientRequestBeta,
+                    IWebServiceVersion, name="beta")
+    """
+    pass
+
 class IJSONRequestCache(Interface):
     """A cache of objects exposed as URLs or JSON representations."""
 

=== modified file 'src/lazr/restful/metazcml.py'
--- src/lazr/restful/metazcml.py	2009-04-16 20:45:55 +0000
+++ src/lazr/restful/metazcml.py	2010-01-12 15:21:22 +0000
@@ -82,8 +82,14 @@
         context.action(
             discriminator=('adapter', interface, provides, ''),
             callable=handler,
+            # XXX leonardr bug=503948 Register the adapter against a
+            # generic IWebServiceClientRequest.  It will be picked up
+            # for all versions of the web service. Later on, this will
+            # be changed to register different adapters for different
+            # versions.
             args=('registerAdapter',
-                  factory, (interface, ), provides, '', context.info),
+                  factory, (interface, IWebServiceClientRequest),
+                            provides, '', context.info),
             )
         register_webservice_operations(context, interface)
 

=== modified file 'src/lazr/restful/publisher.py'
--- src/lazr/restful/publisher.py	2009-11-19 15:53:26 +0000
+++ src/lazr/restful/publisher.py	2010-01-12 15:21:22 +0000
@@ -35,7 +35,7 @@
 from lazr.restful.interfaces import (
     IByteStorage, ICollection, ICollectionField, IEntry, IEntryField,
     IHTTPResource, IServiceRootResource, IWebBrowserInitiatedRequest,
-    IWebServiceClientRequest, IWebServiceConfiguration)
+    IWebServiceClientRequest, IWebServiceConfiguration, IWebServiceVersion)
 
 
 class WebServicePublicationMixin:
@@ -57,8 +57,10 @@
         # handle traversing to the scoped collection itself.
         if len(request.getTraversalStack()) == 0:
             try:
-                entry = IEntry(ob)
-            except TypeError:
+                entry = getMultiAdapter((ob, request), IEntry)
+            except ComponentLookupError:
+                # This doesn't look like a lazr.restful object. Let
+                # the superclass handle traversal.
                 pass
             else:
                 if name.endswith("_link"):
@@ -111,7 +113,7 @@
         collection = getattr(entry, name, None)
         if collection is None:
             return None
-        scoped_collection = ScopedCollection(entry.context, entry)
+        scoped_collection = ScopedCollection(entry.context, entry, request)
         # Tell the IScopedCollection object what collection it's managing,
         # and what the collection's relationship is to the entry it's
         # scoped to.
@@ -138,11 +140,11 @@
         appropriate resource.
         """
         if (ICollection.providedBy(ob) or
-            queryAdapter(ob, ICollection) is not None):
+            queryMultiAdapter((ob, request), ICollection) is not None):
             # Object supports ICollection protocol.
             resource = CollectionResource(ob, request)
         elif (IEntry.providedBy(ob) or
-              queryAdapter(ob, IEntry) is not None):
+              queryMultiAdapter((ob, request), IEntry) is not None):
             # Object supports IEntry protocol.
             resource = EntryResource(ob, request)
         elif (IEntryField.providedBy(ob) or
@@ -255,11 +257,17 @@
             raise NotFound(self, '', self)
         self.annotations[self.VERSION_ANNOTATION] = version
 
+        # Find the version-specific interface this request should
+        # provide, and provide it.
+        to_provide = getUtility(IWebServiceVersion, name=version)
+        alsoProvides(self, to_provide)
+        self.version = version
+
         # Find the appropriate service root for this version and set
         # the publication's application appropriately.
         try:
             # First, try to find a version-specific service root.
-            service_root = getUtility(IServiceRootResource, name=version)
+            service_root = getUtility(IServiceRootResource, name=self.version)
         except ComponentLookupError:
             # Next, try a version-independent service root.
             service_root = getUtility(IServiceRootResource)

=== modified file 'src/lazr/restful/simple.py'
--- src/lazr/restful/simple.py	2009-11-12 17:03:06 +0000
+++ src/lazr/restful/simple.py	2010-01-12 15:21:22 +0000
@@ -22,7 +22,9 @@
 from zope.publisher.browser import BrowserRequest
 from zope.publisher.interfaces import IPublication, IPublishTraverse, NotFound
 from zope.publisher.publish import mapply
+from zope.proxy import sameProxiedObjects
 from zope.security.management import endInteraction, newInteraction
+from zope.traversing.browser import AbsoluteURL as ZopeAbsoluteURL
 from zope.traversing.browser.interfaces import IAbsoluteURL
 from zope.traversing.browser.absoluteurl import _insufficientContext, _safe
 
@@ -188,7 +190,8 @@
         # First collect the top-level collections.
         for name, (schema_interface, obj) in (
             self.top_level_collections.items()):
-            adapter = EntryAdapterUtility.forSchemaInterface(schema_interface)
+            adapter = EntryAdapterUtility.forSchemaInterface(
+                schema_interface, self.request)
             link_name = ("%s_collection_link" % adapter.plural_type)
             top_level_resources[link_name] = obj
         # Then collect the top-level entries.

=== modified file 'src/lazr/restful/tales.py'
--- src/lazr/restful/tales.py	2009-05-04 19:11:00 +0000
+++ src/lazr/restful/tales.py	2010-01-12 15:21:22 +0000
@@ -13,7 +13,8 @@
 from epydoc.markup import DocstringLinker
 from epydoc.markup.restructuredtext import parse_docstring
 
-from zope.component import adapts, queryAdapter, getGlobalSiteManager
+from zope.component import (
+    adapts, getGlobalSiteManager, getUtility, queryMultiAdapter)
 from zope.interface import implements
 from zope.interface.interfaces import IInterface
 from zope.schema import getFieldsInOrder
@@ -31,7 +32,8 @@
     ICollection, ICollectionField, IEntry, IJSONRequestCache,
     IReferenceChoice, IResourceDELETEOperation, IResourceGETOperation,
     IResourceOperation, IResourcePOSTOperation, IScopedCollection,
-    ITopLevelEntryLink, IWebServiceClientRequest, LAZR_WEBSERVICE_NAME)
+    ITopLevelEntryLink, IWebServiceClientRequest, IWebServiceVersion,
+    LAZR_WEBSERVICE_NAME)
 from lazr.restful.utils import get_current_browser_request
 
 
@@ -108,13 +110,14 @@
     @property
     def is_entry(self):
         """Whether the object is published as an entry."""
-        return queryAdapter(self.context, IEntry) != None
+        return queryMultiAdapter(
+            (self.context, get_current_browser_request()), IEntry) != None
 
     @property
     def json(self):
         """Return a JSON description of the object."""
         request = IWebServiceClientRequest(get_current_browser_request())
-        if queryAdapter(self.context, IEntry):
+        if queryMultiAdapter((self.context, request), IEntry):
             resource = EntryResource(self.context, request)
         else:
             # Just dump it as JSON.
@@ -283,9 +286,11 @@
         # adapting.
         model_class = self._model_class
         operations = []
+        request_interface = getUtility(
+            IWebServiceVersion, get_current_browser_request().version)
         for interface in (IResourceGETOperation, IResourcePOSTOperation):
             operations.extend(getGlobalSiteManager().adapters.lookupAll(
-                    (model_class, IWebServiceClientRequest), interface))
+                    (model_class, request_interface), interface))
         return [{'name' : name, 'op' : op} for name, op in operations]
 
 
@@ -297,7 +302,8 @@
     def __init__(self, entry_interface):
         super(WadlEntryInterfaceAdapterAPI, self).__init__(
             entry_interface, IEntry)
-        self.utility = EntryAdapterUtility.forEntryInterface(entry_interface)
+        self.utility = EntryAdapterUtility.forEntryInterface(
+            entry_interface, get_current_browser_request())
 
     @property
     def entry_page_representation_link(self):
@@ -370,8 +376,10 @@
     @property
     def supports_delete(self):
         """Return true if this entry responds to DELETE."""
+        request_interface = getUtility(
+            IWebServiceVersion, get_current_browser_request().version)
         operations = getGlobalSiteManager().adapters.lookupAll(
-            (self._model_class, IWebServiceClientRequest),
+            (self._model_class, request_interface),
             IResourceDELETEOperation)
         return len(operations) > 0
 
@@ -506,7 +514,8 @@
             raise TypeError("Field is not of a supported type.")
         assert schema is not IObject, (
             "Null schema provided for %s" % self.field.__name__)
-        return EntryAdapterUtility.forSchemaInterface(schema)
+        return EntryAdapterUtility.forSchemaInterface(
+            schema, get_current_browser_request())
 
 
     @property
@@ -530,7 +539,8 @@
 
     def type_link(self):
         return EntryAdapterUtility.forSchemaInterface(
-            self.entry_link.entry_type).type_link
+            self.entry_link.entry_type,
+            get_current_browser_request()).type_link
 
 
 class WadlOperationAPI(RESTUtilityBase):

=== modified file 'src/lazr/restful/testing/webservice.py'
--- src/lazr/restful/testing/webservice.py	2009-11-19 16:28:38 +0000
+++ src/lazr/restful/testing/webservice.py	2010-01-12 15:21:22 +0000
@@ -104,7 +104,11 @@
     # get_current_browser_request()
     implements(IHTTPApplicationRequest, IWebServiceLayer)
 
-    def __init__(self, traversed=None, stack=None):
+    def __init__(self, traversed=None, stack=None, version=None):
+        if version is None:
+            config = getUtility(IWebServiceConfiguration)
+            version = config.latest_version_uri_prefix
+        self.version = version
         self._traversed_names = traversed
         self._stack = stack
         self.response = FakeResponse()

=== modified file 'src/lazr/restful/tests/test_navigation.py'
--- src/lazr/restful/tests/test_navigation.py	2009-07-27 02:27:38 +0000
+++ src/lazr/restful/tests/test_navigation.py	2010-01-12 15:21:22 +0000
@@ -6,80 +6,101 @@
 
 import unittest
 
+from zope.component import getSiteManager
 from zope.interface import Interface, implements
 from zope.publisher.interfaces import NotFound
 from zope.schema import Text, Object
+from zope.testing.cleanup import cleanUp
 
-from lazr.restful.interfaces import IEntry
-from lazr.restful.publisher import WebServicePublicationMixin
+from lazr.restful.interfaces import IEntry, IWebServiceClientRequest
+from lazr.restful.simple import Publication
+from lazr.restful.testing.webservice import FakeRequest
 
 
 class IChild(Interface):
+    """Interface for a simple entry."""
     one = Text(title=u'One')
     two = Text(title=u'Two')
 
 
-class IChildEntry(IChild, IEntry):
-    pass
-
-
 class IParent(Interface):
+    """Interface for a simple entry that contains another entry."""
     three = Text(title=u'Three')
     child = Object(schema=IChild)
 
 
-class IParentEntry(IParent, IEntry):
-    pass
-
-
 class Child:
-    implements(IChildEntry)
-    schema = IChild
-
+    """A simple implementation of IChild."""
+    implements(IChild)
     one = u'one'
     two = u'two'
 
 
+class ChildEntry:
+    """Implementation of an entry wrapping a Child."""
+    schema = IChild
+    def __init__(self, context, request):
+        self.context = context
+
+
 class Parent:
-    implements(IParentEntry)
-    schema = IParent
-
+    """A simple implementation of IParent."""
+    implements(IParent)
     three = u'three'
     child = Child()
 
+
+class ParentEntry:
+    """Implementation of an entry wrapping a Parent, containing a Child."""
+    schema = IParent
+
+    def __init__(self, context, request):
+        self.context = context
+
     @property
-    def context(self):
-        return self
-
-
-class FakeRequest:
+    def child(self):
+        return self.context.child
+
+
+class FakeRequestWithEmptyTraversalStack(FakeRequest):
     """A fake request satisfying `traverseName()`."""
 
     def getTraversalStack(self):
         return ()
 
 
-class NavigationPublication(WebServicePublicationMixin):
-    pass
-
-
 class NavigationTestCase(unittest.TestCase):
 
+    def setUp(self):
+        # Register ChildEntry as the IEntry implementation for IChild.
+        sm = getSiteManager()
+        sm.registerAdapter(
+            ChildEntry, [IChild, IWebServiceClientRequest], provided=IEntry)
+
+        # Register ParentEntry as the IEntry implementation for IParent.
+        sm.registerAdapter(
+            ParentEntry, [IParent, IWebServiceClientRequest], provided=IEntry)
+
+    def tearDown(self):
+        cleanUp()
+
     def test_toplevel_navigation(self):
         # Test that publication can reach sub-entries.
-        publication = NavigationPublication()
-        obj = publication.traverseName(FakeRequest(), Parent(), 'child')
+        publication = Publication(None)
+        request = FakeRequestWithEmptyTraversalStack(version='trunk')
+        obj = publication.traverseName(request, Parent(), 'child')
         self.assertEqual(obj.one, 'one')
 
     def test_toplevel_navigation_without_subentry(self):
         # Test that publication raises NotFound when subentry attribute
         # returns None.
+        request = FakeRequestWithEmptyTraversalStack(version='trunk')
         parent = Parent()
         parent.child = None
-        publication = NavigationPublication()
+        publication = Publication(None)
         self.assertRaises(
             NotFound, publication.traverseName,
-            FakeRequest(), parent, 'child')
+            request, parent, 'child')
 
 
 def additional_tests():

=== modified file 'src/lazr/restful/tests/test_webservice.py'
--- src/lazr/restful/tests/test_webservice.py	2009-08-11 18:36:20 +0000
+++ src/lazr/restful/tests/test_webservice.py	2010-01-12 15:21:22 +0000
@@ -9,22 +9,26 @@
 from types import ModuleType
 import unittest
 
-from zope.component import getGlobalSiteManager
+from zope.component import getGlobalSiteManager, getUtility
 from zope.configuration import xmlconfig
-from zope.interface import implements, Interface
+from zope.interface import alsoProvides, implements, Interface
 from zope.schema import Date, Datetime, TextLine
 from zope.testing.cleanup import CleanUp
 
 from lazr.restful.fields import Reference
 from lazr.restful.interfaces import (
     ICollection, IEntry, IEntryResource, IResourceGETOperation,
-    IWebServiceClientRequest)
+    IWebServiceClientRequest, IWebServiceVersion)
 from lazr.restful import EntryResource, ServiceRootResource, ResourceGETOperation
-from lazr.restful.simple import Request
+from lazr.restful.simple import BaseWebServiceConfiguration, Request
 from lazr.restful.declarations import (
     collection_default_content, exported, export_as_webservice_collection,
     export_as_webservice_entry, export_read_operation, operation_parameters)
+from lazr.restful.interfaces import IWebServiceConfiguration
+from lazr.restful.testing.webservice import (
+    create_web_service_request, WebServiceTestPublication)
 from lazr.restful.testing.tales import test_tales
+from lazr.restful.utils import get_current_browser_request
 
 
 def get_resource_factory(model_interface, resource_interface):
@@ -36,8 +40,9 @@
         `IEntry` or `ICollection`.
     :return: the resource factory (the autogenerated adapter class.
     """
-    return getGlobalSiteManager().adapters.lookup1(
-        model_interface, resource_interface)
+    request_interface = getUtility(IWebServiceVersion, name='trunk')
+    return getGlobalSiteManager().adapters.lookup(
+        (model_interface, request_interface), resource_interface)
 
 
 def get_operation_factory(model_interface, name):
@@ -87,6 +92,23 @@
         """Returns all the entries."""
 
 
+class SimpleWebServiceConfiguration(BaseWebServiceConfiguration):
+     implements(IWebServiceConfiguration)
+     show_tracebacks = False
+     latest_version_uri_prefix = 'trunk'
+     hostname = "webservice_test"
+
+     def createRequest(self, body_instream, environ):
+         request = Request(body_instream, environ)
+         request.setPublication(WebServiceTestPublication(None))
+         request.version = 'trunk'
+         return request
+
+
+class IWebServiceRequestTrunk(IWebServiceClientRequest):
+    """A marker interface for requests to the 'trunk' web service."""
+
+
 class WebServiceTestCase(CleanUp, unittest.TestCase):
     """A test case for web service operations."""
 
@@ -96,6 +118,17 @@
         """Set the component registry with the given model."""
         super(WebServiceTestCase, self).setUp()
 
+        # Register a simple configuration object.
+        webservice_configuration = SimpleWebServiceConfiguration()
+        sm = getGlobalSiteManager()
+        sm.registerUtility(webservice_configuration)
+
+        # Register an IWebServiceVersion for the
+        # 'trunk' web service version.
+        alsoProvides(IWebServiceRequestTrunk, IWebServiceVersion)
+        sm.registerUtility(
+            IWebServiceRequestTrunk, IWebServiceVersion, name='trunk')
+
         # Build a test module that exposes the given resource interfaces.
         testmodule = ModuleType('testmodule')
         for interface in self.testmodule_objects:
@@ -195,8 +228,8 @@
         entry_class = get_resource_factory(IHasRestrictedField, IEntry)
         request = Request(StringIO(""), {})
 
-        entry = entry_class(HasRestrictedField(""))
-        resource = EntryResource(entry, request)
+        entry = entry_class(HasRestrictedField(""), request)
+        resource = EntryResource(HasRestrictedField(""), request)
 
         entry.schema['a_field'].restrict_to_interface = IHasRestrictedField
         resource.applyChanges({'a_field': 'a_value'})
@@ -308,6 +341,7 @@
         This will fail due to a name conflict.
         """
         resource = ServiceRootResource()
+        request = create_web_service_request('/')
         try:
             resource.toWADL()
             self.fail('Expected toWADL to fail with an AssertionError')

=== modified file 'src/lazr/restful/utils.py'
--- src/lazr/restful/utils.py	2009-10-12 20:47:21 +0000
+++ src/lazr/restful/utils.py	2010-01-12 15:21:22 +0000
@@ -7,6 +7,7 @@
     'camelcase_to_underscore_separated',
     'get_current_browser_request',
     'implement_from_dict',
+    'make_identifier_safe',
     'safe_js_escape',
     'safe_hasattr',
     'smartquote',
@@ -16,6 +17,7 @@
 
 import cgi
 import re
+import string
 import subprocess
 
 from simplejson import encoder
@@ -51,6 +53,21 @@
     return new_class
 
 
+def make_identifier_safe(name):
+    """Change a string so it can be used as a Python identifier.
+
+    Changes all characters other than letters, numbers, and underscore
+    into underscore. If the first character is not a letter or
+    underscore, prepends an underscore.
+    """
+    if name is None:
+        raise ValueError("Cannot make None value identifier-safe.")
+    name = re.sub("[^A-Za-z0-9_]", "_", name)
+    if len(name) == 0 or name[0] not in string.letters and name[0] != '_':
+        name = '_' + name
+    return name
+
+
 def camelcase_to_underscore_separated(name):
     """Convert 'ACamelCaseString' to 'a_camel_case_string'"""
     def prepend_underscore(match):