2011/5/10 Emmanuel Bernard <emman...@hibernate.org>: > 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.
+1, reasoning in next paragraph > > 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? I'd consider a BoostStrategy or a FieldBridge part of the API as people do directly refer to it in the model: @DynamicBoost(MyStrategy.class), so it's one of those things that if we change the package, class name or interface it breaks the user's application. I mention the interface because for example the BoostStrategy implementation is very likely provided by the users and strongly coupled to their code (both model and business). I agree it's not black/white, but when integrating search with Infinispan Query for example we definitely don't care about the DynamicBoost & co, we don't use them to integrate with third party projects, app servers, grids, but I consider them "user facing". > > > 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? I don't think exposing this as SPI is very useful to people, but at some point in future it's possible we might want to make this a replaceable component, to let the AS (for example) provide threads and monitor them. Even if it's private, wouldn't our tests still be able to use it? > > 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 Can't we keep stuff in .impl packages but not necessarily private? > > 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 Having something like NumericFieldUtils is useful to write numeric queries, but it doesn't necessarily have to have the current API. I'm fine in hiding it and suggest people to use the DSL, and eventually add a better helper later on if needed. > > o SearchConfiguration is very likely an SPI which means we will need to break > Infinispan's query module, is that OK? I'ts definitely and SPI. what do you mean by breaking Query? if you only want to move it to a different package that's not an issue; if you want to change the exposed methods please suggest how and I'll check with Query if that is arrangeable. > 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. +1 let's do that, as you say not very urgent. > > 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. Sanne > > That's all for now but more will come :) > > Emmanuel > > > _______________________________________________ > hibernate-dev mailing list > hibernate-dev@lists.jboss.org > https://lists.jboss.org/mailman/listinfo/hibernate-dev > _______________________________________________ hibernate-dev mailing list hibernate-dev@lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev
