You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2021/03/04 17:31:55 UTC
[isis] 07/09: ISIS-2444: event docs
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch ISIS-2444
in repository https://gitbox.apache.org/repos/asf/isis.git
commit 57c7c5303ab8a429c0cdb9a3476ec894a27f7473
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Wed Mar 3 22:07:08 2021 +0000
ISIS-2444: event docs
---
.../applib-classes/pages/events/domainevent.adoc | 21 ++---
.../pages/events/lifecycleevent.adoc | 99 +++++++++-------------
.../lifecycleevent/AbstractLifecycleEvent.adoc | 20 -----
.../events/lifecycleevent/ObjectCreatedEvent.adoc | 14 ---
.../events/lifecycleevent/ObjectLoadedEvent.adoc | 12 ---
.../lifecycleevent/ObjectPersistedEvent.adoc | 11 ---
.../lifecycleevent/ObjectPersistingEvent.adoc | 12 ---
.../events/lifecycleevent/ObjectRemovingEvent.adoc | 12 ---
.../events/lifecycleevent/ObjectUpdatedEvent.adoc | 13 ---
.../events/lifecycleevent/ObjectUpdatingEvent.adoc | 13 ---
.../applib-classes/pages/events/uievent.adoc | 76 ++++++++---------
.../pages/events/uievent/CssClassUiEvent.adoc | 17 ----
.../pages/events/uievent/IconUiEvent.adoc | 19 -----
.../pages/events/uievent/TitleUiEvent.adoc | 17 ----
...ng.adoc => TranslatableString_usage-notes.adoc} | 0
.../events/lifecycle/AbstractLifecycleEvent.java | 5 ++
.../events/lifecycle/ObjectCreatedEvent.java | 25 ++++--
.../applib/events/lifecycle/ObjectLoadedEvent.java | 21 +++--
.../events/lifecycle/ObjectPersistedEvent.java | 8 ++
.../events/lifecycle/ObjectPersistingEvent.java | 8 ++
.../events/lifecycle/ObjectRemovingEvent.java | 8 ++
.../events/lifecycle/ObjectUpdatedEvent.java | 5 ++
.../events/lifecycle/ObjectUpdatingEvent.java | 5 ++
.../isis/applib/events/ui/CssClassUiEvent.java | 40 +++++++--
.../apache/isis/applib/events/ui/IconUiEvent.java | 51 ++++++++---
.../isis/applib/events/ui/LayoutUiEvent.java | 38 +++++++--
.../apache/isis/applib/events/ui/TitleUiEvent.java | 39 +++++++--
27 files changed, 290 insertions(+), 319 deletions(-)
diff --git a/antora/components/refguide/modules/applib-classes/pages/events/domainevent.adoc b/antora/components/refguide/modules/applib-classes/pages/events/domainevent.adoc
index 8dcc604..b5f9e1b 100644
--- a/antora/components/refguide/modules/applib-classes/pages/events/domainevent.adoc
+++ b/antora/components/refguide/modules/applib-classes/pages/events/domainevent.adoc
@@ -4,43 +4,38 @@
:page-partial:
-This section catalogues the various domain event classes defined by Apache Isis.
+Domain events are broadcast through the xref:refguide:applib:index/services/eventbus/EventBusService.adoc[EventBusService] whenever the framework interacts with the domain object members.
+
+They allow subscribers to change either veto the interaction, or to trigger other operations as a result of the interaction.
-These events are broadcast through the xref:refguide:applib:index/services/eventbus/EventBusService.adoc[EventBusService] whenever the framework interacts with the domain object members
.Domain Event Classes
-[cols="1a,2a,2a,2a", options="header"]
+[cols="2a,2a,2a", options="header"]
|===
|API
-|Raised by
-|Fallback +
-Implementation
+|Event class defined by
|Published when
|xref:refguide:applib:index/events/domain/AbstractDomainEvent.adoc[AbstractDomainEvent]
|n/a
-|(abstract class)
-|Superclass of the other domain events, listed below in this table.
+|n/a - superclass of the other domain events.
|xref:refguide:applib:index/events/domain/ActionDomainEvent.adoc[ActionDomainEvent]
|xref:refguide:applib:index/annotation/Action.adoc#domainEvent[@Action#domainEvent()]
-|`ActionDomainEvent.Default`
-|(hide/disable/validate/pre-execute/post-execute) with an object's action.
+|interact with (hide, disable, validate, pre-execute, post-execute) an object's action.
|xref:refguide:applib:index/events/domain/CollectionDomainEvent.adoc[CollectionDomainEvent]
|xref:refguide:applib:index/annotation/Collection.adoc#domainEvent[@Collection#domainEvent()]
-|`CollectionDomainEvent.Default`
|hide an object's collection.
|xref:refguide:applib:index/events/domain/PropertyDomainEvent.adoc[PropertyDomainEvent]
|xref:refguide:applib:index/annotation/Property.adoc#domainEvent[@Property#domainEvent()]
-|`PropertyDomainEvent.Default`
-|hide/disable/validate/pre-edit/post-edit with an object's property.
+|interact with (hide, disable, validate, pre-edit, post-edit) an object's property.
|===
diff --git a/antora/components/refguide/modules/applib-classes/pages/events/lifecycleevent.adoc b/antora/components/refguide/modules/applib-classes/pages/events/lifecycleevent.adoc
index 969c9b4..b6717b6 100644
--- a/antora/components/refguide/modules/applib-classes/pages/events/lifecycleevent.adoc
+++ b/antora/components/refguide/modules/applib-classes/pages/events/lifecycleevent.adoc
@@ -5,95 +5,74 @@
:page-partial:
-This section catalogues the various lifecycle event classes defined by Apache Isis.
-These events are fired automatically when a domain object is loaded, created, updated and so forth.
+Lifecycle events are broadcast through the xref:refguide:applib:index/services/eventbus/EventBusService.adoc[EventBusService] when a domain entity is loaded, created, updated to/from the database.
-The lifecycle event classes are listed in the table below:
+They allow subscribers to trigger other operations as a result of these persistence operations.
+One use case is to maintain an alternate data store.
.Lifecycle Event Classes
-[cols="1a,2a,2a", options="header"]
+[cols="2a,2a,2a", options="header"]
|===
|API
-|Implementation
-|Notes
+|Event class defined by
+|Raised when
-|xref:applib-classes:events.adoc#AbstractLifecycleEvent[`o.a.i.applib.` +
-`AbstractLifecycleEvent`]
-|(abstract class)
-|Superclass of the other lifecycle events, listed below in this table.
+|xref:refguide:applib:index/events/lifecycle/AbstractLifecycleEvent.adoc[AbstractLifecycleEvent]
+|n/a
+|n/a - superclass of the other lifecycle events.
-|xref:applib-classes:events.adoc#ObjectCreatedEvent[`o.a.i.applib.` +
-`ObjectCreatedEvent`]
-|(abstract class). +
-`ObjectCreatedEvent.Default` is the concrete implementation that is used.
-|Broadcast when an object is first instantiated using the xref:refguide:applib:index/services/factory/FactoryService.adoc[FactoryService]'s
-`#instantiate(...)` method.
+|xref:refguide:applib:index/events/lifecycle/ObjectCreatedEvent.adoc[ObjectCreatedEvent]
+|xref:refguide:applib:index/annotation/DomainObject.adoc#createdLifecycleEvent[DomainObject +
+#createdLifecycleEvent()]
+|entity is first instantiated using xref:refguide:applib:index/services/factory/FactoryService.adoc[FactoryService] +
+Also raised for view models.
-|xref:applib-classes:events.adoc#ObjectLoadedEvent[`o.a.i.applib.` +
-`ObjectLoadedEvent`]
-|(abstract class). +
-`ObjectLoadedEvent.Default` is the concrete implementation that is used.
-|Broadcast when an object is retrieved from the database.
+|xref:refguide:applib:index/events/lifecycle/ObjectLoadedEvent.adoc[ObjectLoadedEvent]
+|xref:refguide:applib:index/annotation/DomainObject.adoc#loadedLifecycleEvent[DomainObject +
+#loadedLifecycleEvent()]
+|entity is retrieved from the database.
-|xref:applib-classes:events.adoc#ObjectPersistedEvent[`o.a.i.applib.` +
-`ObjectPersistedEvent`]
-|(abstract class). +
-`ObjectPersistedEvent.Default` is the concrete implementation that is used.
-|Broadcast when an object is first saved (inserted) into the database using the xref:refguide:applib:index/services/repository/RepositoryService.adoc[RepositoryService]'s
+
+|xref:refguide:applib:index/events/lifecycle/ObjectPersistedEvent.adoc[ObjectPersistedEvent]
+|xref:refguide:applib:index/annotation/DomainObject.adoc#persistedLifecycleEvent[DomainObject +
+#persistedLifecycleEvent()]
+|entity is first saved (inserted) into the database using the xref:refguide:applib:index/services/repository/RepositoryService.adoc[RepositoryService]'s
`#persist(...)` method.
-|xref:applib-classes:events.adoc#ObjectPersistingEvent[`o.a.i.applib.` +
-`ObjectPersistingEvent`]
-|(abstract class). +
-`ObjectPersistingEvent.Default` is the concrete implementation that is used.
-|Broadcast when an object is about to be saved (inserted) into the database using the xref:refguide:applib:index/services/repository/RepositoryService.adoc[RepositoryService]'s
+|xref:refguide:applib:index/events/lifecycle/ObjectPersistingEvent.adoc[ObjectPersistingEvent]
+|xref:refguide:applib:index/annotation/DomainObject.adoc#persistingLifecycleEvent[DomainObject +
+#persistingLifecycleEvent()]
+|entity is about to be saved (inserted) into the database using the xref:refguide:applib:index/services/repository/RepositoryService.adoc[RepositoryService]'s
`#persist(...)` method.
-|xref:applib-classes:events.adoc#ObjectRemovingEvent[`o.a.i.applib.` +
-`ObjectRemovingEvent`]
-|(abstract class). +
-`ObjectRemovingEvent.Default` is the concrete implementation that is used.
-|Broadcast when an object is about to be deleted from the database using the xref:refguide:applib:index/services/repository/RepositoryService.adoc[RepositoryService]'s
+|xref:refguide:applib:index/events/lifecycle/ObjectRemovingEvent.adoc[ObjectRemovingEvent]
+|xref:refguide:applib:index/annotation/DomainObject.adoc#removingLifecycleEvent[DomainObject +
+#removingLifecycleEvent()]
+|entity is about to be deleted from the database using the xref:refguide:applib:index/services/repository/RepositoryService.adoc[RepositoryService]'s
`#remove(...)` method.
-|xref:applib-classes:events.adoc#ObjectUpdatedEvent[`o.a.i.applib.` +
-`ObjectUpdatedEvent`]
-|(abstract class). +
-`ObjectUpdatedEvent.Default` is the concrete implementation that is used.
-|Broadcast when an object has just been updated in the database.
-This is done either explicitly when the current transaction is flushed using the xref:refguide:applib:index/services/repository/RepositoryService.adoc[RepositoryService]'s `#flush(...)` method, else is done implicitly when the transaction commits at the end of the user request.
+|xref:refguide:applib:index/events/lifecycle/ObjectUpdatedEvent.adoc[ObjectUpdatedEvent]
+|xref:refguide:applib:index/annotation/DomainObject.adoc#updatingLifecycleEvent[DomainObject +
+#updatingLifecycleEvent()]
+|entity has just been updated in the database.
-|xref:applib-classes:events.adoc#ObjectUpdatingEvent[`o.a.i.applib.` +
-`ObjectUpdatingEvent`]
-|``o.a.i.core`` +
-``events.lifecycle`` +
-``isis-applib``
-|(abstract class). +
-`ObjectUpdatingEvent.Default` is the concrete implementation that is used.
-|Broadcast when an object is about to be updated in the database.
-This is done either explicitly when the current transaction is flushed using the xref:refguide:applib:index/services/repository/RepositoryService.adoc[RepositoryService]'s `#flush(...)` method, else is done implicitly when the transaction commits at the end of the user request.
+|xref:refguide:applib:index/events/lifecycle/ObjectUpdatingEvent.adoc[ObjectUpdatingEvent]
+|xref:refguide:applib:index/annotation/DomainObject.adoc#updatedLifecycleEvent[DomainObject +
+#updatedLifecycleEvent()]
+|entity is about to be updated in the database.
|===
-
-include::lifecycleevent/AbstractLifecycleEvent.adoc[leveloffset=+1]
-include::lifecycleevent/ObjectCreatedEvent.adoc[leveloffset=+1]
-include::lifecycleevent/ObjectLoadedEvent.adoc[leveloffset=+1]
-include::lifecycleevent/ObjectPersistedEvent.adoc[leveloffset=+1]
-include::lifecycleevent/ObjectPersistingEvent.adoc[leveloffset=+1]
-include::lifecycleevent/ObjectRemovingEvent.adoc[leveloffset=+1]
-include::lifecycleevent/ObjectUpdatedEvent.adoc[leveloffset=+1]
-include::lifecycleevent/ObjectUpdatingEvent.adoc[leveloffset=+1]
diff --git a/antora/components/refguide/modules/applib-classes/pages/events/lifecycleevent/AbstractLifecycleEvent.adoc b/antora/components/refguide/modules/applib-classes/pages/events/lifecycleevent/AbstractLifecycleEvent.adoc
deleted file mode 100644
index 2fff7df..0000000
--- a/antora/components/refguide/modules/applib-classes/pages/events/lifecycleevent/AbstractLifecycleEvent.adoc
+++ /dev/null
@@ -1,20 +0,0 @@
-[[AbstractLifecycleEvent]]
-= `AbstractLifecycleEvent`
-
-: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 ag [...]
-:page-partial:
-
-
-This class is the superclass for all lifecycle events that are raised by the framework when loading, saving, updating or deleting objects from the database.
-
-Its immediate subclasses are:
-
-* xref:applib-classes:events.adoc#ObjectCreatedEvent[ObjectCreatedEvent]
-* xref:applib-classes:events.adoc#ObjectLoadedEvent[ObjectLoadedEvent]
-* xref:applib-classes:events.adoc#ObjectPersistedEvent[ObjectPersistedEvent]
-* xref:applib-classes:events.adoc#ObjectPersistingEvent[ObjectPersistingEvent]
-* xref:applib-classes:events.adoc#ObjectRemovingEvent[ObjectRemovingEvent]
-* xref:applib-classes:events.adoc#ObjectUpdatedEvent[ObjectUpdatedEvent]
-* xref:applib-classes:events.adoc#ObjectUpdatingEvent[ObjectUpdatingEvent]
-
-
diff --git a/antora/components/refguide/modules/applib-classes/pages/events/lifecycleevent/ObjectCreatedEvent.adoc b/antora/components/refguide/modules/applib-classes/pages/events/lifecycleevent/ObjectCreatedEvent.adoc
deleted file mode 100644
index 913bc4f..0000000
--- a/antora/components/refguide/modules/applib-classes/pages/events/lifecycleevent/ObjectCreatedEvent.adoc
+++ /dev/null
@@ -1,14 +0,0 @@
-[[ObjectCreatedEvent]]
-= `ObjectCreatedEvent`
-
-: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 ag [...]
-:page-partial:
-
-
-
-Subclass of xref:applib-classes:events.adoc#AbstractLifecycleEvent[AbstractLifecycleEvent], broadcast when an object is first instantiated using the xref:refguide:applib:index/services/factory/FactoryService.adoc[FactoryServuce]'s `#instantiate(...)` method.
-
-`ObjectCreatedEvent.Default` is the implementation that is used by default, but this can be overridden using xref:refguide:applib:index/annotation/DomainObject.adoc#createdLifecycleEvent[@DomainObject#createdLifecycleEvent].
-
-
-
diff --git a/antora/components/refguide/modules/applib-classes/pages/events/lifecycleevent/ObjectLoadedEvent.adoc b/antora/components/refguide/modules/applib-classes/pages/events/lifecycleevent/ObjectLoadedEvent.adoc
deleted file mode 100644
index e49f0e5..0000000
--- a/antora/components/refguide/modules/applib-classes/pages/events/lifecycleevent/ObjectLoadedEvent.adoc
+++ /dev/null
@@ -1,12 +0,0 @@
-[[ObjectLoadedEvent]]
-= `ObjectLoadedEvent`
-
-: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 ag [...]
-:page-partial:
-
-
-
-Subclass of xref:applib-classes:events.adoc#AbstractLifecycleEvent[AbstractLifecycleEvent], broadcast when an object is retrieved from the database.
-
-`ObjectLoadedEvent.Default` is the concrete implementation that is used.
-
diff --git a/antora/components/refguide/modules/applib-classes/pages/events/lifecycleevent/ObjectPersistedEvent.adoc b/antora/components/refguide/modules/applib-classes/pages/events/lifecycleevent/ObjectPersistedEvent.adoc
deleted file mode 100644
index 38dc32f..0000000
--- a/antora/components/refguide/modules/applib-classes/pages/events/lifecycleevent/ObjectPersistedEvent.adoc
+++ /dev/null
@@ -1,11 +0,0 @@
-[[ObjectPersistedEvent]]
-= `ObjectPersistedEvent`
-
-: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 ag [...]
-:page-partial:
-
-
-Subclass of xref:applib-classes:events.adoc#AbstractLifecycleEvent[AbstractLifecycleEvent], broadcast when an object is first saved (inserted) into the database using the xref:refguide:applib:index/services/repository/RepositoryService.adoc[RepositoryService]'s `#persist(...)` method.
-
-
-`ObjectPersistedEvent.Default` is the implementation that is used by default, but this can be overridden using xref:refguide:applib:index/annotation/DomainObject.adoc#persistedLifecycleEvent[@DomainObject#persistedLifecycleEvent].
diff --git a/antora/components/refguide/modules/applib-classes/pages/events/lifecycleevent/ObjectPersistingEvent.adoc b/antora/components/refguide/modules/applib-classes/pages/events/lifecycleevent/ObjectPersistingEvent.adoc
deleted file mode 100644
index 1d122be..0000000
--- a/antora/components/refguide/modules/applib-classes/pages/events/lifecycleevent/ObjectPersistingEvent.adoc
+++ /dev/null
@@ -1,12 +0,0 @@
-[[ObjectPersistingEvent]]
-= `ObjectPersistingEvent`
-
-: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 ag [...]
-:page-partial:
-
-
-Subclass of xref:applib-classes:events.adoc#AbstractLifecycleEvent[AbstractLifecycleEvent], broadcast when an object is about to be saved (inserted) into the database using the xref:refguide:applib:index/services/repository/RepositoryService.adoc[RepositoryService]'s `#persist(...)` method.
-
-
-`ObjectPersistingEvent.Default` is the implementation that is used by default, but this can be overridden using xref:refguide:applib:index/annotation/DomainObject.adoc#persistingLifecycleEvent[@DomainObject#persistingLifecycleEvent].
-
diff --git a/antora/components/refguide/modules/applib-classes/pages/events/lifecycleevent/ObjectRemovingEvent.adoc b/antora/components/refguide/modules/applib-classes/pages/events/lifecycleevent/ObjectRemovingEvent.adoc
deleted file mode 100644
index 776575d..0000000
--- a/antora/components/refguide/modules/applib-classes/pages/events/lifecycleevent/ObjectRemovingEvent.adoc
+++ /dev/null
@@ -1,12 +0,0 @@
-[[ObjectRemovingEvent]]
-= `ObjectRemovingEvent`
-
-: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 ag [...]
-:page-partial:
-
-
-Subclass of xref:applib-classes:events.adoc#AbstractLifecycleEvent[AbstractLifecycleEvent], broadcast when an object is about to be deleted from the database using the xref:refguide:applib:index/services/repository/RepositoryService.adoc[RepositoryService]'s `#remove(...)` method.
-
-
-`ObjectRemovingEvent.Default` is the implementation that is used by default, but this can be overridden using xref:refguide:applib:index/annotation/DomainObject.adoc#removingLifecycleEvent[@DomainObject#removingLifecycleEvent].
-
diff --git a/antora/components/refguide/modules/applib-classes/pages/events/lifecycleevent/ObjectUpdatedEvent.adoc b/antora/components/refguide/modules/applib-classes/pages/events/lifecycleevent/ObjectUpdatedEvent.adoc
deleted file mode 100644
index 235f5ff..0000000
--- a/antora/components/refguide/modules/applib-classes/pages/events/lifecycleevent/ObjectUpdatedEvent.adoc
+++ /dev/null
@@ -1,13 +0,0 @@
-[[ObjectUpdatedEvent]]
-= `ObjectUpdatedEvent`
-
-: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 ag [...]
-:page-partial:
-
-
-
-Subclass of xref:applib-classes:events.adoc#AbstractLifecycleEvent[AbstractLifecycleEvent], broadcast when an object has just been updated in the database.
-This is done either explicitly when the current transaction is flushed using the xref:refguide:applib:index/services/repository/RepositoryService.adoc[RepositoryService]'s `#flush(...)` method, else is done implicitly when the transaction commits at the end of the user request.
-
-`ObjectUpdatedEvent.Default` is the implementation that is used by default, but this can be overridden using xref:refguide:applib:index/annotation/DomainObject.adoc#updatedLifecycleEvent[@DomainObject#updatedLifecycleEvent].
-
diff --git a/antora/components/refguide/modules/applib-classes/pages/events/lifecycleevent/ObjectUpdatingEvent.adoc b/antora/components/refguide/modules/applib-classes/pages/events/lifecycleevent/ObjectUpdatingEvent.adoc
deleted file mode 100644
index 21611d7..0000000
--- a/antora/components/refguide/modules/applib-classes/pages/events/lifecycleevent/ObjectUpdatingEvent.adoc
+++ /dev/null
@@ -1,13 +0,0 @@
-[[ObjectUpdatingEvent]]
-= `ObjectUpdatingEvent`
-
-: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 ag [...]
-:page-partial:
-
-
-
-Subclass of xref:applib-classes:events.adoc#AbstractLifecycleEvent[AbstractLifecycleEvent], broadcast when an object is about to be updated in the database.
-This is done either explicitly when the current transaction is flushed using the xref:refguide:applib:index/services/repository/RepositoryService.adoc[RepositoryService]'s `#flush(...)` method, else is done implicitly when the transaction commits at the end of the user request.
-
-
-`ObjectUpdatingEvent.Default` is the implementation that is used by default, but this can be overridden using xref:refguide:applib:index/annotation/DomainObject.adoc#updatingLifecycleEvent[@DomainObject#updatingLifecycleEvent].
diff --git a/antora/components/refguide/modules/applib-classes/pages/events/uievent.adoc b/antora/components/refguide/modules/applib-classes/pages/events/uievent.adoc
index 4ad6ff7..ac3033a 100644
--- a/antora/components/refguide/modules/applib-classes/pages/events/uievent.adoc
+++ b/antora/components/refguide/modules/applib-classes/pages/events/uievent.adoc
@@ -4,58 +4,50 @@
:page-partial:
-This section catalogues the various UI event classes defined by Apache Isis.
+UI events are broadcast on the xref:refguide:applib:index/services/eventbus/EventBusService.adoc[EventBusService] as the result of rendering a domain object.
+
+They allow subscribers to change various presentation aspects of the rendered object.
+
+Note that if the domain object defines its own layout preferences (for example, a xref:refguide:applib-methods:reserved.adoc#title[title()] supporting method) then these will take precedence.
-These events are broadcast on the xref:refguide:applib:index/services/eventbus/EventBusService.adoc[EventBusService]. The domain
-events are broadcast as a result of being specified in the xref:refguide:applib:index/annotation/DomainObjectLayout.adoc#titleUiEvent[@DomainObjectLayout#titleUiEvent()], xref:refguide:applib:index/annotation/DomainObjectLayout.adoc#iconUiEvent[@DomainObjectLayout#iconUiEvent()] or xref:refguide:applib:index/annotation/DomainObjectLayout.adoc#cssClassUiEvent[@DomainObjectLayout#cssClassUiEvent()] attributes.
-They are listed in the table below.
.UI Event Classes
-[cols="1a,2a,2a", options="header"]
+[cols="2a,2a,2a,2a", options="header"]
|===
|API
-|Implementation
-|Notes
-
-
-|xref:applib-classes:events.adoc#TitleUiEvent[`o.a.i.applib.` +
-`TitleUiEvent`]
-|(abstract class). +
-`TitleUiEvent.Default` is the concrete implementation used if no `@DomainObjectLayout#titleUiEvent` attribute is specified
-|Broadcast whenever there is a requirement to obtain a title for a domain object.
-Note that if the domain object defines its own xref:refguide:applib-methods:reserved.adoc#title[title()] supporting method, or has xref:refguide:applib:index/annotation/Title.adoc[@Title] annotation(s) on its properties, then these will take precedence.
-
-|xref:applib-classes:events.adoc#IconUiEvent[`o.a.i.applib.` +
-`IconUiEvent`]
-|(abstract class). +
-`IconUiEvent.Default` is the concrete implementation used if no `@DomainObjectLayout#iconUiEvent` attribute is specified
-|Broadcast whenever there is a requirement to obtain an icon (or rather, the name of an icon) for a domain object.
-Note that if the domain object defines its own xref:refguide:applib-methods:reserved.adoc#iconName[iconName()] supporting method, or if it has the xref:refguide:applib:index/annotation/DomainObjectLayout.adoc#cssClassFa[@DomainObjectLayout#cssClassFa()] attribute, then these will take precedence.
-
-|xref:applib-classes:events.adoc#CssClassUiEvent[`o.a.i.applib.` +
-`CssClassUiEvent`]
-|(abstract class). +
-`CssClassUiEvent.Default` is the concrete implementation used if no `@DomainObjectLayout#cssClassUiEvent` attribute is specified
-|Broadcast whenever there is a requirement to obtain a CSS class hint for a domain object.
-Note that if the domain object defines its own xref:refguide:applib-methods:reserved.adoc#cssClass[cssClass()] supporting method then this
-will take precedence.
-
-|xref:applib-classes:events.adoc#LayoutUiEvent[`o.a.i.applib.` +
-`LayoutUiEvent`]
-|(abstract class). +
-`LayoutUiEvent.Default` is the concrete implementation used if no `@DomainObjectLayout#layoutUiEvent` attribute is specified
-|Broadcast whenever there is a requirement to obtain an alternative layout for a domain object.
-Note that if the domain object defines its own xref:refguide:applib-methods:reserved.adoc#layout[layout()] supporting method then this
-will take precedence.
+|Event class defined by
+|Raised when
+|Overridden by
+
+
+|xref:refguide:applib:index/events/ui/TitleUiEvent.adoc[TitleUiEvent]
+|xref:refguide:applib:index/annotation/DomainObjectLayout.adoc#titleUiEvent[@DomainObjectLayout#titleUiEvent()]
+|\... rendering the title for a domain object.
+|xref:refguide:applib-methods:reserved.adoc#title[title()] +
+xref:refguide:applib:index/annotation/Title.adoc[@Title]
+
-|===
+|xref:refguide:applib:index/events/ui/IconUiEvent.adoc[IconUiEvent]
+|xref:refguide:applib:index/annotation/DomainObjectLayout.adoc#iconUiEvent[@DomainObjectLayout#iconUiEvent()]
+|\... rendering an icon for a domain object.
+|xref:refguide:applib-methods:reserved.adoc#iconName[iconName()]
+
+
+|xref:refguide:applib:index/events/ui/CssClassUiEvent.adoc[CssClassUiEvent]
+|xref:refguide:applib:index/annotation/DomainObjectLayout.adoc#cssClassUiEvent[@DomainObjectLayout#cssClassUiEvent()]
+|\... obtaining a CSS class hint for a domain object.
+|xref:refguide:applib-methods:reserved.adoc#cssClass[cssClass()]
+
+|xref:refguide:applib:index/events/ui/LayoutUiEvent.adoc[LayoutUiEvent]
+|xref:refguide:applib:index/annotation/DomainObjectLayout.adoc#layoutUiEvent[@DomainObjectLayout#layoutUiEvent()]
+|\... obtain an alternative layout for a domain object.
+|xref:refguide:applib-methods:reserved.adoc#layout[layout()]
+
+|===
-include::uievent/TitleUiEvent.adoc[leveloffset=+1]
-include::uievent/IconUiEvent.adoc[leveloffset=+1]
-include::uievent/CssClassUiEvent.adoc[leveloffset=+1]
diff --git a/antora/components/refguide/modules/applib-classes/pages/events/uievent/CssClassUiEvent.adoc b/antora/components/refguide/modules/applib-classes/pages/events/uievent/CssClassUiEvent.adoc
deleted file mode 100644
index 9d92bac..0000000
--- a/antora/components/refguide/modules/applib-classes/pages/events/uievent/CssClassUiEvent.adoc
+++ /dev/null
@@ -1,17 +0,0 @@
-[[CssClassUiEvent]]
-= `CssClassUiEvent`
-
-: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 ag [...]
-:page-partial:
-
-
-This event class represents a request to obtain the a CSS class hint of a domain object.
-The class has a number of responsibilities:
-
-* capture the target object being interacted with
-
-* capture the CSS class, if any, as specified to one of the subscribers
-
-The class itself is instantiated automatically by the framework whenever interacting with a rendered object's action.
-
-If the domain object defines its own xref:refguide:applib-methods:reserved.adoc#cssClass[cssClass()] supporting method then this will take precedence.
diff --git a/antora/components/refguide/modules/applib-classes/pages/events/uievent/IconUiEvent.adoc b/antora/components/refguide/modules/applib-classes/pages/events/uievent/IconUiEvent.adoc
deleted file mode 100644
index 5d086d2..0000000
--- a/antora/components/refguide/modules/applib-classes/pages/events/uievent/IconUiEvent.adoc
+++ /dev/null
@@ -1,19 +0,0 @@
-[[IconUiEvent]]
-= `IconUiEvent`
-
-: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 ag [...]
-:page-partial:
-
-
-This event class represents a request to obtain the icon (or rather, name of icon) of a domain object.
-The class has a number of responsibilities:
-
-* capture the target object being interacted with
-
-* capture the icon (name), if any, as specified to one of the subscribers
-
-The class itself is instantiated automatically by the framework whenever interacting with a rendered object's action.
-
-If the domain object defines its own xref:refguide:applib-methods:reserved.adoc#iconName[iconName()] supporting method, or if it has the
-xref:refguide:applib:index/annotation/DomainObjectLayout.adoc#cssClassFa[@DomainObjectLayout#cssClassFa()] attribute, then these will take precedence.
-r
diff --git a/antora/components/refguide/modules/applib-classes/pages/events/uievent/TitleUiEvent.adoc b/antora/components/refguide/modules/applib-classes/pages/events/uievent/TitleUiEvent.adoc
deleted file mode 100644
index 55a7fb2..0000000
--- a/antora/components/refguide/modules/applib-classes/pages/events/uievent/TitleUiEvent.adoc
+++ /dev/null
@@ -1,17 +0,0 @@
-[[TitleUiEvent]]
-= `TitleUiEvent`
-
-: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 ag [...]
-:page-partial:
-
-
-This event class represents a request to obtain the title of a domain object.
-The class has a number of responsibilities:
-
-* capture the target object being interacted with
-
-* capture the title, if any, as specified to one of the subscribers
-
-The class itself is instantiated automatically by the framework whenever interacting with a rendered object's action.
-
-If the domain object defines its own xref:refguide:applib-methods:reserved.adoc#title[title()] supporting method, or has xref:refguide:applib:index/annotation/Title.adoc[@Title] annotation(s) on its properties, then these will take precedence.
diff --git a/antora/components/refguide/modules/applib-classes/pages/i18n/TranslatableString.adoc b/antora/components/refguide/modules/applib-classes/pages/i18n/TranslatableString_usage-notes.adoc
similarity index 100%
rename from antora/components/refguide/modules/applib-classes/pages/i18n/TranslatableString.adoc
rename to antora/components/refguide/modules/applib-classes/pages/i18n/TranslatableString_usage-notes.adoc
diff --git a/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/AbstractLifecycleEvent.java b/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/AbstractLifecycleEvent.java
index 2d1c726..33b9a45 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/AbstractLifecycleEvent.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/AbstractLifecycleEvent.java
@@ -18,9 +18,14 @@
*/
package org.apache.isis.applib.events.lifecycle;
+import javax.annotation.Nullable;
+
import org.apache.isis.applib.events.EventObjectBase;
/**
+ * Superclass for all lifecycle events that are raised by the framework when
+ * loading, saving, updating or deleting objects from the database.
+ *
* @since 1.x {@index}
*/
public abstract class AbstractLifecycleEvent<S> extends EventObjectBase<S> {
diff --git a/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectCreatedEvent.java b/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectCreatedEvent.java
index 831c2e5..87bc51d 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectCreatedEvent.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectCreatedEvent.java
@@ -19,27 +19,40 @@
package org.apache.isis.applib.events.lifecycle;
/**
+ * Broadcast when an object (entiy or view model) is first instantiated using
+ * the {@link org.apache.isis.applib.services.factory.FactoryService}.
+ *
+ * @see org.apache.isis.applib.services.factory.FactoryService#detachedEntity(Class)
+ * @see org.apache.isis.applib.services.factory.FactoryService#viewModel(Class)
+ *
* @since 1.x {@index}
*/
public abstract class ObjectCreatedEvent<S> extends AbstractLifecycleEvent<S> {
/**
* This class is the default for the
- * {@link org.apache.isis.applib.annotation.DomainObject#createdLifecycleEvent()} annotation attribute. Whether this
- * raises an event or not depends upon the <tt>isis.core.meta-model.annotation.domain-object.created-lifecycle-event.post-for-default</tt>
+ * {@link org.apache.isis.applib.annotation.DomainObject#createdLifecycleEvent()}
+ * annotation element.
+ *
+ * <p>
+ * Whether this raises an event or not depends upon the
+ * <tt>isis.applib.annotation.domain-object.created-lifecycle-event.post-for-default</tt>
* configuration property.
+ * </p>
*/
public static class Default extends ObjectCreatedEvent<Object> {}
/**
- * Convenience class to use indicating that an event should <i>not</i> be posted (irrespective of the configuration
- * property setting for the {@link Default} event.
+ * Convenience class to use indicating that an event should <i>not</i> be
+ * posted (irrespective of the configuration property setting for the
+ * {@link Default} event.
*/
public static class Noop extends ObjectCreatedEvent<Object> {}
/**
- * Convenience class meaning that an event <i>should</i> be posted (irrespective of the configuration
- * property setting for the {@link Default} event..
+ * Convenience class meaning that an event <i>should</i> be posted
+ * (irrespective of the configuration property setting for the
+ * {@link Default} event..
*/
public static class Doop extends ObjectCreatedEvent<Object> {}
diff --git a/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectLoadedEvent.java b/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectLoadedEvent.java
index 82aaf11..4463f0b 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectLoadedEvent.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectLoadedEvent.java
@@ -19,27 +19,36 @@
package org.apache.isis.applib.events.lifecycle;
/**
+ * Broadcast when an entity is retrieved from the database.
+ *
* @since 1.x {@index}
*/
public abstract class ObjectLoadedEvent<S> extends AbstractLifecycleEvent<S> {
/**
* This class is the default for the
- * {@link org.apache.isis.applib.annotation.DomainObject#loadedLifecycleEvent()} annotation attribute. Whether this
- * raises an event or not depends upon the <tt>isis.core.meta-model.annotation.domain-object.loaded-lifecycle-event.post-for-default</tt>
+ * {@link org.apache.isis.applib.annotation.DomainObject#loadedLifecycleEvent()}
+ * annotation element.
+ *
+ * <p>
+ * Whether this raises an event or not depends upon the
+ * <tt>isis.applib.annotation.domain-object.loaded-lifecycle-event.post-for-default</tt>
* configuration property.
+ * </p>
*/
public static class Default extends ObjectLoadedEvent<Object> {}
/**
- * Convenience class to use indicating that an event should <i>not</i> be posted (irrespective of the configuration
- * property setting for the {@link Default} event.
+ * Convenience class to use indicating that an event should <i>not</i> be
+ * posted (irrespective of the configuration property setting for the
+ * {@link Default} event.
*/
public static class Noop extends ObjectLoadedEvent<Object> {}
/**
- * Convenience class meaning that an event <i>should</i> be posted (irrespective of the configuration
- * property setting for the {@link Default} event..
+ * Convenience class meaning that an event <i>should</i> be posted
+ * (irrespective of the configuration property setting for the
+ * {@link Default} event..
*/
public static class Doop extends ObjectLoadedEvent<Object> {}
diff --git a/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectPersistedEvent.java b/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectPersistedEvent.java
index 9f1d5f6..43f900f 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectPersistedEvent.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectPersistedEvent.java
@@ -19,6 +19,14 @@
package org.apache.isis.applib.events.lifecycle;
/**
+ * Broadcast when an entity is first saved (inserted) into the database either
+ * explicitly using the
+ * {@link org.apache.isis.applib.services.repository.RepositoryService}, or
+ * implicitly, for example due to persistence-by-reachability or similar
+ * persistence mechanisms.
+ *
+ * @see ObjectPersistingEvent
+ *
* @since 1.x {@index}
*/
public abstract class ObjectPersistedEvent<S> extends AbstractLifecycleEvent<S> {
diff --git a/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectPersistingEvent.java b/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectPersistingEvent.java
index 74c0dcb..d7518ba 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectPersistingEvent.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectPersistingEvent.java
@@ -19,6 +19,14 @@
package org.apache.isis.applib.events.lifecycle;
/**
+ * Broadcast when an entity is about to be saved (inserted) into the database
+ * either explicitly using the
+ * {@link org.apache.isis.applib.services.repository.RepositoryService}, or
+ * implicitly, for example due to persistence-by-reachability or similar
+ * persistence mechanisms.
+ *
+ * @see ObjectPersistedEvent
+ *
* @since 1.x {@index}
*/
public abstract class ObjectPersistingEvent<S> extends AbstractLifecycleEvent<S> {
diff --git a/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectRemovingEvent.java b/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectRemovingEvent.java
index aa23e84..0ff9995 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectRemovingEvent.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectRemovingEvent.java
@@ -19,6 +19,14 @@
package org.apache.isis.applib.events.lifecycle;
/**
+ * Broadcast when an entity is about to be removed (deleted) into the database
+ * either explicitly using the
+ * {@link org.apache.isis.applib.services.repository.RepositoryService}, or
+ * implicitly, for example due to cascade delete or similar
+ * persistence mechanisms.
+ *
+ * @see ObjectRemovingEvent
+ *
* @since 1.x {@index}
*/
public abstract class ObjectRemovingEvent<S> extends AbstractLifecycleEvent<S> {
diff --git a/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectUpdatedEvent.java b/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectUpdatedEvent.java
index b835a38..860873b 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectUpdatedEvent.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectUpdatedEvent.java
@@ -19,6 +19,11 @@
package org.apache.isis.applib.events.lifecycle;
/**
+ * Broadcast when an entity has just been updated in the database, usually
+ * as the result of the ORM dirty tracking mechanisms.
+ *
+ * @see ObjectUpdatingEvent
+ *
* @since 1.x {@index}
*/
public abstract class ObjectUpdatedEvent<S> extends AbstractLifecycleEvent<S> {
diff --git a/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectUpdatingEvent.java b/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectUpdatingEvent.java
index ca3ff49..1c6764d 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectUpdatingEvent.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectUpdatingEvent.java
@@ -19,6 +19,11 @@
package org.apache.isis.applib.events.lifecycle;
/**
+ * Broadcast when an entity is about to be updated in the database, usually
+ * as the result of the ORM dirty tracking mechanisms.
+ *
+ * @see ObjectUpdatedEvent
+ *
* @since 1.x {@index}
*/
public abstract class ObjectUpdatingEvent<S> extends AbstractLifecycleEvent<S> {
diff --git a/api/applib/src/main/java/org/apache/isis/applib/events/ui/CssClassUiEvent.java b/api/applib/src/main/java/org/apache/isis/applib/events/ui/CssClassUiEvent.java
index bc84e18..cee48d0 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/events/ui/CssClassUiEvent.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/events/ui/CssClassUiEvent.java
@@ -23,7 +23,26 @@ import org.apache.isis.applib.annotation.DomainObjectLayout;
import lombok.Getter;
/**
- * Emitted for subscribers to obtain a cssClass hint (equivalent to the <tt>cssClass()</tt> supporting method or the {@link DomainObjectLayout#cssClass()} attribute).
+ * Emitted for subscribers to provide a cssClass hint (equivalent to the
+ * <tt>cssClass()</tt> supporting method or the
+ * {@link DomainObjectLayout#cssClass()} element).
+ *
+ * <p>
+ * The class has a number of responsibilities:
+ * </p>
+ *
+ * <ul>
+ * <li>
+ * capture the target object being interacted with
+ * </li>
+ * <li>
+ * capture the CSS class, if any, as specified to one of the subscribers
+ * </li>
+ * </ul>
+ *
+ * <p>
+ * The class itself is instantiated automatically by the framework.
+ * </p>
*
* @since 1.x {@index}
*/
@@ -31,21 +50,28 @@ public abstract class CssClassUiEvent<S> extends AbstractUiEvent<S> {
/**
* This class is the default for the
- * {@link org.apache.isis.applib.annotation.DomainObjectLayout#cssClassUiEvent()} annotation attribute. Whether this
- * raises an event or not depends upon the <tt>isis.core.meta-model.annotation.domain-object-layout.css-class-ui-event.post-for-default</tt>
+ * {@link org.apache.isis.applib.annotation.DomainObjectLayout#cssClassUiEvent()}
+ * annotation element.
+ *
+ * <p>
+ * Whether this raises an event or not depends upon the
+ * <tt>isis.applib.annotation.domain-object-layout.css-class-ui-event.post-for-default</tt>
* configuration property.
+ * </p>
*/
public static class Default extends CssClassUiEvent<Object> {}
/**
- * Convenience class to use indicating that an event should <i>not</i> be posted (irrespective of the configuration
- * property setting for the {@link Default} event.
+ * Convenience class to use indicating that an event should <i>not</i> be
+ * posted (irrespective of the configuration property setting for the
+ * {@link Default} event.
*/
public static class Noop extends CssClassUiEvent<Object> {}
/**
- * Convenience class meaning that an event <i>should</i> be posted (irrespective of the configuration
- * property setting for the {@link Default} event..
+ * Convenience class meaning that an event <i>should</i> be posted
+ * (irrespective of the configuration property setting for the
+ * {@link Default} event..
*/
public static class Doop extends CssClassUiEvent<Object> {}
diff --git a/api/applib/src/main/java/org/apache/isis/applib/events/ui/IconUiEvent.java b/api/applib/src/main/java/org/apache/isis/applib/events/ui/IconUiEvent.java
index fc70cab..2173e88 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/events/ui/IconUiEvent.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/events/ui/IconUiEvent.java
@@ -21,13 +21,38 @@ package org.apache.isis.applib.events.ui;
import java.util.EventObject;
/**
- * Emitted for subscribers to obtain a cssClass hint (equivalent to the <tt>iconName()</tt> supporting method).
+ * Emitted for subscribers to provide a cssClass hint (equivalent to the
+ * <tt>iconName()</tt> supporting method).
+ *
+ * <p>
+ * The class has a number of responsibilities:
+ * </p>
+ *
+ * <ul>
+ * <li>
+ * capture the target object being interacted with
+ * </li>
+ * <li>
+ * capture the icon (name), if any, as specified to one of the subscribers
+ * </li>
+ * </ul>
+ *
+ * <p>
+ * The class itself is instantiated automatically by the framework.
+ * </p>
+ *
+ *
+ * *
+ *
+ *
+ * If the domain object defines its own xref:refguide:applib-methods:reserved.adoc#iconName[iconName()] supporting method, or if it has the
+ * xref:refguide:applib:index/annotation/DomainObjectLayout.adoc#cssClassFa[@DomainObjectLayout#cssClassFa()] attribute, then these will take precedence.
+ * </p>
*
* @since 1.x {@index}
*/
public abstract class IconUiEvent<S> extends AbstractUiEvent<S> {
- // -- constructors
/**
* If used then the framework will set state via (non-API) setters.
*
@@ -45,21 +70,24 @@ public abstract class IconUiEvent<S> extends AbstractUiEvent<S> {
- // -- Default class
/**
* This class is the default for the
- * {@link org.apache.isis.applib.annotation.DomainObjectLayout#iconUiEvent()} annotation attribute. Whether this
- * raises an event or not depends upon the <tt>isis.core.meta-model.annotation.domain-object-layout.icon-ui-event.post-for-default</tt>
+ * {@link org.apache.isis.applib.annotation.DomainObjectLayout#iconUiEvent()}
+ * annotation element.
+ *
+ * <p>
+ * Whether this raises an event or not depends upon the
+ * <tt>isis.applib.annotation.domain-object-layout.icon-ui-event.post-for-default</tt>
* configuration property.
+ * </p>
*/
public static class Default extends IconUiEvent<Object> { }
- // -- Noop class
-
/**
- * Convenience class to use indicating that an event should <i>not</i> be posted (irrespective of the configuration
- * property setting for the {@link Default} event.
+ * Convenience class to use indicating that an event should <i>not</i> be
+ * posted (irrespective of the configuration property setting for the
+ * {@link Default} event.
*/
public static class Noop extends IconUiEvent<Object> { }
@@ -67,8 +95,9 @@ public abstract class IconUiEvent<S> extends AbstractUiEvent<S> {
// -- Doop class
/**
- * Convenience class meaning that an event <i>should</i> be posted (irrespective of the configuration
- * property setting for the {@link Default} event..
+ * Convenience class meaning that an event <i>should</i> be posted
+ * (irrespective of the configuration property setting for the
+ * {@link Default} event..
*/
public static class Doop extends IconUiEvent<Object> { }
diff --git a/api/applib/src/main/java/org/apache/isis/applib/events/ui/LayoutUiEvent.java b/api/applib/src/main/java/org/apache/isis/applib/events/ui/LayoutUiEvent.java
index 06be512..610e0c2 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/events/ui/LayoutUiEvent.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/events/ui/LayoutUiEvent.java
@@ -25,7 +25,25 @@ import org.apache.isis.applib.annotation.DomainObjectLayout;
import lombok.Getter;
/**
- * Emitted for subscribers to obtain a layout hint (equivalent to the <tt>layout()</tt> supporting method).
+ * Emitted for subscribers to obtain a layout hint (equivalent to the
+ * <tt>layout()</tt> supporting method).
+ *
+ * <p>
+ * The class has a number of responsibilities:
+ * </p>
+ *
+ * <ul>
+ * <li>
+ * capture the target object being interacted with
+ * </li>
+ * <li>
+ * capture the layout, if any, as specified to one of the subscribers
+ * </li>
+ * </ul>
+ *
+ * <p>
+ * The class itself is instantiated automatically by the framework.
+ * </p>
*
* @since 1.x {@index}
*/
@@ -33,21 +51,27 @@ public abstract class LayoutUiEvent<S> extends AbstractUiEvent<S> {
/**
* This class is the default for the
- * {@link DomainObjectLayout#layoutUiEvent()} annotation attribute. Whether this
- * raises an event or not depends upon the <tt>isis.core.meta-model.annotation.domain-object-layout.layout-ui-event.post-for-default</tt>
+ * {@link DomainObjectLayout#layoutUiEvent()} annotation element.
+ *
+ * <p>
+ * Whether this raises an event or not depends upon the
+ * <tt>isis.applib.annotation.domain-object-layout.layout-ui-event.post-for-default</tt>
* configuration property.
+ * </p>
*/
public static class Default extends LayoutUiEvent<Object> { }
/**
- * Convenience class to use indicating that an event should <i>not</i> be posted (irrespective of the configuration
- * property setting for the {@link Default} event.
+ * Convenience class to use indicating that an event should <i>not</i> be
+ * posted (irrespective of the configuration property setting for the
+ * {@link Default} event.
*/
public static class Noop extends LayoutUiEvent<Object> { }
/**
- * Convenience class meaning that an event <i>should</i> be posted (irrespective of the configuration
- * property setting for the {@link Default} event..
+ * Convenience class meaning that an event <i>should</i> be posted
+ * (irrespective of the configuration property setting for the
+ * {@link Default} event..
*/
public static class Doop extends LayoutUiEvent<Object> { }
diff --git a/api/applib/src/main/java/org/apache/isis/applib/events/ui/TitleUiEvent.java b/api/applib/src/main/java/org/apache/isis/applib/events/ui/TitleUiEvent.java
index 121f281..f8332e7 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/events/ui/TitleUiEvent.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/events/ui/TitleUiEvent.java
@@ -25,7 +25,25 @@ import org.apache.isis.applib.services.i18n.TranslatableString;
import lombok.Getter;
/**
- * Emitted for subscribers to obtain a cssClass hint (equivalent to the <tt>title()</tt> supporting method).
+ * Emitted for subscribers to obtain a title hint (equivalent to the
+ * <tt>title()</tt> supporting method).
+ *
+ * <p>
+ * The class has a number of responsibilities:
+ * </p>
+ *
+ * <ul>
+ * <li>
+ * capture the target object being interacted with
+ * </li>
+ * <li>
+ * capture the title, if any, as specified to one of the subscribers
+ * </li>
+ * </ul>
+ *
+ * <p>
+ * The class itself is instantiated automatically by the framework.
+ * </p>
*
* @since 1.x {@index}
*/
@@ -33,21 +51,28 @@ public abstract class TitleUiEvent<S> extends AbstractUiEvent<S> {
/**
* This class is the default for the
- * {@link org.apache.isis.applib.annotation.DomainObjectLayout#titleUiEvent()} annotation attribute. Whether this
- * raises an event or not depends upon the <tt>isis.core.meta-model.annotation.domain-object-layout.title-ui-event.post-for-default</tt>
+ * {@link org.apache.isis.applib.annotation.DomainObjectLayout#titleUiEvent()}
+ * annotation element.
+ *
+ * <p>
+ * Whether this raises an event or not depends upon the
+ * <tt>isis.applib.annotation.domain-object-layout.title-ui-event.post-for-default</tt>
* configuration property.
+ * </p>
*/
public static class Default extends TitleUiEvent<Object> {}
/**
- * Convenience class to use indicating that an event should <i>not</i> be posted (irrespective of the configuration
- * property seting for the {@link Default} event.
+ * Convenience class to use indicating that an event should <i>not</i> be
+ * posted (irrespective of the configuration property seting for the
+ * {@link Default} event.
*/
public static class Noop extends TitleUiEvent<Object> {}
/**
- * Convenience class meaning that an event <i>should</i> be posted (irrespective of the configuration
- * property setting for the {@link Default} event..
+ * Convenience class meaning that an event <i>should</i> be posted
+ * (irrespective of the configuration property setting for the
+ * {@link Default} event.
*/
public static class Doop extends TitleUiEvent<Object> {}