[xwiki-devs] [Proposal] strategy for string vs Reference usage in vm files
Hi, I'd like to suggest the following strategy for now: * We modify all our vm files to use references (by using the ModelScriptService, see below) * We introduce APIs taking References in api.* (ex: api.Document, api.XWiki) * We _don't_ deprecate existing APIs in api.*. This means we allow users to use the older string APIs for ease of use FYI here's what I've started adding in ModelScriptService: @Component("model") public class ModelScriptService implements ScriptService { @Requirement private ComponentManager componentManager; public DocumentReference createDocumentReference(String wiki, String space, String page, String hint) { EntityReference reference = null; if (!StringUtils.isEmpty(wiki)) { reference = new EntityReference(wiki, EntityType.WIKI); } if (!StringUtils.isEmpty(space)) { reference = new EntityReference(space, EntityType.SPACE, reference); } if (!StringUtils.isEmpty(page)) { reference = new EntityReference(page, EntityType.DOCUMENT, reference); } DocumentReference documentReference; try { documentReference = this.componentManager.lookup(DocumentReferenceResolver.class, hint).resolve(reference); } catch (ComponentLookupException e) { documentReference = null; } return documentReference; } public DocumentReference resolveDocument(String stringRepresentation, String hint) { DocumentReference result; try { result = this.componentManager.lookup(DocumentReferenceResolver.class, hint).resolve( stringRepresentation); } catch (ComponentLookupException e) { result = null; } return result; } public String serialize(EntityReference reference, String hint) { String result; try { result = (String) this.componentManager.lookup(EntityReferenceSerializer.class, hint).serialize(reference); } catch (ComponentLookupException e) { result = null; } return result; } } Thanks -Vincent
+1 On Tue, Feb 16, 2010 at 12:42, Vincent Massol <[email protected]> wrote:
Hi,
I'd like to suggest the following strategy for now:
* We modify all our vm files to use references (by using the ModelScriptService, see below) * We introduce APIs taking References in api.* (ex: api.Document, api.XWiki) * We _don't_ deprecate existing APIs in api.*. This means we allow users to use the older string APIs for ease of use
FYI here's what I've started adding in ModelScriptService:
@Component("model") public class ModelScriptService implements ScriptService { @Requirement private ComponentManager componentManager;
public DocumentReference createDocumentReference(String wiki, String space, String page, String hint) { EntityReference reference = null; if (!StringUtils.isEmpty(wiki)) { reference = new EntityReference(wiki, EntityType.WIKI); } if (!StringUtils.isEmpty(space)) { reference = new EntityReference(space, EntityType.SPACE, reference); } if (!StringUtils.isEmpty(page)) { reference = new EntityReference(page, EntityType.DOCUMENT, reference); }
DocumentReference documentReference; try { documentReference = this.componentManager.lookup(DocumentReferenceResolver.class, hint).resolve(reference); } catch (ComponentLookupException e) { documentReference = null; } return documentReference; }
public DocumentReference resolveDocument(String stringRepresentation, String hint) { DocumentReference result; try { result = this.componentManager.lookup(DocumentReferenceResolver.class, hint).resolve( stringRepresentation); } catch (ComponentLookupException e) { result = null; } return result; }
public String serialize(EntityReference reference, String hint) { String result; try { result = (String) this.componentManager.lookup(EntityReferenceSerializer.class, hint).serialize(reference); } catch (ComponentLookupException e) { result = null; } return result; } }
Thanks -Vincent _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne
Hi,
I'd like to suggest the following strategy for now:
* We modify all our vm files to use references (by using the ModelScriptService, see below) * We introduce APIs taking References in api.* (ex: api.Document, api.XWiki) * We _don't_ deprecate existing APIs in api.*. This means we allow users to use the older string APIs for ease of use
Hello Vincent, Before I can make up my mind, I would like to know: * What will be the strategy for velocity code in wiki pages (here you mention only .vm pages - will the strategy be voted again for wiki pages?) * Considering we use the same strategy for wiki pages, and since we do not deprecate the old APIs that manipulate strings, what will be the 'recommanded' way of say getting a document ? (the one we would advertise on xwiki.org code examples for example) Thanks, Jerome
FYI here's what I've started adding in ModelScriptService:
@Component("model") public class ModelScriptService implements ScriptService { @Requirement private ComponentManager componentManager;
public DocumentReference createDocumentReference(String wiki, String space, String page, String hint) { EntityReference reference = null; if (!StringUtils.isEmpty(wiki)) { reference = new EntityReference(wiki, EntityType.WIKI); } if (!StringUtils.isEmpty(space)) { reference = new EntityReference(space, EntityType.SPACE, reference); } if (!StringUtils.isEmpty(page)) { reference = new EntityReference(page, EntityType.DOCUMENT, reference); }
DocumentReference documentReference; try { documentReference = this.componentManager.lookup(DocumentReferenceResolver.class, hint).resolve(reference); } catch (ComponentLookupException e) { documentReference = null; } return documentReference; }
public DocumentReference resolveDocument(String stringRepresentation, String hint) { DocumentReference result; try { result = this.componentManager.lookup(DocumentReferenceResolver.class, hint).resolve( stringRepresentation); } catch (ComponentLookupException e) { result = null; } return result; }
public String serialize(EntityReference reference, String hint) { String result; try { result = (String) this.componentManager.lookup(EntityReferenceSerializer.class, hint).serialize(reference); } catch (ComponentLookupException e) { result = null; } return result; } }
Thanks -Vincent _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
On Wed, Feb 17, 2010 at 10:45, Jerome Velociter <[email protected]> wrote:
Hi,
I'd like to suggest the following strategy for now:
* We modify all our vm files to use references (by using the ModelScriptService, see below) * We introduce APIs taking References in api.* (ex: api.Document, api.XWiki) * We _don't_ deprecate existing APIs in api.*. This means we allow users to use the older string APIs for ease of use
Hello Vincent,
Before I can make up my mind, I would like to know:
* What will be the strategy for velocity code in wiki pages (here you mention only .vm pages - will the strategy be voted again for wiki pages?)
* Considering we use the same strategy for wiki pages, and since we do not deprecate the old APIs that manipulate strings, what will be the 'recommanded' way of say getting a document ? (the one we would advertise on xwiki.org code examples for example)
To summarize: * String based methods: helper methods for users * EntityReference based methods: what we are supposed to use or anyone that want to write proper code
Thanks, Jerome
FYI here's what I've started adding in ModelScriptService:
@Component("model") public class ModelScriptService implements ScriptService { @Requirement private ComponentManager componentManager;
public DocumentReference createDocumentReference(String wiki, String space, String page, String hint) { EntityReference reference = null; if (!StringUtils.isEmpty(wiki)) { reference = new EntityReference(wiki, EntityType.WIKI); } if (!StringUtils.isEmpty(space)) { reference = new EntityReference(space, EntityType.SPACE, reference); } if (!StringUtils.isEmpty(page)) { reference = new EntityReference(page, EntityType.DOCUMENT, reference); }
DocumentReference documentReference; try { documentReference = this.componentManager.lookup(DocumentReferenceResolver.class, hint).resolve(reference); } catch (ComponentLookupException e) { documentReference = null; } return documentReference; }
public DocumentReference resolveDocument(String stringRepresentation, String hint) { DocumentReference result; try { result = this.componentManager.lookup(DocumentReferenceResolver.class, hint).resolve( stringRepresentation); } catch (ComponentLookupException e) { result = null; } return result; }
public String serialize(EntityReference reference, String hint) { String result; try { result = (String) this.componentManager.lookup(EntityReferenceSerializer.class, hint).serialize(reference); } catch (ComponentLookupException e) { result = null; } return result; } }
Thanks -Vincent _______________________________________________ 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
On Feb 17, 2010, at 11:03 AM, Thomas Mortagne wrote:
On Wed, Feb 17, 2010 at 10:45, Jerome Velociter <[email protected]> wrote:
Hi,
I'd like to suggest the following strategy for now:
* We modify all our vm files to use references (by using the ModelScriptService, see below) * We introduce APIs taking References in api.* (ex: api.Document, api.XWiki) * We _don't_ deprecate existing APIs in api.*. This means we allow users to use the older string APIs for ease of use
Hello Vincent,
Before I can make up my mind, I would like to know:
* What will be the strategy for velocity code in wiki pages (here you mention only .vm pages - will the strategy be voted again for wiki pages?)
* Considering we use the same strategy for wiki pages, and since we do not deprecate the old APIs that manipulate strings, what will be the 'recommanded' way of say getting a document ? (the one we would advertise on xwiki.org code examples for example)
To summarize: * String based methods: helper methods for users * EntityReference based methods: what we are supposed to use or anyone that want to write proper code
Yes. You can use the the string-based APIs but then you *MUST* be sure to perform the correct escapes. For example: $xwiki.getDocument("Main.My\\.Page") Thanks -Vincent
Thanks, Jerome
FYI here's what I've started adding in ModelScriptService:
@Component("model") public class ModelScriptService implements ScriptService { @Requirement private ComponentManager componentManager;
public DocumentReference createDocumentReference(String wiki, String space, String page, String hint) { EntityReference reference = null; if (!StringUtils.isEmpty(wiki)) { reference = new EntityReference(wiki, EntityType.WIKI); } if (!StringUtils.isEmpty(space)) { reference = new EntityReference(space, EntityType.SPACE, reference); } if (!StringUtils.isEmpty(page)) { reference = new EntityReference(page, EntityType.DOCUMENT, reference); }
DocumentReference documentReference; try { documentReference = this.componentManager.lookup(DocumentReferenceResolver.class, hint).resolve(reference); } catch (ComponentLookupException e) { documentReference = null; } return documentReference; }
public DocumentReference resolveDocument(String stringRepresentation, String hint) { DocumentReference result; try { result = this.componentManager.lookup(DocumentReferenceResolver.class, hint).resolve( stringRepresentation); } catch (ComponentLookupException e) { result = null; } return result; }
public String serialize(EntityReference reference, String hint) { String result; try { result = (String) this.componentManager.lookup(EntityReferenceSerializer.class, hint).serialize(reference); } catch (ComponentLookupException e) { result = null; } return result; } }
Thanks -Vincent
On Wed, Feb 17, 2010 at 10:45, Jerome Velociter <[email protected]> wrote:
Hi,
I'd like to suggest the following strategy for now:
* We modify all our vm files to use references (by using the ModelScriptService, see below) * We introduce APIs taking References in api.* (ex: api.Document, api.XWiki) * We _don't_ deprecate existing APIs in api.*. This means we allow users to use the older string APIs for ease of use
Hello Vincent,
Before I can make up my mind, I would like to know:
* What will be the strategy for velocity code in wiki pages (here you mention only .vm pages - will the strategy be voted again for wiki pages?)
* Considering we use the same strategy for wiki pages, and since we do not deprecate the old APIs that manipulate strings, what will be the 'recommanded' way of say getting a document ? (the one we would advertise on xwiki.org code examples for example)
To summarize: * String based methods: helper methods for users * EntityReference based methods: what we are supposed to use or anyone that want to write proper code
OK, that's what I wanted to know :) I share this vision, and would be -1 to deprecate string based APIs (unless of course replaced with new string based helpers). I think it's important that we keep (velocity) simple scripting accessible to non-developers and that was my concern. You don't want to force users to know/understand what a reference resolver is for instance. As for what we do for velocity code in our own wiki pages (not .vms), I would tend to think we should keep it simple to read for users (so with string based APIs) but I'm a bit undecided. Jerome
Thanks, Jerome
On Feb 17, 2010, at 11:35 AM, Jerome Velociter wrote:
On Wed, Feb 17, 2010 at 10:45, Jerome Velociter <[email protected]> wrote:
Hi,
I'd like to suggest the following strategy for now:
* We modify all our vm files to use references (by using the ModelScriptService, see below) * We introduce APIs taking References in api.* (ex: api.Document, api.XWiki) * We _don't_ deprecate existing APIs in api.*. This means we allow users to use the older string APIs for ease of use
Hello Vincent,
Before I can make up my mind, I would like to know:
* What will be the strategy for velocity code in wiki pages (here you mention only .vm pages - will the strategy be voted again for wiki pages?)
* Considering we use the same strategy for wiki pages, and since we do not deprecate the old APIs that manipulate strings, what will be the 'recommanded' way of say getting a document ? (the one we would advertise on xwiki.org code examples for example)
To summarize: * String based methods: helper methods for users * EntityReference based methods: what we are supposed to use or anyone that want to write proper code
OK, that's what I wanted to know :)
I share this vision, and would be -1 to deprecate string based APIs (unless of course replaced with new string based helpers). I think it's important that we keep (velocity) simple scripting accessible to non-developers and that was my concern. You don't want to force users to know/understand what a reference resolver is for instance.
... and you'll get lots of complaints on the list telling us our software don't work because they'll have "forgotten" (or simply don't know about it) to escape special chars... ;)
As for what we do for velocity code in our own wiki pages (not .vms), I would tend to think we should keep it simple to read for users (so with string based APIs) but I'm a bit undecided.
It's not a question of choice. There's simply no choice jerome. If you don't use the reference-based apis then you have to manually perform parsing/serialization, i.e. manually recode the reference API. Thanks -Vincent
On Feb 17, 2010, at 11:42 AM, Vincent Massol wrote:
On Feb 17, 2010, at 11:35 AM, Jerome Velociter wrote:
On Wed, Feb 17, 2010 at 10:45, Jerome Velociter <[email protected]> wrote:
Hi,
I'd like to suggest the following strategy for now:
* We modify all our vm files to use references (by using the ModelScriptService, see below) * We introduce APIs taking References in api.* (ex: api.Document, api.XWiki) * We _don't_ deprecate existing APIs in api.*. This means we allow users to use the older string APIs for ease of use
Hello Vincent,
Before I can make up my mind, I would like to know:
* What will be the strategy for velocity code in wiki pages (here you mention only .vm pages - will the strategy be voted again for wiki pages?)
* Considering we use the same strategy for wiki pages, and since we do not deprecate the old APIs that manipulate strings, what will be the 'recommanded' way of say getting a document ? (the one we would advertise on xwiki.org code examples for example)
To summarize: * String based methods: helper methods for users * EntityReference based methods: what we are supposed to use or anyone that want to write proper code
OK, that's what I wanted to know :)
I share this vision, and would be -1 to deprecate string based APIs (unless of course replaced with new string based helpers). I think it's important that we keep (velocity) simple scripting accessible to non-developers and that was my concern. You don't want to force users to know/understand what a reference resolver is for instance.
... and you'll get lots of complaints on the list telling us our software don't work because they'll have "forgotten" (or simply don't know about it) to escape special chars... ;)
As for what we do for velocity code in our own wiki pages (not .vms), I would tend to think we should keep it simple to read for users (so with string based APIs) but I'm a bit undecided.
It's not a question of choice. There's simply no choice jerome.
If you don't use the reference-based apis then you have to manually perform parsing/serialization, i.e. manually recode the reference API.
Except of course for the cases where you know the full reference specifically and you can guarantee there's no special chars in it. -Vincent
On Feb 17, 2010, at 11:42 AM, Vincent Massol wrote:
On Feb 17, 2010, at 11:35 AM, Jerome Velociter wrote:
On Wed, Feb 17, 2010 at 10:45, Jerome Velociter <[email protected]> wrote:
Hi,
I'd like to suggest the following strategy for now:
* We modify all our vm files to use references (by using the ModelScriptService, see below) * We introduce APIs taking References in api.* (ex: api.Document, api.XWiki) * We _don't_ deprecate existing APIs in api.*. This means we allow users to use the older string APIs for ease of use
Hello Vincent,
Before I can make up my mind, I would like to know:
* What will be the strategy for velocity code in wiki pages (here you mention only .vm pages - will the strategy be voted again for wiki pages?)
* Considering we use the same strategy for wiki pages, and since we do not deprecate the old APIs that manipulate strings, what will be the 'recommanded' way of say getting a document ? (the one we would advertise on xwiki.org code examples for example)
To summarize: * String based methods: helper methods for users * EntityReference based methods: what we are supposed to use or anyone that want to write proper code
OK, that's what I wanted to know :)
I share this vision, and would be -1 to deprecate string based APIs (unless of course replaced with new string based helpers). I think it's important that we keep (velocity) simple scripting accessible to non-developers and that was my concern. You don't want to force users to know/understand what a reference resolver is for instance.
... and you'll get lots of complaints on the list telling us our software don't work because they'll have "forgotten" (or simply don't know about it) to escape special chars... ;)
As for what we do for velocity code in our own wiki pages (not .vms), I would tend to think we should keep it simple to read for users (so with string based APIs) but I'm a bit undecided.
It's not a question of choice. There's simply no choice jerome.
If you don't use the reference-based apis then you have to manually perform parsing/serialization, i.e. manually recode the reference API.
Except of course for the cases where you know the full reference specifically and you can guarantee there's no special chars in it.
That's what I am talking about. For example : $xwiki.getDocument('XWiki.Ratings') or $xwiki.ssx.use('XWiki.Ratings')
-Vincent _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
On Feb 17, 2010, at 2:41 PM, Jerome Velociter wrote:
On Feb 17, 2010, at 11:42 AM, Vincent Massol wrote:
On Feb 17, 2010, at 11:35 AM, Jerome Velociter wrote:
On Wed, Feb 17, 2010 at 10:45, Jerome Velociter <[email protected]> wrote:
> Hi, > > I'd like to suggest the following strategy for now: > > * We modify all our vm files to use references (by using the > ModelScriptService, see below) > * We introduce APIs taking References in api.* (ex: api.Document, > api.XWiki) > * We _don't_ deprecate existing APIs in api.*. This means we allow > users > to use the older string APIs for ease of use
Hello Vincent,
Before I can make up my mind, I would like to know:
* What will be the strategy for velocity code in wiki pages (here you mention only .vm pages - will the strategy be voted again for wiki pages?)
* Considering we use the same strategy for wiki pages, and since we do not deprecate the old APIs that manipulate strings, what will be the 'recommanded' way of say getting a document ? (the one we would advertise on xwiki.org code examples for example)
To summarize: * String based methods: helper methods for users * EntityReference based methods: what we are supposed to use or anyone that want to write proper code
OK, that's what I wanted to know :)
I share this vision, and would be -1 to deprecate string based APIs (unless of course replaced with new string based helpers). I think it's important that we keep (velocity) simple scripting accessible to non-developers and that was my concern. You don't want to force users to know/understand what a reference resolver is for instance.
... and you'll get lots of complaints on the list telling us our software don't work because they'll have "forgotten" (or simply don't know about it) to escape special chars... ;)
As for what we do for velocity code in our own wiki pages (not .vms), I would tend to think we should keep it simple to read for users (so with string based APIs) but I'm a bit undecided.
It's not a question of choice. There's simply no choice jerome.
If you don't use the reference-based apis then you have to manually perform parsing/serialization, i.e. manually recode the reference API.
Except of course for the cases where you know the full reference specifically and you can guarantee there's no special chars in it.
That's what I am talking about.
For example : $xwiki.getDocument('XWiki.Ratings') or $xwiki.ssx.use('XWiki.Ratings')
vs $xwiki.getDocument($services.model.createReference("XWiki", "Ratings")) Actually in this case I'd be for adding a new method instead: $xwiki.getDocument("XWiki", "Ratings") Thanks -Vincent
On 02/17/2010 02:51 PM, Vincent Massol wrote:
On Feb 17, 2010, at 2:41 PM, Jerome Velociter wrote:
On Feb 17, 2010, at 11:42 AM, Vincent Massol wrote:
On Feb 17, 2010, at 11:35 AM, Jerome Velociter wrote:
On Wed, Feb 17, 2010 at 10:45, Jerome Velociter<[email protected]> wrote: >> Hi, >> >> I'd like to suggest the following strategy for now: >> >> * We modify all our vm files to use references (by using the >> ModelScriptService, see below) >> * We introduce APIs taking References in api.* (ex: api.Document, >> api.XWiki) >> * We _don't_ deprecate existing APIs in api.*. This means we allow >> users >> to use the older string APIs for ease of use > > Hello Vincent, > > Before I can make up my mind, I would like to know: > > * What will be the strategy for velocity code in wiki pages (here you > mention only .vm pages - will the strategy be voted again for wiki > pages?) > > * Considering we use the same strategy for wiki pages, and since we > do > not > deprecate the old APIs that manipulate strings, what will be the > 'recommanded' way of say getting a document ? (the one we would > advertise > on xwiki.org code examples for example)
To summarize: * String based methods: helper methods for users * EntityReference based methods: what we are supposed to use or anyone that want to write proper code
OK, that's what I wanted to know :)
I share this vision, and would be -1 to deprecate string based APIs (unless of course replaced with new string based helpers). I think it's important that we keep (velocity) simple scripting accessible to non-developers and that was my concern. You don't want to force users to know/understand what a reference resolver is for instance.
... and you'll get lots of complaints on the list telling us our software don't work because they'll have "forgotten" (or simply don't know about it) to escape special chars... ;)
As for what we do for velocity code in our own wiki pages (not .vms), I would tend to think we should keep it simple to read for users (so with string based APIs) but I'm a bit undecided.
It's not a question of choice. There's simply no choice jerome.
If you don't use the reference-based apis then you have to manually perform parsing/serialization, i.e. manually recode the reference API.
Except of course for the cases where you know the full reference specifically and you can guarantee there's no special chars in it.
That's what I am talking about.
For example : $xwiki.getDocument('XWiki.Ratings') or $xwiki.ssx.use('XWiki.Ratings')
vs $xwiki.getDocument($services.model.createReference("XWiki", "Ratings"))
Actually in this case I'd be for adding a new method instead: $xwiki.getDocument("XWiki", "Ratings")
Which actually exists already. -- Sergiu Dumitriu http://purl.org/net/sergiu/
On Feb 17, 2010, at 2:41 PM, Jerome Velociter wrote:
On Feb 17, 2010, at 11:42 AM, Vincent Massol wrote:
On Feb 17, 2010, at 11:35 AM, Jerome Velociter wrote:
On Wed, Feb 17, 2010 at 10:45, Jerome Velociter <[email protected]> wrote: >> Hi, >> >> I'd like to suggest the following strategy for now: >> >> * We modify all our vm files to use references (by using the >> ModelScriptService, see below) >> * We introduce APIs taking References in api.* (ex: api.Document, >> api.XWiki) >> * We _don't_ deprecate existing APIs in api.*. This means we allow >> users >> to use the older string APIs for ease of use > > Hello Vincent, > > Before I can make up my mind, I would like to know: > > * What will be the strategy for velocity code in wiki pages (here > you > mention only .vm pages - will the strategy be voted again for wiki > pages?) > > * Considering we use the same strategy for wiki pages, and since we > do > not > deprecate the old APIs that manipulate strings, what will be the > 'recommanded' way of say getting a document ? (the one we would > advertise > on xwiki.org code examples for example)
To summarize: * String based methods: helper methods for users * EntityReference based methods: what we are supposed to use or anyone that want to write proper code
OK, that's what I wanted to know :)
I share this vision, and would be -1 to deprecate string based APIs (unless of course replaced with new string based helpers). I think it's important that we keep (velocity) simple scripting accessible to non-developers and that was my concern. You don't want to force users to know/understand what a reference resolver is for instance.
... and you'll get lots of complaints on the list telling us our software don't work because they'll have "forgotten" (or simply don't know about it) to escape special chars... ;)
As for what we do for velocity code in our own wiki pages (not .vms), I would tend to think we should keep it simple to read for users (so with string based APIs) but I'm a bit undecided.
It's not a question of choice. There's simply no choice jerome.
If you don't use the reference-based apis then you have to manually perform parsing/serialization, i.e. manually recode the reference API.
Except of course for the cases where you know the full reference specifically and you can guarantee there's no special chars in it.
That's what I am talking about.
For example : $xwiki.getDocument('XWiki.Ratings') or $xwiki.ssx.use('XWiki.Ratings')
vs $xwiki.getDocument($services.model.createReference("XWiki", "Ratings"))
Actually in this case I'd be for adding a new method instead: $xwiki.getDocument("XWiki", "Ratings")
Yes that would be good. We also need a helper for old "full names" (Space.Name), i.e. the ones returned by #searchDocuments APIs I would not like to see/write : #foreach($docName in $xwiki.searchDocuments("where doc.author<>'XWiki.Admin'")) #set($myDoc = $xwiki.getDocument($services.model.resolveDocument($docName, "current"))) ## ... do something with myDoc #end Thanks, Jerome.
Thanks -Vincent
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
On Feb 17, 2010, at 4:11 PM, Jerome Velociter wrote:
On Feb 17, 2010, at 2:41 PM, Jerome Velociter wrote:
On Feb 17, 2010, at 11:42 AM, Vincent Massol wrote:
On Feb 17, 2010, at 11:35 AM, Jerome Velociter wrote:
> On Wed, Feb 17, 2010 at 10:45, Jerome Velociter <[email protected]> > wrote: >>> Hi, >>> >>> I'd like to suggest the following strategy for now: >>> >>> * We modify all our vm files to use references (by using the >>> ModelScriptService, see below) >>> * We introduce APIs taking References in api.* (ex: api.Document, >>> api.XWiki) >>> * We _don't_ deprecate existing APIs in api.*. This means we allow >>> users >>> to use the older string APIs for ease of use >> >> Hello Vincent, >> >> Before I can make up my mind, I would like to know: >> >> * What will be the strategy for velocity code in wiki pages (here >> you >> mention only .vm pages - will the strategy be voted again for wiki >> pages?) >> >> * Considering we use the same strategy for wiki pages, and since we >> do >> not >> deprecate the old APIs that manipulate strings, what will be the >> 'recommanded' way of say getting a document ? (the one we would >> advertise >> on xwiki.org code examples for example) > > To summarize: > * String based methods: helper methods for users > * EntityReference based methods: what we are supposed to use or > anyone > that want to write proper code
OK, that's what I wanted to know :)
I share this vision, and would be -1 to deprecate string based APIs (unless of course replaced with new string based helpers). I think it's important that we keep (velocity) simple scripting accessible to non-developers and that was my concern. You don't want to force users to know/understand what a reference resolver is for instance.
... and you'll get lots of complaints on the list telling us our software don't work because they'll have "forgotten" (or simply don't know about it) to escape special chars... ;)
As for what we do for velocity code in our own wiki pages (not .vms), I would tend to think we should keep it simple to read for users (so with string based APIs) but I'm a bit undecided.
It's not a question of choice. There's simply no choice jerome.
If you don't use the reference-based apis then you have to manually perform parsing/serialization, i.e. manually recode the reference API.
Except of course for the cases where you know the full reference specifically and you can guarantee there's no special chars in it.
That's what I am talking about.
For example : $xwiki.getDocument('XWiki.Ratings') or $xwiki.ssx.use('XWiki.Ratings')
vs $xwiki.getDocument($services.model.createReference("XWiki", "Ratings"))
Actually in this case I'd be for adding a new method instead: $xwiki.getDocument("XWiki", "Ratings")
Yes that would be good.
We also need a helper for old "full names" (Space.Name), i.e. the ones returned by #searchDocuments APIs
I would not like to see/write :
#foreach($docName in $xwiki.searchDocuments("where doc.author<>'XWiki.Admin'")) #set($myDoc = $xwiki.getDocument($services.model.resolveDocument($docName, "current"))) ## ... do something with myDoc #end
yes but that's covered by adding new reference-based APIs: List<DocumentReference> searchDocuments(...) To summarize the goal is to remove the need to manipulate any reference as Strings. Manipulating strings representing wiki name, space name or document name is ok. Thanks -Vincent
On Wed, Feb 17, 2010 at 16:11, Jerome Velociter <[email protected]> wrote:
On Feb 17, 2010, at 2:41 PM, Jerome Velociter wrote:
On Feb 17, 2010, at 11:42 AM, Vincent Massol wrote:
On Feb 17, 2010, at 11:35 AM, Jerome Velociter wrote:
> On Wed, Feb 17, 2010 at 10:45, Jerome Velociter <[email protected]> > wrote: >>> Hi, >>> >>> I'd like to suggest the following strategy for now: >>> >>> * We modify all our vm files to use references (by using the >>> ModelScriptService, see below) >>> * We introduce APIs taking References in api.* (ex: api.Document, >>> api.XWiki) >>> * We _don't_ deprecate existing APIs in api.*. This means we allow >>> users >>> to use the older string APIs for ease of use >> >> Hello Vincent, >> >> Before I can make up my mind, I would like to know: >> >> * What will be the strategy for velocity code in wiki pages (here >> you >> mention only .vm pages - will the strategy be voted again for wiki >> pages?) >> >> * Considering we use the same strategy for wiki pages, and since we >> do >> not >> deprecate the old APIs that manipulate strings, what will be the >> 'recommanded' way of say getting a document ? (the one we would >> advertise >> on xwiki.org code examples for example) > > To summarize: > * String based methods: helper methods for users > * EntityReference based methods: what we are supposed to use or > anyone > that want to write proper code
OK, that's what I wanted to know :)
I share this vision, and would be -1 to deprecate string based APIs (unless of course replaced with new string based helpers). I think it's important that we keep (velocity) simple scripting accessible to non-developers and that was my concern. You don't want to force users to know/understand what a reference resolver is for instance.
... and you'll get lots of complaints on the list telling us our software don't work because they'll have "forgotten" (or simply don't know about it) to escape special chars... ;)
As for what we do for velocity code in our own wiki pages (not .vms), I would tend to think we should keep it simple to read for users (so with string based APIs) but I'm a bit undecided.
It's not a question of choice. There's simply no choice jerome.
If you don't use the reference-based apis then you have to manually perform parsing/serialization, i.e. manually recode the reference API.
Except of course for the cases where you know the full reference specifically and you can guarantee there's no special chars in it.
That's what I am talking about.
For example : $xwiki.getDocument('XWiki.Ratings') or $xwiki.ssx.use('XWiki.Ratings')
vs $xwiki.getDocument($services.model.createReference("XWiki", "Ratings"))
Actually in this case I'd be for adding a new method instead: $xwiki.getDocument("XWiki", "Ratings")
Yes that would be good.
We also need a helper for old "full names" (Space.Name), i.e. the ones returned by #searchDocuments APIs
I would not like to see/write :
#foreach($docName in $xwiki.searchDocuments("where doc.author<>'XWiki.Admin'")) #set($myDoc = $xwiki.getDocument($services.model.resolveDocument($docName, "current"))) ## ... do something with myDoc #end
Sure but you will be supposed to use #searchDocumentReferences method, etc. The only issue is that not all APIs have the new reference based version yet but it will.
Thanks, Jerome.
Thanks -Vincent
_______________________________________________ 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
On 17/02/10 16:41, Thomas Mortagne wrote:
On Wed, Feb 17, 2010 at 16:11, Jerome Velociter<[email protected]> wrote:
On Feb 17, 2010, at 2:41 PM, Jerome Velociter wrote:
On Feb 17, 2010, at 11:42 AM, Vincent Massol wrote:
On Feb 17, 2010, at 11:35 AM, Jerome Velociter wrote:
>> On Wed, Feb 17, 2010 at 10:45, Jerome Velociter<[email protected]> >> wrote: >> >>>> Hi, >>>> >>>> I'd like to suggest the following strategy for now: >>>> >>>> * We modify all our vm files to use references (by using the >>>> ModelScriptService, see below) >>>> * We introduce APIs taking References in api.* (ex: api.Document, >>>> api.XWiki) >>>> * We _don't_ deprecate existing APIs in api.*. This means we allow >>>> users >>>> to use the older string APIs for ease of use >>>> >>> Hello Vincent, >>> >>> Before I can make up my mind, I would like to know: >>> >>> * What will be the strategy for velocity code in wiki pages (here >>> you >>> mention only .vm pages - will the strategy be voted again for wiki >>> pages?) >>> >>> * Considering we use the same strategy for wiki pages, and since we >>> do >>> not >>> deprecate the old APIs that manipulate strings, what will be the >>> 'recommanded' way of say getting a document ? (the one we would >>> advertise >>> on xwiki.org code examples for example) >>> >> To summarize: >> * String based methods: helper methods for users >> * EntityReference based methods: what we are supposed to use or >> anyone >> that want to write proper code >> > OK, that's what I wanted to know :) > > I share this vision, and would be -1 to deprecate string based APIs > (unless of course replaced with new string based helpers). I think > it's > important that we keep (velocity) simple scripting accessible to > non-developers and that was my concern. You don't want to force users > to > know/understand what a reference resolver is for instance. > ... and you'll get lots of complaints on the list telling us our software don't work because they'll have "forgotten" (or simply don't know about it) to escape special chars... ;)
> As for what we do for velocity code in our own wiki pages (not .vms), > I > would tend to think we should keep it simple to read for users (so > with > string based APIs) but I'm a bit undecided. > It's not a question of choice. There's simply no choice jerome.
If you don't use the reference-based apis then you have to manually perform parsing/serialization, i.e. manually recode the reference API.
Except of course for the cases where you know the full reference specifically and you can guarantee there's no special chars in it.
That's what I am talking about.
For example : $xwiki.getDocument('XWiki.Ratings') or $xwiki.ssx.use('XWiki.Ratings')
vs $xwiki.getDocument($services.model.createReference("XWiki", "Ratings"))
Actually in this case I'd be for adding a new method instead: $xwiki.getDocument("XWiki", "Ratings")
Yes that would be good.
We also need a helper for old "full names" (Space.Name), i.e. the ones returned by #searchDocuments APIs
I would not like to see/write :
#foreach($docName in $xwiki.searchDocuments("where doc.author<>'XWiki.Admin'")) #set($myDoc = $xwiki.getDocument($services.model.resolveDocument($docName, "current"))) ## ... do something with myDoc #end
Sure but you will be supposed to use #searchDocumentReferences method, etc. The only issue is that not all APIs have the new reference based version yet but it will.
OK, thanks for the explanations. I'm +1 for the strategy expressed by Vincent, especially +1 _not to_ deprecate old String APIs Jerome.
Thanks, Jerome.
Thanks -Vincent
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
On 02/17/2010 04:11 PM, Jerome Velociter wrote:
On Feb 17, 2010, at 2:41 PM, Jerome Velociter wrote:
On Feb 17, 2010, at 11:42 AM, Vincent Massol wrote:
On Feb 17, 2010, at 11:35 AM, Jerome Velociter wrote:
> On Wed, Feb 17, 2010 at 10:45, Jerome Velociter<[email protected]> > wrote: >>> Hi, >>> >>> I'd like to suggest the following strategy for now: >>> >>> * We modify all our vm files to use references (by using the >>> ModelScriptService, see below) >>> * We introduce APIs taking References in api.* (ex: api.Document, >>> api.XWiki) >>> * We _don't_ deprecate existing APIs in api.*. This means we allow >>> users >>> to use the older string APIs for ease of use >> >> Hello Vincent, >> >> Before I can make up my mind, I would like to know: >> >> * What will be the strategy for velocity code in wiki pages (here >> you >> mention only .vm pages - will the strategy be voted again for wiki >> pages?) >> >> * Considering we use the same strategy for wiki pages, and since we >> do >> not >> deprecate the old APIs that manipulate strings, what will be the >> 'recommanded' way of say getting a document ? (the one we would >> advertise >> on xwiki.org code examples for example) > > To summarize: > * String based methods: helper methods for users > * EntityReference based methods: what we are supposed to use or > anyone > that want to write proper code
OK, that's what I wanted to know :)
I share this vision, and would be -1 to deprecate string based APIs (unless of course replaced with new string based helpers). I think it's important that we keep (velocity) simple scripting accessible to non-developers and that was my concern. You don't want to force users to know/understand what a reference resolver is for instance.
... and you'll get lots of complaints on the list telling us our software don't work because they'll have "forgotten" (or simply don't know about it) to escape special chars... ;)
As for what we do for velocity code in our own wiki pages (not .vms), I would tend to think we should keep it simple to read for users (so with string based APIs) but I'm a bit undecided.
It's not a question of choice. There's simply no choice jerome.
If you don't use the reference-based apis then you have to manually perform parsing/serialization, i.e. manually recode the reference API.
Except of course for the cases where you know the full reference specifically and you can guarantee there's no special chars in it.
That's what I am talking about.
For example : $xwiki.getDocument('XWiki.Ratings') or $xwiki.ssx.use('XWiki.Ratings')
vs $xwiki.getDocument($services.model.createReference("XWiki", "Ratings"))
Actually in this case I'd be for adding a new method instead: $xwiki.getDocument("XWiki", "Ratings")
Yes that would be good.
We also need a helper for old "full names" (Space.Name), i.e. the ones returned by #searchDocuments APIs
I would not like to see/write :
#foreach($docName in $xwiki.searchDocuments("where doc.author<>'XWiki.Admin'")) #set($myDoc = $xwiki.getDocument($services.model.resolveDocument($docName, "current"))) ## ... do something with myDoc #end
There's $xwiki.wrapDocs -- Sergiu Dumitriu http://purl.org/net/sergiu/
On Wed, Feb 17, 2010 at 11:35, Jerome Velociter <[email protected]> wrote:
On Wed, Feb 17, 2010 at 10:45, Jerome Velociter <[email protected]> wrote:
Hi,
I'd like to suggest the following strategy for now:
* We modify all our vm files to use references (by using the ModelScriptService, see below) * We introduce APIs taking References in api.* (ex: api.Document, api.XWiki) * We _don't_ deprecate existing APIs in api.*. This means we allow users to use the older string APIs for ease of use
Hello Vincent,
Before I can make up my mind, I would like to know:
* What will be the strategy for velocity code in wiki pages (here you mention only .vm pages - will the strategy be voted again for wiki pages?)
* Considering we use the same strategy for wiki pages, and since we do not deprecate the old APIs that manipulate strings, what will be the 'recommanded' way of say getting a document ? (the one we would advertise on xwiki.org code examples for example)
To summarize: * String based methods: helper methods for users * EntityReference based methods: what we are supposed to use or anyone that want to write proper code
OK, that's what I wanted to know :)
I share this vision, and would be -1 to deprecate string based APIs (unless of course replaced with new string based helpers). I think it's important that we keep (velocity) simple scripting accessible to non-developers and that was my concern. You don't want to force users to know/understand what a reference resolver is for instance.
As for what we do for velocity code in our own wiki pages (not .vms), I would tend to think we should keep it simple to read for users (so with string based APIs) but I'm a bit undecided.
I don't agree with that, using strings generate a lot's of bugs. We are supposed to write good application so we should use proper APIs and anyway better give references based examples than string based examples. Also reference based code is not unreadable when already written it's just a little more difficult for the use to know how to create the proper reference to deal with reference based APIs.
Jerome
Thanks, Jerome
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne
On Wed, Feb 17, 2010 at 11:35, Jerome Velociter <[email protected]> wrote:
On Wed, Feb 17, 2010 at 10:45, Jerome Velociter <[email protected]> wrote:
Hi,
I'd like to suggest the following strategy for now:
* We modify all our vm files to use references (by using the ModelScriptService, see below) * We introduce APIs taking References in api.* (ex: api.Document, api.XWiki) * We _don't_ deprecate existing APIs in api.*. This means we allow users to use the older string APIs for ease of use
Hello Vincent,
Before I can make up my mind, I would like to know:
* What will be the strategy for velocity code in wiki pages (here you mention only .vm pages - will the strategy be voted again for wiki pages?)
* Considering we use the same strategy for wiki pages, and since we do not deprecate the old APIs that manipulate strings, what will be the 'recommanded' way of say getting a document ? (the one we would advertise on xwiki.org code examples for example)
To summarize: * String based methods: helper methods for users * EntityReference based methods: what we are supposed to use or anyone that want to write proper code
OK, that's what I wanted to know :)
I share this vision, and would be -1 to deprecate string based APIs (unless of course replaced with new string based helpers). I think it's important that we keep (velocity) simple scripting accessible to non-developers and that was my concern. You don't want to force users to know/understand what a reference resolver is for instance.
As for what we do for velocity code in our own wiki pages (not .vms), I would tend to think we should keep it simple to read for users (so with string based APIs) but I'm a bit undecided.
I don't agree with that, using strings generate a lot's of bugs. We are supposed to write good application so we should use proper APIs and anyway better give references based examples than string based examples.
Also reference based code is not unreadable when already written it's just a little more difficult for the use to know how to create the proper reference to deal with reference based APIs.
I read that : "you have to be a developer" :) Jerome.
Jerome
Thanks, Jerome
_______________________________________________ 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
On Feb 17, 2010, at 10:45 AM, Jerome Velociter wrote:
Hi,
I'd like to suggest the following strategy for now:
* We modify all our vm files to use references (by using the ModelScriptService, see below) * We introduce APIs taking References in api.* (ex: api.Document, api.XWiki) * We _don't_ deprecate existing APIs in api.*. This means we allow users to use the older string APIs for ease of use
Hello Vincent,
Before I can make up my mind, I would like to know:
* What will be the strategy for velocity code in wiki pages (here you mention only .vm pages - will the strategy be voted again for wiki pages?)
* Considering we use the same strategy for wiki pages, and since we do not deprecate the old APIs that manipulate strings, what will be the 'recommanded' way of say getting a document ? (the one we would advertise on xwiki.org code examples for example)
The decision to deprecate string-based APIs is open. I thought it was a bit early to do so before we have a proper full-fledged API from velocity. Maybe we'll do it in the future if we're happy about the referenced-based API. The pb with the string based-api is that it's error-prone and that alone would be a good reason to deprecate it relatively quickly once we have moved our code to use the referenced-based APIs. For ex: #set ($var = .....) $xwiki.getDocument("Main.${var}") Has a high chance of being wrong. If var contains a "." or ":" and it's not escaped then it'll be wrong. Thanks -Vincent
Thanks, Jerome
FYI here's what I've started adding in ModelScriptService:
@Component("model") public class ModelScriptService implements ScriptService { @Requirement private ComponentManager componentManager;
public DocumentReference createDocumentReference(String wiki, String space, String page, String hint) { EntityReference reference = null; if (!StringUtils.isEmpty(wiki)) { reference = new EntityReference(wiki, EntityType.WIKI); } if (!StringUtils.isEmpty(space)) { reference = new EntityReference(space, EntityType.SPACE, reference); } if (!StringUtils.isEmpty(page)) { reference = new EntityReference(page, EntityType.DOCUMENT, reference); }
DocumentReference documentReference; try { documentReference = this.componentManager.lookup(DocumentReferenceResolver.class, hint).resolve(reference); } catch (ComponentLookupException e) { documentReference = null; } return documentReference; }
public DocumentReference resolveDocument(String stringRepresentation, String hint) { DocumentReference result; try { result = this.componentManager.lookup(DocumentReferenceResolver.class, hint).resolve( stringRepresentation); } catch (ComponentLookupException e) { result = null; } return result; }
public String serialize(EntityReference reference, String hint) { String result; try { result = (String) this.componentManager.lookup(EntityReferenceSerializer.class, hint).serialize(reference); } catch (ComponentLookupException e) { result = null; } return result; } }
Thanks -Vincent _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
participants (4)
-
Jerome Velociter -
Sergiu Dumitriu -
Thomas Mortagne -
Vincent Massol