Annotations

Apache Isis documentation is broken out into a number of user, reference and "supporting procedures" guides.

The user guides available are:

The reference guides are:

The remaining guides are:

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

Some annotations act as UI hints, for example:

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.

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

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

Apache Isis uses JDO/DataNucleus as its ORM, and infers some of its own metadata from the JDO annotations.

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

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

While Apache Isis does, as of today, define a good number 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.

As Apache Isis has evolved and grown, we found ourselves adding more and more annotations; but most of these related to either an object type (entity, view model, service) or an object member (property, collection, action). Over time it became harder and harder for end programmers to discover these new features.

Accordingly, (in v1.8.0) we decided to unify the semantics into the main (core) annotations listed above.

The annotations listed in the table below are still supported by Apache Isis, but will be retired in Apache Isis v2.0.

These annotations have only incomplete/partial support, primarily relating to the management of value types. We recommend that you do not use them for now. Future versions of Apache Isis may either formally deprecate/retire them, or we may go the other way and properly support them. This will depend in part on the interactions between the Apache Isis runtime, its two viewer implementations, and DataNucleus persistence.

The @Action(command=…​) attribute (and the related @Action(commandPersistence=…​) and @Action(commandExecuteIn=…​) attributes) allows an action invocation to be made into a concrete object such that it can be inspected and persisted. The primary use case for this is enhanced profiling/auditing, and it also supports the deferring the execution of the action such that it can be invoked in the background.

The annotation works with (and is influenced by the behaviour of) a number of domain services:

Each action invocation is reified by the CommandContext service into a Command object, capturing details of the target object, the action, the parameter arguments, the user, a timestamp and so on.

If an appropriate CommandService is configured (for example using (non-ASF) Incode Platform’s command module), then the Command itself is persisted.

By default, actions are invoked in directly in the thread of the invocation. If there is an implementation of BackgroundCommandService (as the (non-ASF) Incode Platform's command module does provide), then this means in turn that the BackgroundService can be used by the domain object code to programmatically create background Commands.

The command() attribute determines whether the action invocation should be reified into a Command object (by the CommandContext service).

The default is AS_CONFIGURED, meaning that the configuration property isis.services.command.actions is used to determine the whether the action is reified:

If there is no configuration property in isis.properties then all actions are reified into Commands.

This default can be overridden on an action-by-action basis; if command() is set to ENABLED then the action is reified irrespective of the configured value; if set to DISABLED then the action is NOT reified irrespective of the configured value.

For example:

corresponds to the behaviour described above; the Command object is persisted (assuming an appropriate CommandService is defined, and executed immediately in the foreground).

Whenever a domain object (or list of domain objects) is to be rendered, the framework fires off multiple domain events for every property, collection and action of the domain object. In the cases of the domain object’s actions, the events that are fired are:

Subscribers subscribe through the EventBusService using either Guava or Axon Framework annotations and can influence each of these phases.

By default the event raised is ActionDomainEvent.Default. For example:

The domainEvent() attribute allows a custom subclass to be emitted allowing more precise subscriptions (to those subclasses) to be defined instead. This attribute is also supported for collections and properties.

For example:

The benefit is that subscribers can be more targeted as to the events that they subscribe to.

Actions can be hidden at the domain-level, indicating that they are not visible to the end-user. This attribute can also be applied to properties and collections.

For example:

The acceptable values for the where parameter are:

The other values of the Where enum have no meaning for a collection.

The invokeOn() attribute indicates whether the an action can be invoked on a single object (the default) and/or on many objects in a collection.

For example:

Actions to be invoked on collection (currently) have a number of constraints. It:

The example given above is probably ok, because setCompleted() is most likely idempotent. However, if the action also called some other method, then we should add a guard.

For example, for this non-idempotent action:

we should instead write it as:

The publishing() attribute determines whether and how an action invocation is published via the registered implementation of a PublishingService) or PublisherService. This attribute is also supported for domain objects, where it controls whether changed objects are published as events, and for @Property#publishing(), where it controls whether property edits are published as events.

A common use case is to notify external "downstream" systems of changes in the state of the Isis application. The default value for the attribute is AS_CONFIGURED, meaning that the configuration property isis.services.publish.actions is used to determine the whether the action is published:

If there is no configuration property in isis.properties then publishing is automatically enabled.

This default can be overridden on an action-by-action basis; if publishing() is set to ENABLED then the action invocation is published irrespective of the configured value; if set to DISABLED then the action invocation is not published, again irrespective of the configured value.

For example:

By default actions are available irrespective of the deployment mode. The restrictTo() attribute specifies whether the action should instead be restricted to only available in prototyping mode.

For example:

In this case the listing of all orders (in the listAllOrders() action) probably doesn’t make sense for production; there could be thousands or millions. However, it would be useful to disaply how for a test or demo system where there are only a handful of orders.

The semantics() attribute describes whether the invocation modifies state of the system, and if so whether it does so idempotently. If the action invocation does not modify the state of the system, in other words is safe, then it also can beused to specify whether the results of the action can be cached automatically for the remainder of the request.

The attribute was originally introduced for the RestfulObjects viewer in order that action invocations could be using the appropriate HTTP verb (GET, PUT and POST).

The table below summarizes the semantics:

The actions' semantics are also used by the core runtime as part of the in-built concurrency checkng; invocation of a safe action (which includes request-cacheable) does not perform a concurrency check, whereas non-safe actions do perform a concurrency check.

For example:

Actions that are safe and request-cacheable automatically use the QueryResultsCache service to cache the result of the method. Note though that the results of this caching will only be apparent if the action is invoked from another method using the WrapperFactory service.

Continuing the example above, imagine code that loops over a set of Orders where each Order has an associated Customer. We want to check the credit rating of each Customer (a potentially expensive operation) but we don’t want to do it more than once per Customer. Invoking through the WrapperFactory will allow us to accomplish this by exploiting the semantics of checkCredit() action:

In the above example we’ve used wrapSkipRules(…​) but if we wanted to enforce any business rules associated with the checkCredit() method, we would have used wrap(…​).

The typeOf() attribute specifies the expected type of an element returned by the action (returning a collection), when for whatever reason the type cannot be inferred from the generic type, or to provide a hint about the actual run-time (as opposed to compile-time) type. This attribute can also be specified for collections.

For example:

The bookmarking() attribute indicates if an action (with safe action semantics) is automatically bookmarked. This attribute is also supported for domain objects.

In the Wicket viewer, a link to a bookmarked object is shown in the bookmarks panel:

For example:

indicates that the notYetComplete() action is bookmarkable.

As an alternative to using the annotation, the dynamic file-based layout can be used instead, eg:

For a domain service action that can be contributed, the contributedAs() attribute determines how it is contributed: as an action or as an association (ie a property or collection).

The distinction between property or collection is automatic: if the action returns a java.util.Collection (or subtype) then the action is contributed as a collection; otherwise it is contributed as a property.

For a domain service action to be contributed, the domain services must have a nature nature of either VIEW or VIEW_CONTRIBUTIONS_ONLY, and the action must have safe action semantics, and takes a single argument, namely the contributee domain object.

For example:

It’s also possible to use the attribute to suppress the action completely:

In such cases, though, it would probably make more sense to annotate the action as either hidden or indeed @Programmatic.

The cssClass() attribute can be used to render additional CSS classes in the HTML (a wrapping <div>) that represents the action. Application-specific CSS can then be used to target and adjust the UI representation of that particular element.

This attribute can also be applied to domain objects, view models, properties, collections and parameters.

For example:

As an alternative to using the annotation, the dynamic file-based layout can be used instead, eg:

The cssClassFa() attribute is used to specify the name of a Font Awesome icon name, to be rendered on the action’s representation as a button or menu item. The related cssClassFaPosition() attribute specifies the positioning of the icon, to the left or the right of the text.

These attributes can also be applied to domain objects and to view models to specify the object’s icon.

For example:

There can be multiple "fa-" classes, eg to mirror or rotate the icon. There is no need to include the mandatory fa "marker" CSS class; it will be automatically added to the list. The fa- prefix can also be omitted from the class names; it will be prepended to each if required.

As an alternative to using the annotation, the dynamic file-based layout can be used instead, eg:

The describedAs() attribute is used to provide a short description of the action to the user. In the Wicket viewer it is displayed as a 'tool tip'.

This attribute can also be specified for collections, properties, parameters, domain objects and view models.

For example:

As an alternative to using the annotation, the dynamic file-based layout can be used instead, eg:

The hidden() attribute indicates where (in the UI) the action should be hidden from the user. This attribute can also be applied to properties and collections.

For example:

The acceptable values for the where parameter are:

The other values of the Where enum have no meaning for a collection.

As an alternative to using the annotation, the dynamic file-based layout can be used instead, eg:

The named() attribute explicitly specifies the action’s name, overriding the name that would normally be inferred from the Java source code. This attribute can also be specified for collections, properties, parameters, domain objects, view models and domain services.

For example:

As an alternative to using the annotation, the dynamic file-based layout can be used instead, eg:

The position() attribute pertains only to actions that have been associated with properties using @MemberOrder#named(). For these actions, it specifies the positioning of the action’s button with respect to the field representing the object property.

The attribute can take one of four values: BELOW, RIGHT, PANEL or PANEL_DROPDOWN.

For example:

The default is BELOW, which is rendered (by the Wicket viewer) as shown below:

If the action is positioned as RIGHT, then the action’s button is rendered to the right of the property’s field, in a compact drop-down. This is ideal if there are many actions associated with a property:

If the action is positioned as PANEL, then the action’s button is rendered on the header of the panel that contains the property:

And finally, if the action is positioned as PANEL_DROPDOWN, then the action’s button is again rendered on the panel header, but as a drop-down:

If there are multiple actions associated with a single property then the positioning can be mix’ed-and-match’ed as required. If the PANEL or PANEL_DROPDOWN are used, then (as the screenshots above show) the actions from potentially multiple properties grouped by that panel will be shown together.

As an alternative to using the annotation, the dynamic file-based layout can be used instead, eg:

The fact that the layout is dynamic (does not require a rebuild/restart) is particularly useful in that the look-n-feel can be easily experimented with and adjusted.

Whenever a domain object (or list of domain objects) is to be rendered, the framework fires off multiple domain events for every property, collection and action of the domain object. In the cases of the domain object’s collections, the events that are fired are:

Subscribers subscribe through the EventBusService using either Guava or Axon Framework annotations and can influence each of these phases.

By default the event raised is CollectionDomainEvent.Default. For example:

The domainEvent() attribute allows a custom subclass to be emitted allowing more precise subscriptions (to those subclasses) to be defined instead. This attribute is also supported for actions and properties.

For example:

The benefit is that subscribers can be more targetted as to the events that they subscribe to.

The editing() annotation indicates whether a collection can be added to or removed from within the UI. This attribute can also be specified for properties, and can also be specified for the domain object

The related editingDisabledReason() attribute specifies the a hard-coded reason why the collection cannot be modified directly.

Whether a collection is enabled or disabled depends upon these factors:

Thus, to make a collection read-only even if the object would otherwise be editable, use:

Collections can be hidden at the domain-level, indicating that they are not visible to the end-user. This attribute can also be applied to actions and properties.

For example:

The acceptable values for the where parameter are:

The other values of the Where enum have no meaning for a collection.

The (somewhat misnamed) notPersisted() attribute indicates that the collection should be excluded from any snapshots generated by the XmlSnapshotService. This attribute is also supported for properties.

For example:

Historically this annotation also hinted as to whether the collection’s contents should be persisted in the object store. However, the JDO/DataNucleus objectstore does not recognize this annotation. Thus, to ensure that a collection is actually not persisted, it should also be annotated with @javax.jdo.annotations.NotPersistent.

For example:

Alternatively, if the collection is derived, then providing only a "getter" will also work:

The typeOf() attribute specifies the expected type of an element contained within a collection when for whatever reason the type cannot be inferred from the generic type, or to provide a hint about the actual run-time (as opposed to compile-time) type. This attribute can also be specified for actions.

For example:

The cssClass() attribute can be used to render additional CSS classes in the HTML (a wrapping <div>) that represents the collection. Application-specific CSS can then be used to target and adjust the UI representation of that particular element.

This attribute can also be applied to domain objects, view models, actions, properties and parameters.

For example:

As an alternative to using the annotation, the dynamic file-based layout can be used instead, eg:

The Wicket viewer allows additional views to be configured to render collections of objects; at the time of writing thesee include the excel, fullcalendar2 and gmap3 provided by the (non-ASF) Incode Platform. If the objects to be rendered have the correct "shape", then the appropriate view will be made available. For example, objects with a date can be rendered using calendar; objects with locations can be rendered using map.

The defaultView() attribute is used to select which of these views should be used by default for a given collection.

For example:

As an alternative to using the annotation, the dynamic file-based layout can be used instead, eg:

The describedAs() attribute is used to provide a short description of the collection to the user. In the Wicket viewer it is displayed as a 'tool tip'.

The describedAs() attribute can also be specified for properties, actions, parameters, domain objects and view models.

For example:

As an alternative to using the annotation, the dynamic file-based layout can be used instead, eg:

The hidden() attribute indicates where (in the UI) the collection should be hidden from the user. This attribute can also be applied to actions and properties.

For example:

The acceptable values for the where parameter are:

The other values of the Where enum have no meaning for a collection.

As an alternative to using the annotation, the dynamic file-based layout can be used instead, eg:

The named() attribute explicitly specifies the collection’s name, overriding the name that would normally be inferred from the Java source code. This attribute can also be specified for actions, properties, parameters, domain objects, view models and domain services.

By default the name is HTML escaped. To allow HTML markup, set the related namedEscaped() attribute to false.

For example:

As an alternative to using the annotation, the dynamic file-based layout can be used instead, eg:

The paged() attribute specifies the number of rows to display in a (parented) collection. This attribute can also be applied to domain objects and view models.

For example:

It is also possible to specify a global default for the page size of standalone collections, using the configuration property isis.viewer.paged.parented.

As an alternative to using the annotation, the dynamic file-based layout can be used instead, eg:

The render() attribute specifies that the collection be rendered either "eagerly" (shown open, displaying its contents) or "lazily" (shown closed, hiding its contents). The terminology here is based on the similar concept of lazy loading of collections in the domain/persistence layer boundary (except that the rendering relates to the presentation/domain layer boundary).

For example:

As an alternative to using the annotation, the dynamic file-based layout can be used instead, eg:

The sortedBy() attribute specifies that the collection be ordered using the specified comparator, rather than the natural ordering of the entity (as would usually be the case).

For example:

When the dependencies collection is rendered, the elements are sorted by the description property first:

Without this annotation, the order would have been inverted (because the natural ordering places items not completed before those items that have been completed.

As an alternative to using the annotation, the dynamic file-based layout can be used instead, eg:

The allowsNull() attribute is used to specify if a property is mandatory or is optional.

For example:

Isis also provides @Property#optionality() attribute. If both are specified, Apache Isis will check when it initializes for any contradictions, and will fail-fast with an appropriate error message in the log if there are.

You should also be aware that in the lack of either the @Column#allowsNull() or the @Property#optionality() attributes, that the JDO and Apache Isis defaults differ. Apache Isis rule is straight-forward: properties are assumed to be required. JDO on the other hand specifies that only primitive types are mandatory; everything else is assumed to be optional. Therefore a lack of either annotation can also trigger the fail-fast validation check.

In the vast majority of cases you should be fine just to add the @Column#allowsNull() attribute to the getter. But see the documentation for @Property#optionality() attribute for discussion on one or two minor edge cases.

The length() attribute is used to specify the length of java.lang.String property types as they map to varchar(n) columns.

For example:

Isis also provides @Property#maxLength() attribute. If both are specified, Apache Isis will check when it initializes for any contradictions, and will fail-fast with an appropriate error message in the log if there are.

The length() and scale() attributes are used to infer the precision/scale of java.math.BigDecimal property types as they map to decimal(n,p) columns.

For example:

For BigDecimals it is also possible to specify the @Digits annotation, whose form is @Digits(integer, fraction). There is a subtle difference here: while @Column#scale() corresponds to @Digits#fraction(), the value of @Column#length() (ie the precision) is actually the _sum of the @Digits’ `integer() and fraction() parts.

If both are specified, Apache Isis will check when it initializes for any contradictions, and will fail-fast with an appropriate error message in the log if there are.

This seems to be a good place to describe some additional common mappings that use @Column. Unlike the sections above, the attributes specified in these hints and tips aren’t actually part of Apache Isis metamodel.

Isis provides custom value types for Blobs and Clobs. These value types have multiple internal fields, meaning that they corresponding to multiple columns in the database. Mapping this correctly requires using @Column within JDO’s @Persistent annotation.

For example, here’s how to map a Blob (taken from (non-ASF) Isis addons' todoapp):

And here’s how to map a Clob (also taken from the todoapp):

For example:

has an object type of custmgmt.Customer.

The rules of precedence for determining a domain object’s object type are:

The auditing() attribute indicates that if the object is modified, then each of its changed properties should be submitted to the AuditingService (if one has been configured), or to any

The default value for the attribute is AS_CONFIGURED, meaning that the configuration property isis.services.audit.objects is used to determine the whether the action is audited:

If there is no configuration property in isis.properties then auditing is automatically enabled for domain objects.

This default can be overridden on an object-by-object basis; if auditing() is set to ENABLED then changed properties of instances of the domain class are audited irrespective of the configured value; if set to DISABLED then the changed properties of instances are not audited, again irrespective of the configured value.

For example:

The autoCompleteRepository() attribute nominates a single method on a domain service as the fallback means for looking up instances of the domain object using a simple string.

For example, this might search for a customer by their name or number. Or it could search for a country based on its ISO-3 code or user-friendly name.

For example:

where:

Some domain classes are immutable to the user, and moreover have only a fixed number of instances. Often these are "reference" ("standing") data, or lookup data/pick lists. Typical examples could include categories, countries, states, and tax or interest rate tables.

Where the number of instances is relatively small, ie bounded, then the bounded() attribute can be used as a hint. For such domain objects the framework will automatically allow instances to be selected; Wicket viewer displays these as a drop-down list.

For example:

Whenever a domain object is instantiated or otherwise becomes known to the framework, a "created" lifecycle event is fired. This is typically when the DomainObjectContainer's newTransientInstance() is called; it will also happen if the object is simply instantiated with new(…​), and then the container’s injectServicesInto(…​) method is called.

Subscribers subscribe through the EventBusService and can use the event to obtain a reference to the object just created. The subscriber could then, for example, update the object, eg looking up state from some external datastore.

By default the event raised is ObjectCreatedEvent.Default. For example:

The purpose of the createdLifecycleEvent() attribute is to allows a custom subclass to be emitted instead. A similar attribute is available for other lifecycle events.

For example:

The benefit is that subscribers can be more targeted as to the events that they subscribe to.

The editing() attribute determines whether a domain object’s properties and collections are not editable (are read-only).

The default is AS_CONFIGURED, meaning that the configuration property isis.objects.editing is used to determine the whether the object is modifiable:

If there is no configuration property in isis.properties then object are assumed to be modifiable.

The related editingDisabledReason() attribute specifies the a hard-coded reason why the object’s properties and collections cannot be modified directly.

This default can be overridden on an object-by-object basis; if editing() is set to ENABLED then the object’s properties and collections are editable irrespective of the configured value; if set to DISABLED then the object’s properties and collections are not editable irrespective of the configured value.

For example:

Whenever a persistent domain object is loaded from the database, a "loaded" lifecycle event is fired.

Subscribers subscribe through the EventBusService and can use the event to obtain a reference to the domain object just loaded. The subscriber could then, for example, update or default values on the object (eg to support on-the-fly migration scenarios).

By default the event raised is ObjectLoadedEvent.Default. For example:

The purpose of the loadedLifecycleEvent() attribute is to allows a custom subclass to be emitted instead. A similar attribute is available for other lifecycle events.

For example:

The benefit is that subscribers can be more targeted as to the events that they subscribe to.

The mixinMethod() attribute specifies the name of the method to be treated as a "reserved" method name, meaning that the mixin’s name should instead be inferred from the mixin’s type.

For example:

This allows all mixins to follow a similar convention, with the name of the mixin inferred entirely from its type ("placeOrder").

When invoked programmatically, the code reads:

The nature() attribute is used to characterize the domain object as either an entity (part of the domain layer) or as a view model (part of the application layer). If the domain object should be thought of as an entity, it also captures how the persistence of that entity is managed.

For example:

Specifically, the nature must be one of:

Those natures that indicate the domain object is an entity (of some sort or another) mean then that the domain object is considered to be part of the domain model layer. As such the domain object’s class cannot be annotated with @ViewModel or implement the ViewModel interface.

Whenever a (just created, still transient) domain object has been saved (INSERTed in)to the database, a "persisted" lifecycle event is fired.

Subscribers subscribe through the EventBusService and can use the event to obtain a reference to the domain object. The subscriber could then, for example, maintain an external datastore.

By default the event raised is ObjectPersistedEvent.Default. For example:

The purpose of the persistedLifecycleEvent() attribute is to allows a custom subclass to be emitted instead. A similar attribute is available for other lifecycle events.

For example:

The benefit is that subscribers can be more targeted as to the events that they subscribe to.