On 10/13/2011 07:08 AM, Vincent Massol wrote: > 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.
Looks good, +1. > 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 -- Sergiu Dumitriu http://purl.org/net/sergiu/ _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
