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

[Gunnar Morling]

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?

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
>