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

[Yoann Rodiere]

Since the names are about to be set in stone, and there has been some
discussion off list, I'd like to talk a bit about the Elasticsearch/Lucene
module names...

In the Search 6 architecture, these modules really provide a "backend",
i.e. a component that actually implements indexing/querying over multiple
indexes, but operates "behind" the engine (the engine uses the backend).
Essentially the data flow is:

Indexing: User => Mapper (user APIs) => Engine => Backend => Disk/network
Querying: User <= Mapper (user APIs) <= Engine <= Backend <= Disk/network

We discussed it a bit with Sanne (and with Guillaume) and agreed that
"backend" was the right word for this part of our architecture.

Now, the discussion is about module names, not component names.

Still, there are several reasons because of which I'd rather use
"org.hibernate.search.backend.<elasticsearch/lucene>":

   - It is closer to how we will probably refer to the module on a
   day-to-day basis: I don't know about you, but I'll probably talk about "the
   Elasticsearch backend" rather than "Elasticsearch indexing" or "the
   Elasticsearch module".
   - It is generic enough to cover all of the tasks we delegate to
   Elasticsearch/Lucene.
"org.hibernate.search.indexing.<elasticsearch/lucene>",
   on the other hand, feels like it's only about indexing, and not querying,
   maybe not even about defining a schema.
   - It is consistent with our architecture and APIs in Search 6:
      - The main component (and entry point) in those modules will be an
      object implementing BackendImplementor (SPI)
      - We will actually expose "backends" as part of our Java APIs, for
      instance to allow users to retrieve the Elasticsearch client, or to query
      some backend-scoped metadata.
      - We will also use the word "backend" in the user configuration,
      where the user will have to define a backend, its type and its options
      using the "hibernate.search.backends.<backendName>.*" properties
   - As opposed to the "prefix-less" naming scheme
   ("org.hibernate.search.<elasticsearch/lucene>"), it makes it easy to infer
   what the module actually provides to users: the actual implementation
   behind Hibernate Search, even without extensive knowledge about Hibernate
   Search.
      - When listing all the modules of Hibernate Search, it makes it easy
      to spot which module is about what, and which modules provide the same
      thing using a different technology:

      org.hibernate.search.engine
      org.hibernate.search.orm
      org.hibernate.search.clustering.jms
      org.hibernate.search.clustering.jgroups
      org.hibernate.search.backend.elasticsearch
      org.hibernate.search.backend.lucene

      vs:

      org.hibernate.search.engine
      org.hibernate.search.orm
      org.hibernate.search.jms
      org.hibernate.search.jgroups
      org.hibernate.search.elasticsearch
      org.hibernate.search.lucene
      - When the module name appears in some error message (for instance
      when a user starts experimenting with Java 9), it will also make it clear
      which part of Hibernate Search is misconfigured. And that may be
important
      to some users, since not all the people working on an application
      know the details of every part of the application...


Of course, in the meantime in Search 5, there will be some confusion due to
the fact "backend" has a different meaning in Search 5.

If you are worried about that, I'm not opposed to slightly altering the
module names between Search 5 and Search 6: users will have to make changes
when migrating anyway.
In particular, a lot of APIs will change, some class may be moved to
different packages to comply the "no split package" constraint of Java 9,
Maven coordinates will change to use the "org.hibernate.search" group ID
instead of "org.hibernate", and people using the Lucene backend will have
to depend on a new module (both in their Maven dependencies and in their
Java 9 module dependencies).

So we could just use "org.hibernate.elasticsearch" in Search 5, and switch
to "org.hibernate.backend.elasticsearch" in Search 6. It's not even a big
deal, since the Elastisearch module is openly advertised as experimental.

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

> On 13 February 2018 at 11:48, Guillaume Smet <guillaume.smet at gmail.com>
> wrote:
> > On Tue, Feb 13, 2018 at 11:59 AM, Yoann Rodiere <yoann at hibernate.org>
> wrote:
> >>
> >> >   - 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.
> >
> >
> > +1 to find a distinctive name for JGroups and JMS artifacts and same for
> > Lucene and Elasticsearch (either this round or for 6).
> >
> > org.hibernate.search.clustering.jms
> > org.hibernate.search.clustering.jgroups
> >
> > and
> >
> > org.hibernate.search.indexing.lucene
> > org.hibernate.search.indexing.elasticsearch
> >
> > would be my choice as it's very understandable by the end user.
>
> Great names! I'll take them. These will allow us to gracefully phase
> out the backend terminology, and also suggest the additional
> dependency tree they will pull in.
>
> >
> > It might be an orthogonal discussion so feel free to ignore me :).
> >
> > --
> > Guillaume
> >
> _______________________________________________
> 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