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

[Davide D'Alto]

> 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).

I think I've missed it, what is it your suggestion for internal packages?



On Mon, Feb 10, 2014 at 4:09 PM, Sanne Grinovero <sanne at hibernate.org>wrote:

> 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.." ;-)
>
> 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.
>
> Sanne
>
>
>
> >
> > 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
> >
> >
> _______________________________________________
> hibernate-dev mailing list
> hibernate-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/hibernate-dev
>