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

[Yoann Rodiere]

>   - org.hibernate.search.jms-support

Not sure it's a valid name (aren't hyphens forbidden in package names, and
aren't module names constrained by the same rules?), but apart from that it
looks good. Maybe "jms_support" instead, if "jms-support" is not allowed.
I would like to find a name for what the JMS and JGroups modules provide in
Hibernate Search 6 though, something less misleading than "backend".
Something like "work routing" or "clustering support" or "distribution
support" or whatever. Would you be ok with changing the module name in 6?
If not, maybe we have to think about it now... Note that we'll change the
Maven group ID anyway, so it's arguably just another breaking change.

On Tue, 13 Feb 2018 at 11:43 Sanne Grinovero <sanne at hibernate.org> wrote:

> On 13 February 2018 at 08:44, Yoann Rodiere <yoann at hibernate.org> wrote:
> >> 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.
> >
> > If I understood correctly, automatic module names were introduced to
> > facilitate the transition to Jigsaw modules. The point was to allow
> projects
> > to give a name to their modules, and, yes, declare them as ready, but
> even
> > if they couldn't be made full modules yet because of their dependencies.
> > Declaring a name doesn't mean the module will work, it means it will work
> > when dependencies are fixed. If we wait for all of our dependencies to
> work
> > in a modular environment before we give a name to our modules, we may
> very
> > well never do it because of circular dependencies (Infinispan comes to
> mind:
> > Infinispan-query depends on Search for, which depends on ORM, which
> depends
> > on the Infinispan 2nd level cache provider).
> > Declaring a full module-info.java is another matter, but as you
> mentioned,
> > we simply can't do that yet because of split packages in Lucene.
>
> Understood and agree. We should add the automatic module names to get
> people unstuck, and I wouldn't propose this if I didn't have enough
> confidence that they should work: we have some basic tests.
>
>
> > Back to naming... It looks good and consistent with the current naming
> our
> > Maven artifacts. In 6, I would probably choose to rename the
> Elasticsearch
> > one to something like
> > org.hibernate.search.<backendOrSomething>.elasticsearch, but we still
> have
> > to coin the right term for "<backendOrSomething>", and I would probably
> > rename the Maven artifact too, so that can wait.
> >
> > I think you forgot the JSR 352 integration, but I guess the name would be
> > rather obvious:
> >  - org.hibernate.search.jsr352
>
> +1, thanks
>
>
> > As to non-public APIs, can you confirm automatic modules can access the
> > classpath transparently? If so then I agree, no need to name those....
> > Except for the JMS backend: it is unusable without the user extending
> > AbstractJMSHibernateSearchController, so this class at least must be
> exposed
> > to the user. Even if it's just SPI.
>
> That's the "guidelines" I was referring to in my first email.
> We could give it a name, so let's suggest one, but I feel like this is
> not essential as while we suggest people to extend our SPI, there are
> alternatives to that.
> I wanted to avoid this one at a first shot as it might be controversial ;)
>
> Proposed name:
>   - org.hibernate.search.jms-support
>
> Why:
>  # I'd like to avoid using "backend" in the name.
>  # Makes it clear this is the module you want to add when you're into
> JMS - or at the opposite if your system doesn't care about JMS.
>
> IMO the goal of Jigsaw modules is to trim a system from unnecessary
> stuff, so having the names express what kind of technologies it brings
> in is most helpful.
>
> Thanks,
> Sanne
>
> > On Tue, 13 Feb 2018 at 00:39 Sanne Grinovero <sanne at hibernate.org>
> wrote:
> >>
> >> The split package problem with Lucene won't easily go away, as we
> >> can't upgrade Lucene now.
> >>
> >> But I vaguely remember working with you on that, didn't we figure out
> >> that one of the Lucene modules wasn't essential?
> >>
> >> Either way, that's interesting to experiment with but we can't publish
> >> full modules as almost none of our dependencies are ready; they should
> >> at least all have an automatic module name.
> >>
> >> Thanks,
> >> Sanne
> >>
> >> On 12 February 2018 at 19:43, Gunnar Morling <gunnar at hibernate.org>
> wrote:
> >> >
> >> >
> >> > 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
> >> >> >
> >> >> >
> >> >
> >> >
> >> _______________________________________________
> >> hibernate-dev mailing list
> >> hibernate-dev at lists.jboss.org
> >> https://lists.jboss.org/mailman/listinfo/hibernate-dev
> >
> > --
> > Yoann Rodiere
> > yoann at hibernate.org / yrodiere at redhat.com
> > Software Engineer
> > Hibernate NoORM team
>
-- 
Yoann Rodiere
yoann at hibernate.org / yrodiere at redhat.com
Software Engineer
Hibernate NoORM team