Domain Event Defaults

Whenever an member of a domain object is interacted with then a domain event will be fired, for each of the various phases (hidden, disabled, validated, executing, executed).

For each of the three types of members (action, property and collection), the DomainObject provides an element that defines a common event domain class to be fired whenever interacting with members of that type. This default event type can be overridden with a more specific event type if necessary.

Type

@DomainObject default

Overridden with

Actions

actionDomainEvent()

@Action#domainEvent.

Properties

propertyDomainEvent()

@Property#domainEvent().

Collections

collectionDomainEvent()

@Collection#domainEvent().

Action example

For an action:

@DomainObject(
    actionDomainEvent=ToDoItem.ActionDomainEventDefault.class
)
public class ToDoItem {

    public static class ActionDomainEventDefault extends
        org.apache.causeway.applib.events.domain.ActionDomainEvent<Object> { }
    // ...

    public void updateDescription(final String description) {
        this.description = description;
    }

}

The specified class will also be used as the event for any mixin action contributed to the class.

Note though one small difference between the events emitted by a "regular" action and a contributed action is that the source of the event (as in event#getSource() will be different. In the former case it will be the domain object instance, in the latter it will be the mixin object instantiated automatically by the framework.

However, the domain object is available using event#getMixedIn(). Even easier, event#getSubject() will always return the domain object (it returns the #getMixedIn() if present, otherwise the #getSource().

Action domain events have generic types, with the (first and only) generic type indicating the event’s source’s type.

Because an event specified at the class level might have either the domain object or a mixin for the domain object as its source, they should therefore use simply Object as their generic type.

Property example

For example:

@DomainObject(
    propertyDomainEvent=ToDoItem.PropertyDomainEventDefault.class
)
public class ToDoItem {
    public static class PropertyDomainEventDefault
        extends org.apache.causeway.applib.events.domain.PropertyDomainEvent<Object> { }
    ...

    @Getter @Setter
    private String description;
}

If there is a mixin for the domain object, then this will also honour the domain event. For example:

@Property(
	propertyDomainEvent=ToDoItem_priority.PropertyDomainEventDefault.class
)
public class ToDoItem_priority {
    private final ToDoItem todoItem;
    // constructor omitted

    public static class PropertyDomainEventDefault
        extends org.apache.causeway.applib.events.domain.PropertyDomainEvent<Object> { }

    public Integer prop() { /* ... */ }
}

Interactions with the property contributed by this mixin will emit the domain event of the subject (ToDoItem).

One small difference between the events emitted by a "regular" property and a contributed property is that the source of the event (as in event#getSource() will be different. In the former case it will be the domain object instance, in the latter it will be the mixin object instantiated automatically by the framework.

However, the domain object is available using event#getMixedIn(). Even easier, event#getSubject() will always return the domain object (it returns the #getMixedIn() if present, otherwise the #getSource().

Property domain events have generic types, with the first generic type indicating the event’s source’s type, and the second generic type indicating the property return type.

Because an event specified at the class level might have either the domain object or a mixin for the domain object as its source, they should therefore use simply Object as their first generic type.

They should also have Object for their second generic type, because the return type of the various properties of the domain object will or could be different.

Collection example

For example:

import lombok.Getter;
import lombok.Setter;

@DomainObject(
    collectionDomainEvent=ToDoItem.CollectionDomainEventDefault.class
)
public class ToDoItem {
    public static class CollectionDomainEventDefault extends
            org.apache.causeway.applib.events.domain.CollectionDomainEvent<Object> { }
    ...

    @Getter @Setter
    private Set<Category> categories = new TreeSet<>();
}

If there is a mixin for the domain object, then this will also honour the domain event. For example:

public class ToDoItem {

    @Collection
    @CollectionLayout(defaultView = "table")
    public class related {

        public List<ToDoItem> coll() {
            // ...
        }
    }

}

Interactions with the collection contributed by this mixin will emit the domain event of the subject (ToDoItem).

One small difference between the events emitted by a "regular" collection and a contributed action is that the source of the event (as in event#getSource() will be different. In the former case it will be the domain object instance, in the latter it will be the mixin object instantiated automatically by the framework.

However, the domain object is available using event#getMixedIn(). Even easier, event#getSubject() will always return the domain object (it returns the #getMixedIn() if present, otherwise the #getSource().

Collection domain events have generic types, with the first generic type indicating the event’s source’s type, and the second generic type indicating the element type.

Because an event specified at the class level might have either the domain object or a mixin for the domain object as its source, they should therefore use simply Object as their first generic type.

They should also have Object for their second generic type, because the element type of the various collections of the domain object will or could be different.