[xwiki-devs] [Proposal][Model] ResourceName refactoring
Hi, I'd like to propose a refactoring for org.xwiki.model.DocumentName/ AttachmentName. There are currently 2 problems with the current implementation: - DocumentName doesn't support nested spaces (we need that for the future) - We need to generalize the concept of resource names so that we can use the generic concept in the Model in some APIs Thus I'd like to propose: enum ResourceType - WIKI, DOCUMENT, SPACE, ATTACHMENT ResourceName - ResourceName(String name, ResourceName parent) - get/setName() - get/setParent(ResourceName) - get/setType(ResourceType) DocumentName extends ResourceName - DocumentName(String pageName, SpaceName parent) AttachmentName extends ResourceName - AttachmentName(String fileName, DocumentName parent) WikiName extends ResourceName - WikiName(String wikiName) SpaceName extends ResourceName - SpaceName(String spaceName, SpaceName parent) - SpaceName(String spaceName, WikiName parent) Open questions and comments ======================== - Should we replace "Name" by "Reference", i.e. DocumentReference instead of DocumentName, WikiReference instead of WikiName? - Note: A name (or reference) isn't resistant to change. Resources (Document, Space, Wiki, etc) must also have an Identifier (unique id) to uniquely identify them. For example a Document can be moved from one space to another (the DocumentName changes in this case). - The scheme above allows to map this easily to the JCR API - Do we want helper methods for locating the wiki in which a DocumentName is? That would mean adding: WikiName DocumentName.getWiki() (algo: getParent() till getType == WIKI or null) Same question for getting the last Space or Wiki from AttachmentName - Do we want a helper constructor to make it easier to create a DocumentName? With the proposal above it means: new DocumentName("page", new SpaceName("space", new WikiName("wiki"))); A helper constructor could be: DocumentName(String page, String space, String wiki). Problems: a) we would need another constructor to support a list of spaces and b) if there are fields other than the name to set on ResourceNames later on, it's not going to work as smoothly) Factory and Serializer ================= This is a big question I haven't yet solved. We have 2 options: 1) have specialized Factory/Serializer. For ex: DocumentNameFactory, DocumentNameSerializer 2) have generic ones: ResourceNameFactory/ResourceNameSerializer 2) seems nicer initially but the problem with 2) is that we need a global String representation of any resource in the system. There are 2 problems with that: - we may not want that. For example when the user is asked to enter a document name in a field, we may not need/want to parse this as a general resource that could for example point to an attachment (and btw as a consequence allow entering "@" which is our separator for attachments) - it's very hard to add new Resource types later on (since we'd need more special characters to separate them and this means these chars wouldn't be allowed in names for pages for ex) The other option is to have 2) but with the type passed as parameter: ResourceName ResourceNameFactory.create(String stringRepresentation, ResourceType) However this simply means that ResourceNameFactory would be a factory for actual factories (DocumentNameFactory, AttachmentNameFactory, etc) so I don't really see the added value in our component-based world (we can look up the right factory directly). Thus IMO we want 1). WDYT? Thanks -Vincent
On Tue, Dec 15, 2009 at 15:40, Vincent Massol <[email protected]> wrote:
Hi,
I'd like to propose a refactoring for org.xwiki.model.DocumentName/ AttachmentName.
There are currently 2 problems with the current implementation: - DocumentName doesn't support nested spaces (we need that for the future) - We need to generalize the concept of resource names so that we can use the generic concept in the Model in some APIs
Thus I'd like to propose:
enum ResourceType - WIKI, DOCUMENT, SPACE, ATTACHMENT
ResourceName - ResourceName(String name, ResourceName parent) - get/setName() - get/setParent(ResourceName) - get/setType(ResourceType)
DocumentName extends ResourceName - DocumentName(String pageName, SpaceName parent)
AttachmentName extends ResourceName - AttachmentName(String fileName, DocumentName parent)
WikiName extends ResourceName - WikiName(String wikiName)
SpaceName extends ResourceName - SpaceName(String spaceName, SpaceName parent) - SpaceName(String spaceName, WikiName parent)
Open questions and comments ========================
- Should we replace "Name" by "Reference", i.e. DocumentReference instead of DocumentName, WikiReference instead of WikiName?
"Reference" or "Path" or something like that yes since it's not really a name.
- Note: A name (or reference) isn't resistant to change. Resources (Document, Space, Wiki, etc) must also have an Identifier (unique id) to uniquely identify them. For example a Document can be moved from one space to another (the DocumentName changes in this case). - The scheme above allows to map this easily to the JCR API - Do we want helper methods for locating the wiki in which a DocumentName is? That would mean adding: WikiName DocumentName.getWiki() (algo: getParent() till getType == WIKI or null) Same question for getting the last Space or Wiki from AttachmentName
Seems useful yes, we are using it a lot in the current DocumentName.
- Do we want a helper constructor to make it easier to create a DocumentName? With the proposal above it means: new DocumentName("page", new SpaceName("space", new WikiName("wiki"))); A helper constructor could be: DocumentName(String page, String space, String wiki).
I don't think it's really necessary. We can always add it latter.
Problems: a) we would need another constructor to support a list of spaces and b) if there are fields other than the name to set on ResourceNames later on, it's not going to work as smoothly)
Factory and Serializer =================
This is a big question I haven't yet solved. We have 2 options: 1) have specialized Factory/Serializer. For ex: DocumentNameFactory, DocumentNameSerializer 2) have generic ones: ResourceNameFactory/ResourceNameSerializer
2) seems nicer initially but the problem with 2) is that we need a global String representation of any resource in the system. There are 2 problems with that: - we may not want that. For example when the user is asked to enter a document name in a field, we may not need/want to parse this as a general resource that could for example point to an attachment (and btw as a consequence allow entering "@" which is our separator for attachments) - it's very hard to add new Resource types later on (since we'd need more special characters to separate them and this means these chars wouldn't be allowed in names for pages for ex)
We need escaping support anyway, we can't continue to use a syntax that does not support all characters, it introduce important limitations for no reason. In a real syntax the special characters has nothing to do with the supported content...
The other option is to have 2) but with the type passed as parameter: ResourceName ResourceNameFactory.create(String stringRepresentation, ResourceType)
However this simply means that ResourceNameFactory would be a factory for actual factories (DocumentNameFactory, AttachmentNameFactory, etc) so I don't really see the added value in our component-based world (we can look up the right factory directly).
In this case I don't see the point of having lots of different components interfaces just to support this ResourceType parameter. Plus: - when you need to write another (un)serializer syntax for resources (URIResourceNameSerializer for example) it's a lot less work/classes - it's easier to handle escaping when you serialize in a central component like ResourceNameSerializer that knows all the syntaxes to escape. If you separate it in several different serializers WikiDocumentNameSerializer don't know it has to escape '@' for example since at its level attachment does not exists or you have to copy/past the code but with escaping of '@' in WikiAttachmentNameSerializer
Thus IMO we want 1).
+1 for 2), -0 for 1)
WDYT?
Thanks -Vincent _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne
On Dec 15, 2009, at 6:39 PM, Thomas Mortagne wrote:
On Tue, Dec 15, 2009 at 15:40, Vincent Massol <[email protected]> wrote:
Hi,
I'd like to propose a refactoring for org.xwiki.model.DocumentName/ AttachmentName.
There are currently 2 problems with the current implementation: - DocumentName doesn't support nested spaces (we need that for the future) - We need to generalize the concept of resource names so that we can use the generic concept in the Model in some APIs
Thus I'd like to propose:
enum ResourceType - WIKI, DOCUMENT, SPACE, ATTACHMENT
ResourceName - ResourceName(String name, ResourceName parent) - get/setName() - get/setParent(ResourceName) - get/setType(ResourceType)
DocumentName extends ResourceName - DocumentName(String pageName, SpaceName parent)
AttachmentName extends ResourceName - AttachmentName(String fileName, DocumentName parent)
WikiName extends ResourceName - WikiName(String wikiName)
SpaceName extends ResourceName - SpaceName(String spaceName, SpaceName parent) - SpaceName(String spaceName, WikiName parent)
Open questions and comments ========================
- Should we replace "Name" by "Reference", i.e. DocumentReference instead of DocumentName, WikiReference instead of WikiName?
"Reference" or "Path" or something like that yes since it's not really a name.
- Note: A name (or reference) isn't resistant to change. Resources (Document, Space, Wiki, etc) must also have an Identifier (unique id) to uniquely identify them. For example a Document can be moved from one space to another (the DocumentName changes in this case). - The scheme above allows to map this easily to the JCR API - Do we want helper methods for locating the wiki in which a DocumentName is? That would mean adding: WikiName DocumentName.getWiki() (algo: getParent() till getType == WIKI or null) Same question for getting the last Space or Wiki from AttachmentName
Seems useful yes, we are using it a lot in the current DocumentName.
- Do we want a helper constructor to make it easier to create a DocumentName? With the proposal above it means: new DocumentName("page", new SpaceName("space", new WikiName("wiki"))); A helper constructor could be: DocumentName(String page, String space, String wiki).
I don't think it's really necessary. We can always add it latter.
Problems: a) we would need another constructor to support a list of spaces and b) if there are fields other than the name to set on ResourceNames later on, it's not going to work as smoothly)
Factory and Serializer =================
This is a big question I haven't yet solved. We have 2 options: 1) have specialized Factory/Serializer. For ex: DocumentNameFactory, DocumentNameSerializer 2) have generic ones: ResourceNameFactory/ResourceNameSerializer
2) seems nicer initially but the problem with 2) is that we need a global String representation of any resource in the system. There are 2 problems with that: - we may not want that. For example when the user is asked to enter a document name in a field, we may not need/want to parse this as a general resource that could for example point to an attachment (and btw as a consequence allow entering "@" which is our separator for attachments) - it's very hard to add new Resource types later on (since we'd need more special characters to separate them and this means these chars wouldn't be allowed in names for pages for ex)
We need escaping support anyway, we can't continue to use a syntax that does not support all characters, it introduce important limitations for no reason. In a real syntax the special characters has nothing to do with the supported content...
The factory cannot know if it needs to escape the '@' char (for e ex). So it would the code handling the form (for ex) that would need to escape characters depending on what it is expecting (it would need to escape '@' for ex if it's expecting a document name and not escape it if it's expecting an attachment name). The multi-factory solution removes this problem. Thanks -Vincent
The other option is to have 2) but with the type passed as parameter: ResourceName ResourceNameFactory.create(String stringRepresentation, ResourceType)
However this simply means that ResourceNameFactory would be a factory for actual factories (DocumentNameFactory, AttachmentNameFactory, etc) so I don't really see the added value in our component-based world (we can look up the right factory directly).
In this case I don't see the point of having lots of different components interfaces just to support this ResourceType parameter. Plus: - when you need to write another (un)serializer syntax for resources (URIResourceNameSerializer for example) it's a lot less work/classes - it's easier to handle escaping when you serialize in a central component like ResourceNameSerializer that knows all the syntaxes to escape. If you separate it in several different serializers WikiDocumentNameSerializer don't know it has to escape '@' for example since at its level attachment does not exists or you have to copy/past the code but with escaping of '@' in WikiAttachmentNameSerializer
Thus IMO we want 1).
+1 for 2), -0 for 1)
WDYT?
Thanks -Vincent
On Tue, Dec 15, 2009 at 19:02, Vincent Massol <[email protected]> wrote:
On Dec 15, 2009, at 6:39 PM, Thomas Mortagne wrote:
On Tue, Dec 15, 2009 at 15:40, Vincent Massol <[email protected]> wrote:
Hi,
I'd like to propose a refactoring for org.xwiki.model.DocumentName/ AttachmentName.
There are currently 2 problems with the current implementation: - DocumentName doesn't support nested spaces (we need that for the future) - We need to generalize the concept of resource names so that we can use the generic concept in the Model in some APIs
Thus I'd like to propose:
enum ResourceType - WIKI, DOCUMENT, SPACE, ATTACHMENT
ResourceName - ResourceName(String name, ResourceName parent) - get/setName() - get/setParent(ResourceName) - get/setType(ResourceType)
DocumentName extends ResourceName - DocumentName(String pageName, SpaceName parent)
AttachmentName extends ResourceName - AttachmentName(String fileName, DocumentName parent)
WikiName extends ResourceName - WikiName(String wikiName)
SpaceName extends ResourceName - SpaceName(String spaceName, SpaceName parent) - SpaceName(String spaceName, WikiName parent)
Open questions and comments ========================
- Should we replace "Name" by "Reference", i.e. DocumentReference instead of DocumentName, WikiReference instead of WikiName?
"Reference" or "Path" or something like that yes since it's not really a name.
- Note: A name (or reference) isn't resistant to change. Resources (Document, Space, Wiki, etc) must also have an Identifier (unique id) to uniquely identify them. For example a Document can be moved from one space to another (the DocumentName changes in this case). - The scheme above allows to map this easily to the JCR API - Do we want helper methods for locating the wiki in which a DocumentName is? That would mean adding: WikiName DocumentName.getWiki() (algo: getParent() till getType == WIKI or null) Same question for getting the last Space or Wiki from AttachmentName
Seems useful yes, we are using it a lot in the current DocumentName.
- Do we want a helper constructor to make it easier to create a DocumentName? With the proposal above it means: new DocumentName("page", new SpaceName("space", new WikiName("wiki"))); A helper constructor could be: DocumentName(String page, String space, String wiki).
I don't think it's really necessary. We can always add it latter.
Problems: a) we would need another constructor to support a list of spaces and b) if there are fields other than the name to set on ResourceNames later on, it's not going to work as smoothly)
Factory and Serializer =================
This is a big question I haven't yet solved. We have 2 options: 1) have specialized Factory/Serializer. For ex: DocumentNameFactory, DocumentNameSerializer 2) have generic ones: ResourceNameFactory/ResourceNameSerializer
2) seems nicer initially but the problem with 2) is that we need a global String representation of any resource in the system. There are 2 problems with that: - we may not want that. For example when the user is asked to enter a document name in a field, we may not need/want to parse this as a general resource that could for example point to an attachment (and btw as a consequence allow entering "@" which is our separator for attachments) - it's very hard to add new Resource types later on (since we'd need more special characters to separate them and this means these chars wouldn't be allowed in names for pages for ex)
We need escaping support anyway, we can't continue to use a syntax that does not support all characters, it introduce important limitations for no reason. In a real syntax the special characters has nothing to do with the supported content...
The factory cannot know if it needs to escape the '@' char (for e ex). So it would the code handling the form (for ex) that would need to escape characters depending on what it is expecting (it would need to escape '@' for ex if it's expecting a document name and not escape it if it's expecting an attachment name).
The factory does not escape anything. A factory take a string in some syntax (syntax including escaping syntax) and parse it to create an object where all the part of the names are separated and unescaped. You have to give it a proper string, i don't see what it has to do with HTML form. I you want the factory to not take care of the attachment syntax part then you use ResourceNameFactory.create(String stringRepresentation, ResourceType.DOCUMENT) you put in your proposal...
The multi-factory solution removes this problem.
Multi-factory does not bring any value, it's the opposite. It will just generate more classes and code duplicate.
Thanks -Vincent
The other option is to have 2) but with the type passed as parameter: ResourceName ResourceNameFactory.create(String stringRepresentation, ResourceType)
However this simply means that ResourceNameFactory would be a factory for actual factories (DocumentNameFactory, AttachmentNameFactory, etc) so I don't really see the added value in our component-based world (we can look up the right factory directly).
In this case I don't see the point of having lots of different components interfaces just to support this ResourceType parameter. Plus: - when you need to write another (un)serializer syntax for resources (URIResourceNameSerializer for example) it's a lot less work/classes - it's easier to handle escaping when you serialize in a central component like ResourceNameSerializer that knows all the syntaxes to escape. If you separate it in several different serializers WikiDocumentNameSerializer don't know it has to escape '@' for example since at its level attachment does not exists or you have to copy/past the code but with escaping of '@' in WikiAttachmentNameSerializer
Thus IMO we want 1).
+1 for 2), -0 for 1)
WDYT?
Thanks -Vincent
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne
On Tue, Dec 15, 2009 at 20:39, Thomas Mortagne <[email protected]> wrote:
On Tue, Dec 15, 2009 at 19:02, Vincent Massol <[email protected]> wrote:
On Dec 15, 2009, at 6:39 PM, Thomas Mortagne wrote:
On Tue, Dec 15, 2009 at 15:40, Vincent Massol <[email protected]> wrote:
Hi,
I'd like to propose a refactoring for org.xwiki.model.DocumentName/ AttachmentName.
There are currently 2 problems with the current implementation: - DocumentName doesn't support nested spaces (we need that for the future) - We need to generalize the concept of resource names so that we can use the generic concept in the Model in some APIs
Thus I'd like to propose:
enum ResourceType - WIKI, DOCUMENT, SPACE, ATTACHMENT
Side note: what about the language part ? We need to starting thinking of it, it mainly depends of how we see it in the new model. Is it part of the model between documents and objects nodes or is it at the same level than objects as direct children of the document ?
ResourceName - ResourceName(String name, ResourceName parent) - get/setName() - get/setParent(ResourceName) - get/setType(ResourceType)
DocumentName extends ResourceName - DocumentName(String pageName, SpaceName parent)
AttachmentName extends ResourceName - AttachmentName(String fileName, DocumentName parent)
WikiName extends ResourceName - WikiName(String wikiName)
SpaceName extends ResourceName - SpaceName(String spaceName, SpaceName parent) - SpaceName(String spaceName, WikiName parent)
Open questions and comments ========================
- Should we replace "Name" by "Reference", i.e. DocumentReference instead of DocumentName, WikiReference instead of WikiName?
"Reference" or "Path" or something like that yes since it's not really a name.
- Note: A name (or reference) isn't resistant to change. Resources (Document, Space, Wiki, etc) must also have an Identifier (unique id) to uniquely identify them. For example a Document can be moved from one space to another (the DocumentName changes in this case). - The scheme above allows to map this easily to the JCR API - Do we want helper methods for locating the wiki in which a DocumentName is? That would mean adding: WikiName DocumentName.getWiki() (algo: getParent() till getType == WIKI or null) Same question for getting the last Space or Wiki from AttachmentName
Seems useful yes, we are using it a lot in the current DocumentName.
- Do we want a helper constructor to make it easier to create a DocumentName? With the proposal above it means: new DocumentName("page", new SpaceName("space", new WikiName("wiki"))); A helper constructor could be: DocumentName(String page, String space, String wiki).
I don't think it's really necessary. We can always add it latter.
Problems: a) we would need another constructor to support a list of spaces and b) if there are fields other than the name to set on ResourceNames later on, it's not going to work as smoothly)
Factory and Serializer =================
This is a big question I haven't yet solved. We have 2 options: 1) have specialized Factory/Serializer. For ex: DocumentNameFactory, DocumentNameSerializer 2) have generic ones: ResourceNameFactory/ResourceNameSerializer
2) seems nicer initially but the problem with 2) is that we need a global String representation of any resource in the system. There are 2 problems with that: - we may not want that. For example when the user is asked to enter a document name in a field, we may not need/want to parse this as a general resource that could for example point to an attachment (and btw as a consequence allow entering "@" which is our separator for attachments) - it's very hard to add new Resource types later on (since we'd need more special characters to separate them and this means these chars wouldn't be allowed in names for pages for ex)
We need escaping support anyway, we can't continue to use a syntax that does not support all characters, it introduce important limitations for no reason. In a real syntax the special characters has nothing to do with the supported content...
The factory cannot know if it needs to escape the '@' char (for e ex). So it would the code handling the form (for ex) that would need to escape characters depending on what it is expecting (it would need to escape '@' for ex if it's expecting a document name and not escape it if it's expecting an attachment name).
The factory does not escape anything. A factory take a string in some syntax (syntax including escaping syntax) and parse it to create an object where all the part of the names are separated and unescaped. You have to give it a proper string, i don't see what it has to do with HTML form.
I you want the factory to not take care of the attachment syntax part then you use ResourceNameFactory.create(String stringRepresentation, ResourceType.DOCUMENT) you put in your proposal...
The multi-factory solution removes this problem.
Multi-factory does not bring any value, it's the opposite. It will just generate more classes and code duplicate.
Thanks -Vincent
The other option is to have 2) but with the type passed as parameter: ResourceName ResourceNameFactory.create(String stringRepresentation, ResourceType)
However this simply means that ResourceNameFactory would be a factory for actual factories (DocumentNameFactory, AttachmentNameFactory, etc) so I don't really see the added value in our component-based world (we can look up the right factory directly).
In this case I don't see the point of having lots of different components interfaces just to support this ResourceType parameter. Plus: - when you need to write another (un)serializer syntax for resources (URIResourceNameSerializer for example) it's a lot less work/classes - it's easier to handle escaping when you serialize in a central component like ResourceNameSerializer that knows all the syntaxes to escape. If you separate it in several different serializers WikiDocumentNameSerializer don't know it has to escape '@' for example since at its level attachment does not exists or you have to copy/past the code but with escaping of '@' in WikiAttachmentNameSerializer
Thus IMO we want 1).
+1 for 2), -0 for 1)
WDYT?
Thanks -Vincent
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne
-- Thomas Mortagne
On Dec 15, 2009, at 9:01 PM, Thomas Mortagne wrote:
On Tue, Dec 15, 2009 at 20:39, Thomas Mortagne <[email protected]> wrote:
On Tue, Dec 15, 2009 at 19:02, Vincent Massol <[email protected]> wrote:
On Dec 15, 2009, at 6:39 PM, Thomas Mortagne wrote:
On Tue, Dec 15, 2009 at 15:40, Vincent Massol <[email protected]> wrote:
Hi,
I'd like to propose a refactoring for org.xwiki.model.DocumentName/ AttachmentName.
There are currently 2 problems with the current implementation: - DocumentName doesn't support nested spaces (we need that for the future) - We need to generalize the concept of resource names so that we can use the generic concept in the Model in some APIs
Thus I'd like to propose:
enum ResourceType - WIKI, DOCUMENT, SPACE, ATTACHMENT
Side note: what about the language part ? We need to starting thinking of it, it mainly depends of how we see it in the new model. Is it part of the model between documents and objects nodes or is it at the same level than objects as direct children of the document ?
It's a difficult question. I have thought quite a lot about it this morning (even changing my mind) and my latest opinion is that we should have the language part of the reference/path/name. One thing that convinced me is that I'd like that all our model APIs are compatible with the JCR specification and in JCR the language would be a Node and thus would appear in the path. OTOH the version wouldn't appear in the path in JCR since versions are handled for all versionable Nodes and is thus a cross-cutting concern. I suggest we do the same. I don't think we should go as far as having a ResourceName for the Language though so I'd like to propose: DocumentName - get/setLocale(Locale locale) Notes: - It wouldn't be in the constructor since it's optional (when not specified, the default language would be used). - Also note the use of Locale which IMO is much better than using a String (since for example "fr" can be for France, for Canada, for Belgium, etc). In our backward-compatible implementation we'd use only the language part probably since that's what's currently supported. - I'm hesitating between get/setLocale(Locale) and get/ setLanguage(Locale) but the pb is Locale.getLanguage() will be misleading vs get/setLanguage()(the same term "language" is used to represent different things). WDYT? Thanks -Vincent [snip]
On Thu, Dec 17, 2009 at 13:35, Vincent Massol <[email protected]> wrote:
On Dec 15, 2009, at 9:01 PM, Thomas Mortagne wrote:
On Tue, Dec 15, 2009 at 20:39, Thomas Mortagne <[email protected]> wrote:
On Tue, Dec 15, 2009 at 19:02, Vincent Massol <[email protected]> wrote:
On Dec 15, 2009, at 6:39 PM, Thomas Mortagne wrote:
On Tue, Dec 15, 2009 at 15:40, Vincent Massol <[email protected]> wrote:
Hi,
I'd like to propose a refactoring for org.xwiki.model.DocumentName/ AttachmentName.
There are currently 2 problems with the current implementation: - DocumentName doesn't support nested spaces (we need that for the future) - We need to generalize the concept of resource names so that we can use the generic concept in the Model in some APIs
Thus I'd like to propose:
enum ResourceType - WIKI, DOCUMENT, SPACE, ATTACHMENT
Side note: what about the language part ? We need to starting thinking of it, it mainly depends of how we see it in the new model. Is it part of the model between documents and objects nodes or is it at the same level than objects as direct children of the document ?
It's a difficult question. I have thought quite a lot about it this morning (even changing my mind) and my latest opinion is that we should have the language part of the reference/path/name. One thing that convinced me is that I'd like that all our model APIs are compatible with the JCR specification and in JCR the language would be a Node and thus would appear in the path.
OTOH the version wouldn't appear in the path in JCR since versions are handled for all versionable Nodes and is thus a cross-cutting concern.
I suggest we do the same.
I don't think we should go as far as having a ResourceName for the Language though so I'd like to propose:
DocumentName - get/setLocale(Locale locale)
And what does it would mean in the model ? Document(Space.Page) |__ DocumentTranslation(Space.Page.en) |__ DocumentTranslation(Space.Page.fr) |__ Object Document(Space.Page) |__ DocumentTranslation(Space.Page.en) |__ Object |__ DocumentTranslation(Space.Page.fr) |__ Object Document(Space.Page.en) |__ Object Document(Space.Page.fr) |__ Object [...] ?
Notes: - It wouldn't be in the constructor since it's optional (when not specified, the default language would be used).
What about the current language instead ? I makes a lot easier for an application to handle languages without having to take about it.
- Also note the use of Locale which IMO is much better than using a String (since for example "fr" can be for France, for Canada, for Belgium, etc). In our backward-compatible implementation we'd use only the language part probably since that's what's currently supported.
Big +1 for Locale
- I'm hesitating between get/setLocale(Locale) and get/ setLanguage(Locale) but the pb is Locale.getLanguage() will be misleading vs get/setLanguage()(the same term "language" is used to represent different things).
It's a locale so it should be get/setLocale(Locale) IMO
WDYT?
Thanks -Vincent
[snip]
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne
On Tue, Dec 15, 2009 at 20:39, Thomas Mortagne <[email protected]> wrote:
On Tue, Dec 15, 2009 at 19:02, Vincent Massol <[email protected]> wrote:
On Dec 15, 2009, at 6:39 PM, Thomas Mortagne wrote:
On Tue, Dec 15, 2009 at 15:40, Vincent Massol <[email protected]> wrote:
Hi,
I'd like to propose a refactoring for org.xwiki.model.DocumentName/ AttachmentName.
There are currently 2 problems with the current implementation: - DocumentName doesn't support nested spaces (we need that for the future) - We need to generalize the concept of resource names so that we can use the generic concept in the Model in some APIs
Thus I'd like to propose:
enum ResourceType - WIKI, DOCUMENT, SPACE, ATTACHMENT
ResourceName - ResourceName(String name, ResourceName parent) - get/setName() - get/setParent(ResourceName) - get/setType(ResourceType)
DocumentName extends ResourceName - DocumentName(String pageName, SpaceName parent)
AttachmentName extends ResourceName - AttachmentName(String fileName, DocumentName parent)
WikiName extends ResourceName - WikiName(String wikiName)
SpaceName extends ResourceName - SpaceName(String spaceName, SpaceName parent) - SpaceName(String spaceName, WikiName parent)
Open questions and comments ========================
- Should we replace "Name" by "Reference", i.e. DocumentReference instead of DocumentName, WikiReference instead of WikiName?
"Reference" or "Path" or something like that yes since it's not really a name.
- Note: A name (or reference) isn't resistant to change. Resources (Document, Space, Wiki, etc) must also have an Identifier (unique id) to uniquely identify them. For example a Document can be moved from one space to another (the DocumentName changes in this case). - The scheme above allows to map this easily to the JCR API - Do we want helper methods for locating the wiki in which a DocumentName is? That would mean adding: WikiName DocumentName.getWiki() (algo: getParent() till getType == WIKI or null) Same question for getting the last Space or Wiki from AttachmentName
Seems useful yes, we are using it a lot in the current DocumentName.
- Do we want a helper constructor to make it easier to create a DocumentName? With the proposal above it means: new DocumentName("page", new SpaceName("space", new WikiName("wiki"))); A helper constructor could be: DocumentName(String page, String space, String wiki).
I don't think it's really necessary. We can always add it latter.
Problems: a) we would need another constructor to support a list of spaces and b) if there are fields other than the name to set on ResourceNames later on, it's not going to work as smoothly)
Factory and Serializer =================
This is a big question I haven't yet solved. We have 2 options: 1) have specialized Factory/Serializer. For ex: DocumentNameFactory, DocumentNameSerializer 2) have generic ones: ResourceNameFactory/ResourceNameSerializer
2) seems nicer initially but the problem with 2) is that we need a global String representation of any resource in the system. There are 2 problems with that: - we may not want that. For example when the user is asked to enter a document name in a field, we may not need/want to parse this as a general resource that could for example point to an attachment (and btw as a consequence allow entering "@" which is our separator for attachments) - it's very hard to add new Resource types later on (since we'd need more special characters to separate them and this means these chars wouldn't be allowed in names for pages for ex)
We need escaping support anyway, we can't continue to use a syntax that does not support all characters, it introduce important limitations for no reason. In a real syntax the special characters has nothing to do with the supported content...
The factory cannot know if it needs to escape the '@' char (for e ex). So it would the code handling the form (for ex) that would need to escape characters depending on what it is expecting (it would need to escape '@' for ex if it's expecting a document name and not escape it if it's expecting an attachment name).
I think there is a misunderstanding, if what you mean is that ResourceNameFactory is too generic to know '@' syntax i don't see why. The resources types are an enum and not generic string in your proposal so ResourceNameFactory knows very well all the types and can decide to have different separators character for each element.
The factory does not escape anything. A factory take a string in some syntax (syntax including escaping syntax) and parse it to create an object where all the part of the names are separated and unescaped. You have to give it a proper string, i don't see what it has to do with HTML form.
I you want the factory to not take care of the attachment syntax part then you use ResourceNameFactory.create(String stringRepresentation, ResourceType.DOCUMENT) you put in your proposal...
The multi-factory solution removes this problem.
Multi-factory does not bring any value, it's the opposite. It will just generate more classes and code duplicate.
Thanks -Vincent
The other option is to have 2) but with the type passed as parameter: ResourceName ResourceNameFactory.create(String stringRepresentation, ResourceType)
However this simply means that ResourceNameFactory would be a factory for actual factories (DocumentNameFactory, AttachmentNameFactory, etc) so I don't really see the added value in our component-based world (we can look up the right factory directly).
In this case I don't see the point of having lots of different components interfaces just to support this ResourceType parameter. Plus: - when you need to write another (un)serializer syntax for resources (URIResourceNameSerializer for example) it's a lot less work/classes - it's easier to handle escaping when you serialize in a central component like ResourceNameSerializer that knows all the syntaxes to escape. If you separate it in several different serializers WikiDocumentNameSerializer don't know it has to escape '@' for example since at its level attachment does not exists or you have to copy/past the code but with escaping of '@' in WikiAttachmentNameSerializer
Thus IMO we want 1).
+1 for 2), -0 for 1)
WDYT?
Thanks -Vincent
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne
-- Thomas Mortagne
Should there be a ResourceType.OBJECT? If I were to redesign the core, I would make objects able to have "child" objects. That way Document, Attachment, Space and even Wiki could extend Object. It might be a lofty ideal but I think we ought to make our APIs so they would be compatible if we were to go that route. Caleb Thomas Mortagne wrote: > On Tue, Dec 15, 2009 at 20:39, Thomas Mortagne > <[email protected]> wrote: >> On Tue, Dec 15, 2009 at 19:02, Vincent Massol <[email protected]> wrote: >>> On Dec 15, 2009, at 6:39 PM, Thomas Mortagne wrote: >>> >>>> On Tue, Dec 15, 2009 at 15:40, Vincent Massol <[email protected]> >>>> wrote: >>>>> Hi, >>>>> >>>>> I'd like to propose a refactoring for org.xwiki.model.DocumentName/ >>>>> AttachmentName. >>>>> >>>>> There are currently 2 problems with the current implementation: >>>>> - DocumentName doesn't support nested spaces (we need that for the >>>>> future) >>>>> - We need to generalize the concept of resource names so that we can >>>>> use the generic concept in the Model in some APIs >>>>> >>>>> Thus I'd like to propose: >>>>> >>>>> enum ResourceType >>>>> - WIKI, DOCUMENT, SPACE, ATTACHMENT >>>>> >>>>> ResourceName >>>>> - ResourceName(String name, ResourceName parent) >>>>> - get/setName() >>>>> - get/setParent(ResourceName) >>>>> - get/setType(ResourceType) >>>>> >>>>> DocumentName extends ResourceName >>>>> - DocumentName(String pageName, SpaceName parent) >>>>> >>>>> AttachmentName extends ResourceName >>>>> - AttachmentName(String fileName, DocumentName parent) >>>>> >>>>> WikiName extends ResourceName >>>>> - WikiName(String wikiName) >>>>> >>>>> SpaceName extends ResourceName >>>>> - SpaceName(String spaceName, SpaceName parent) >>>>> - SpaceName(String spaceName, WikiName parent) >>>>> >>>>> Open questions and comments >>>>> ======================== >>>>> >>>>> - Should we replace "Name" by "Reference", i.e. DocumentReference >>>>> instead of DocumentName, WikiReference instead of WikiName? >>>> "Reference" or "Path" or something like that yes since it's not >>>> really a name. >>>> >>>>> - Note: A name (or reference) isn't resistant to change. Resources >>>>> (Document, Space, Wiki, etc) must also have an Identifier (unique id) >>>>> to uniquely identify them. For example a Document can be moved from >>>>> one space to another (the DocumentName changes in this case). >>>>> - The scheme above allows to map this easily to the JCR API >>>>> - Do we want helper methods for locating the wiki in which a >>>>> DocumentName is? That would mean adding: >>>>> WikiName DocumentName.getWiki() (algo: getParent() till getType == >>>>> WIKI or null) >>>>> Same question for getting the last Space or Wiki from AttachmentName >>>> Seems useful yes, we are using it a lot in the current DocumentName. >>>> >>>>> - Do we want a helper constructor to make it easier to create a >>>>> DocumentName? With the proposal above it means: >>>>> new DocumentName("page", new SpaceName("space", new >>>>> WikiName("wiki"))); >>>>> A helper constructor could be: DocumentName(String page, String >>>>> space, >>>>> String wiki). >>>> I don't think it's really necessary. We can always add it latter. >>>> >>>>> Problems: a) we would need another constructor to support a list of >>>>> spaces and b) if there are fields other than the name to set on >>>>> ResourceNames later on, it's not going to work as smoothly) >>>>> >>>>> Factory and Serializer >>>>> ================= >>>>> >>>>> This is a big question I haven't yet solved. We have 2 options: >>>>> 1) have specialized Factory/Serializer. For ex: DocumentNameFactory, >>>>> DocumentNameSerializer >>>>> 2) have generic ones: ResourceNameFactory/ResourceNameSerializer >>>>> >>>>> 2) seems nicer initially but the problem with 2) is that we need a >>>>> global String representation of any resource in the system. There are >>>>> 2 problems with that: >>>>> - we may not want that. For example when the user is asked to enter a >>>>> document name in a field, we may not need/want to parse this as a >>>>> general resource that could for example point to an attachment (and >>>>> btw as a consequence allow entering "@" which is our separator for >>>>> attachments) >>>>> - it's very hard to add new Resource types later on (since we'd need >>>>> more special characters to separate them and this means these chars >>>>> wouldn't be allowed in names for pages for ex) >>>> We need escaping support anyway, we can't continue to use a syntax >>>> that does not support all characters, it introduce important >>>> limitations for no reason. In a real syntax the special characters has >>>> nothing to do with the supported content... >>> The factory cannot know if it needs to escape the '@' char (for e ex). >>> So it would the code handling the form (for ex) that would need to >>> escape characters depending on what it is expecting (it would need to >>> escape '@' for ex if it's expecting a document name and not escape it >>> if it's expecting an attachment name). > > I think there is a misunderstanding, if what you mean is that > ResourceNameFactory is too generic to know '@' syntax i don't see why. > The resources types are an enum and not generic string in your > proposal so ResourceNameFactory knows very well all the types and can > decide to have different separators character for each element. > >> The factory does not escape anything. A factory take a string in some >> syntax (syntax including escaping syntax) and parse it to create an >> object where all the part of the names are separated and unescaped. >> You have to give it a proper string, i don't see what it has to do >> with HTML form. >> >> I you want the factory to not take care of the attachment syntax part >> then you use ResourceNameFactory.create(String stringRepresentation, >> ResourceType.DOCUMENT) you put in your proposal... >> >>> The multi-factory solution removes this problem. >> Multi-factory does not bring any value, it's the opposite. It will >> just generate more classes and code duplicate. >> >>> Thanks >>> -Vincent >>> >>>>> The other option is to have 2) but with the type passed as parameter: >>>>> ResourceName ResourceNameFactory.create(String stringRepresentation, >>>>> ResourceType) >>>>> >>>>> However this simply means that ResourceNameFactory would be a factory >>>>> for actual factories (DocumentNameFactory, AttachmentNameFactory, >>>>> etc) >>>>> so I don't really see the added value in our component-based world >>>>> (we >>>>> can look up the right factory directly). >>>> In this case I don't see the point of having lots of different >>>> components interfaces just to support this ResourceType parameter. >>>> Plus: >>>> - when you need to write another (un)serializer syntax for resources >>>> (URIResourceNameSerializer for example) it's a lot less work/classes >>>> - it's easier to handle escaping when you serialize in a central >>>> component like ResourceNameSerializer that knows all the syntaxes to >>>> escape. If you separate it in several different serializers >>>> WikiDocumentNameSerializer don't know it has to escape '@' for example >>>> since at its level attachment does not exists or you have to copy/past >>>> the code but with escaping of '@' in WikiAttachmentNameSerializer >>>> >>>>> Thus IMO we want 1). >>>> +1 for 2), -0 for 1) >>>> >>>>> WDYT? >>>>> >>>>> Thanks >>>>> -Vincent >>> _______________________________________________ >>> devs mailing list >>> [email protected] >>> http://lists.xwiki.org/mailman/listinfo/devs >>> >> >> >> -- >> Thomas Mortagne >> > > >
Hi Caleb, On Dec 16, 2009, at 1:46 AM, Caleb James DeLisle wrote: > Should there be a ResourceType.OBJECT? Yes definitely. I haven't put everything in this proposal. But yes the idea is to have OBJECT and PROPERTY too and possibly others too. What's important to me in the proposal at this stage is that it's extensible and can allow other types to be added easily later on. Note that the next step will be to propose some textual syntax to represent all resource types. We'll probably start by implementing it with the current syntax but can change it later on when we're ready to move (the current syntax for docs for ex is: "Wiki:Space.Page" and for attachments it's "Wiki:Space.Page@Filename"). We need a new format since this old one doesn't support: - Nested spaces - Escaping (to allow chars such as ":", "@") - Make the syntax less "fragile" (by doubling special keywords for ex to prevent having to escape special chars all the time) > If I were to redesign the core, I would make objects able to have > "child" > objects. That way Document, Attachment, Space and even Wiki could > extend Object. > It might be a lofty ideal but I think we ought to make our APIs so > they > would be compatible if we were to go that route. Yes, I agree. I'm still working on a proposal for the new model. You can see the work in progress here: http://svn.xwiki.org/svnroot/xwiki/contrib/sandbox/xwiki-model/ Thanks -Vincent > Caleb > > Thomas Mortagne wrote: >> On Tue, Dec 15, 2009 at 20:39, Thomas Mortagne >> <[email protected]> wrote: >>> On Tue, Dec 15, 2009 at 19:02, Vincent Massol <[email protected]> >>> wrote: >>>> On Dec 15, 2009, at 6:39 PM, Thomas Mortagne wrote: >>>> >>>>> On Tue, Dec 15, 2009 at 15:40, Vincent Massol <[email protected]> >>>>> wrote: >>>>>> Hi, >>>>>> >>>>>> I'd like to propose a refactoring for >>>>>> org.xwiki.model.DocumentName/ >>>>>> AttachmentName. >>>>>> >>>>>> There are currently 2 problems with the current implementation: >>>>>> - DocumentName doesn't support nested spaces (we need that for >>>>>> the >>>>>> future) >>>>>> - We need to generalize the concept of resource names so that >>>>>> we can >>>>>> use the generic concept in the Model in some APIs >>>>>> >>>>>> Thus I'd like to propose: >>>>>> >>>>>> enum ResourceType >>>>>> - WIKI, DOCUMENT, SPACE, ATTACHMENT >>>>>> >>>>>> ResourceName >>>>>> - ResourceName(String name, ResourceName parent) >>>>>> - get/setName() >>>>>> - get/setParent(ResourceName) >>>>>> - get/setType(ResourceType) >>>>>> >>>>>> DocumentName extends ResourceName >>>>>> - DocumentName(String pageName, SpaceName parent) >>>>>> >>>>>> AttachmentName extends ResourceName >>>>>> - AttachmentName(String fileName, DocumentName parent) >>>>>> >>>>>> WikiName extends ResourceName >>>>>> - WikiName(String wikiName) >>>>>> >>>>>> SpaceName extends ResourceName >>>>>> - SpaceName(String spaceName, SpaceName parent) >>>>>> - SpaceName(String spaceName, WikiName parent) >>>>>> >>>>>> Open questions and comments >>>>>> ======================== >>>>>> >>>>>> - Should we replace "Name" by "Reference", i.e. DocumentReference >>>>>> instead of DocumentName, WikiReference instead of WikiName? >>>>> "Reference" or "Path" or something like that yes since it's not >>>>> really a name. >>>>> >>>>>> - Note: A name (or reference) isn't resistant to change. >>>>>> Resources >>>>>> (Document, Space, Wiki, etc) must also have an Identifier >>>>>> (unique id) >>>>>> to uniquely identify them. For example a Document can be moved >>>>>> from >>>>>> one space to another (the DocumentName changes in this case). >>>>>> - The scheme above allows to map this easily to the JCR API >>>>>> - Do we want helper methods for locating the wiki in which a >>>>>> DocumentName is? That would mean adding: >>>>>> WikiName DocumentName.getWiki() (algo: getParent() till getType >>>>>> == >>>>>> WIKI or null) >>>>>> Same question for getting the last Space or Wiki from >>>>>> AttachmentName >>>>> Seems useful yes, we are using it a lot in the current >>>>> DocumentName. >>>>> >>>>>> - Do we want a helper constructor to make it easier to create a >>>>>> DocumentName? With the proposal above it means: >>>>>> new DocumentName("page", new SpaceName("space", new >>>>>> WikiName("wiki"))); >>>>>> A helper constructor could be: DocumentName(String page, String >>>>>> space, >>>>>> String wiki). >>>>> I don't think it's really necessary. We can always add it latter. >>>>> >>>>>> Problems: a) we would need another constructor to support a >>>>>> list of >>>>>> spaces and b) if there are fields other than the name to set on >>>>>> ResourceNames later on, it's not going to work as smoothly) >>>>>> >>>>>> Factory and Serializer >>>>>> ================= >>>>>> >>>>>> This is a big question I haven't yet solved. We have 2 options: >>>>>> 1) have specialized Factory/Serializer. For ex: >>>>>> DocumentNameFactory, >>>>>> DocumentNameSerializer >>>>>> 2) have generic ones: ResourceNameFactory/ResourceNameSerializer >>>>>> >>>>>> 2) seems nicer initially but the problem with 2) is that we >>>>>> need a >>>>>> global String representation of any resource in the system. >>>>>> There are >>>>>> 2 problems with that: >>>>>> - we may not want that. For example when the user is asked to >>>>>> enter a >>>>>> document name in a field, we may not need/want to parse this as a >>>>>> general resource that could for example point to an attachment >>>>>> (and >>>>>> btw as a consequence allow entering "@" which is our separator >>>>>> for >>>>>> attachments) >>>>>> - it's very hard to add new Resource types later on (since we'd >>>>>> need >>>>>> more special characters to separate them and this means these >>>>>> chars >>>>>> wouldn't be allowed in names for pages for ex) >>>>> We need escaping support anyway, we can't continue to use a syntax >>>>> that does not support all characters, it introduce important >>>>> limitations for no reason. In a real syntax the special >>>>> characters has >>>>> nothing to do with the supported content... >>>> The factory cannot know if it needs to escape the '@' char (for e >>>> ex). >>>> So it would the code handling the form (for ex) that would need to >>>> escape characters depending on what it is expecting (it would >>>> need to >>>> escape '@' for ex if it's expecting a document name and not >>>> escape it >>>> if it's expecting an attachment name). >> >> I think there is a misunderstanding, if what you mean is that >> ResourceNameFactory is too generic to know '@' syntax i don't see >> why. >> The resources types are an enum and not generic string in your >> proposal so ResourceNameFactory knows very well all the types and can >> decide to have different separators character for each element. >> >>> The factory does not escape anything. A factory take a string in >>> some >>> syntax (syntax including escaping syntax) and parse it to create an >>> object where all the part of the names are separated and unescaped. >>> You have to give it a proper string, i don't see what it has to do >>> with HTML form. >>> >>> I you want the factory to not take care of the attachment syntax >>> part >>> then you use ResourceNameFactory.create(String stringRepresentation, >>> ResourceType.DOCUMENT) you put in your proposal... >>> >>>> The multi-factory solution removes this problem. >>> Multi-factory does not bring any value, it's the opposite. It will >>> just generate more classes and code duplicate. >>> >>>> Thanks >>>> -Vincent >>>> >>>>>> The other option is to have 2) but with the type passed as >>>>>> parameter: >>>>>> ResourceName ResourceNameFactory.create(String >>>>>> stringRepresentation, >>>>>> ResourceType) >>>>>> >>>>>> However this simply means that ResourceNameFactory would be a >>>>>> factory >>>>>> for actual factories (DocumentNameFactory, AttachmentNameFactory, >>>>>> etc) >>>>>> so I don't really see the added value in our component-based >>>>>> world >>>>>> (we >>>>>> can look up the right factory directly). >>>>> In this case I don't see the point of having lots of different >>>>> components interfaces just to support this ResourceType parameter. >>>>> Plus: >>>>> - when you need to write another (un)serializer syntax for >>>>> resources >>>>> (URIResourceNameSerializer for example) it's a lot less work/ >>>>> classes >>>>> - it's easier to handle escaping when you serialize in a central >>>>> component like ResourceNameSerializer that knows all the >>>>> syntaxes to >>>>> escape. If you separate it in several different serializers >>>>> WikiDocumentNameSerializer don't know it has to escape '@' for >>>>> example >>>>> since at its level attachment does not exists or you have to >>>>> copy/past >>>>> the code but with escaping of '@' in WikiAttachmentNameSerializer >>>>> >>>>>> Thus IMO we want 1). >>>>> +1 for 2), -0 for 1) >>>>> >>>>>> WDYT? >>>>>> >>>>>> Thanks >>>>>> -Vincent
On Tue, Dec 15, 2009 at 18:39, Thomas Mortagne <[email protected]> wrote:
On Tue, Dec 15, 2009 at 15:40, Vincent Massol <[email protected]> wrote:
Hi,
I'd like to propose a refactoring for org.xwiki.model.DocumentName/ AttachmentName.
There are currently 2 problems with the current implementation: - DocumentName doesn't support nested spaces (we need that for the future) - We need to generalize the concept of resource names so that we can use the generic concept in the Model in some APIs
Thus I'd like to propose:
enum ResourceType - WIKI, DOCUMENT, SPACE, ATTACHMENT
ResourceName - ResourceName(String name, ResourceName parent) - get/setName() - get/setParent(ResourceName) - get/setType(ResourceType)
DocumentName extends ResourceName - DocumentName(String pageName, SpaceName parent)
AttachmentName extends ResourceName - AttachmentName(String fileName, DocumentName parent)
WikiName extends ResourceName - WikiName(String wikiName)
SpaceName extends ResourceName - SpaceName(String spaceName, SpaceName parent) - SpaceName(String spaceName, WikiName parent)
Open questions and comments ========================
- Should we replace "Name" by "Reference", i.e. DocumentReference instead of DocumentName, WikiReference instead of WikiName?
"Reference" or "Path" or something like that yes since it's not really a name.
- Note: A name (or reference) isn't resistant to change. Resources (Document, Space, Wiki, etc) must also have an Identifier (unique id) to uniquely identify them. For example a Document can be moved from one space to another (the DocumentName changes in this case). - The scheme above allows to map this easily to the JCR API - Do we want helper methods for locating the wiki in which a DocumentName is? That would mean adding: WikiName DocumentName.getWiki() (algo: getParent() till getType == WIKI or null) Same question for getting the last Space or Wiki from AttachmentName
Seems useful yes, we are using it a lot in the current DocumentName.
- Do we want a helper constructor to make it easier to create a DocumentName? With the proposal above it means: new DocumentName("page", new SpaceName("space", new WikiName("wiki"))); A helper constructor could be: DocumentName(String page, String space, String wiki).
I don't think it's really necessary. We can always add it latter.
Problems: a) we would need another constructor to support a list of spaces and b) if there are fields other than the name to set on ResourceNames later on, it's not going to work as smoothly)
Factory and Serializer =================
This is a big question I haven't yet solved. We have 2 options: 1) have specialized Factory/Serializer. For ex: DocumentNameFactory, DocumentNameSerializer 2) have generic ones: ResourceNameFactory/ResourceNameSerializer
2) seems nicer initially but the problem with 2) is that we need a global String representation of any resource in the system. There are 2 problems with that: - we may not want that. For example when the user is asked to enter a document name in a field, we may not need/want to parse this as a general resource that could for example point to an attachment (and btw as a consequence allow entering "@" which is our separator for attachments) - it's very hard to add new Resource types later on (since we'd need more special characters to separate them and this means these chars wouldn't be allowed in names for pages for ex)
We need escaping support anyway, we can't continue to use a syntax that does not support all characters, it introduce important limitations for no reason. In a real syntax the special characters has nothing to do with the supported content...
The other option is to have 2) but with the type passed as parameter: ResourceName ResourceNameFactory.create(String stringRepresentation, ResourceType)
However this simply means that ResourceNameFactory would be a factory for actual factories (DocumentNameFactory, AttachmentNameFactory, etc) so I don't really see the added value in our component-based world (we can look up the right factory directly).
In this case I don't see the point of having lots of different components interfaces just to support this ResourceType parameter. Plus: - when you need to write another (un)serializer syntax for resources (URIResourceNameSerializer for example) it's a lot less work/classes - it's easier to handle escaping when you serialize in a central component like ResourceNameSerializer that knows all the syntaxes to escape. If you separate it in several different serializers WikiDocumentNameSerializer don't know it has to escape '@' for example since at its level attachment does not exists or you have to copy/past the code but with escaping of '@' in WikiAttachmentNameSerializer
- actually the worst i think is that 2) make pretty much impossible to renderer a generic ResourceName . DocumentName, AttachmentNames etc... are supposed to be only helpers to make easier to manipulate a generic ResourceName but with 2) It mean instead of being generic ResourceName is not more that an abstract class...
Thus IMO we want 1).
+1 for 2), -0 for 1)
WDYT?
Thanks -Vincent _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne
-- Thomas Mortagne
On Dec 16, 2009, at 9:40 AM, Thomas Mortagne wrote:
On Tue, Dec 15, 2009 at 18:39, Thomas Mortagne <[email protected]> wrote:
On Tue, Dec 15, 2009 at 15:40, Vincent Massol <[email protected]> wrote:
Hi,
I'd like to propose a refactoring for org.xwiki.model.DocumentName/ AttachmentName.
There are currently 2 problems with the current implementation: - DocumentName doesn't support nested spaces (we need that for the future) - We need to generalize the concept of resource names so that we can use the generic concept in the Model in some APIs
Thus I'd like to propose:
enum ResourceType - WIKI, DOCUMENT, SPACE, ATTACHMENT
ResourceName - ResourceName(String name, ResourceName parent) - get/setName() - get/setParent(ResourceName) - get/setType(ResourceType)
DocumentName extends ResourceName - DocumentName(String pageName, SpaceName parent)
AttachmentName extends ResourceName - AttachmentName(String fileName, DocumentName parent)
WikiName extends ResourceName - WikiName(String wikiName)
SpaceName extends ResourceName - SpaceName(String spaceName, SpaceName parent) - SpaceName(String spaceName, WikiName parent)
Open questions and comments ========================
- Should we replace "Name" by "Reference", i.e. DocumentReference instead of DocumentName, WikiReference instead of WikiName?
"Reference" or "Path" or something like that yes since it's not really a name.
- Note: A name (or reference) isn't resistant to change. Resources (Document, Space, Wiki, etc) must also have an Identifier (unique id) to uniquely identify them. For example a Document can be moved from one space to another (the DocumentName changes in this case). - The scheme above allows to map this easily to the JCR API - Do we want helper methods for locating the wiki in which a DocumentName is? That would mean adding: WikiName DocumentName.getWiki() (algo: getParent() till getType == WIKI or null) Same question for getting the last Space or Wiki from AttachmentName
Seems useful yes, we are using it a lot in the current DocumentName.
- Do we want a helper constructor to make it easier to create a DocumentName? With the proposal above it means: new DocumentName("page", new SpaceName("space", new WikiName("wiki"))); A helper constructor could be: DocumentName(String page, String space, String wiki).
I don't think it's really necessary. We can always add it latter.
Problems: a) we would need another constructor to support a list of spaces and b) if there are fields other than the name to set on ResourceNames later on, it's not going to work as smoothly)
Factory and Serializer =================
This is a big question I haven't yet solved. We have 2 options: 1) have specialized Factory/Serializer. For ex: DocumentNameFactory, DocumentNameSerializer 2) have generic ones: ResourceNameFactory/ResourceNameSerializer
2) seems nicer initially but the problem with 2) is that we need a global String representation of any resource in the system. There are 2 problems with that: - we may not want that. For example when the user is asked to enter a document name in a field, we may not need/want to parse this as a general resource that could for example point to an attachment (and btw as a consequence allow entering "@" which is our separator for attachments) - it's very hard to add new Resource types later on (since we'd need more special characters to separate them and this means these chars wouldn't be allowed in names for pages for ex)
We need escaping support anyway, we can't continue to use a syntax that does not support all characters, it introduce important limitations for no reason. In a real syntax the special characters has nothing to do with the supported content...
The other option is to have 2) but with the type passed as parameter: ResourceName ResourceNameFactory.create(String stringRepresentation, ResourceType)
However this simply means that ResourceNameFactory would be a factory for actual factories (DocumentNameFactory, AttachmentNameFactory, etc) so I don't really see the added value in our component-based world (we can look up the right factory directly).
In this case I don't see the point of having lots of different components interfaces just to support this ResourceType parameter. Plus: - when you need to write another (un)serializer syntax for resources (URIResourceNameSerializer for example) it's a lot less work/classes - it's easier to handle escaping when you serialize in a central component like ResourceNameSerializer that knows all the syntaxes to escape. If you separate it in several different serializers WikiDocumentNameSerializer don't know it has to escape '@' for example since at its level attachment does not exists or you have to copy/ past the code but with escaping of '@' in WikiAttachmentNameSerializer
- actually the worst i think is that 2) make pretty much impossible to renderer a generic ResourceName . DocumentName, AttachmentNames etc... are supposed to be only helpers to make easier to manipulate a generic ResourceName but with 2) It mean instead of being generic ResourceName is not more that an abstract class...
Ok, I agree. I'd like to use this signature though: ResourceNameFactory.create(String textualRepresentation, ResourceType type) The reason is that we need to know what the text represents in order to have a performant implementation and also because the text passed shouldn't have to escape "@" for example if it represents a Document name since it's a character allowed in a document name. Thanks -Vincent
Thus IMO we want 1).
+1 for 2), -0 for 1)
WDYT?
Thanks -Vincent
On Thu, Dec 17, 2009 at 13:57, Vincent Massol <[email protected]> wrote:
On Dec 16, 2009, at 9:40 AM, Thomas Mortagne wrote:
On Tue, Dec 15, 2009 at 18:39, Thomas Mortagne <[email protected]> wrote:
On Tue, Dec 15, 2009 at 15:40, Vincent Massol <[email protected]> wrote:
Hi,
I'd like to propose a refactoring for org.xwiki.model.DocumentName/ AttachmentName.
There are currently 2 problems with the current implementation: - DocumentName doesn't support nested spaces (we need that for the future) - We need to generalize the concept of resource names so that we can use the generic concept in the Model in some APIs
Thus I'd like to propose:
enum ResourceType - WIKI, DOCUMENT, SPACE, ATTACHMENT
ResourceName - ResourceName(String name, ResourceName parent) - get/setName() - get/setParent(ResourceName) - get/setType(ResourceType)
DocumentName extends ResourceName - DocumentName(String pageName, SpaceName parent)
AttachmentName extends ResourceName - AttachmentName(String fileName, DocumentName parent)
WikiName extends ResourceName - WikiName(String wikiName)
SpaceName extends ResourceName - SpaceName(String spaceName, SpaceName parent) - SpaceName(String spaceName, WikiName parent)
Open questions and comments ========================
- Should we replace "Name" by "Reference", i.e. DocumentReference instead of DocumentName, WikiReference instead of WikiName?
"Reference" or "Path" or something like that yes since it's not really a name.
- Note: A name (or reference) isn't resistant to change. Resources (Document, Space, Wiki, etc) must also have an Identifier (unique id) to uniquely identify them. For example a Document can be moved from one space to another (the DocumentName changes in this case). - The scheme above allows to map this easily to the JCR API - Do we want helper methods for locating the wiki in which a DocumentName is? That would mean adding: WikiName DocumentName.getWiki() (algo: getParent() till getType == WIKI or null) Same question for getting the last Space or Wiki from AttachmentName
Seems useful yes, we are using it a lot in the current DocumentName.
- Do we want a helper constructor to make it easier to create a DocumentName? With the proposal above it means: new DocumentName("page", new SpaceName("space", new WikiName("wiki"))); A helper constructor could be: DocumentName(String page, String space, String wiki).
I don't think it's really necessary. We can always add it latter.
Problems: a) we would need another constructor to support a list of spaces and b) if there are fields other than the name to set on ResourceNames later on, it's not going to work as smoothly)
Factory and Serializer =================
This is a big question I haven't yet solved. We have 2 options: 1) have specialized Factory/Serializer. For ex: DocumentNameFactory, DocumentNameSerializer 2) have generic ones: ResourceNameFactory/ResourceNameSerializer
2) seems nicer initially but the problem with 2) is that we need a global String representation of any resource in the system. There are 2 problems with that: - we may not want that. For example when the user is asked to enter a document name in a field, we may not need/want to parse this as a general resource that could for example point to an attachment (and btw as a consequence allow entering "@" which is our separator for attachments) - it's very hard to add new Resource types later on (since we'd need more special characters to separate them and this means these chars wouldn't be allowed in names for pages for ex)
We need escaping support anyway, we can't continue to use a syntax that does not support all characters, it introduce important limitations for no reason. In a real syntax the special characters has nothing to do with the supported content...
The other option is to have 2) but with the type passed as parameter: ResourceName ResourceNameFactory.create(String stringRepresentation, ResourceType)
However this simply means that ResourceNameFactory would be a factory for actual factories (DocumentNameFactory, AttachmentNameFactory, etc) so I don't really see the added value in our component-based world (we can look up the right factory directly).
In this case I don't see the point of having lots of different components interfaces just to support this ResourceType parameter. Plus: - when you need to write another (un)serializer syntax for resources (URIResourceNameSerializer for example) it's a lot less work/classes - it's easier to handle escaping when you serialize in a central component like ResourceNameSerializer that knows all the syntaxes to escape. If you separate it in several different serializers WikiDocumentNameSerializer don't know it has to escape '@' for example since at its level attachment does not exists or you have to copy/ past the code but with escaping of '@' in WikiAttachmentNameSerializer
- actually the worst i think is that 2) make pretty much impossible to renderer a generic ResourceName . DocumentName, AttachmentNames etc... are supposed to be only helpers to make easier to manipulate a generic ResourceName but with 2) It mean instead of being generic ResourceName is not more that an abstract class...
Ok, I agree. I'd like to use this signature though: ResourceNameFactory.create(String textualRepresentation, ResourceType type)
The reason is that we need to know what the text represents in order to have a performant implementation and also because the text passed shouldn't have to escape "@" for example if it represents a Document name since it's a character allowed in a document name.
Ok for me. Note that ResourceNameSerializer does not need that (since the type is located in the ResourceName itself).
Thanks -Vincent
Thus IMO we want 1).
+1 for 2), -0 for 1)
WDYT?
Thanks -Vincent
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne
participants (3)
-
Caleb James DeLisle -
Thomas Mortagne -
Vincent Massol