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

[Gunnar Morling]

I've created https://github.com/hibernate/hibernate-ogm/pull/285 which
moves all the types from a dialect module to one parent package per
dialect, e.g. org.hibernate.ogm.dialect.mongodb.*.

The dialect type, the store identifier type (e.g. MongoDB) and the
properties type (if present, e.g. MongDBProperties) all live at the root
package of a store. This should make it easier for users to find the things
they are supposed to reference.


2014/2/11 Davide D'Alto <davide at hibernate.org>

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

I'd create an "impl" (or "internal") package right under the top-level
package of each dialect, e.g. org.hibernate.ogm.dialect.mongodb.impl, and
move all internal packages there. You can find an example at
https://github.com/gunnarmorling/hibernate-ogm/tree/0482d2e3f57d2be220d771b48ed038e49ff196e1/couchdb/src/main/java/org/hibernate/ogm/dialect/couchdb.
As said, IMO this makes it much easier for a user to tell public things
apart from private stuff and it also avoids many intermediary packages in
the tree.

--Gunnar

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