[#domain-events]
= Domain Events

:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
:page-partial:


Domain events are fired for every user interaction with each object member (property, collection or action).

By default, rendering a property causes a `PropertyDomainEvent` to be fired, though the xref:refguide:applib:index/annotation/Property.adoc#domainEvent[@Property#domainEvent()] attribute allows a custom subclass to be specified if necessary.
Similarly, rendering a collection causes a `DomainEvent` to be fired, and rendering an action causes an `ActionDomainEvent` to be fired.

In fact, each event can be fired up to five times, with the event's `getEventPhase()` method indicating to the subscriber the phase:

* *hide* phase allows the subscriber to hide the member

* *disable* phase allows the subscriber to disable the member.
+
For a property this makes it read-only; for an action this makes it "greyed out".
(Collections are implicitly read-only).

* *validate* phase allows the subscriber to validate the proposed change.
+
For a property this means validating the proposed new value of the property; for an action this means validating the action parameter arguments.
For example, a referential integrity restrict could be implemented here.

* *executing* phase is prior to the actual property edit/action invocation, allowing the subscriber to perform side-effects.
+
For example, a cascade delete could be implemented here.

* *executed* phase is after the actual property edit/action invocation.
+
For example, a business audit event could be implemented here.

For more details on the actual domain event classes, see the xref:refguide:applib-classes:events.adoc#domain-event-classes[domain event] section of the relevant reference guide.

