[hibernate-dev] [OGM] Public packages of datastore modules

[Gunnar Morling]

Am 10.02.2014 17:10 schrieb "Sanne Grinovero" <sanne at hibernate.org>:
>
> On 10 February 2014 14:52, Gunnar Morling <gunnar at hibernate.org> wrote:
> > 2014/2/10 Sanne Grinovero <sanne at hibernate.org>
> >>
> >> On 10 February 2014 12:32, Davide D'Alto <daltodavide at gmail.com> wrote:
> >> > I can work on this today and start to plan the release for Wednesday.
> >> >
> >> > I don't think this change should block the next release though.
> >> >
> >> > It would also be nice to include this:
> >> > https://github.com/hibernate/hibernate-ogm/pull/282
> >> > so that people can actually use the enitty manager to create queries
> >> >
> >> >
> >> >
> >> > On Mon, Feb 10, 2014 at 10:50 AM, Gunnar Morling
> >> > <gunnar at hibernate.org>wrote:
> >> >
> >> >> Hi,
> >> >>
> >> >> One thing I'd like to address before doing the next OGM release is
the
> >> >> structure of public packages in the datastore-specific modules.
> >> >>
> >> >> Currently we have the following structure:
> >> >>
> >> >> * org.hibernate.ogm.datastore.<infinispan|ehcache|mongodb|...>
> >> >> * org.hibernate.ogm.dialect.<infinispan|ehcache|mongodb|...>
> >> >> * org.hibernate.ogm.logging.<infinispan|ehcache|mongodb|...>
> >> >> ...
> >> >>
> >> >> I think it makes sense to pull the datastore-specific package up one
> >> >> level,
> >> >> moving all the types of a backend under one shared super-package.
So it
> >> >> would like this instead:
> >> >>
> >> >> * org.hibernate.ogm.<infinispan|ehcache|mongodb|...>.datastore
> >> >> * org.hibernate.ogm.<infinispan|ehcache|mongodb|...>.dialect
> >> >> * org.hibernate.ogm.<infinispan|ehcache|mongodb|...>.logging
> >> >> ...
> >> >>
> >> >> The reason I'm bringing this up is that we're introducing new
> >> >> user-exposed
> >> >> types with that release: the store identifier types (MongoDB,
CouchDB
> >> >> etc.)
> >> >> and their properties class (MongoDBProperties, CouchDBProperties
etc.).
> >> >> So
> >> >> if we agree to do this change it would be good to do it now before
> >> >> having
> >> >> to move these public types later on.
> >>
> >> Since you mention users as a reason for this change, I've to admit
> >> that I don't see how it helps users.
> >> Personally I think it's quite helpfull to have the package to help me
> >> quickly identify which dialects I have available;
> >
> >
> > That's my thinking as well, but how do the intermediary "datastore",
> > "dialect" etc. packages (at a higher level than the actual datastore
> > package) help to achieve this?
> >
> > To me, packages should be organized by the most important criteria
first,
> > and that's IMO the type of datastore here. Thus I think it should be
> > org.hibernate.ogm.mongodb.* for everything MongoDB instead of
> > org.hibernate.ogm.*.mongodb. Why have these rather technical packages in
> > between?
>
> I understand that you like that better, but we need to figure if
> that's an objective statement: dialects in Hibernate ORM don't work
> like that, and people are used to the current approach:
>
http://docs.jboss.org/hibernate/orm/4.3/manual/en-US/html/ch03.html#configuration-optional-dialects
>
> My impression is that ORM users are familiar with the concept of
> "dialect", hence they know they are searching for a dialect which does
> make it quite straight forward to go for something in
>
> org.hibernate.dialect
>
> For example it's
>  > org.hibernate.dialect.H2Dialect
> and not
> > org.hibernate.h2.Dialect
> and also it's not
> > h2.dialect.hibernate
>
> I realize the ORM is slightly different as it has just one class,
> still that's what people are used to in terms of dialects.
>
> "most important criteria first, as you say.." ;-)

You already outlined the major difference yourself, in OGM it can be quite
a few classes which make up a "dialect".

But following your line of thought and resembling the structure from ORM it
may actually make sense to have everything in sub-trees under
org.hibernate.ogm.dialect.<dialect>.* I could live with that as well, it's
the non-user relevant stuff like logging showing up at the top-level which
I find confusing.
>
> Maybe 100% of our users would disagree with the ORM naming choice if
> asked about it, but I've seen no complains so either that's not true
> or nobody cares enough, which is why I'm still not persuaded on this
> being worth of our time to change.

Yes, but consider that we provide new user facing classes with this
release, so we should take some minutes to make sure they are at the right
place.

>
> Sanne

--Gunnar
>
>
>
> >
> > Also I'm trying to expose as less packages and types to the user as
> > possible. So e.g. I'd like to put the dialect identifier type from the
> > option API straight into a backend's root package, e.g.
> > org.hibernate.ogm.mongodb.MongoDB. With the current approach that's not
> > possible, in between there is the org.hibernate.ogm.datastore package
(which
> > itself is empty for all the datastore modules).
> >
> >>
> >> we should also
> >> expect potentially to have sub-types in the future like
> >>
> >> org.hibernate.ogm.datastore.infinispan.local
> >> org.hibernate.ogm.datastore.infinispan.clusterable
> >> org.hibernate.ogm.datastore.cassandra.embedded
> >>
> >> Since I don't see a value advantage in changing the packages, I'll
> >> side with the "resistance against change" party, unless you share some
> >> compelling argument of course :-)
> >>
> >> the "logging" case is different: that's a private package so we might
> >> want to highlight that in the package structure.
> >
> >
> > Agreed, that's caused by the current rule of putting the "impl"
packages at
> > the bottom of the tree. So actually the complete logging package
currently
> > is org.hibernate.ogm.logging.mongodb.impl.
> >
> > I dislike this pattern for several reasons, a) it adds many empty
packages
> > which seem user-exposed but actually aren't (org.hibernate.ogm.logging,
> > org.hibernate.ogm.logging.mongodb) and b) it makes it cumbersome to
> > structure impl-internal stuff into sub-packages (have a look at the
CouchDB
> > module [1] to see what I mean).
> >
> > So far I couldn't convince Emmanuel to let go of this pattern, though
;) In
> > HV we did the split at the top-most level (i.e. everything not
user-exposed
> > is under org.hibernate.validator.internal), and IMO that works much
better
> > than the current approach in OGM.
> >
> >> >> Another question is how to differentiate between public and internal
> >> >> packages, but I think we can discuss this later on, as a change
would
> >> >> only
> >> >> affect internal packages. Emmanuel and I couldn't agree on a best
> >> >> approach
> >> >> when discussing it shortly, so this might need some more time :)
> >> >>
> >> >> Any thoughts?
> >>
> >> I'd move things to .impl for the private ones, leaving all others as
> >> they are. That should also simplify for example a filtering rule for
> >> the javadoc generation.
> >
> >
> > Move in which way exactly, do you suggest to have one "impl" package or
> > many?
> >
> > --Gunnar
> >
> > [1]
> >
https://github.com/hibernate/hibernate-ogm/tree/master/couchdb/src/main/java/org/hibernate/ogm/dialect/couchdb
> >
> >
> >>
> >>
> >>  -- Sanne
> >>
> >> >>
> >> >> --Gunnar
> >> >> _______________________________________________
> >> >> 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
> >
> >