On Jun 29, 2010, at 1:29 PM, Caleb James DeLisle wrote: > > > Thomas Mortagne wrote: >> On Tue, Jun 29, 2010 at 12:32, Caleb James DeLisle >> <[email protected]> wrote: >>> >>> Thomas Mortagne wrote: >>>> On Tue, Jun 29, 2010 at 11:42, Caleb James DeLisle >>>> <[email protected]> wrote: >>>>> I believe that in order for a new api to be accepted by the community, it >>>>> must be more useful and/or easier to use >>>>> than the api which it replaces. >>>>> >>>>> The old way of getting a document was this: >>>>> $xwiki.getDocument("xwiki:Main.WebHome") >>>>> >>>>> The current way to get a document is this: >>>>> $xwiki.getDocument($services.model.createDocumentReference($context.wiki, >>>>> $space, "WebHome")) >>>>> >>>>> I am quite sure that the user community will choose the former even if it >>>>> has escaping issues. >>>>> >>>>> Lest one think we can bully the community into choosing the latter by >>>>> deprecation or removal of methods, recall >>>>> the dismal sales of Windows Vista even with the control afforded by the >>>>> proprietary license and the awesome power >>>>> Microsoft wields over the market. The user is the boss, their word is law. >>>>> >>>>> My first proposal is that we move to an easier way to handle document >>>>> names. >>>>> >>>>> >>>>> >>>>> My second proposal is a possible way to do it. >>>>> I would like velocity and groovy script authors to be able to give a >>>>> command like this: >>>>> xwiki.getDocument(["Main", "WebHome"]); >>>>> or in velocity >>>>> $xwiki.getDocument(["Main", "WebHome"]) >>>>> >>>>> To make that possible I am proposing we change the reference model as >>>>> follows: >>>>> EntityReference extends List<String> >>>>> Each reference has a name which is expressed as a string, it also has a >>>>> reference to the next node and the last >>>>> node. This is a classic example of a LinkedList. The point is that any >>>>> List<String> is a valid (although reletive) >>>>> reference. When a relative reference is passed, it is replaced with a >>>>> complete reference which is completed using >>>>> the document in the context. >>>>> >>>>> As you prepare your -1's please recognize that the community will never >>>>> go for the current model and almost >>>>> anything is better than a rift between the community and the development >>>>> team. If there are any other ideas of >>>>> how to make it that easy, I would be glad to hear them. >>>> I don't see why making public script API to get a document easier >>>> imply to change EntityReferences. You can always have this >>>> xwiki.getDocument(["Main", "WebHome"]); without touching >>>> EntityReferences design, you just create a reference from this list in >>>> the getDocument implementation. >>> Then we will have >>> getDocument(Reference) >>> getDocument(String) >>> getDocument(List) >>> not to mention rename, copyDocument etc. >>> >>> If we must add new methods because we can't make references easy to create >>> then I think sooner or later we are >>> going to have to change direction. >> >> Note that you forget one feature of Velocity: we can implements an >> uberspector that automatically convert give list to the corresponding >> EntityReference. >> >> So you would only have >> >> getDocument(DocumentReference) in the api >> >> but if someone calls getDocument(["Main", "WebHome"]); the uberspector >> will see that there is not direct match but there is a EntityReference >> based one so it will convert the List and calls >> getDocument(DocumentReference) > > So you advocate for adding API which is not explicit in the code, not listed > in javadoc, and might create a > collision that is undetected on compile? That sounds to me like a hack. > >> >> Groovy does not needs a service to create a document reference so it's >> not an issue for it IMO > > So in groovy/python/ruby/etc. users will not be able to get documents or will > they be given the choice > of the buggy method and the one nobody is likely to adopt?
We *already* have a Java API. This discussion should be only for Velocity not other languages. For the record I agree word for word with Thomas' comments so far :) Thanks -Vincent >>>> Problem with your proposal is that it will introduce several >>>> limitations since you have only strings: You have no idea what is >>>> what in this String list you can only rely on the index of the string >>>> in the list. >>>> - the current EntityReferences is that way because we wanted to make >>>> possible to have a reference with just the wiki and the page and give >>>> it to a resolver to get a full reference >>>> - how do you support multiple spaces since you can't know which of >>>> theses strings are spaces ? >>> The algorithm would work like this. If the current document is: >>> xwiki:one.two.three.space.doc >>> and you reference ["xwiki", "Main", "WebHome"] >>> it would count back 3 from the current document location and you would get >>> xwiki:one.two.xwiki.Main.WebHome >>> To make an explicit reference you could pass an entity which is illegal >>> such as: >>> [0, "xwiki", "Main", "WebHome"] >>> or >>> [$xwiki, "xwiki", "Main", "WebHome"] >>> Since nested spaces are not implemented I don't see why we need to worry >>> too much about >>> how easy it is to work around them as long as we know it won't be >>> impossible to implement >>> when the time comes. >> >> Except that, as I said, it is impossible with the design you are proposing... > > Please explain why that is, I see no problem with taking a List as a relative > Reference and completing it using > the document in the context. The biggest challenge I see is signaling what > the "current node" is since each > reference is a node as well as a list containing that node and I'm sure there > is a way to sneak that information > out through a method in the list interface. A hack it would be but I don't > see that it would have any major user > affecting consequences as would some other ideas. > >> >>> >>>>> Caleb _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
