[Python-Dev] 318: Annotation background

[Neil Hodgson]

   It appears from the discussion and PEP that there has not been a lot of
experience here with the Java and C# analogues of decorators.

   In Java, especially server edition features like Entity Java Beans, there
is a requirement for large volumes of supporting files for a system. Some of
these are Java files defining a set of related classes and some are XML
files defining how these can be used. For example, say I have two database
tables, Master and Detail, defined as expected. These will need to be
defined as Java classes, with fields corresponding to the database columns.
Extra fields will be needed for transient attributes, some of which will be
defined by the developer and others by the infrastructure such as dirty
bits, transaction IDs, and remote connection handles. As well as the main
class, there is a need for derived classes such as a remote interface that
looks like the class, a value class that contains the fields (or a subset of
the fields) that can be sensibly copied together to a remote system, and
views of the data that turn relational artifacts like keys into a more
object-oriented form, such as providing a pointer from a Detail to a Master
or having the Detail records appear to be a list on the Master object.

   Maintaining all these files requires far too much work and you will
always be coping with updates that forgot one file. Then along came XDoclet
[1]. XDoclet uses doc comment tags to move the information about associated
source and XML files into the main class file. For example,

/**
 * @ejb.bean
 *   type="CMP"
 *   name="Master"
 */
public abstract class MasterEJB implements EntityBean {
    /**
     * @ejb.value-object
     *   aggregate="example.vo.DetailValue"
     *   aggregate-name="Details"
     *   type="Collection"
     * @ejb.relation
     *   name="Master-Detail"
     */
    public abstract Collection getDetails();
    public abstract void setDetails(Collection details);

   However, comments should be for documentation, not implementation code,
and these 'comments' are now some of the most important and most difficult
to maintain parts of the source. So there was a desire to move this into the
main language where there could be more consistency and earlier checking for
correctness. This has led to JSR 175 [2] which allows @ annotations to be
applied directly to identifiers rather than indirectly through preceding
comments.

[1] http://xdoclet.sourceforge.net/xdoclet/index.html
[2] http://www.jcp.org/aboutJava/communityprocess/review/jsr175/

   Neil