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 > _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
