Re: [xwiki-devs] [VOTE] Adding notions of Locale and Version in EntityReference

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