13 Oct
2011
13 Oct
'11
1:08 p.m.
After more brainstorming with Denis and Thomas here's some updated information about
what we'd like to do:
* Make EntityReference immutable (ie remove the set* methods) - it's a best practice
since it reduces potential mistakes (you pass a reference to some code and then somewhere
else you call setXXX())
* Remove the clone() method (since it's less needed when the object is immutable and
it's hard to implement in a generic way for generic parameters)
* Have equals(), toString(), hashCode(), compareTo() all act on all EntityReference class
fields (ie including the parameters)
* Modify or add a new EntityReferenceResolver that will fill the parameters when
they're missing. Of course the resolver will only know how to handle some parameters
(Version and Locale ATM).
* We thought that the safest way was to add the get/setLocale() and get/setVersion methods
in DocumentReference for now (as helper methods to the generic add/getParameter methods in
EntityReference. This is because the new model hasn't been voted yet and thus
we're not yet sure that all Entities will support Version/Locale
Note that this will break backward compatibility in EntityReference but we think we need
to do this ASAP.
Let us know if you think there's a problem.
Thanks
-Vincent
On Sep 15, 2011, at 4:35 PM, Vincent Massol wrote:
Hi devs,
After much brainstorming with Thomas and with the implementation of the new model I'm
doing, we've come to the conclusion that it would be better to add the notions of
Locale and Version in EntityReference.
The main reasons are:
* otherwise we need to introduce a notion of UniqueEntityReference in the model and it
makes it very awkward at an API level (user need to constuct a UniqueEntityReference from
an EntityReference depending on the APIs used)
* it makes APIs more complex than what they could be.
For example:
- getDocument(EntityReference)
- getDocument(EntityReference, Locale)
- getDocument(EntityReference, Version)
- getDocument(EntityReference, Locale, Version)
vs
- getDocument(EntityReference)
(subnote: this is why I introduced UniqueEntityReference in the model)
* It'll mean that anywhere we use an entity reference we'll be able to reference
a specific version of that entity and/or a specific language. Some example: including a
specific version of a page, referencing a specific version of an attachment in wiki
syntax, etc.
In a first version I'd like to only introduce a generic get/setAttributes (to allow
extensibility) in EntityReference + get/setLocale/Version (for easiness of access).
ATM I'm not planning to define a textual syntax for attributes (but it could
something like: wiki:space.page[name1=value1, … nameN=valueN]). I'm not asking to vote
on this.
Here's my +1
Thanks
-Vincent