Emphasise XML-driven configuration over annotations for AOP injection and configuration in documentation [SPR-2849]

[spring-projects-issues]

Antranig Basman opened SPR-2849 and commented

One might be forgiven for coming to think that different parts of the Spring documentation were written by different people :P

For example, the last section of 3.3.8 includes the evaluation "The above example is generally is not a desirable solution since the business code is then aware of and coupled to the Spring Framework. Method Injection, a somewhat advanced feature of the Spring IoC container, allows this use case to be handled in a clean fashion."

This has as I see it always been one of the overriding goals of the Spring framework, that is to ensure that clients have as few dependencies as possible handed on to them. Unfortunately in the area of Java 5 annotations, there doesn't seem to be the same awareness/eagerness to ensure dependency cleanliness.

For example, section 6.4.2 on "@AspectJ or XML for Spring AOP?" gives as the headline advice "If you are using Java 5, use annotations" which is inconsistent with this philosophy. Further, section 6.8.1 shows an extensively worked example using annotations with little if any consideration given to the externally-specified (XML or other) equivalent. Whilst section 6.3 opens with a discussion of the <aop: namespace for configuration and its uses, it receives insufficient attention and enthusiasm throughout the rest of chapter 6 :P

I suggest that these sections of the documentation be reworked to show the XML-driven solution continuing as the "primary" form, with the annotation equivalent presented afterwards as an option for those who are happy with the dependency burden.

There is some discussion of this issue in the Spring forums later in this "Architecture" thread:
http://forum.springframework.org/showthread.php?t=15294&page=9

---

Affects: 2.0 final

1 votes, 1 watchers

[spring-projects-issues]

Juergen Hoeller commented

We noticed this ourselves recently, and started a bit of internal discussion about how the documentation should discuss this. I'm not quite sure what the current state of things is there; Rick knows best :-) In any case, we will definitely do something about it.

Juergen

[spring-projects-issues]

Oleksandr Alesinskyy commented

Can not completely agree with this proposal - using annotations does not increase, rather reduce dependency from Spring.
E.g. you may anytime switch from Spring to pure AspectJ implementation (with LWT or postcompilation). Or for that matter, to any other AOP tool with annotation support.

Annotation is not implementation, it is rather declaration of intentions, which often belong to code itself. The more drasctic example is transaction management - whatever peoples says transactionality of code is a business concern and is (or shall be) determined by business requirments,
while transaction management itselg is a pure techicality and clutter the code enormously. Annotations solve this dillema perfectly (or as near to perfection as it is possible in real world).

Definitely, there are aspects that are completely independent from business logic, but they are, usually, less crucial). For them XML-based configuration suits better, but, IMHO, desicion has to be made in favour of crucial ones.

Oleksandr

[spring-projects-issues]

Antranig Basman commented

Oleksandr - I think your observation misses the point of this report.

The point is that any annotation represents a direct dependency, of exactly the same grade as an interface, since both must appear in the import definitions and amongst the code of the target. Noone is arguing with the importance of declarative transaction definitions or of AOP itself, but the strategy of declaring these in annotations. The XML style for these declarations is equivalent in effect, but produces no intrusion on the target code. This "zero-dependence" version is a crucial design option that should not only be maintained, but promoted to developers. Your statement "you may switch anytime to any other AOP tool with annotation support" is not correct - the tool must recognise the specific annotation "classes" which are imported, or else the code must be changed.

[spring-projects-issues]

Oleksandr Alesinskyy commented

Have to disagree - you decouple from code its inherent requirements, without which code is unusable (while runnable). You loss any possibility to understand from code itself these requirements and ever less to automatically extract them. Such approach is just dangerous and shall be not promoted, but demoted to largest possible extent. Developers shall be warned to use it with great caution and only for aspects that has no direct influence on business behavior of code (e.g.logging).

Concerning transaction classes - yes, they shall be recognized, but they are trivial (no behavior, just set of markers), so it is not such great sort of task. And when I say "switch" I do not mean switch with no efforts, I mean switch with reasonable amount of them.

The real problem behind this discussion is that while aspects are supposed to be "orthogonal" to code, many of them are not, and in such cases to separate them from code you need to tear-off them leaving bleeding wounds.

[spring-projects-issues]

Oleksandr Alesinskyy commented

Try to formulate it in less emotional and more pragmatic way -
if something is part of method (or class) contract (as transactionality), it better to be expressed by annotation,
if not - XML configuration is superior.

Regards,
Oleksandr

[spring-projects-issues]

Rick Evans commented

Hi Antranig and Oleksandr

I have taken all of your comments on board, and have made some changes to the AOP chapter of the Spring reference documentation.

I have not changed the ordering of the chapter contents: the @AspectJ-style is still covered prior to the XML-style, but i have fleshed out the section entitled 'Choosing which AOP declaration style to use'. I have based the changes to said section on both of your comments... there is no hard and fast rule as to which style is 'better', and there is no hard and fast opinion within the Spring team as to which style is better.

Both of you made good points though, and I hope that the changes to the documentation make for a better read. If you still don't like the somewhat fence sitting text, I shall try to get one of the Big Four (Juergen , Rod, Adrian, Rob) to blog about this.

Happy New Year, cheers
Rick