Should i specify that my methods "throws ConstraintViolationException" if the exception is actually thrown by a CDI interceptor?

Question

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?

• Caleth: 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?
• cidra: @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.
• Caleth: Yes, but do you consider the action of the interceptor as part of the method?
• Caleth: 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: Is it meaningful for your classes to be "manually instantiated"? I don't think it is correct to test this method without the interceptors

Answer 1

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.

• cidra: 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)
• candied_orange: @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?
• cidra: an interceptor can't throw a checked exception: that would break its interface
• candied_orange: @cidra so......