Annotations

Since 3.0 (2023-02), a service could be defined with a @Service annotation instead of a <service> element in services.xml. In 4.0 the annotation system covers every definition kind:

• Services, entities and view entities.
• Controllers: requests, views and events.
• Widgets: screens, forms, menus and trees.

The shipped applications are migrated. Commit 4d34564a9e (“Complete XML-to-annotation migration: delete redundant XML, fix loaders and converters”, 2026-08-30) deleted the XML files that annotation classes now cover, across widget forms, menus, trees and screens, service and entity definitions, and reduced controller.xml files to includes, handlers and events. Existing XML still loads: an application, an addon or a hot-deploy component that keeps its <service>, <entity> or widget XML does not need to convert it.

Where each kind lives#

How the annotations are found#

You do not declare an annotation class anywhere. Each component carries a ComponentReflectInfo with a ReflectQuery over that component’s own classes, and each reader asks it for the classes that carry its annotation: getAnnotatedClasses(Entity.class) for entities, and the same for services, SECA and EECA rules, controllers and widgets.

The readers run when the model they feed is built, not in a container of their own:

• ModelReader calls EntityAnnotationReader and ViewEntityAnnotationReader while it builds the entity model.
• ModelServiceReader reads @Service while it builds the service model.
• ConfigXMLReader reads @ControllerDef when a webapp’s controller is first needed.
• ScreenAnnotationReader reads the widget annotations when a screen is first resolved.

So a component’s annotations are available as soon as that component’s model is read, and a delegator exists by then. Put the class anywhere in the component’s source; the package does not matter.

Convert XML to annotations#

The convertXmlToAnnotation Gradle task reads an existing XML definition file and writes the matching Java annotation class.

./gradlew convertXmlToAnnotation -PxmlFile=applications/setup/widget/SetupForms.xml
./gradlew convertXmlToAnnotation -Pcomponent=setup
./gradlew convertXmlToAnnotation -PxmlFile=... -PoutputPackage=com.ilscipio.scipio.setup.widget
./gradlew convertXmlToAnnotation -Pcomponent=setup -PremoveXml=true

A companion task, removeMigratedXml -Pcomponent=<name>, deletes XML files that a previous conversion already fully covers, with a -PdryRun=true preview.