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 five 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 Apache Causeway Annotations

These annotations are also commonly used, but relate not to objects or object members but instead to other aspects of the Apache Causeway metamodel.

Table 2. Other Causeway 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
@Programmatic	Ignore a public method, excluded from the Apache Causeway metamodel.	Domain
@Title	Indicates which of the object’s properties should be used to build up a title for the object.	UI

JDO Annotations

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

Table 3. 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	Override for the object type, as used in `Bookmark`s, URLs for RestfulObjects viewer and elsewhere. Note that the discriminator overrides the object type that may otherwise be inferred from the @PersistenceCapable annotation.	Domain / persistence	Class
@javax.jdo.annotations. NotPersistent	Used to determine whether to enforce or skip some metamodel validation for `@Column` versus equivalent Causeway annotations.	Domain / persistence	Property
@javax.jdo.annotations. PersistenceCapable	Used to build Apache Causeway' own internal identifier for objects. If the `schema` attribute is specified (and if @Discriminator hasn’t been specified), is also used to derive the object type, as used in `Bookmark`s, URLs for RestfulObjects viewer and elsewhere.	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 4. 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

JPA Annotations

TODO: v2 - JPA is now also supported as an ORM. (As with JDO), some of JPA’s annotations are recognised by Apache Causeway.

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. Expect to see more added in future releases of Apache Causeway.

Table 5. 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
`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

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=EditingDISABLED).
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).