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

Tue Feb 13 05:42:48 EST 2018

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