[xwiki-devs] [Discussion] Should our components be user-public or not? - xwiki-devs@xwiki.org

Thomas Mortagne

23 Aug 23 Aug

11:50 a.m.

New subject: [xwiki-devs] [Discussion] Should our components be user-public or not?

+1 for internal On Fri, Aug 22, 2008 at 11:05 PM, Vincent Massol <vincent(a)massol.net> wrote:

Hi, We need to decide if we want our component implementations (the class implementing the interface of a component) to be user-public or not. By user-public I mean allowing user of the code to use them (for composition, for inheritance). The alternative is to make them internal and forbid users to import them. This means moving them to an internal package (see http://www.eclipse.org/articles/ article.php?file=Article-API-Use/index.html) and telling our users that they change anytime so they shouldn't use them. This would also mean we wouldn't have to go through a deprecation stage to make any change to our components. My initial reaction to this was that they should be public but the more I think about it the more I think making them internal might be the best choice. WDYT? Thanks -Vincent _______________________________________________ devs mailing list devs(a)xwiki.org http://lists.xwiki.org/mailman/listinfo/devs

-- Thomas Mortagne

Reply

Sergiu Dumitriu

10:56 p.m.

Vincent Massol wrote:

...

Hi, We need to decide if we want our component implementations (the class implementing the interface of a component) to be user-public or not. By user-public I mean allowing user of the code to use them (for composition, for inheritance). The alternative is to make them internal and forbid users to import them. This means moving them to an internal package (see http://www.eclipse.org/articles/ article.php?file=Article-API-Use/index.html) and telling our users that they change anytime so they shouldn't use them. This would also mean we wouldn't have to go through a deprecation stage to make any change to our components. My initial reaction to this was that they should be public but the more I think about it the more I think making them internal might be the best choice.

Private. The component's description (the interface) is enough. If we need a more detailed "interface", then maybe we should either create a new component, or redesign the code using that component. Implementations should stay hidden. -- Sergiu Dumitriu http://purl.org/net/sergiu/

Reply

Sergiu Dumitriu

26 Aug 26 Aug

4:03 a.m.

Vincent Massol wrote:

...

On Aug 24, 2008, at 10:56 PM, Sergiu Dumitriu wrote:

Vincent Massol wrote:

Hi, We need to decide if we want our component implementations (the class implementing the interface of a component) to be user-public or not. By user-public I mean allowing user of the code to use them (for composition, for inheritance). The alternative is to make them internal and forbid users to import them. This means moving them to an internal package (see http://www.eclipse.org/articles/ article.php?file=Article-API-Use/index.html) and telling our users that they change anytime so they shouldn't use them. This would also mean we wouldn't have to go through a deprecation stage to make any change to our components. My initial reaction to this was that they should be public but the more I think about it the more I think making them internal might be the best choice.

Private. The component's description (the interface) is enough. If we need a more detailed "interface", then maybe we should either create a new component, or redesign the code using that component. Implementations should stay hidden.

Yes but this was not the problem. The problem is for example if a user wants to create, say, a XHTML2 macro based on our XHTML macro. He'll have to have it injected for example (or inherit from it). In both cases this means exposing the internal package (in components.xml or in the import). Thus if the class name is changed for example, it'll break the user. Same for protected methods which will also break backward compat if used and modified. But I think this is ok. It just means our component implementations cannot be reused since they are private. We'll just need to make this very clear.

I understand now. Yes, the implementations should not be for the public, meaning that the developers of the official platform can use (inherit) them internally, and we can change whatever we want between releases, but third party code should never rely on these implementations. -- Sergiu Dumitriu http://purl.org/net/sergiu/

Reply

Vincent Massol

8:30 a.m.

New subject: [xwiki-devs] [Discussion] Should our components be user-public or not? (SUMMARY)

So far: - sergiu: +1 for internal - thomas: +1 for internal - marius: +1 for internal - vincent: +1 for internal but not as strongly as the others above ;) Ok so I've added it to our best practices here: http://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices http://dev.xwiki.org/xwiki/bin/view/Community/CodeStyle Thanks -Vincent On Aug 22, 2008, at 11:05 PM, Vincent Massol wrote:

...

Hi, We need to decide if we want our component implementations (the class implementing the interface of a component) to be user-public or not. By user-public I mean allowing user of the code to use them (for composition, for inheritance). The alternative is to make them internal and forbid users to import them. This means moving them to an internal package (see http://www.eclipse.org/articles/ article.php?file=Article-API-Use/index.html) and telling our users that they change anytime so they shouldn't use them. This would also mean we wouldn't have to go through a deprecation stage to make any change to our components. My initial reaction to this was that they should be public but the more I think about it the more I think making them internal might be the best choice. WDYT? Thanks -Vincent

Reply