There's a fine tension in technical specifications between making the content bulletproof and readable.
Bulletproof
specifications can can be implemented by more than one party or vendor with little to no variation, which allows
for binary compatibility, reduces porting issues and vendor lock-in. Techniques such as BNF are used to help increase
the un-misinterpretability of the content. These characteristics can come at the sacrifice of readability.
Readable specifications, on the other hand, can be read by real human beings, most of whom are not planning on
creating a commercial-grade implementation of the specification and who can be waylaid and lost by being overly
anally retentive in language.
These two tensions needn't necessarily be resolved in a single document. It's possible to write one document to aid
with the implementation and interpretation of the finer, subtler points for experts, and another document to aid in
introduction, comprehension and adoption. I'm surprised this approach isn't used more often than it is.
The Proposed Final Draft of JSR 250 falls on the readable side;
don't fear to crack open the PDF and take a peek, there are no W3C-like specification trolls hiding within, waiting to
ambush you with document cross-references and jargon.
In particular, the guidelines on annotations and inheritance are welcome; this is something I've thought about a few
times lately, so it's nice to see someone laying some ground rules. I haven't done enough annotation with inheritence
to form a strong opinion, but this is, at least, a starting point to which I can react.
If you're not willing to give it a read, it covers the following annotations:
@Generated: for marking the results of code generation
IoC and Container Lifecycle
@Resource(s): for marking injection points (IoC). Seems to be JNDI-based. Not sure I clearly understand the class-level (which is neither setter nor field injection, but runtime); I believe this, like existing resource references, simply declares the dependency, but leaves you to look up the resource through JNDI the good ol' way (POJNDI?)
@PostConstruct and @PreDestroy: container-based initialization and destruction methods
Security
@RunAs: a marks methods as running with a particular security-context (think sudo for JEE)
@RolesAllowed, @PermitAll, @DenyAll: more security methods, these ones more for access control
@DeclareRules: To declare the roles the above can use; not sure why this wasn't described before the other two.
There's more overlap between this spec and the EJB 3.X spec than I had initially expected, so most of these annotations should come as no surprise to anyone who's been following EJB 3.
As many such readable documents do, it seems to leave a fair amount to the imagination, so while I'm pleased to see the
beginnings of standardization, I'm inclined to believe that there will be several more revisions before we can truly
expect to port annotated beans from one framework to another without intervention. This kind of flexibility is often
preferable in early-stage technologies so as to allow vendors to work out the kinks and establish preferences before
locking down the details.
Previous Topic
