#5: Componentize Reference Engine

Contents
  1. Definitions
  2. Motivation
  3. Assumptions
  4. Proposal
  5. Implementation
  6. Deliverables
  7. Risks
  8. Progress log
  9. Participants
by Jens W. Klein — last modified Jun 16, 2006 06:15 AM

Reference engine one important part of Archetypes. Make it independent to re-use it in other context. Make it Zope3ish.

Proposed by
Jens Klein
Seconded by
Whit Morriss
Proposal type
Architecture
Repository branch
components
State
in-progress

Definitions

Reference Engine
is all code that deals with a references - an directed association - from one object to another. This includes catalogs for lookup, current mixin code, etc.

Motivation

We all are loving and hating the current Reference Engine. Its very powerful but otoh also very fragile. Only a few people are able to maintain its code and are knowing what a change will imply. And last but not least it's driving me nuts debugging it.

Also current Reference Engine is integrated in depth of Archteypes, it isnt extensible or pluggable and also not reusable. Also current Zope/CMF/Plone/Archetypes doesnt have any event-systems - one reason why the current Reference Engine is so difficult to handle.

Assumptions

Providing and generating UUID's for generation and should be handled by an own component outside ReferenceEngine, since UID's are needed for behavior outside Reference Engine.

Proposal

Make the current Reference Engine own Product, define interfaces, make it transparent and replaceable. If parts are not backwards-compatible provide migrations.

Implementation

  1. Extract use-cases from current Archetypes Reference Engine and also look at Relations product, thats uses and extends the Reference Engine.
  2. Think about how to implement a clean Reference Engine solution in a five/zope3ish manner.
  3. Define interfaces for the new style Reference Engine.
  4. Extract all current Reference Engine code out of current Archetypes and turn it into a product. Make it replaceable inside Archetypes. Use wrapper/ adapters where needed. This can go into Archetypes 1.4.x release
  5. Start a clean rewrite of the ReferenceEngine.
  6. Replace the old ReferenceEngine with the new one. (Archetypes 1.5/2.0 or however its called).

Deliverables

We need a new release with an additional Product "ReferenceEngine".

Risks

Risk is to break current sometimes odd behaviour of the ReferenceEngine. We need - as usal - good tests. I propose to extend current ReferenceEngine related tests in Archetypes, but not chnage current tests behaviour to ensure backward compatibility. There a projects out in the real world, where information in stored using References is similar or more important than information stored in contents fields.

Progress log

after Snowsprint 2006
current code is located at http://svn.plone.org/svn/archetypes/components/. Its a good base for further development. Several base design decisions where done.

Participants

  • Jens Klein - jensens
  • Whit Morriss
  • Daniel Nouri
  • Alec Mitchell
  • add your name here

Association Classes

Posted by Floyd May at May 03, 2006 07:03 PM
Would it be possible to give some extra refactoring attention to how ContentReference works in this process? It seems rather... odd... that the Reference instance itself isn't the ContentReference, but requires you to do a getContentObject, yielding two separate AT objects with two separate UIDs.

I second that!

Posted by Jeremy McMillan at Aug 22, 2006 07:14 PM
Can we get some documentation on how to traverse the relationships from object to object? That's really a loaded question. If the documentation seems too difficult or just too much work then maybe the interface left for developers isn't simple enough.

The power of references combined with the simplicity of Archetypes creates very high expectations thus maximizing the stinging sensation of any let-downs.