Java Annotations

Annotations provide information so the application can deal with the code in certain classes. These annotations can instruct the generator on how to generate the superclass, how to register the class, and at runtime can affect the behavior of the class. The annotations are potent metadata used at several levels in the application.

Technically, annotations are structures described inside a JavaDoc comment before classes or methods. They start with an at sign character (@), followed by the annotation name, and the body of the annotation inside parenthesis. The body can be either comma-separated key=value pairs or a single value specified for a unique default key. The values can be any of strings (needing to be bound by quotes if there are special characters inside the string itself), lists (of either annotations or strings) bound by curly braces {} and separated by commas, or other annotations.

Each managed class (entity, change handler, business component, maintenance, and so on) typically has its own annotation. Each of these annotations has an underlying Java class in the com.splwg.shared.annotations package, where the name of the class is the name of the annotation suffixed by Annotation. The JavaDoc comments of these annotation classes should give more detail for each specific annotation.

For example:

Here is the entity annotation for batch control:


/**
 * @BusinessEntity (tableName = CI_BATCH_CTRL,
      oneToManyCollections = { @Child (collectionName = parameters, childTableName = CI_BATCH_CTRL_P,
                  orderByColumnNames = { "SEQ_NUM"})})
*/
public class BatchControl_Impl

The name of the annotation is BusinessEntity. It has as specified properties tableName and oneToManyCollections (there are others available, but not all of them need to be specified). The property tableName specifies the CI_​BATCH_​CTRL table as the table that this entity maintains. It also contains some oneToMany child collections, specified by the list of child annotations. In this case, there is a single child, with a collection name of parameters, pointing to the child table CI_​BATCH_​CTRL_​P, with a native order given by the column name SEQ_​NUM.

Once an annotation exists, the annotation wizard (in the Eclipse editors' plugin) can be used to maintain the annotation, showing the available annotation properties and validating the values entered. Thus, one way to create an annotation from scratch is to create a purely empty annotation with the correct name at the start of the class, and then use the annotation editor to fill in the details, avoiding typographical errors and the need to hunt down the allowed properties.

Here is a list of top-level annotations and their corresponding purpose or managed class type, and a pointer to an example class in the FW code where available.