I think changing the return type of ConstraintViolationBuilder#addNode() to NodeBuilderCustomizableContext is a problem.
While that change is source compatible (code using addNode() can be compiled against the new API version without having to be adapted) it is not binary compatible. That is, code compiled against the previous version will fail at runtime:
java.lang.NoSuchMethodError: javax.validation.ConstraintValidatorContext$ConstraintViolationBuilder.addNode(Ljava/lang/String;)Ljavax/validation/ConstraintValidatorContext$ConstraintViolationBuilder$NodeBuilderDefinedContext;
This error occurs, no matter wether the result of addNode() is assigned to a variable or not.
What we might try to do is to return an intersection type from ConstraintViolationBuilder#addNode() like this:
interface ConstraintViolationBuilder {
<T extends NodeBuilderDefinedContext & NodeBuilderCustomizableContext> T addNode(String name);
ConstraintValidatorContext addConstraintViolation();
}
This is source compatible and AFAICS it's also binary compatible because the erasure of T is its leftmost bound, that is NodeBuilderDefinedContext. That way code compiled against the old API can still dispatch the addNode() method, while code written against the new version can invoke all methods defined on NodeBuilderDefinedContext and NodeBuilderCustomizableContext.
Btw. I stumbled upon [1] which gives a very good overview on the compatibility of all sorts of API changes.
--Gunnar