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

[Sanne Grinovero]

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