[Zope3-dev] Adapters & Interface Implementations (was Re: [Zope-dev] Cool stuff!)

[Phillip J. Eby]

At 01:54 PM 12/5/01 -0500, Ken Manheimer wrote:
>FWIW, something registered on me last week that made "feature" more
>palatable.  This may be obvious to everyone else, but i hadn't put
>together how "new application functionality" is also stated as "new
>feature" - along the lines of, for example: "linux ext3 filesystem
>features a journalling capability".
>
>In this vein, zope3 "feature" components graft new abilities - new
>features - onto existing components.  So i see "feature" as being a good
>word to describe their _effect_.

I agree that from that perspective, it makes sense -- but only if you are 
okay with creating a new term that has to be explicitly learned in order to 
work with Zope.  See below...


>"Adapter" makes more sense to me for describing _how_ the things do what
>they do (provided we disregard the conventional patterns usages).

So how about calling them FeatureAdapters?  :)

Seriously, though, I find that the term "implementation of an interface" 
best describes what these things *are*.  I would be comfortable with making 
the API have a call like: "getImplementation(object, interface, default)", 
because that is, after all, what you *want*.  An implementation of the 
desired interface, for that object.  You don't care if the implementation 
is the original object, an Adapter, a Facade, a Proxy, or god knows what 
else.  You just want an interface implementation.  From my POV, 
"getFeature" is poor naming because it is all about *how*, not *what*.  It 
makes me need to know what a "feature" is in this context -- a 
Zope-specific term added to my learning curve -- where getImplementation() 
does not.

As for "Adapter" being the wrong GoF patterns term, I'm pretty sure it's 
not.  I've got the "Design Patterns" book open to "Adapter" right now, and 
the Applicability section says:


"Use the adapter pattern when:

* you want to use an existing class, and its interface does not match the 
one you need.

* you want to create a reusable class that cooperates with unrelated or 
unforeseen classes, that is, classes that don't necessarily have compatible 
interfaces.

* (object adapter only) you need to use several existing subclasses, but 
it's impractical to adapt their interface by subclassing every one.  An 
object adapter can adapt the interface of its parent class."


All of these motivations seem directly applicable here.  Also, an excerpt 
from the "Consequences" section of the pattern (emphasis on last part added):

"Adapters vary in the amount of work they do to adapt Adaptee to the Target 
interface.  There is a spectrum of possible work, from simple interface 
conversion -- for example, changing the names of operations -- *to 
supporting an entirely different set of operations*."

So I don't see where calling these things adapters conflicts with the GoF 
patterns usage at all.

What I propose, then, is that the documentation (and API naming) focus on 
getting an implementation of an interface, and that the term for an adapted 
interface be "adapter".  So a description of 
getImplementation(object,interface,default) might read:

"Get an implementation of Interface 'interface' for 'object'.  If 'object' 
supports 'interface' directly, 'object' is returned.  Otherwise, creates 
and returns an adapter object that implements 'interface' for 'object', if 
an appropriate adapter type can be found.  If no such adapter type can be 
found, returns 'default'.  Adapter types are found by blah blah... placeful 
lookups blah blah... registry etc...."

This description eliminates the need for a term that requires specific 
contextual definition.  A "typical programmer" can read the above paragraph 
and understand what's going on right away, especially if they have 
encountered the ideas in other systems.  I can't see anyone reasonably 
objecting to the use of "adapter" either, particularly since it is used as 
a descriptive term here rather than as a proper noun (i.e. "adapter", not 
"Adapter").  IMHO, we should avoid having special Zope-defined proper nouns 
whenever a simple descriptive term will suffice.

Also, notice the distinction the paragraph makes between "adapter object" 
and "adapter type" - something which is not entirely clear in the "feature" 
terminology currently.  It is important, I think, to keep the two 
straight.  Right now, one makes a "feature" by creating a class, but 
getFeature() returns an instance, not a class!  So what does the proper 
noun "Feature" mean?  An instance, or a class?  In the terminology above, 
one registers an adapter type, and getImplementation() returns an instance 
of that type.  While some of us would just "know" this without having to be 
told in this way, it would be best to flatten the learning curve wherever 
we can.