# 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.

- `BatchJobAnnotation` for batch jobs, defining such properties as whether the batch is multithreaded and what soft parameters it uses. An example batch job in Java is defined in the class `com.splwg.base.domain.todo.batch .BatchErrorToDoCreation`.
- `BusinessComponentAnnotation` for business components. This will register the business component either as a new one (and define whether it can be replaced or not), or a replacement of an existing one. An example business component is `com.splwg.base.domain.todo.toDoEntry.ToDoEntryAssigner_Impl`.
- `AlgorithmComponentAnnotation` for defining algorithm implementations. This is used to create a new algorithm implementation, defining which algorithm spot it is for, and what soft parameters it uses. An example algorithm component is `com.splwg.base.domain.common.characteristicType.AdhocNumericValidationAlgComp_Impl`.
- `EntityChangeAuditorAnnotation` for implementing audit behavior when an entity is modified. An example auditing component is `com.splwg.base.domain.common.audit.DefaultTableAuditor_Impl`.
- `BusinessEntityAnnotation` for defining or extending business entities, with properties defining the table maintained and any one-to-many child tables, etc. An example entity is `com.splwg.base.domain.batch.batchControl.BatchControl_Impl`.
- `ChangeHandlerAnnotation` for extending entity persistence behavior by adding validations or extra code to execute on add/change/delete actions. An example change handler is `com.splwg.base.domain.common.characteristicType.CharacteristicType_CHandler`.
- `CodeDescriptionQueryAnnotation` for adding services to handle drop-down lists for the UI. There are no examples of this general component; the Oracle Utilities Application Framework implements only entity code descriptions.
- `EntityCodeDescriptionQueryAnnotation` for adding services to handle drop-down lists for the UI, that are directly related to entities. An example of an entity code description component is `com.splwg.base.domain.common.country.CountryCodeDescriptionQuery`.
- `MaintenanceExtensionAnnotation` for extending a maintenance. There are no examples of maintenance extensions in the framework. It is purely an implementer component. See Maintenance Extensions (User Guide: Cookbook, Hooking into User exits: Hooking into Maintenance Class User Exits).
- `QueryPageAnnotation` for creating a new query page service. An example is `com.splwg.base.domain.todo.toDoQueryByCriteria.ToDoQueryByCriteriaMaintenance`.
- `PageMaintenanceAnnotation` for creating a new generic page maintenance. An example is `com.splwg.base.domain.security.user.SwitchUserLanguageMaintenance`.
- `EntityListPageMaintenanceAnnotation` for creating a new maintenance for an entity-type, with a list based front end. An example is `com.splwg.base.domain.common.phoneType.PhoneTypeListMaintenance`.
- `EntityPageMaintenanceAnnotation` for creating a new entity maintenance, that maintains a single instance at a time. An example is `com.splwg.base.domain.batch.batchControl.BatchControlMaintenance`.
- `ListServiceAnnotation` for creating a list service (read only), meant for trees for example. An example is `com.splwg.base.domain.security.user.UserAccessGroupCountListInquiry`.

Parent topic: Developer Guide