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.