Annotations

This guide describes the various annotations used by Apache Isis 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 Isis break out into five categories.

Core annotations

In Apache Isis 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 Isis.

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 Isis Annotations

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

Table 2. Other Isis Annotations
Annotation Purpose Layer File-based layout?

@Facets

Install arbitrary facets within the Apache Isis metamodel.

(any)

@HomePage

Query-only action (on domain service) to be invoked, result of which is rendered as the user’s home page.

UI

@MemberOrder

Ordering of properties, collections and actions, and also associating actions with either a property or a collection.

UI

Yes

@MinLength

Minimum number of characters required for an auto-complete search argument.

UI

@Programmatic

Ignore a public method, excluded from the Apache Isis metamodel.

Domain

JDO Annotations

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

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 Isis annotations.

Domain / persistence

Property

@javax.jdo.annotations.
PersistenceCapable

Used to build Apache Isis' 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 Isis does not overwrite application-defined primary keys, and to ensure is read-only in the UI.

Domain / persistence

Property

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

Table 4. JDO Annotations (unused within Apache Isis)
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 Isis.

Java EE Annotations

While Apache Isis 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 Isis.

Table 5. Java EE Annotations
Annotation Purpose Layer File-based layout?

@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 Isis:

  • 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).