On Tue, Jun 29, 2010 at 13:29, Caleb James DeLisle
<[email protected]> 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.
I don't see how you can consider that replacing a safe typed generic
API by a list of strings is better...
>
>>
>> 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?
I don't see the point of debating for the old already dead to me api $xwiki.
There is possible way better script oriented APIs that works in all
languages IMO.
Here is an example I have in mind since we introduce EnityReference
but did not had time to think about it a lot:
$services.model.wikiname.spacename.pagename.reference (gets reference
of document "wikiname:spacename.pagename")
$services.model.wikiname.spacename.space("subspacename").pagename.reference
(gets reference of document
"wikiname:spacename.subspacename.pagename", depends if we give
priority to space or page in the get(String) from a space)
$services.model.wikiname.spacename.pagename.document (gets document
"wikiname:spacename.pagename")
$services.model.document (gets current document)
$services.model.get("wik:iname").spacename.pagename.reference (gets
reference of document "wik\:iname:spacename.pagename")
$services.model.page("pagename").reference (gets "pagename" document
in current spaces and current wiki)
$services.model.space("spacename").pagename.relativeReference (gets
"spacename.pagename" relative entity reference, could be
$services.model.page("pagename").getReference(false) also)
$services.model.page("pagename").getReference("default") (gets
"pagename" document in default space and default wiki, "default" is
the identifier of the resolver to use, the default being "current")
etc.
Pretty much all that takes one class with few methods and covers a
lots of use cases.
And I'm sure it can be improved (maybe $services.model.builder instead
of just $services.model to more more easily other things in
$services.model if we need, )
>
>>
>>>> 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
>>>>>
>>>>
>>>>
>>> _______________________________________________
>>> devs mailing list
>>> [email protected]
>>> http://lists.xwiki.org/mailman/listinfo/devs
>>>
>>
>>
>>
>
> _______________________________________________
> devs mailing list
> [email protected]
> http://lists.xwiki.org/mailman/listinfo/devs
>
--
Thomas Mortagne
_______________________________________________
devs mailing list
[email protected]
http://lists.xwiki.org/mailman/listinfo/devs
