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/03 22:08:12 UTC
[isis] 01/07: ISIS-2444: cleaning up domain 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 343feebd3c2e8a6b77a01e3f0014bb8d1a8c684c
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Wed Mar 3 06:44:19 2021 +0000
ISIS-2444: cleaning up domain event docs
---
.../applib-classes/pages/events/domainevent.adoc | 51 ++++-----
.../events/domainevent/AbstractDomainEvent.adoc | 109 -------------------
.../events/domainevent/ActionDomainEvent.adoc | 49 ---------
.../events/domainevent/CollectionDomainEvent.adoc | 12 --
.../applib/events/domain/AbstractDomainEvent.java | 121 ++++++++++++++++-----
.../applib/events/domain/ActionDomainEvent.java | 105 ++++++++++++++----
.../events/domain/CollectionDomainEvent.java | 52 ++++++---
.../applib/events/domain/PropertyDomainEvent.java | 7 +-
.../main/adoc/modules/metamodel/pages/about.adoc | 2 +-
persistence/jpa/adoc/modules/ROOT/pages/about.adoc | 2 +-
security/adoc/modules/ROOT/pages/about.adoc | 4 +-
testing/adoc/modules/ROOT/pages/about.adoc | 4 +-
12 files changed, 240 insertions(+), 278 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 8be777f..a26d546 100644
--- a/antora/components/refguide/modules/applib-classes/pages/events/domainevent.adoc
+++ b/antora/components/refguide/modules/applib-classes/pages/events/domainevent.adoc
@@ -7,54 +7,43 @@
This section catalogues the various domain event classes defined by Apache Isis.
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/Action.adoc#domainEvent[@Action#domainEvent()], xref:refguide:applib:index/annotation/Property.adoc#domainEvent[@Property#domainEvent()] or xref:refguide:applib:index/annotation/Collection.adoc#domainEvent[@Collection#domainEvent()] attributes.
+The domain events are broadcast as a result of being specified in the , or xref:refguide:applib:index/annotation/Collection.adoc#domainEvent[@Collection#domainEvent()] attributes.
They are listed in the table below.
.Domain Event Classes
-[cols="1a,2a,2a", options="header"]
+[cols="1a,2a,2a,2a", options="header"]
|===
|API
-|Implementation
-|Notes
+|Raised by
+|Fallback +
+Implementation
+|Published when
-|xref:applib-classes:events.adoc#AbstractDomainEvent[`o.a.i.applib.` +
-`AbstractDomainEvent`]
+|xref:refguide:applib:index/events/domain/AbstractDomainEvent.adoc[AbstractDomainEvent]
+|n/a
|(abstract class)
|Superclass of the other domain events, listed below in this table.
-|xref:applib-classes:events.adoc#ActionDomainEvent[`o.a.i.applib.` +
-`ActionDomainEvent`]
-|(abstract class). +
-`ActionDomainEvent.Default` is the concrete implementation used if no `@Action#domainEvent` attribute is specified
-|Broadcast whenever there is an interaction (hide/disable/validate/pre-execute/post-execute) with an object's action.
+|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.
+|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:applib-classes:events.adoc#CollectionDomainEvent[`o.a.i.applib.` +
-`CollectionDomainEvent`]
-|(abstract class). +
-`CollectionDomainEvent.Default` is the concrete implementation used if no `@Collection#domainEvent` attribute
-is specified.
-|Broadcast whenever there is an interaction (hide/disable/validate/access) with an object's collection.
-
-|xref:applib-classes:events.adoc#PropertyDomainEvent[`o.a.i.applib.` +
-`PropertyDomainEvent`]
-|(abstract class). +
-`PropertyDomainEvent.Default` is the concrete implementation used if no `@Propert#domainEvent` attribute is specified
-|Broadcast whenever there is an interaction (hide/disable/validate/access) with an object's property.
+|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.
|===
-
-
-
-
-include::domainevent/AbstractDomainEvent.adoc[leveloffset=+1]
-include::domainevent/ActionDomainEvent.adoc[leveloffset=+1]
-include::domainevent/CollectionDomainEvent.adoc[leveloffset=+1]
-include::domainevent/PropertyDomainEvent.adoc[leveloffset=+1]
diff --git a/antora/components/refguide/modules/applib-classes/pages/events/domainevent/AbstractDomainEvent.adoc b/antora/components/refguide/modules/applib-classes/pages/events/domainevent/AbstractDomainEvent.adoc
deleted file mode 100644
index a20d5d8..0000000
--- a/antora/components/refguide/modules/applib-classes/pages/events/domainevent/AbstractDomainEvent.adoc
+++ /dev/null
@@ -1,109 +0,0 @@
-[[AbstractDomainEvent]]
-= `AbstractDomainEvent`
-
-: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 domain events that are raised by the framework when interacting with actions, properties or collections.
-
-Its immediate subclasses are:
-
-* xref:applib-classes:events.adoc#ActionDomainEvent[ActionDomainEvent]
-* xref:applib-classes:events.adoc#PropertyDomainEvent[PropertyDomainEvent]
-* xref:applib-classes:events.adoc#CollectionDomainEvent[CollectionDomainEvent]
-
-The main purpose of the class is to define the protocol by which subscribers can influence an interaction (eg hide a collection, disable a property, validate action arguments).
-It class also provides a simple mechanism to allow adhoc sharing of user data between different phases.
-
-== API
-
-The API of the class is:
-
-// TODO: v2: use include::[]
-
-[source,java]
-----
-public abstract class AbstractDomainEvent<S> extends java.util.EventObject {
-
- public S getSource(); // <.>
- public Object getMixedIn(); // <.>
- public Object getSubject(); // <.>
-
- public Identifier getIdentifier(); // <.>
-
- public Phase getEventPhase(); // <.>
-
- public void hide(); // <.>
- public boolean isHidden(); // <.>
-
- public void disable(final String reason); // <.>
- public void disable(final TranslatableString reason);
- public String getDisabledReason(); // <.>
- public TranslatableString getDisabledReasonTranslatable();
- public boolean isDisabled();
-
- public void invalidate(final String reason); // <.>
- public void invalidate(final TranslatableString reason);
- public String getInvalidityReason(); // <.>
- public TranslatableString getInvalidityReasonTranslatable();
- public boolean isInvalid();
-
- public void veto(final String reason, final Object... args); // <.>
- public void veto(final TranslatableString translatableReason);
-
- public Object get(Object key); // <.>
- public void put(Object key, Object value);
-}
-----
-
-<.> The domain object raising this event.
-+
-For a "regular" action, property or collection then this will be the target domain object.
-But for a "mixin" action, this will be an instance of the mixin itself.
-
-<.> For a "mixin", this will be the target object that is being contributed to.
-+
-For a "regular" action, this will return `null`.
-
-<.> Returns the domain object being interacted with, irrespective of whether this is a "regular" action/property/collection or a "mixin".
-+
-* For a regular member, this will return the same as `getSource()`.
-+
-* For a mixin, this will return the same as `getMixedIn()`.
-
-<.> Identifier of the action, property or collection being interacted with.
-
-<.> Whether the framework is checking visibility, enablement, validity or actually executing (invoking action, editing property), as per the `Phase` enum (defined below).
-
-<.> API for subscribers to hide the member
-
-<.> Used by the framework to determine if the member should be hidden (not rendered)
-
-<.> API for subscribers to disable the member, specifying the reason why (possibly translated)
-
-<.> Used by the framework to determine whether the member should be disabled (greyed out) when rendered.
-
-<.> API for subscribers to invalidate an interaction, eg invalid arguments to an action
-
-<.> Used by the framework to determine whether the interaction is invalid and should be blocked (eg pressing OK shows message)
-
-<.> Convenience API for subscribers to veto; will automatically call either `hide()`, `disable(...)` or `invalidate(...)` based on the phase
-
-<.> Mechanism to allow subscribers to share arbitrary information between phases.
-One event instance is used for both the hide and disable phases, and a different event instance is shared between validate/pre-execute/post-execute.
-
-The referenced `Phase` enum is in turn:
-
-[source,java]
-----
-public enum Phase {
- HIDE,
- DISABLE,
- VALIDATE,
- EXECUTING,
- EXECUTED;
- public boolean isValidatingOrLater(); // <.>
-}
-----
-<.> The significance being that at this point the proposed values/arguments are known, and so the event can be fully populated.
diff --git a/antora/components/refguide/modules/applib-classes/pages/events/domainevent/ActionDomainEvent.adoc b/antora/components/refguide/modules/applib-classes/pages/events/domainevent/ActionDomainEvent.adoc
deleted file mode 100644
index d647dcf..0000000
--- a/antora/components/refguide/modules/applib-classes/pages/events/domainevent/ActionDomainEvent.adoc
+++ /dev/null
@@ -1,49 +0,0 @@
-[[ActionDomainEvent]]
-= `ActionDomainEvent`
-
-: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#AbstractDomainEvent[AbstractDomainEvent] for actions.
-
-The class has a number of responsibilities (in addition to those it inherits):
-
-* capture the target object being interacted with
-* capture the arguments for each of the action's parameters
-* provide selected metadata about the action parameters from the metamodel (names, types)
-
-The class itself is instantiated automatically by the framework whenever interacting with a rendered object's action.
-
-== API
-
-The API of the class is:
-
-// TODO: v2: use include::[]
-
-[source,java]
-----
-public abstract class ActionDomainEvent<S> extends AbstractDomainEvent<S> {
-
- public static class Default extends ActionDomainEvent<Object> { } // <.>
- public static class Noop extends ActionDomainEvent<Object> { } // <.>
- public static class Doop extends ActionDomainEvent<Object> { } // <.>
-
- public SemanticsOf getSemantics();
-
- public List<String> getParameterNames();
- public List<Class<?>> getParameterTypes();
-
- public List<Object> getArguments(); // <.>
- public Object getReturnValue(); // <.>
- public void setReturnValue(); // <.>
-}
-----
-<.> The `Default` nested static class is the default for the xref:refguide:applib:index/annotation/Action.adoc#domainEvent[@Action#domainEvent()]
-annotation attribute.
-Whether this raises an event or not depends upon the `isis.reflector.facet.actionAnnotation.domainEvent.postForDefault` configuration property.
-<.> The `Noop` class is provided as a convenience to indicate that an event should _not_ be posted (irrespective of the configuration property setting).
-<.> Similarly, the `Doop` class is provided as a convenience to indicate that an event _should_ be raised (irrespective of the configuration property setting).
-<.> The arguments being used to invoke the action; populated during validate phase and subsequent phases.
-<.> The value returned by the action; populated only in the executed phase.
-<.> Allows the subscriber to effectively change the value returned by the action; may only be called in the executed phase.
diff --git a/antora/components/refguide/modules/applib-classes/pages/events/domainevent/CollectionDomainEvent.adoc b/antora/components/refguide/modules/applib-classes/pages/events/domainevent/CollectionDomainEvent.adoc
index 02826ac..e35af06 100644
--- a/antora/components/refguide/modules/applib-classes/pages/events/domainevent/CollectionDomainEvent.adoc
+++ b/antora/components/refguide/modules/applib-classes/pages/events/domainevent/CollectionDomainEvent.adoc
@@ -5,18 +5,6 @@
:page-partial:
-Subclass of xref:applib-classes:events.adoc#AbstractDomainEvent[AbstractDomainEvent] for collections.
-
-The class has a couple of responsibilities (in addition to those it inherits):
-
-* capture the target object being interacted with
-
-* indicate whether the interaction is to add or remove an object from the collection (or simply to indicate that the collection is being accessed/read)
-
-* capture the object reference being added or removed
-
-
-The class itself is instantiated automatically by the framework whenever interacting with a rendered object's collection.
== API
diff --git a/api/applib/src/main/java/org/apache/isis/applib/events/domain/AbstractDomainEvent.java b/api/applib/src/main/java/org/apache/isis/applib/events/domain/AbstractDomainEvent.java
index 08ddedf..2bfa27e 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/events/domain/AbstractDomainEvent.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/events/domain/AbstractDomainEvent.java
@@ -21,6 +21,8 @@ package org.apache.isis.applib.events.domain;
import java.util.HashMap;
import java.util.Map;
+import javax.annotation.Nullable;
+
import org.apache.isis.applib.Identifier;
import org.apache.isis.applib.events.EventObjectBase;
import org.apache.isis.applib.services.i18n.TranslatableString;
@@ -31,6 +33,24 @@ import org.apache.isis.commons.internal.exceptions._Exceptions;
import lombok.Getter;
/**
+ * Superclass for all domain events that are raised by the framework when
+ * interacting with actions, properties or collections.
+ *
+ * <p>
+ * The main purpose of the class is to define the protocol by which
+ * subscribers can influence an interaction (eg hide a collection,
+ * disable a property, validate action arguments).
+ * </p>
+ *
+ * <p>
+ * The class also provides a simple mechanism to allow adhoc sharing of
+ * user data between different phases.
+ * </p>
+ *
+ * @see ActionDomainEvent
+ * @see PropertyDomainEvent
+ * @see CollectionDomainEvent
+ *
* @since 1.x {@index}
*/
public abstract class AbstractDomainEvent<S> extends EventObjectBase<S> {
@@ -55,7 +75,31 @@ public abstract class AbstractDomainEvent<S> extends EventObjectBase<S> {
}
/**
- * Populated only for mixins; holds the underlying domain object that the mixin contributes to.
+ * The domain object raising this event.
+ *
+ * <p>
+ * For a "regular" action, property or collection then this will be the
+ * target domain object.
+ * </p>
+ *
+ * <p>
+ * But for a "mixin" action, this will be an instance of the mixin
+ * itself.
+ * </p>
+ */
+ @Nullable
+ @Override
+ public S getSource() {
+ return super.getSource();
+ }
+
+ /**
+ * Populated only for mixins; holds the underlying domain object that the
+ * mixin contributes to.
+ *
+ * <p>
+ * For a "regular" action, this will return <code>null</code>.
+ * </p>
*/
@Getter
private Object mixedIn;
@@ -69,7 +113,8 @@ public abstract class AbstractDomainEvent<S> extends EventObjectBase<S> {
/**
- * The subject of the event, which will be either the {@link #getSource() source} for a regular action, or the
+ * The subject of the event, which will be either the
+ * {@link #getSource() source} for a regular action, or the
* {@link #getMixedIn() mixed-in} domain object for a mixin.
*/
public Object getSubject() {
@@ -77,6 +122,10 @@ public abstract class AbstractDomainEvent<S> extends EventObjectBase<S> {
return mixedIn != null ? mixedIn : getSource();
}
+ /**
+ *
+ * {@index}
+ */
public enum Phase {
HIDE,
@@ -132,7 +181,8 @@ public abstract class AbstractDomainEvent<S> extends EventObjectBase<S> {
}
/**
- * If the no-arg constructor is used, then the framework will populate this field reflectively.
+ * Identifier of the action, property or collection being interacted with.
+ *
*/
@Getter
private Identifier identifier;
@@ -144,21 +194,25 @@ public abstract class AbstractDomainEvent<S> extends EventObjectBase<S> {
this.identifier = identifier;
}
+ /**
+ * Used by the framework to determine if the member should be hidden (not
+ * rendered).
+ */
@Getter
private boolean hidden;
/**
+ * API for subscribers to hide the member.
+ *
* @see #veto(String, Object...)
*/
public void hide() {
-
this.hidden = true;
-
- // ...
}
/**
- * If {@link #isDisabled() disabled}, then either this method returns non-null or {@link #getDisabledReasonTranslatable()} will.
+ * If {@link #isDisabled() disabled}, then either this method returns
+ * non-null or {@link #getDisabledReasonTranslatable()} will.
*/
@Getter
private String disabledReason;
@@ -175,36 +229,47 @@ public abstract class AbstractDomainEvent<S> extends EventObjectBase<S> {
/**
+ * API for subscribers to disable the member, specifying the reason why.
+ *
* @see #disable(org.apache.isis.applib.services.i18n.TranslatableString)
* @see #veto(String, Object...)
*/
public void disable(final String reason) {
-
this.disabledReason = reason;
-
- // ...
}
/**
+ * API for subscribers to disable the member, specifying the reason why as
+ * a {@link TranslatableString}.
+ *
* @see #disable(java.lang.String)
* @see #veto(org.apache.isis.applib.services.i18n.TranslatableString)
*/
public void disable(final TranslatableString reason) {
-
this.disabledReasonTranslatable = reason;
-
- // ...
}
/**
- * If {@link #isInvalid() invalid}, then either this method returns non-null or {@link #getInvalidityReasonTranslatable()} will.
+ * Used by the framework to determine whether the interaction is invalid
+ * and should be blocked (eg pressing OK shows message).
+ *
+ * <p>
+ * If {@link #isInvalid() invalid}, then either this method returns
+ * non-null or {@link #getInvalidityReasonTranslatable()} will.
+ * </p>
*/
@Getter
private String invalidityReason;
/**
- * If {@link #isInvalid() invalid}, then either this method returns non-null or {@link #getInvalidityReason()} will.
+ * Used by the framework to determine whether the interaction is invalid
+ * and should be blocked (eg pressing OK shows message).
+ *
+ * <p>
+ * If {@link #isInvalid() invalid}, then either this method returns non-null
+ * or {@link #getInvalidityReason()} will.
+ * </p>
*/
@Getter
private TranslatableString invalidityReasonTranslatable;
@@ -214,36 +279,38 @@ public abstract class AbstractDomainEvent<S> extends EventObjectBase<S> {
}
/**
+ * API for subscribers to invalidate an interaction, eg invalid arguments
+ * to an action.
+ *
* @see #invalidate(org.apache.isis.applib.services.i18n.TranslatableString)
* @see #veto(String, Object...)
*/
public void invalidate(final String reason) {
-
this.invalidityReason = reason;
-
- // ...
}
/**
+ * API for subscribers to invalidate an interaction, specifying the reason
+ * as a {@link TranslatableString}.
+ *
* @see #invalidate(String)
* @see #veto(org.apache.isis.applib.services.i18n.TranslatableString)
*/
public void invalidate(final TranslatableString reason) {
-
this.invalidityReasonTranslatable = reason;
-
- // ...
}
/**
- * Use instead of {@link #hide()}, {@link #disable(String)} and {@link #invalidate(String)}; just delegates to
+ * Use instead of {@link #hide()}, {@link #disable(String)} and
+ * {@link #invalidate(String)}; just delegates to
* appropriate vetoing method based upon the {@link #getEventPhase() phase}.
*
* <p>
* If hiding, just pass <tt>null</tt> for the parameter.
* </p>
*
- * @param reason - reason why the interaction is being invalidated (ignored if in {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#HIDE hide} phase).
+ * @param reason - reason why the interaction is being invalidated (ignored
+ * if in {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#HIDE hide} phase).
* @param args
*
* @see #veto(org.apache.isis.applib.services.i18n.TranslatableString)
@@ -272,8 +339,6 @@ public abstract class AbstractDomainEvent<S> extends EventObjectBase<S> {
default:
throw _Exceptions.unmatchedCase(getEventPhase());
}
-
- // ...
}
/**
@@ -306,8 +371,6 @@ public abstract class AbstractDomainEvent<S> extends EventObjectBase<S> {
default:
throw _Exceptions.unmatchedCase(getEventPhase());
}
-
- // ...
}
/**
@@ -323,6 +386,10 @@ public abstract class AbstractDomainEvent<S> extends EventObjectBase<S> {
}
/**
+ * Mechanism to allow subscribers to share arbitrary information between
+ * phases. One event instance is used for both the hide and disable phases,
+ * and a different event instance is shared between validate/pre-execute/post-execute.
+ *
* Set user-data, for the use of a subsequent {@link #getEventPhase() phase}.
*/
public void put(Object key, Object value) {
diff --git a/api/applib/src/main/java/org/apache/isis/applib/events/domain/ActionDomainEvent.java b/api/applib/src/main/java/org/apache/isis/applib/events/domain/ActionDomainEvent.java
index a327141..983b711 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/events/domain/ActionDomainEvent.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/events/domain/ActionDomainEvent.java
@@ -20,6 +20,7 @@ package org.apache.isis.applib.events.domain;
import java.util.List;
+import org.apache.isis.applib.annotation.Action;
import org.apache.isis.applib.annotation.SemanticsOf;
import org.apache.isis.applib.util.ObjectContracts;
import org.apache.isis.applib.util.ToString;
@@ -28,47 +29,97 @@ import lombok.Getter;
import lombok.Setter;
/**
+ * Subclass of {@link AbstractDomainEvent} for actions.
+ *
+ * <p>
+ * The class has a number of responsibilities (in addition to those it inherits):
+ * </p>
+ *
+ * <ul>
+ * <li>
+ * capture the target object being interacted with
+ * </li>
+ * <li>
+ * capture the arguments for each of the action's parameters
+ * </li>
+ * <li>
+ * provide selected metadata about the action parameters from the
+ * metamodel (names, types)
+ * </li>
+ * </ul>
+ *
+ * <p>
+ * The class itself is instantiated automatically by the framework whenever
+ * interacting with a rendered object's action.
+ * </p>
+ *
* @since 1.x {@index}
*/
public abstract class ActionDomainEvent<S> extends AbstractDomainEvent<S> {
/**
* This class is the default for the
- * {@link org.apache.isis.applib.annotation.Action#domainEvent()} annotation attribute. Whether this
- * raises an event or not depends upon the
+ * {@link org.apache.isis.applib.annotation.Action#domainEvent()} annotation attribute.
+ *
+ * <p>
+ * Whether this raises an event or not depends upon the
* <tt>isis.core.meta-model.annotation.action.domain-event.post-for-default</tt>
* configuration property.
+ * </p>
*/
public static class Default extends ActionDomainEvent<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 ActionDomainEvent<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 ActionDomainEvent<Object> {}
/**
- * If used then the framework will set state via (non-API) setters.
- *
- * <p>
- * Recommended because it reduces the amount of boilerplate in the domain object classes.
- * </p>
+ * Subtypes can define a no-arg constructor; the framework sets state
+ * via (non-API) setters.
*/
public ActionDomainEvent() {
}
+ /**
+ * The semantics of the action being invoked.
+ *
+ * <p>
+ * Copied over from {@link Action#semantics()}
+ * </p>
+ */
@Getter
private SemanticsOf semantics;
+ /**
+ * The names of the parameters of the actions.
+ *
+ * @see #getParameterTypes()
+ * @see #getArguments()
+ */
@Getter
private List<String> parameterNames;
+ /**
+ * The types of the parameters of the actions.
+ *
+ * <p>
+ * The {@link #getArguments() arguments} will be castable to the
+ * parameter types here.
+ * </p>
+ *
+ * @see #getParameterNames()
+ * @see #getArguments()
+ */
@Getter
private List<Class<?>> parameterTypes;
@@ -79,17 +130,23 @@ public abstract class ActionDomainEvent<S> extends AbstractDomainEvent<S> {
private Object mixedIn;
/**
- * The arguments being used to invoke the action;
- * populated at {@link AbstractDomainEvent.Phase#VALIDATE} and subsequent phases
- * (but null for {@link AbstractDomainEvent.Phase#HIDE hidden} and
+ * The arguments being used to invoke the action.
+ *
+ * <p>
+ * Populated at {@link AbstractDomainEvent.Phase#VALIDATE} and subsequent
+ * phases (but null for {@link AbstractDomainEvent.Phase#HIDE hidden} and
* {@link AbstractDomainEvent.Phase#DISABLE disable} phases).
+ * </p>
*
* <p>
* The argument values can also be modified by event handlers
- * during the {@link AbstractDomainEvent.Phase#EXECUTING} phase. The new value must be
- * the same type as the expected value; the framework performs
- * no sanity checks.
+ * during the {@link AbstractDomainEvent.Phase#EXECUTING} phase. The
+ * new value must be the same type as the expected value; the framework
+ * performs no sanity checks.
* </p>
+ *
+ * @see #getParameterNames()
+ * @see #getParameterTypes()
*/
@Getter @Setter
private List<Object> arguments;
@@ -108,33 +165,35 @@ public abstract class ActionDomainEvent<S> extends AbstractDomainEvent<S> {
/**
* Set by the framework.
*
- * Event subscribers can replace the value with some other value if they wish, though only in the
- * {@link AbstractDomainEvent.Phase#EXECUTED} phase.
+ * <p>
+ * Event subscribers can replace the value with some other value if they
+ * wish, though only in the {@link AbstractDomainEvent.Phase#EXECUTED} phase.
+ * </p>
*/
public void setReturnValue(final Object returnValue) {
this.returnValue = returnValue;
}
/**
- * Not API - set by the framework.
+ * @apiNote : NOT API, set by the framework
*/
public void setSemantics(SemanticsOf semantics) {
this.semantics = semantics;
}
/**
- * Not API - set by the framework.
+ * @apiNote : NOT API, set by the framework
*/
public void setParameterNames(final List<String> parameterNames) {
this.parameterNames = parameterNames;
}
/**
- * Not API - set by the framework.
+ * @apiNote : NOT API, set by the framework
*/
public void setParameterTypes(final List<Class<?>> parameterTypes) {
this.parameterTypes = parameterTypes;
}
/**
- * Not API - set by the framework.
+ * @apiNote : NOT API, set by the framework
*/
@Override
public void setMixedIn(final Object mixedIn) {
diff --git a/api/applib/src/main/java/org/apache/isis/applib/events/domain/CollectionDomainEvent.java b/api/applib/src/main/java/org/apache/isis/applib/events/domain/CollectionDomainEvent.java
index 8b843e6..6d4c57c 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/events/domain/CollectionDomainEvent.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/events/domain/CollectionDomainEvent.java
@@ -24,37 +24,59 @@ import org.apache.isis.applib.util.ToString;
import lombok.Getter;
/**
+ * Subclass of {@link AbstractDomainEvent} for collections.
+ *
+ * <p>
+ * The class has a couple of responsibilities (in addition to those it
+ * inherits):
+ * </p>
+ *
+ * <ul>
+ * <li>
+ * capture the target object being interacted with
+ * </li>
+ * </ul>
+ *
+ * <p>
+ * The class itself is instantiated automatically by the framework whenever
+ * interacting with a rendered object's collection.
+ * </p>
+ *
* @since 1.x {@index}
*/
public abstract class CollectionDomainEvent<S,T> extends AbstractDomainEvent<S> {
/**
* This class is the default for the
- * {@link org.apache.isis.applib.annotation.Collection#domainEvent()} annotation attribute. Whether this
- * raises an event or not depends upon the <tt>isis.core.meta-model.annotation.collection.domain-event.post-for-default</tt>
+ * {@link org.apache.isis.applib.annotation.Collection#domainEvent()}
+ * annotation attribute.
+ *
+ * <p>
+ * Whether this raises an event or not depends upon the
+ * <tt>isis.core.meta-model.annotation.collection.domain-event.post-for-default</tt>
* configuration property.
+ * </p>
*/
public static class Default extends CollectionDomainEvent<Object, 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 CollectionDomainEvent<Object, 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 CollectionDomainEvent<Object, Object> {}
/**
- * If used then the framework will set state via (non-API) setters.
- *
- * <p>
- * Recommended because it reduces the amount of boilerplate in the domain object classes.
- * </p>
+ * Subtypes can define a no-arg constructor; the framework sets state
+ * via (non-API) setters.
*/
public CollectionDomainEvent() {
}
@@ -62,10 +84,10 @@ public abstract class CollectionDomainEvent<S,T> extends AbstractDomainEvent<S>
/**
- * The proposed reference to either add or remove (per {@link #getOf()}), populated at
+ * The proposed reference to either add or remove (per {@link #getOf()}), populated at
* {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#VALIDATE}
- * and subsequent phases (is null for
- * {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#HIDE hidden}
+ * and subsequent phases (is null for
+ * {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#HIDE hidden}
* and {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#DISABLE disable} phases).
*/
@Getter
@@ -105,7 +127,7 @@ public abstract class CollectionDomainEvent<S,T> extends AbstractDomainEvent<S>
this.value = value;
}
/**
- * Not API; updates from {@link Of#ACCESS} to either {@link Of#ADD_TO}
+ * Not API; updates from {@link Of#ACCESS} to either {@link Of#ADD_TO}
* or {@link Of#REMOVE_FROM} when hits the
* {@link AbstractDomainEvent.Phase#VALIDATE validation phase}.
*/
diff --git a/api/applib/src/main/java/org/apache/isis/applib/events/domain/PropertyDomainEvent.java b/api/applib/src/main/java/org/apache/isis/applib/events/domain/PropertyDomainEvent.java
index 43c390f..2801a66 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/events/domain/PropertyDomainEvent.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/events/domain/PropertyDomainEvent.java
@@ -50,11 +50,8 @@ public abstract class PropertyDomainEvent<S,T> extends AbstractDomainEvent<S> {
public static class Doop extends PropertyDomainEvent<Object, Object> {}
/**
- * If used then the framework will set state via (non-API) setters.
- *
- * <p>
- * Recommended because it reduces the amount of boilerplate in the domain object classes.
- * </p>
+ * Subtypes can define a no-arg constructor; the framework sets state
+ * via (non-API) setters.
*/
public PropertyDomainEvent() {
}
diff --git a/legacy/extensions/core/metamodel/src/main/adoc/modules/metamodel/pages/about.adoc b/legacy/extensions/core/metamodel/src/main/adoc/modules/metamodel/pages/about.adoc
index 8c28ea0..1bf059a 100644
--- a/legacy/extensions/core/metamodel/src/main/adoc/modules/metamodel/pages/about.adoc
+++ b/legacy/extensions/core/metamodel/src/main/adoc/modules/metamodel/pages/about.adoc
@@ -2,5 +2,5 @@
: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 [...]
-WARNING: TODO: v2: placeholder for documentation about legacy/metamodel
+WARNING: TODO: v2: to document
diff --git a/persistence/jpa/adoc/modules/ROOT/pages/about.adoc b/persistence/jpa/adoc/modules/ROOT/pages/about.adoc
index ecb2a85..b977118 100644
--- a/persistence/jpa/adoc/modules/ROOT/pages/about.adoc
+++ b/persistence/jpa/adoc/modules/ROOT/pages/about.adoc
@@ -4,5 +4,5 @@
:page-toc: ~
-WARNING: TODO: v2 - in development.
+WARNING: TODO: v2 - to document.
diff --git a/security/adoc/modules/ROOT/pages/about.adoc b/security/adoc/modules/ROOT/pages/about.adoc
index 0905a6b..b48aa37 100644
--- a/security/adoc/modules/ROOT/pages/about.adoc
+++ b/security/adoc/modules/ROOT/pages/about.adoc
@@ -70,11 +70,11 @@ The framework provides a "bypass" implementation, useful for quick-n-dirty proto
=== KeyCloak
-WARNING: TODO: v2 - not yet documented.
+WARNING: TODO: v2 - to document.
=== Spring
-WARNING: TODO: v2 - WIP, not yet documented.
+WARNING: TODO: v2 - WIP, to document
== SecMan
diff --git a/testing/adoc/modules/ROOT/pages/about.adoc b/testing/adoc/modules/ROOT/pages/about.adoc
index 6c3897e..a1074c0 100644
--- a/testing/adoc/modules/ROOT/pages/about.adoc
+++ b/testing/adoc/modules/ROOT/pages/about.adoc
@@ -131,12 +131,10 @@ Apache Isis provides the xref:testing:fakedata:about.adoc[Fake Data] library to
Using fake data works very well with fixture scripts; the fixture script can invoke the business action with sensible (fake/random) defaults, and only require that the essential information is passed into it by the test.
====
-
== Feature Toggles
Writing automated tests is just good development practice.
-Also good practice is developing on the mainline (master, trunk); so that your continuous integration system really is integrating all code.
-Said another way: link:http://martinfowler.com/bliki/FeatureBranch.html[don't use branches]!
+Also good practice is developing on the mainline (main, trunk); so that your continuous integration system really is integrating all code.
Sometimes, though, a feature will take longer to implement than your iteration cycle.
In such a case, how do you use continuous integration to keep everyone working on the mainline without revealing a half-implemented feature on your releases?