[xwiki-dev] [ArchitectureV2] Model proposal

[Vincent Massol]

On Jun 4, 2007, at 9:34 PM, Sergiu Dumitriu wrote:

[snip]

>> * Our model classes should call the storage interface for any methods
>> requiring storage access (for example: Space.getDocuments()). If
>> other services are required they should be called out too. We still
>> need to define a rule for when a new method can be added to the model
>> classes and when a new component should rather be created. I have
>> some ideas but I'm not 100% sure here so I'd like to hear what you
>> think.
>>
>
> This requires less programming than writing our own lazy loaders, and
> is safer than using JPOX. I wish there was a better method to hide the
> storage, and still not load the complete database in memory.
>
> Btw, space.getDocuments() returns all the documents in that space,
> fully loaded?

Yes. We need to think about how many methods do we offer in the Model  
API. For example do we offer:

Space.getDocuments(DocumentFilter filter)
Space.getDocuments(Query query)
Space.getDocument(String name)
Space.getDocumentsForXXX(...)

or do we create some external Search components for each Model class?

I think we could get away with a single Space.getDocument 
(DocumentFilter filter) + Space.getDocument(String), where  
DocumentFilter is a way to filter documents independent of the  
underlying storage mechanism.

And we can then have some other Query component that transforms free  
form queries (like hibernate queries) into DocumentFilter objects (or  
whatever we want to call it). I haven't thought much about the  
DocumentFilter API itself but we would need something pretty generic.

Anyway the question here right now is whether we think  
Space.getDocument(DocumentFilter filter) is enough or not?

If we agree it's enough then I wonder if Space.getDocuments() should  
stay. I would be in favor of removing it. It would be replaced by  
Space.getDocuments(DocumentFilter.ALL).

I really like minimal APIs and I don't think overloaded methods  
should go in the Model classes. But everything has pros and cons. One  
con: Someone may later create a SpaceHelper.getAllDocuments() helper  
method/component...

Other question: Transversal queries. Example: let's say we want to  
get the document named D in the S space. Do we offer a  
Wiki.getDocument(Space space, String docname) API? Or do we say the  
user has to traverse the object hierarchy: Wiki.getSpace 
(space).getDocument(docname)? (the latter is my preference). We may  
need some transversal APIs though but I think these should go in some  
other component (not sure though).

> space.getDocumentsNames() loads the list of documents,
> or just retrieves the names?

Ah that's another API for getting documents which I haven't listed  
above... :)

I think we should only have one API: Space.getDocuments 
(DocumentFilter filter). However this will NOT load the metadata of  
documents. These will be only loaded when Document.getMetadata() is  
called. Thus retrieving documents or just their names will be about  
the same in execution time (it'll only load data in one table).

WDYT?

Are there cases where this is not true?

> Regarding the latter issue, we should try to make the components as
> stable as possible. After we all agree on a component, we need strong
> reasons to introduce something new.

Agreed. I'd like to use something like Clirr later on to ensure the  
build fails
(see http://blogs.codehaus.org/people/vmassol/archives/ 
001324_ensuring_binary_compatibility.html)

In any case we need a consensus that changing something in the Model  
requires a vote.

> Another issue, as far as I remember, components should be interfaces.
> Will the model be an interface, too, with a default implementation? Or
> will it not be a component?

They shouldn't be components as we need to be able to do new on them  
and pass them around in method calls, etc.

>> * I think it would be a good idea to have our model defined
>> independently of the language (for example in XML - Here's for
>> example the Maven model defined in xml:
>> http://svn.apache.org/repos/asf/maven/components/trunk/maven-model/
>> src/main/mdo/maven.mdo
>>
>
> +1 on that, as I'm a total adept of XML. But, what language should we
> use for the definition? I'd go for XSD, as I know nothing about
> Modello.

It's just a build time tool to easily generate stuff. It's pretty  
powerful, has lots of cool features, integrates supra well with  
Maven. XSLT transformation is a major PITA and I wouldn't want us to  
touch that as much as possible ;)

Modello can use velocity templates for the generation, java code, etc.

[snip]

Thanks
-Vincent