[hibernate-dev] Hibernate ORM and Java 8 usage

Gunnar Morling gunnar at hibernate.org
Wed Jan 13 10:07:00 EST 2016 

Right; you also can use the same tag several times if you want several
distinct snippets from a file to end up in one listing in the docs:
https://github.com/hibernate/hibernate-validator/blob/master/documentation/src/test/java/org/hibernate/validator/referenceguide/chapter11/failfast/Car.java
.

The usage in the docs is like so:
https://github.com/hibernate/hibernate-validator/blame/master/documentation/src/main/asciidoc/ch11.asciidoc#L206..L213
.

I am very happy with this in general, the only (minor) downside is that it
naturally adds a bit of build time for compiling/testing the source. But I
think it's well spent and of course one can skip it for quick docs
rendering during authoring.


2016-01-13 15:57 GMT+01:00 Vlad Mihalcea <mihalcea.vlad at gmail.com>:

> This is how you mark an anchor in the source code:
>
>
> //tag::constraintMapping[]HibernateValidatorConfiguration configuration =
> Validation        .byProvider( HibernateValidator.class )
> .configure();
> ConstraintMapping constraintMapping =
> configuration.createConstraintMapping();
> constraintMapping    .type( Car.class )        .property( "manufacturer",
> FIELD )            .constraint( new NotNullDef() )        .property(
> "licensePlate", FIELD )            .ignoreAnnotations()
> .constraint( new NotNullDef() )            .constraint( new
> SizeDef().min( 2 ).max( 14 ) )    .type( RentalCar.class )
> .property( "rentalStation", METHOD )            .constraint( new
> NotNullDef() );
> Validator validator = configuration.addMapping( constraintMapping )
>   .buildValidatorFactory()        .getValidator();
>
> //end::constraintMapping[]
>
> The start/end comments allow to describe what goes in a snippet.
> Now that's another reason for having the tests in the documentation folder.
>
> Vlad
>
>
> On Wed, Jan 13, 2016 at 4:52 PM, Steve Ebersole <steve at hibernate.org>
> wrote:
>
>> Gunnar, that's very awesome.  You mention being able to include snippets
>> of an actual source file.  Do you have pointers to an explanation of the
>> snippets/portion part of that?
>>
>> On Wed, Jan 13, 2016 at 8:47 AM Gunnar Morling <gunnar at hibernate.org>
>> wrote:
>>
>>> Hey Vlad,
>>>
>>> slightly related and just in case you are not aware of this feature
>>> yet: You can include (parts of) actual source code files straight into
>>> AsciiDoc documents. We do that in the HV reference guide, e.g. at [1].
>>> That way you are 100% sure your examples actually compile (and pass
>>> tests) and you don't need to copy & paste them.
>>>
>>> Cheers,
>>>
>>> --Gunnar
>>>
>>> [1]
>>> https://raw.githubusercontent.com/hibernate/hibernate-validator/master/documentation/src/main/asciidoc/ch11.asciidoc
>>>
>>>
>>> 2016-01-13 15:30 GMT+01:00 Vlad Mihalcea <mihalcea.vlad at gmail.com>:
>>> > Hi Steve,
>>> >
>>> > The User Guide illustrations are snippets of code that go into the
>>> extras
>>> > folder, which stays right next to every chapter.
>>> > That's in the main folder.
>>> >
>>> > The tests are now located in the test folder of the documentation
>>> folder, so
>>> > that we can update/evolve them in future.
>>> > They are also a proof that the code snippets work.
>>> > There was a time when I realized that an example was not really ok,
>>> and I
>>> > had to change that.
>>> > I change the test first to see how it worked, and only then I updated
>>> the
>>> > Guide.
>>> > They are also a form of regression testing, so that we are alerted if
>>> some
>>> > future change will break the expectations we made while writing the
>>> > documentation code snippets.
>>> >
>>> > The reader can fork the repo and try them, if he wishes.
>>> >
>>> > Vlad
>>> >
>>> > On Wed, Jan 13, 2016 at 4:12 PM, Steve Ebersole <steve at hibernate.org>
>>> wrote:
>>> >>
>>> >> Vlad, I see you created a PR for moving your new tests out of
>>> >> hibernate-entitymanager into documentation.  I guess that depends on
>>> the
>>> >> intent.  Are they meant as illustrations?  And if so, how are you
>>> >> expecting
>>> >> people will see them?  And if they are meant as real tests rather
>>> than as
>>> >> illustrations, I think moving them is not appropriate.
>>> >>
>>> >> On Tue, Jan 12, 2016 at 4:57 AM andrea boriero <dreborier at gmail.com>
>>> >> wrote:
>>> >>
>>> >> > I'm not against the use of Java 8 letting AnimalSniffer guarding for
>>> >> > compatibility,
>>> >> > but I understand this can cause some problems so I'm ok with
>>> removing
>>> >> > Java
>>> >> > 8 usage from tests.
>>> >> >
>>> >> > On 12 January 2016 at 10:07, Gunnar Morling <gunnar at hibernate.org>
>>> >> > wrote:
>>> >> >
>>> >> > > @Vlad, what Java 8 syntax specifically are you using in the user
>>> guide
>>> >> > > tests (examples?)?
>>> >> > >
>>> >> > > I like the idea of using a current syntax in usage examples, to
>>> give
>>> >> > > the guide a current look and show that our APIs play well with
>>> current
>>> >> > > Java versions (while staying compatible with older ones).
>>> >> > >
>>> >> > >
>>> >> > >
>>> >> > > 2016-01-12 10:51 GMT+01:00 Sanne Grinovero <sanne at hibernate.org>:
>>> >> > > > +1 for Vlad's proposal to use the same JDK for tests and main
>>> code
>>> >> > > > in
>>> >> > > > a given module.
>>> >> > > >
>>> >> > > > Infinispan requires Java8 at runtime too, so that module should
>>> be
>>> >> > > > the
>>> >> > > > only one to use Java8?
>>> >> > > >
>>> >> > > > On 12 January 2016 at 07:55, Vlad Mihalcea <
>>> mihalcea.vlad at gmail.com>
>>> >> > > wrote:
>>> >> > > >> I used Java 8 syntax in the User Guide tests as I remembered
>>> that
>>> >> > tests
>>> >> > > can
>>> >> > > >> use it, but I also agree that this is a rather strange move.
>>> >> > > >> Since we need to support Java 1.6, maybe it's a better idea to
>>> use
>>> >> > > >> the
>>> >> > > >> latest JDK just in the modules where we have no other choice.
>>> >> > > >> For testing, I think that 1.6 is just fine and I could easily
>>> >> > > >> change
>>> >> > > those
>>> >> > > >> tests to remove the 1.8 dependency.
>>> >> > > >>
>>> >> > > >> So I vote for using the same JDK for both main and test in a
>>> >> > particular
>>> >> > > >> module.
>>> >> > > >>
>>> >> > > >> Vlad
>>> >> > > >>
>>> >> > > >> On Mon, Jan 11, 2016 at 11:35 PM, Steve Ebersole
>>> >> > > >> <steve at hibernate.org
>>> >> > >
>>> >> > > >> wrote:
>>> >> > > >>
>>> >> > > >>> The former.  People commit things that already assume the
>>> move to
>>> >> > Java
>>> >> > > 8
>>> >> > > >>> locally to build (and test).  But at the moment we have not
>>> >> > formalized
>>> >> > > >>> that, and so that causes problems when we import into an IDE
>>> - the
>>> >> > > imported
>>> >> > > >>> IDE project is built for 1.6 compliance and so everything we
>>> try
>>> >> > > >>> in
>>> >> > > the IDE
>>> >> > > >>> fails.
>>> >> > > >>>
>>> >> > > >>> On Mon, Jan 11, 2016 at 3:33 PM Gunnar Morling
>>> >> > > >>> <gunnar at hibernate.org
>>> >> > >
>>> >> > > >>> wrote:
>>> >> > > >>>
>>> >> > > >>> > Hey,
>>> >> > > >>> >
>>> >> > > >>> > > or we move to Java 8 and rely on
>>> >> > > >>> > > AnimalSniffer to make sure we are still compatible.
>>> >> > > >>> >
>>> >> > > >>> > WDYM by "move to Java8" exactly? Requiring it at Hibernate's
>>> >> > > >>> > build
>>> >> > > >>> > time, or also at runtime in user apps?
>>> >> > > >>> >
>>> >> > > >>> >
>>> >> > > >>> > 2016-01-11 19:49 GMT+01:00 Steve Ebersole <
>>> steve at hibernate.org>:
>>> >> > > >>> > > The use of Java 8 features in Hibernate ORM is starting to
>>> >> > expand.
>>> >> > > >>> > Luckily
>>> >> > > >>> > > it is still constrained to just tests.
>>> >> > > >>> > >
>>> >> > > >>> > > However these usages make development in an IDE more and
>>> more
>>> >> > > >>> difficult.
>>> >> > > >>> > > Previously this was isolated to hibernate-infinispan.
>>> Now[1]
>>> >> > this
>>> >> > > has
>>> >> > > >>> > > crept into hibernate-entitymanager.  We need to have a
>>> plan
>>> >> > > >>> > > here.
>>> >> > > >>> Either
>>> >> > > >>> > > we stop using Java 8 anywhere, or we move to Java 8 and
>>> rely
>>> >> > > >>> > > on
>>> >> > > >>> > > AnimalSniffer to make sure we are still compatible.
>>> >> > > >>> > >
>>> >> > > >>> > > Votes?  Other options?
>>> >> > > >>> > >
>>> >> > > >>> > > [1]
>>> >> > > >>> > >
>>> >> > > >>> >
>>> >> > > >>>
>>> >> > >
>>> >> >
>>> >> >
>>> https://github.com/hibernate/hibernate-orm/commit/c2ece0108ed52d5e3a227ed0150cfb5cb1a76101
>>> >> > > >>> > > _______________________________________________
>>> >> > > >>> > > 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
>>> >> > > _______________________________________________
>>> >> > > 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
>>> >
>>> >
>>>
>>
>

More information about the hibernate-dev mailing list