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
.