0

Here is a sample method:

@ApplicationScoped
public class MyClass{
    public void getUser(@Min(1) int id){
        //get User logic
    }
}

I'm in a CDI environment with @ValidateOnExecution(type = ExecutableType.ALL) by default, so I don't have to write any validation logic inside the method body. Here what happens if i call the method with an invalid value:

try{
    getUser(-1);
} catch (ConstraintViolationException e) {
    e.printStackTrace();  //this will be executed!
}

But this only happens if MyClass is instantiated by CDI.
If someone manually instantiates MyClass, of course its interceptors won't work. The reasons one may want to manually instantiate (using new) a class could be the followings:

  • Unit testing
  • There is a public empty constructor, as for CDI requirements

So the question is: should I specify in my API contracts (that is, the javadocs) that getUser throws ConstraintViolationException in case of bad input? As I explained above, this is not always true.
Is using bean validation interceptors a bad idea in this case?

10
  • Does this method throw, or does the interceptor throw? Are the interceptors that are "normally" attached, part of the method? Can you just document the constraint?
    – Caleth
    Jan 18 at 12:55
  • @Caleth the interceptor is this: github.com/apache/bval/blob/master/bval-jsr/src/main/java/org/… it is part of an external library (Apache BVal), it checks for parameters correctness and if there's a violation it throws the exception.
    – cidra
    Jan 18 at 14:12
  • 1
    Yes, but do you consider the action of the interceptor as part of the method?
    – Caleth
    Jan 18 at 14:14
  • E.g. can you document that there is a constraint, and when the constraint is violated it throws when instantiated by CDI, otherwise it has undefined behaviour?
    – Caleth
    Jan 18 at 14:16
  • 1
    Is it meaningful for your classes to be "manually instantiated"? I don't think it is correct to test this method without the interceptors
    – Caleth
    Jan 18 at 14:29

1 Answer 1

0

should I specify in my API contracts (that is, the javadocs) that getUser throws ConstraintViolationException in case of bad input?

No.

Avoid @throws in javadoc

@param is where I wanna hear about this. I really don’t care what unchecked exception you throw that I’m not going to handle.

Always think about how documentation is used. Don’t give into temptation and blindly fill in blanks.

4
  • This is a very good point. However, the website you linked assumes that my unchecked exception represents "defects in the program (bugs)" and not "invalid conditions in areas outside the immediate control of the program (invalid user input, database problems, network outages, absent files)" (Source: javapractices.com/topic/TopicAction.do?Id=129)
    – cidra
    Jan 18 at 21:18
  • @cidra if that’s what’s happening, and that’s how this shop works, then isn’t the framework throwing the wrong kind of exception? Jan 18 at 21:41
  • an interceptor can't throw a checked exception: that would break its interface
    – cidra
    Jan 21 at 15:14
  • @cidra so...... Jan 21 at 15:32

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.