[hibernate-dev] HSEARCH-3000 Pick Jigsaw Automatic Module names for all published modules

[Gunnar Morling]

2018-02-12 19:28 GMT+01:00 Sanne Grinovero <sanne at hibernate.org>:

> On 12 February 2018 at 18:00, Gunnar Morling <gunnar at hibernate.org> wrote:
> >
> >
> > 2018-02-12 17:55 GMT+01:00 Sanne Grinovero <sanne at hibernate.org>:
> >>
> >> Picking automatic module names for Hibernate Search isn't going to be
> >> straight-forward as our two main jars (hibernate-search-engine &
> >> hibernate-search-orm) suffer from split package among them.
> >>
> >> We can't really fix the split package problem without breaking all
> >> users, so if we want to consider that, we can debate it but that will
> >> need to happen at another round as we're doing a minor release, so
> >> let's focus on:
> >>  # Which names to pick
> >>  # Should we pick the names at all
> >>  # Which modules should have a name
> >>
> >> For a great background on the possible strategies and pitfalls I
> >> recommend reading Stephen Colebourne's blog on this subject [1].
> >> He persuaded me there are good reasons to use the "reverse DNS, the
> >> top level package", however since we have the split package problem we
> >> can't simply go with that.
> >>
> >> Still, we can respect the principles he recommends with a small
> >> variation. It's fair to assume that the `org.hibernate.search` prefix
> >> is "ours"; since the nature of the suggestion is focused on making
> >> sure there are no misunderstandings in the community about which names
> >> you can choose - as there is no central authority making sure module
> >> names aren't clashing - we should be fine within Hibernate projects
> >> with any `org.hibernate.X` prefix, as long as we coordinate and reach
> >> an agreement on this list.
> >>
> >> So, I propose we use:
> >>
> >> Engine module:
> >>  - org.hibernate.search.engine
> >>
> >> ORM integration module:
> >>  - org.hibernate.search.orm
> >>
> > Those names sound good to me.
> >
> >>
> >> JGroups, JMS backends:
> >>   [ no automatic module name ? Excepting some "guidelines" in the JMS
> >> module, these are not public API so nobody would benefit from it -
> >> also we think we might want to phase out the name "backend" in the
> >> future ]
> >>
> >> Elasticsearch integration module [hibernate-search-elasticsearch.jar]:
> >>  - org.hibernate.search.elasticsearch
> >>
> >> Elasticsearch / AWS security integration:
> >>  [ no automatic module name: no public API ]
> >>
> >> Serialization / Avro
> >>  [ no automatic module name: no public API ]
> >>
> >> WDYT?
> >
> >
> > The user may still need to reference those modules when launching a
> > modularized application. Also if they don't directly declare say the JMS
> > backend as a dependence of their own module, they'd still have to
> specify it
> > via --add-modules, so to resolve these additional modules and add them to
> > the module graph. Hence I'd declare automatic module names for these,
> too.
>
> Good point, I had not thought that our modules wouldn't be able to
> load other extensions from classpath.
>
> >> We could also pick names for the ones which I've listed as "no public
> >> API" but I see no point: as we're only assigning an "Automatic Module
> >> Name" we won't be able to explicitly state that the other modules
> >> depend on these. So nobody will use them, and things are a bit in flux
> >> anyway in this area because of Hibernate Search 6 plans.
> >
> >
> > I don't fully understand this paragraph.
>
> You mostly invalidated it with the previous comment, but what I meant
> is that we can't have the `org.hibernate.search.engine` declare a
> dependency on any implementation module, as we're not adding a
> module-info definition.
>
> >> Another optional altogether: since we have split packages which we'll
> >> have to resolve before we can actually transform these into fully
> >> fledged modules, I think an acceptable position is also to say we
> >> won't be publishing any automatic module name yet. Personally I'm
> >> inclined to go with the names suggested above, at least some others
> >> can start making baby steps, even if it's not all there.
> >
> >
> > IMO automatic module names should only be declared after at least some
> basic
> > vetting that these modules will actually work when used as modules. If
> > that's not the case, I wouldn't add these headers, as users rightfully
> may
> > consider their presence as endorsement of using them as modules.
> >
> > That said, I can't seem to find split packages between engine and orm. In
> > fact I can launch an application with both of them on the module path
> just
> > fine. So there may be no problem actually?
>
> Interesting, I'm pretty sure we had some. We had several issues
> resolved over time to resolve them, I never realized we might have
> completed them all. The "line" defining what belongs where is still
> blurry though, we should make sure this won't have future regressions.
>

Where I had problems with split packages was when exploring HSearch @ Java
9 modules last year was Lucene. In the version used back then (not sure
whether it's still an issue today), there was a split package between
Lucene's core and the util module (the one with the uninverting reader).

You might take my example project I had created for running ORM as modules (
https://github.com/gunnarmorling/hibernate-orm-on-java9-modules/compare/orm-modularized)
if you're interested in doing the same for HSearch. IIRC, the Lucene split
package made me give up back then, it's surely worth taking another look
with the current versions in use.

>
> I'll see if we can produce fully fledged module-info descriptors then :)
>
> >
> >>
> >> # What I don't like:
> >> For one, that the typical application will need to import both
> >> `org.hibernate.search.engine` and `org.hibernate.search.orm`, and
> >> likely more as well (e.g. Elasticsearch API, Lucene API module is
> >> coming, ..).
> >
> >
> > I'm not exactly sure what you mean by "import" here. But if it's about
> the
> > user having to declare dependences in their module descriptor to
> > o.h.s.engine and o.h.s.orm modules, you may consider to make the former a
> > transitive dependence of the latter once you add actual module
> descriptors:
> >
> >     module org.hibernate.search.orm {
> >         requires transitive org.hibernate.search.engine;
> >         ...
> >     }
> >
> > That way the user just has to add declare the dependence to o.h.s.orm.
> > That's definitely suitable if APIs in o.h.s.orm use types from engine in
> > their public API signatures.
>
> +1 that's the better option.
>
> My thought was about automatic module names though, but totally
> irrelevant if we go for full modules.
>
> Thanks,
> Sanne
>
> >
> >>
> >> Maybe similar to BOM's today we could publish a module which
> >> statically imports multiple of these, that could be nicer to use but
> >> we risk needing to publish (and document) one for each of a selection
> >> of combinations. So let's not start with such things yet.
> >>
> >> Thanks,
> >> Sanne
> >>
> >> [1] http://blog.joda.org/2017/05/java-se-9-jpms-automatic-modules.html
> >> _______________________________________________
> >> hibernate-dev mailing list
> >> hibernate-dev at lists.jboss.org
> >> https://lists.jboss.org/mailman/listinfo/hibernate-dev
> >
> >
>