I've started the work to split classes between API, SPI and private classes. Some areas went very well, some are more problematic but that was to be expected. Anyways it did generate a couple of questions from philosophical to concrete. Please try and chime in. 1. API vs SPI: http://opensource.atlassian.com/projects/hibernate/browse/HSEARCH-746 I have a question on API vs SPI. The Hibernate Core team uses the following rule:  - any "public" API not directly called by the user application is a SPI (for example a Bridge would be SPI and I imagine BootStrategy would be too etc). We could however sue a different rule:  -  any API targeted at frameworks integrating with Hibernate Search are SPIs For example SearchConfiguration and SearchFactoryIntegrator would be SPIs but Bridge classes and BoostStrategy would not I'm tempted by the second definition as it separate user focused classes from integration / framework focused classes. Of course nothing is in back and white and some classes can be hard to categorize.

An aternative approach is to mix the two definitions:  - any "public" API not directly called by the user application is a SPI (for example a Bridge would be SPI and I imagine BootStrategy would be too etc).  - any API targeted at frameworks integrating with Hibernate Search are SPIs For example SearchConfiguration and SearchFactoryIntegrator would be SPIs But then we lose the distinction between framework APIs and user APIs. What do you think?

2. Specific issues: o org.hibernate.search.batchindexing.impl.Executors is used by MutablefactoryTest should we keep executors as private or should we consider it an actual API or SPI?

o Should built-in types be public APIs/SPIs? I was tempted to put some if not all as private classes but there are use cases where these classes are used by actual users:  - the programmatic API (ProgrammaticSearchMappingFactory uses them)  - provided id settings

Should we consider some / all as public classes? For example what about ClassBridge? o Is NumericFieldUtils a public class? It is used by NumericFieldTest, ProjectionQueryTest but it seems a user should not use this helper class

o SearchConfiguration is very likely an SPI which means we will need to break Infinispan's query module, is that OK?

o Programmatic API *Mapping objects are messed up with *Descriptor objects It seems to be that *Descriptors should be private while *Mapping should be API, do you think it's worth working on this? The programmatic mapping si still considered experimental so we have some time I guess.

o SearchFactoryIntegrator vs SearchFactoryImplementor In my mind, I introduced SearchFactoryIntegrator to separate private SearchFactory usage from frameworks usage. Does the Infinispan Query module depends on SearchFactoryImplementor only? Or is it depending on SearchFactoryImplementor?

That's all for now but more will come :) Emmanuel _______________________________________________ hibernate-dev mailing list hibernate-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev

See answers inline >> 1. >> API vs SPI: >> http://opensource.atlassian.com/projects/hibernate/browse/HSEARCH-746 >> >> I have a question on API vs SPI. >> The Hibernate Core team uses the following rule: >>  - any "public" API not directly called by the user application is a SPI >> (for example a Bridge would be SPI and I imagine BootStrategy would be too >> etc). >> >> We could however sue a different rule: >>  -  any API targeted at frameworks integrating with Hibernate Search are >> SPIs For example SearchConfiguration and SearchFactoryIntegrator would be >> SPIs but Bridge classes and BoostStrategy would not >> >> I'm tempted by the second definition as it separate user focused classes >> from integration / framework focused classes. Of course nothing is in back >> and white and some classes can be hard to categorize. > > +1, reasoning in next paragraph +1 from me as well. Still not convinced that this rigorous package naming is really a good idea, but it seems we are committed. >> o SearchFactoryIntegrator vs SearchFactoryImplementor >> In my mind, I introduced SearchFactoryIntegrator to separate private >> SearchFactory usage from frameworks usage. >> Does the Infinispan Query module depends on SearchFactoryImplementor >> only? Or is it depending on SearchFactoryImplementor? > > It's built on top of SearchFactoryIntegrator, in some tests this is > cast to SearchFactoryImplementor to be able to verify some state but I > think you can ignore that. > Currently Query needs only #getDocumentBuildersIndexedEntities(), in > worst case we could expose that.

I don't have much to say to the other points, but if we could get rid of one of these I would give it a big +1.

--Hardy

I've started the work to split classes between API, SPI and private classes. Some areas went very well, some are more problematic but that was to be expected. Anyways it did generate a couple of questions from philosophical to concrete. Please try and chime in. 1. API vs SPI: http://opensource.atlassian.com/projects/hibernate/browse/HSEARCH-746 I have a question on API vs SPI. The Hibernate Core team uses the following rule: - any "public" API not directly called by the user application is a SPI (for example a Bridge would be SPI and I imagine BootStrategy would be too etc). We could however sue a different rule: - any API targeted at frameworks integrating with Hibernate Search are SPIs For example SearchConfiguration and SearchFactoryIntegrator would be SPIs but Bridge classes and BoostStrategy would not I'm tempted by the second definition as it separate user focused classes from integration / framework focused classes. Of course nothing is in back and white and some classes can be hard to categorize. An aternative approach is to mix the two definitions: - any "public" API not directly called by the user application is a SPI (for example a Bridge would be SPI and I imagine BootStrategy would be too etc). - any API targeted at frameworks integrating with Hibernate Search are SPIs For example SearchConfiguration and SearchFactoryIntegrator would be SPIs But then we lose the distinction between framework APIs and user APIs. What do you think? 2. Specific issues: o org.hibernate.search.batchindexing.impl.Executors is used by MutablefactoryTest should we keep executors as private or should we consider it an actual API or SPI? o Should built-in types be public APIs/SPIs? I was tempted to put some if not all as private classes but there are use cases where these classes are used by actual users: - the programmatic API (ProgrammaticSearchMappingFactory uses them) - provided id settings Should we consider some / all as public classes? For example what about ClassBridge? o Is NumericFieldUtils a public class? It is used by NumericFieldTest, ProjectionQueryTest but it seems a user should not use this helper class o SearchConfiguration is very likely an SPI which means we will need to break Infinispan's query module, is that OK? o Programmatic API *Mapping objects are messed up with *Descriptor objects It seems to be that *Descriptors should be private while *Mapping should be API, do you think it's worth working on this? The programmatic mapping si still considered experimental so we have some time I guess. o SearchFactoryIntegrator vs SearchFactoryImplementor In my mind, I introduced SearchFactoryIntegrator to separate private SearchFactory usage from frameworks usage. Does the Infinispan Query module depends on SearchFactoryImplementor only? Or is it depending on SearchFactoryImplementor? That's all for now but more will come :) Emmanuel _______________________________________________ hibernate-dev mailing list hibernate-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev