Annotations

This guide describes the various annotations used by Apache Causeway to provide additional metadata about the domain objects. Most of these are defined by the framework itself, but some are from other libraries. It also identifies a number of annotations that are now deprecated, and indicates their replacement.

The annotations supported by Apache Causeway break out into several categories.

Core annotations

In Apache Causeway every domain object is either a domain entity, a view model or a domain service. And each of these are made up of properties, collections and actions (domain services only have actions).

For each of these domain types and members there are two annotations. One covers the semantics intrinsic to the domain (eg whether an action parameter is optional or not), then other (suffix …Layout) captures semantics relating to the UI/presentation layer.

Most UI semantics can also be specified using dynamic object layout.

The table below summarizes these most commonly used annotations in Apache Causeway.

Table 1. Core annotations for domain objects, services and members
Annotation	Purpose	Layer	File-based layout?
@Action	Domain semantics for actions	Domain
@ActionLayout	User interface hints for actions	UI	Yes
@Collection	Domain semantics for collections	Domain
@CollectionLayout	User interface hints for collections	UI	Yes
@DomainObject	Domain semantics for domain object (entities and optionally view models)	Domain
@DomainObjectLayout	User interface hints for domain object (entities and optionally view models)	UI	Yes
@DomainService	Class is a domain service (rather than an entity or view model)	Domain
@DomainServiceLayout	User interface hints for domain services	UI
@Parameter	Domain semantics for action parameters	Domain
@ParameterLayout	Layout hints for an action parameter (currently: its label position either to top or the left).	UI	Yes
@Property	Domain semantics for properties	Domain
@PropertyLayout	Layout hints for a property	UI	Yes

Other Causeway Annotations

There are a number of other annotations defined by the framework, for a variety of purposes.

The following are commonly used:

Table 2. Commonly annotations
Annotation	Purpose	Layer
@HomePage	Query-only action (on domain service) to be invoked, result of which is rendered as the user’s home page.	UI
@MinLength	Minimum number of characters required for an auto-complete search argument.	UI
@Title	Indicates which of the object’s properties should be used to build up a title for the object.	UI

The following are used to indicate whether a given should be included or excluded in the metamodel. Whether they are required depends on the setting of causeway.core.meta-model.introspector.policy, but it is always safe to use them.

Table 3. Programming Model Inclusion/Exclusion
Annotation	Purpose	Layer
@Domain.Include	Explicitly include the method as part of the metamodel.	UI/Domain
@Domain.Exclude	Explicitly exclude the method as part of the metamodel.	UI/Domain
@MemberSupport	Intended to be annotated on `hideXxx()`, `disableXxx()` and other supporting methods, explicitly include the method as part of the metamodel. Equivalent to @Domain.Include	Domain
@ObjectSupport	Intended to be annotated on `title()`, `iconName()` and other UI hint methods, explicitly include the method as part of the metamodel. Equivalent to @Domain.Include	UI
@ObjectLifecycle	Intended to be annotated on `created()`, `updated()` and other lifecycle methods, explicitly include the method as part of the metamodel. Equivalent to @Domain.Include	Persistence
@Programmatic	Indicates that a method is to be called only programmatically, and so is not part of the metamodel. Equivalent to (and the original name of) @Domain.Exclude	UI/Domain

The next annotations relate to the overall system architecture.

Table 4. Architecture
Annotation	Purpose	Layer
@Module	An alias for Spring’s own `@Configuration`, identifies a logical module consisting of a set of services, entities, mixins, fixtures etc.	Domain
@InteractionScope	Annotated on a domain service to indicate that it should be scoped by the interaction (roughly equivalent to an HTTP request).	Domain

The final annotations relate to the definition of custom value types:

Table 5. Custom value type support
Annotation	Purpose	Layer
@Value	Marker annotation that indicates the object is a value type (as opposed to a domain service, entity, view model or mixin). Value types also require an implementation of a ValueSemanticsProvider.	Domain
@ValueSemantics	Annotated on a property or parameter, indicating that the property/parameter’s type should be considered a value type, and supplying details of the service implementing ValueSemanticsProvider that describes how the framework should interact with the value type.	Domain

Java EE Annotations

While Apache Causeway does define many of its own annotations, the policy is to reuse standard Java/JEE annotations wherever they exist or are added to the Java platform.

The table below lists the JEE annotations currently recognized.

Table 6. Java EE Annotations
Annotation	Purpose	Layer
`@javax.validation.` `constraints.` `Digits`	Precision/scale for BigDecimal values.	Domain
`@javax.validation.` `constraints.` `Pattern`	Regular expressions for strings	Domain
`@javax.annotation.` `Nullable`	Specify that a property/parameter is optional.	Domain

JAXB Annotations

Table 7. JAXB Annotations
Annotation	Purpose	Layer
`javax.xml.bind` `.annotation` `XmlRootElement`	JAXB annotation indicating the XML root element when serialized to XML; also used by the framework for view models (whose memento is the XML), often also acting as a DTO.	Application
`javax.xml.bind` `.annotation` `XmlJavaTypeAdapter`	JAXB annotation defining how to serialize an entity. Used in conjunction with the (framework provided) `PersistentEntityAdapter` class to serialize persistent entities into a canonical OID (equivalent to the `Bookmark` provided by the BookmarkService).	Domain

JPA Annotations

The table below lists the JPA/EclipseLink annotations currently recognized by Apache Causeway.

Table 8. JPA Annotations
Annotation	Purpose	Layer	Applies to
@javax.persistence. Entity	Flags that the class is an entity, creating an abstraction layer through which the Causeway framework interacts with the underlying persistent domain object.	Domain / persistence	Class

Causeway also parses the following JPA annotations, but the metadata is currently unused.

Table 9. JPA Annotations (unused within Apache Causeway)
Annotation	Purpose	Layer	Applies to
`@javax.persistence. Transient`	Unused	Persistence	Property
`@javax.persistence. Table`	Unused	Persistence	Class

JDO Annotations

The table below lists the JDO/DataNucleus annotations currently recognized by Apache Causeway.

Table 10. JDO Annotations
Annotation	Purpose	Layer	Applies to
@javax.jdo.annotations. Column	Used to determine whether a property is mandatory or optional. For `String` and `BigDecimal` properties, used to determine length/precision/scale.	Domain / persistence	Property
@javax.jdo.annotations. Discriminator	Infer the logical type name. This takes precedence of `@PersistenceCapable` (below). However, `@DomainObject#logicalTypeName` takes precedence over this.	Domain / persistence	Class
@javax.jdo.annotations. NotPersistent	Used to determine whether to enforce or skip some metamodel validation on nullability (`@Column` vs equivalent Causeway annotations).	Domain / persistence	Property
@javax.jdo.annotations. PersistenceCapable	The `schema` attribute plus table name is used to the logical type name. However, `@Discriminator` (above) takes precedence, as does `@DomainObject#logicalTypeName`. Internally, it also flags that the class is an entity, creating an abstraction layer through which the Causeway framework interacts with the underlying persistent domain object.	Domain / persistence	Class
@javax.jdo.annotations. PrimaryKey	Used to ensure Apache Causeway does not overwrite application-defined primary keys, and to ensure is read-only in the UI.	Domain / persistence	Property

Causeway also parses the following JDO annotations, but the metadata is currently unused.

Table 11. JDO Annotations (unused within Apache Causeway)
Annotation	Purpose	Layer	Applies to
@javax.jdo.annotations. DataStoreIdentity	Unused	Persistence	Class
@javax.jdo.annotations. Queries	Unused	Persistence	Class
@javax.jdo.annotations. Query	Unused	Persistence	Class
@javax.jdo.annotations. Version	Unused	Persistence	Class

Examples

To give just a few examples of annotations supported by Apache Causeway:

if a property is read-only, then this can be annotated with @Property(editing=Editing.DISABLED).
if a class has a small fixed set of instances (eg a picklist), then it can be annotated using @DomainObject(bounded=true)
if a class is a domain service and should be automatically instantiated as a singleton, then it can be annotated using @DomainService
if an action is idempotent, then it can be annotated using @Action(semantics=SemanticsOf.IDEMPOTENT).
if an action parameter is optional, it can be annotated using @Parameter(optionality=Optionality.OPTIONAL)

Some annotations act as UI hints, for example:

if a collection should be rendered "open" rather than collapsed, it can be annotated using @CollectionLayout(defaultView="table")
if an action has a tooltip, it can be annotated using @ActionLayout(describedAs=…)
if a domain object is bookmarkable, it can be annotated using @DomainObjectLayout(bookmarking=BookmarkPolicy.AS_ROOT).