29 Jun
2010
29 Jun
'10
11:42 a.m.
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.
Caleb
29 Jun
29 Jun
11:58 a.m.
On Tue, Jun 29, 2010 at 11:42, Caleb James DeLisle
<calebdelisle(a)lavabit.com> 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.
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 ?
Caleb
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs
--
Thomas Mortagne
12:32 p.m.
Thomas Mortagne wrote:
On Tue, Jun 29, 2010 at 11:42, Caleb James DeLisle
<calebdelisle(a)lavabit.com> wrote:
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.
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.
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.
Caleb
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs
12:58 p.m.
On Tue, Jun 29, 2010 at 12:32, Caleb James DeLisle
<calebdelisle(a)lavabit.com> wrote:
Except that, as I said, it is impossible with the design you are proposing...
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs
--
Thomas Mortagne
Thomas Mortagne wrote:
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)
Groovy does not needs a service to create a document reference so it's
not an issue for it IMO
On Tue, Jun 29, 2010 at 11:42, Caleb James
DeLisle
<calebdelisle(a)lavabit.com> wrote:
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. 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.
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.
Caleb
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs
1:29 p.m.
Thomas Mortagne wrote:
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.
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs
On Tue, Jun 29, 2010 at 12:32, Caleb James DeLisle
<calebdelisle(a)lavabit.com> wrote:
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.
Thomas Mortagne wrote:
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) On Tue, Jun 29, 2010 at 11:42, Caleb James
DeLisle
<calebdelisle(a)lavabit.com> wrote:
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. 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.
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?
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. Caleb
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs
1:26 p.m.
On Jun 29, 2010, at 1:29 PM, Caleb James DeLisle wrote:
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
Thomas Mortagne wrote:
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
On Tue, Jun 29, 2010 at 12:32, Caleb James
DeLisle
<calebdelisle(a)lavabit.com> wrote:
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.
Thomas Mortagne wrote:
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) On Tue, Jun 29, 2010 at 11:42, Caleb James
DeLisle
<calebdelisle(a)lavabit.com> 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.
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? 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.
2:23 p.m.
On Tue, Jun 29, 2010 at 13:29, Caleb James DeLisle
<calebdelisle(a)lavabit.com> wrote:
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, )
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.
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs
--
Thomas Mortagne
Thomas Mortagne wrote:
I don't see how you can consider that replacing a safe typed generic
API by a list of strings is better...
On Tue, Jun 29, 2010 at 12:32, Caleb James
DeLisle
<calebdelisle(a)lavabit.com> wrote:
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.
Thomas Mortagne wrote:
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) On Tue, Jun 29, 2010 at 11:42, Caleb James
DeLisle
<calebdelisle(a)lavabit.com> 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.
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? 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. > Caleb
>
> _______________________________________________
> devs mailing list
> devs(a)xwiki.org
> http://lists.xwiki.org/mailman/listinfo/devs
>
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs
3:02 p.m.
Thomas Mortagne wrote:
On Tue, Jun 29, 2010 at 13:29, Caleb James DeLisle
<calebdelisle(a)lavabit.com> wrote:
I don't see the point of debating for the old already dead to me api $xwiki.
I suppose since we have $services, you are right.
Thomas Mortagne wrote:
I don't see how you can consider that replacing a safe typed generic
API by a list of strings is better...
On Tue, Jun 29, 2010 at 12:32, Caleb James
DeLisle
<calebdelisle(a)lavabit.com> wrote:
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. Thomas Mortagne wrote:
> On Tue, Jun 29, 2010 at 11:42, Caleb James DeLisle
> <calebdelisle(a)lavabit.com> 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) 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?
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")
+1 to that idea.
maybe $services.referenceTo.xwiki.Main.WebHome?
Would that mean a reference had a get method for getting a child node?
A means to get a relative reference would be nice as well, such as:
$doc.referenceTo.Main.WebHome
but that would mean invalid references would have to be returned in the hope that the next
get method would
fill in enough information to use the "count back" algorithm.
How would it be expressed in groovy? How is it done currently in groovy? Surely you
don't expect users to
load components to create a reference.
Really I'm +1 for _anything_ that will make this attractive to script programmers.
$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, )
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.
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs
> 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... >>
Caleb
>>
>> _______________________________________________
>> devs mailing list
>> devs(a)xwiki.org
>> http://lists.xwiki.org/mailman/listinfo/devs
>>
>
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs
3:19 p.m.
On Tue, Jun 29, 2010 at 15:02, Caleb James DeLisle
<calebdelisle(a)lavabit.com> wrote:
Thomas Mortagne wrote:
No it's not reference, if you want the reference you call .reference
at the end, see examples.
What i propose is a script tool and not to touch anything in EntityReference.
On Tue, Jun 29, 2010 at 13:29, Caleb James
DeLisle
<calebdelisle(a)lavabit.com> wrote:
I don't see the point of debating for the old already dead to me api $xwiki.
I suppose since we have $services, you are right.
Thomas Mortagne wrote:
I don't see how you can consider that replacing a safe typed generic
API by a list of strings is better...
On Tue, Jun 29, 2010 at 12:32, Caleb James
DeLisle
<calebdelisle(a)lavabit.com> wrote:
> Thomas Mortagne wrote:
>> On Tue, Jun 29, 2010 at 11:42, Caleb James DeLisle
>> <calebdelisle(a)lavabit.com> 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?
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")
+1 to that idea.
maybe $services.referenceTo.xwiki.Main.WebHome?
Would that mean a reference had a get method for getting a child node? A means to get a relative reference would be nice as
well, such as:
$doc.referenceTo.Main.WebHome
I gave an example for this:
$services.model.space("spacename").pagename.relativeReference (gets
"spacename.pagename" relative entity reference, could be
$services.model.page("pagename").getReference(false) also)
but that would mean invalid references would have to
be returned in the hope that the next get method would
fill in enough information to use the "count back" algorithm.
Relative reference can be useful to store them somewhere.
How would it be expressed in groovy? How is it done currently in groovy? Surely you
don't expect users to
load components to create a reference.
If what you want a reference in groovy you can easily create it the
exact same way you would do in Java as i already said: new
DocumentReference("wiki", "space", "name")
And if what you need is to resolve things Groovy has exactly the same
short cuts support and provide services binding too.
Look at my examples again, my proposal is not only about references
but about model in general.
$services.model.wikiname.spacename.pagename.document
gets the document and not the document reference
Really I'm +1 for _anything_ that will make this attractive to script programmers.
--
Thomas Mortagne
$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, )
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs
>>
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
>>> devs(a)xwiki.org
>>> http://lists.xwiki.org/mailman/listinfo/devs
>>>
>>
> _______________________________________________
> devs mailing list
> devs(a)xwiki.org
> http://lists.xwiki.org/mailman/listinfo/devs
>
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs
12:25 p.m.
On 06/29/2010 12:42 PM, Caleb James DeLisle 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.
I'm +1 for an easier way to handle document names in scripts
(velocity/groovy).
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>
As Thomas said, we could add helper methods like the one you proposed
without changing the model.
Marius
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.
Caleb
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs
12:38 p.m.
Big +1
Jerome.
----- Original Message -----
From: "Caleb James DeLisle" <calebdelisle(a)lavabit.com>
To: "XWiki Developers" <devs(a)xwiki.org>
Sent: Tuesday, June 29, 2010 11:42:36 AM GMT +01:00 Amsterdam / Berlin / Bern / Rome /
Stockholm / Vienna
Subject: [xwiki-devs] [proposal] Make EntityReferences easier to create.
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.
Caleb
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs
5193
days inactive
5193
days old
10 comments
5 participants
participants (5)
-
Caleb James DeLisle -
Jerome Velociter -
Marius Dumitru Florea -
Thomas Mortagne -
Vincent Massol