On Thu, Dec 17, 2009 at 13:57, Vincent Massol <vinc...@massol.net> wrote:
>
> On Dec 16, 2009, at 9:40 AM, Thomas Mortagne wrote:
>
>> On Tue, Dec 15, 2009 at 18:39, Thomas Mortagne
>> <thomas.morta...@xwiki.com> wrote:
>>> On Tue, Dec 15, 2009 at 15:40, Vincent Massol <vinc...@massol.net>
>>> 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
> devs@xwiki.org
> http://lists.xwiki.org/mailman/listinfo/devs
>
--
Thomas Mortagne
_______________________________________________
devs mailing list
devs@xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs
