On Mar 8, 2009, at 10:31 AM, Sergiu Dumitriu wrote:

Vincent Massol wrote:

...

Hi,

Some time ago we agreed that component implementations should be located in the internal package. I now believe it's wrong if we want to allow users to use our modules separately from the rest of XWiki as standard java beans. I think it's a good property to have that users can integrate our modules into their own code without taking the whole of XWiki. This is what I'm trying to do with the rendering module.

Thus I'm proposing to move the components out of the internal module *only* for the rendering module for now even though I suspect that we'll want to do that for all modules eventually.

Here's my +1

What's the advantage? Or, what's wrong with keeping the internal package?

We should keep the internal package for sure for whatever is internal. What it means here is that the component implementation classes are public classes.

Apart from a longer package name, there's no bound semantics on such a package. IMO it even has the advantage that it clearly delimits interfaces and abstract base classes from implementations.

The user will write for example: Parser parser = new WikiModelXWikiParser(...); parser.parse(new StringReader("**whatever**"); ... So this makes WikiModelXWikiParser public (this is an example but is true for all other components - or almost all of them). Thanks -Vincent

On Mar 9, 2009, at 12:26 PM, Dan Miron wrote:

Sergiu Dumitriu wrote:

...

Vincent Massol wrote:

...

Hi,

Some time ago we agreed that component implementations should be located in the internal package. I now believe it's wrong if we want to allow users to use our modules separately from the rest of XWiki as standard java beans. I think it's a good property to have that users can integrate our modules into their own code without taking the whole of XWiki. This is what I'm trying to do with the rendering module.

Thus I'm proposing to move the components out of the internal module *only* for the rendering module for now even though I suspect that we'll want to do that for all modules eventually.

Here's my +1

What's the advantage? Or, what's wrong with keeping the internal package? Apart from a longer package name, there's no bound semantics on such a package. IMO it even has the advantage that it clearly delimits interfaces and abstract base classes from implementations.

I agree to Sergiu. Keeping the implementation and the specifications separately provides more accuracy to our api.

The only possibility to keep our "component" implementation classes non user-public is to add user-public factory classes. ParserFactory parserFactory = new DefaultParserFactory(); Parser parser = parserFactory.createParser(new XWikiSyntax(SyntaxType.XWIKI, "2.0")); parser.parse(new StringReader("**whatever**"); ... instead of: Parser parser = new WikiModelXWikiParser(...); parser.parse(new StringReader("**whatever**"); ... Note that these factory classes will need to have user-public implementations of course so this is swapping one problem for another (albeit smaller). Also, it means that we have an extra class that is useless when using components. Now while this works quite well for parsers since there are different implementations for them, it's going to be a real pita for most other components which have only a default implementation. For example, I don't see us writing: TransformationManagerFactory transformationManagerFactory = new DefaultTransformationManagerFactory(); TransformationManager transformationManager = transformationManagerFactory.createTransformationManager(); transformationManager.performTransformations(...); instead of: TransformationManager transformationManager = new DefaultTransformationManager(); transformationManager.performTransformations(...); Now the first one to suggest using singleton pattern and statics gets a blame... :) WDYT? Thanks -Vincent

On Mar 9, 2009, at 1:58 PM, Sergiu Dumitriu wrote:

Vincent Massol wrote:

...

On Mar 9, 2009, at 12:26 PM, Dan Miron wrote:

...

Sergiu Dumitriu wrote:

...

Vincent Massol wrote:

...

Hi,

Some time ago we agreed that component implementations should be located in the internal package. I now believe it's wrong if we want to allow users to use our modules separately from the rest of XWiki as standard java beans. I think it's a good property to have that users can integrate our modules into their own code without taking the whole of XWiki. This is what I'm trying to do with the rendering module.

Thus I'm proposing to move the components out of the internal module *only* for the rendering module for now even though I suspect that we'll want to do that for all modules eventually.

Here's my +1

What's the advantage? Or, what's wrong with keeping the internal package? Apart from a longer package name, there's no bound semantics on such a package. IMO it even has the advantage that it clearly delimits interfaces and abstract base classes from implementations.

I agree to Sergiu. Keeping the implementation and the specifications separately provides more accuracy to our api.

The only possibility to keep our "component" implementation classes non user-public is to add user-public factory classes.

ParserFactory parserFactory = new DefaultParserFactory(); Parser parser = parserFactory.createParser(new XWikiSyntax(SyntaxType.XWIKI, "2.0")); parser.parse(new StringReader("**whatever**"); ...

instead of:

Parser parser = new WikiModelXWikiParser(...); parser.parse(new StringReader("**whatever**"); ...

Note that these factory classes will need to have user-public implementations of course so this is swapping one problem for another (albeit smaller). Also, it means that we have an extra class that is useless when using components.

Now while this works quite well for parsers since there are different implementations for them, it's going to be a real pita for most other components which have only a default implementation. For example, I don't see us writing:

TransformationManagerFactory transformationManagerFactory = new DefaultTransformationManagerFactory(); TransformationManager transformationManager = transformationManagerFactory.createTransformationManager(); transformationManager.performTransformations(...);

instead of:

TransformationManager transformationManager = new DefaultTransformationManager(); transformationManager.performTransformations(...);

Now the first one to suggest using singleton pattern and statics gets a blame... :)

WDYT?

Vincent, I don't understand what's the problem with keeping the package name as it is now? There's nothing that prevents users (API users) to instantiate classes in the internal package.

The internal package name means that users must never use classes inside these package since they're not user-public. If they do they do it at their own risk and we're not committing ourselves to keep any code located in the internal package. See http://jakarta.apache.org/cactus/participating/apis.html and http://www.eclipse.org/articles/article.php?file=Article-API-Use/index.html It's a contract and compatibility issue. The internal package is there because Java doesn't have the notion of user-public/non-user-public APIs. OSGi has this notion for example since each bundle explicitly mentions which classes are exported and thus user-public. This is the only reason for our "internal" package. Thanks -Vincent

The only thing that changes is the import statement, the same constructor can be used. And with modern development tools the package is transparent.