23 Jun
2008
23 Jun
'08
2:07 p.m.
On 23 juin 08, at 11:59, Vincent Massol wrote:
* This raises the question as to whether we should
continue passing a
String representing a document name in our APIs in the future or
instead pass a DocumentName. I'm not yet sure what is the best answer
to this...
Hi all,
I don't have a strong opinion on these issues, however I might tell
you what I did in the XMLRPC subsystem because it could be interesting
for the discussion.
In the XMLRPC subsystem I used a kind of "XWiki-URIs"[1] that encodes
information in the form of:
Space.Page[?param=value¶m=value&...]
These URIs are used in getPage and storePage[2] in order to retrieve/
store a particular type of object:
Space.Page (retrieves/stores the latest version in the default language)
Space.Page?version=5 (retrieves page at version 5)
space.Page?language=fr (retrieves/stores the page in its fr
translation).
These id are somehow hidden to the client. In fact there are some
helper functions in the "extended" XMLRPC api[3]
that mask the construction of these URI. For example getPage(String
pageId, String language) will simply build an URI and then call the
plain getPage method.
In principle nothing prevents the user from passing a hand-made URI
directly to the getPage method. And of course it will work (provided
that the user uses the right "names" for the parameters).
Everything works fine because these URIs are returned as the IDs of
the page structures that are handled by the client.
What I mean is that
Page p = getPage("Foo.Bar", "fr");
p.setContent("Salut");
storePage(p);
will correctly store the french version of Foo.Bar, because p will
have its ID set to "Foo.Bar?language=fr"
Same thing for getPageHistory that returns a list of PageSummaries
whose IDs will be:
"Foo.Bar?version=1&minorVersion=1"
"Foo.Bar?version=2&minorVersion=1"
"Foo.Bar?version=3&minorVersion=1"
...
So I am more in favor of a loose identifier (such as a string) that
can be parsed/rearranged more easily, rather than a well structured
and codified one (like a DocumentName class).
But frankly, as I said, I haven't a strong opinion on this. In the
XMLRPC subsystem this was an effective and elegant solution to a lot
of issues, but I haven't evaluated in depth the pros and cons in other
contexts.
* BTW this also raises the question as to whether we want to have a
representation for space and wiki or not and instead only use tags, in
which case a document name is simply a String like "mypage". But then
it should be unique. So it could also be made of a list of identity
tags as in: "space=sp1,sp2:wiki:wiki1:language=fr:mypage". Or we could
standardize it as "wiki1:sp1,sp2:fr:mypage" and have the
DocumentNameFactory transform it into tags. In that case the
DocumentName object would be a Map of tags + the document name
("mypage"). I think we need to decide ASAP if we want to keep the
strict and hardcoded notion of Wiki>Space>Document>Object>Property or
instead go full tags since this changes completely the v2 interfaces
and code we're writing.
I can contribute also here, by saying something about my XMLRPC
experience, in particular with respect to Confluence.
Confluence goes the "tag" way. A page in Confluence has an opaque ID
that does not carry any semantics. In fact, it's just a plain integer.
Its space and title fields give the semantics.
In XWiki the ID embeds the "structural" semantics, making also the
assumption that the domain will always be modeled in that way.
I think that putting semantics in the ID is not a good idea; this was
one of the reason why I had to do some tricks in order to make the
XMLRPC API compatible with Confluence[4]. So I think that assigning
the page a simple ID (i.e., integer, string, whatever) and defining
the structural relationships (e.g., belongs to space, etc.) somewhere
else is better.
Again, I haven't thought enough about what are the consequences of
going the "tag" way, but from a more abstract point of view I think
that this is a good choice.
My 2 cents. :)
Cheers,
Fabio
[1]
http://svn.xwiki.org/svnroot/xwiki/xwiki-platform/core/trunk/xwiki-xmlrpc/x…
[2]
http://svn.xwiki.org/svnroot/xwiki/xwiki-platform/core/trunk/xwiki-core/src…
[3]
http://svn.xwiki.org/svnroot/xwiki/xwiki-platform/core/trunk/xwiki-xmlrpc/x…
[4] http://jira.xwiki.org/jira/browse/XWIKI-2428