[hibernate-dev] [HSEARCH] package split in API/SPI/private aka HSEARCH-746

[Emmanuel Bernard]

I've been working on the backend side and made the following split
api
Workspace
TransactionContext
OptimizerStrategy
LuceneWork and *LuceneWork

spi
WorkType
Work
Worker
UpdatableBackendQueueProcessorFactory
BackendQueueProcessorFactory
LuceneIndexingParameters

impl
WorkVisitor
WorkQueue
WorkerFactory
QueueingProcessor

Emmanuel


On 10 mai 2011, at 19:29, Emmanuel Bernard wrote:

> 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 at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/hibernate-dev