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

[Sanne Grinovero]

On 12 February 2018 at 18:28, Sanne Grinovero <sanne at hibernate.org> wrote:
> 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.
>
> I'll see if we can produce fully fledged module-info descriptors then :)

Well, sorry I sent that too fast without thinking.

Of course making full modules is not an option as several of our
dependencies aren't modular yet.

Thanks anyway that was a very interesting observation!

Sanne

>
>>
>>>
>>> # 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
>>
>>