Hibernate Books

All times are UTC - 5 hours [ DST ]



Post new topic Reply to topic  [ 6 posts ] 
Author Message
 Post subject: Suggestions for javadoc Taglet for validation constraints
PostPosted: Thu Jul 13, 2017 1:38 pm 
Regular
Regular

Joined: Mon Aug 07, 2006 6:22 pm
Posts: 66
I'm in the process of writing a javadoc Taglet that is intended to be used in the class overview block, and which will render a table describing the validation constraints for the class and the properties in the class. This will initially be used in internal projects, and I'll release the code and open-source it if there is interest in using this.

I'm really just looking for input on whether this is useful, any suggestions, and one long shot request for help on an issue not related to validator.

For the sample, here are the test classes:
Code:
/**
* @att.det.validationConstraints
*/
@ValidStuff(message = "must be valid stuff")
public class Stuff extends BaseStuff {
    private int foo;
    private String bar;
    private Thing thing;
    private Thing anotherThing;
   
    public int getFoo() { return foo; }
    @Size(min = 3, max = 5)
    @Pattern(regexp = "abc.*")
    public String getBar() { return bar; }
    @Valid
    public Thing getThing() { return thing; }
    @NotNull
    @Valid
    public Thing getAnotherThing() { return anotherThing; }

    ... setters ...
}
public class BaseStuff {
    private int junk;

    @Min(value = 7)
    public int getJunk() { return junk; }

    public void setJunk(int junk) { this.junk = junk; }
}


Here is what the output looks like right now (don't know to display this "inline"):
https://imagebin.ca/v/3TFfMSz7tn13

You can see the following from that example:
* Any constraints on the entire class don't specify a property name
* Properties with multiple constraints list them on separate lines
* Base class property constraints are treated exactly the same
* If the property is cascading (@Valid is present), it adds "See class <classname>"

The last one probably looks a little dumb, as you'd probably prefer to have that be a link to the class in question. I'd like to figure out how to do that. Some of you might be thinking "duh, just use "{@link <classname>.class}", but you'd be wrong, as taglets are executed after tags are parsed, and it can only generate pure text. There might be a javadoc API that I can use to generate the correct output, but I'm not aware of one.

The table title and column headers are not internationalized, not sure how to do that effectively.

Any comments or suggestions?


Top
 Profile  
 
 Post subject: Re: Suggestions for javadoc Taglet for validation constraints
PostPosted: Fri Jul 14, 2017 2:46 pm 
Regular
Regular

Joined: Mon Aug 07, 2006 6:22 pm
Posts: 66
For the record, Gunnar mentioned to me that he'd prefer to see all the constraints for a single property on a single row. I don't know that I would want that, but I could see that some people might want that. I verified it can be done with a configuration option, although I'm currently struggling to find any way to register Taglets with configuration variations. I don't see any way as of yet.


Top
 Profile  
 
 Post subject: Re: Suggestions for javadoc Taglet for validation constraints
PostPosted: Tue Sep 26, 2017 5:15 am 
Hibernate Team
Hibernate Team

Joined: Sat Jan 24, 2009 12:46 pm
Posts: 385
Hey David, did you ever find the time to publish this work on GitHub or similar? I just came a cross a question on StackOverflow (https://stackoverflow.com/questions/464 ... 4#46422334) which seems to ask pretty much for what you have been trying to build here.

_________________
Visit my blog at http://musingsofaprogrammingaddict.blogspot.com/


Top
 Profile  
 
 Post subject: Re: Suggestions for javadoc Taglet for validation constraints
PostPosted: Tue Sep 26, 2017 9:59 am 
Regular
Regular

Joined: Mon Aug 07, 2006 6:22 pm
Posts: 66
So here's the thing.

My goal was, once I got it completely working in my builds, I would release it.

I've gotten it to work fine in "standalone" builds, or "single-project" builds. Getting it to work in multi-project builds has not happened yet, and I've been blocked on that effort. The problem is the build tools. I've tried this in both Maven and Gradle, and they both present different problems. Both of them have to do with the issue that this taglet requires access to the class associated with the source file the taglet is contained within. It's uncommon for taglets to require this, so the tool chain doesn't support this very well right now.

I technically could get it to work in Maven, but what I would have to do to get it work has a bad smell (coding knowledge of all subprojects in a parent pom). In retrospect, this may be my only option for a while, so perhaps I'll come back to this.

I'd really prefer it to work in Gradle, although my current build is using Maven. Once I was able to remove all obstructions of Gradle in this build, I was going to convert.

The problem with Gradle is that the plugin for merging javadoc from multiple subprojects just doesn't work. I've filed an issue for this, but it's been completely ignored. I see Gradle as the "build tool of the future", but issues with plugins are going to have to get worked out.


Top
 Profile  
 
 Post subject: Re: Suggestions for javadoc Taglet for validation constraints
PostPosted: Thu Oct 12, 2017 9:38 am 
Hibernate Team
Hibernate Team

Joined: Sat Jan 24, 2009 12:46 pm
Posts: 385
Hi David,

Great to hear you could make some progress. I'd suggest that you let not stop you by those build tool issues and rather publish a first version on GitHub. I know there's always that one more thing which one feels should be there before releasing it, but it doesn't have to be perfect! Instead, put something out and people may use it on a single module already. You can improve from there, or maybe even someone else steps up to help out.

Looking forward to seeing this project,

Cheers,

--Gunnar

_________________
Visit my blog at http://musingsofaprogrammingaddict.blogspot.com/


Top
 Profile  
 
 Post subject: Re: Suggestions for javadoc Taglet for validation constraints
PostPosted: Thu Oct 12, 2017 2:30 pm 
Regular
Regular

Joined: Mon Aug 07, 2006 6:22 pm
Posts: 66
Acknowledged. Just trying to find the time amongst priorities.


Top
 Profile  
 
Display posts from previous:  Sort by  
Post new topic Reply to topic  [ 6 posts ] 

All times are UTC - 5 hours [ DST ]


You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum

Search for:
© Copyright 2014, Red Hat Inc. All rights reserved. JBoss and Hibernate are registered trademarks and servicemarks of Red Hat, Inc.