Enforcing Component Constraints

[Rod Widdowson]

I'd kept clear of this because SAL (if you'll don't know SAL, you're in luck) has taught me to dislike annotations, but that is
irrational dislike - somewhere deep in my cynical heart I do believe in their utility as documentation.

SAL as also taught me to hate with Scott's "heat of a thousand burning suns" any tool which pretends to be able to do anything
sensible with annotations.  In my (admittedly limited experience) they invariably show up flaws in the annotation, or the tool
developer's ability to write code, often both.  Blind obedience can then lead you to compromise your design and architecture and
then the boot is on the wrong foot.

Nonetheless for me there is an important case for testing as well as annotating, an example is the case of a @Notnull parameter for
a method which will mostly work when it is null.  Such code could escape gentle testing and might even escape full testing, but it
would sure as hell bite the end user.

As a concrete example consider some code I'm mulling over to rationalize function between two similar, but not derived classes. 

I'm considering writing a protoype like this:

 protected static BeanDefinition buildTLSSocketFactory(
            final @Nonnull Logger log,
            final @Nonnull Element element, 
           final @Nonull ParserContext parserContext,
           final @Nullable String tlsTrustEngineRef, 
           final @Nullable String httpClientSecurityParametersRef) {

I'm sure that you can infer that event without a constraints check, a caller will find out real quick if 2nd or3rd parameter is not
null.  But "log"?  Well I'm only using that when I hit a misconfiguration.  So if a null parameterization hit that then there is a
chance that we'd not notice until the first user misconfigured, and we've replaced a warning with a crash.

This is a bit contrived I know, most of our tests hit this sort of thing, but not all.  So for me it is a cheap bit of "left-shift"
and I try to annotate (for documentation) and check (for left shift).  

Why not just check (no annotation ) ?  Because that makes for more work for us (to read the method), and people are more likely to
(accidentally or otherwise) strip out constraints checks tham annotation.

Is annotation API ? I just don't know.

But when it comes to it, I do understand that my views have been driven by exposure to poor tools..