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 2020/03/17 17:27:06 UTC
[isis] 04/07: ISIS-2062: docs for annotations
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/isis.git
commit 08433253281900f55cda8648e50a8626dd6cb1ff
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Tue Mar 17 12:47:18 2020 +0000
ISIS-2062: docs for annotations
---
.../programming-model/view-models/non-jaxb.adoc | 2 +-
.../applib-ant/examples/annotation/Action.java | 161 +++++++++++----------
.../examples/annotation/ActionLayout.java | 66 +++++----
.../applib-ant/examples/annotation/Collection.java | 30 ++--
.../examples/annotation/CollectionLayout.java | 36 +++--
.../examples/annotation/CommandReification.java | 5 -
.../examples/annotation/DomainObject.java | 156 +++++++++++++-------
.../examples/annotation/DomainObjectLayout.java | 126 +++++++++-------
.../main/adoc/modules/applib-ant/pages/Action.adoc | 124 ++++++----------
.../modules/applib-ant/pages/Action/command.adoc | 4 +-
.../modules/applib-ant/pages/ActionLayout.adoc | 85 ++++-------
.../adoc/modules/applib-ant/pages/Collection.adoc | 70 +++------
...notPersisted.adoc => mementoSerialization.adoc} | 34 +----
.../modules/applib-ant/pages/CollectionLayout.adoc | 100 ++++---------
.../main/adoc/modules/applib-ant/pages/Column.adoc | 38 ++---
.../modules/applib-ant/pages/Discriminator.adoc | 24 ++-
.../modules/applib-ant/pages/DomainObject.adoc | 157 ++++++++++----------
.../applib-ant/pages/DomainObjectLayout.adoc | 23 ++-
.../modules/applib-ant/pages/DomainService.adoc | 16 +-
.../applib-ant/pages/DomainServiceLayout.adoc | 19 +--
.../main/adoc/modules/applib-ant/pages/Facets.adoc | 4 +-
.../adoc/modules/applib-ant/pages/HomePage.adoc | 3 +-
.../main/adoc/modules/applib-ant/pages/Inject.adoc | 27 +---
.../applib-ant/pages/MemberGroupLayout.adoc | 17 ---
.../adoc/modules/applib-ant/pages/MemberOrder.adoc | 5 +-
.../adoc/modules/applib-ant/pages/MinLength.adoc | 4 +
.../main/adoc/modules/applib-ant/pages/Mixin.adoc | 7 +-
.../modules/applib-ant/pages/NotPersistent.adoc | 6 +-
.../adoc/modules/applib-ant/pages/Nullable.adoc | 18 +--
.../adoc/modules/applib-ant/pages/Parameter.adoc | 14 +-
.../modules/applib-ant/pages/ParameterLayout.adoc | 5 +
.../applib-ant/pages/PersistenceCapable.adoc | 25 ++--
.../adoc/modules/applib-ant/pages/PreDestroy.adoc | 2 +-
.../modules/applib-ant/pages/Programmatic.adoc | 4 +-
.../adoc/modules/applib-ant/pages/Property.adoc | 8 +-
...notPersisted.adoc => mementoSerialization.adoc} | 38 +----
.../modules/applib-ant/pages/PropertyLayout.adoc | 5 +
.../main/adoc/modules/applib-ant/pages/Title.adoc | 12 +-
.../adoc/modules/applib-ant/pages/ViewModel.adoc | 10 +-
.../modules/applib-ant/pages/ViewModelLayout.adoc | 22 +--
.../applib-ant/pages/XmlJavaTypeAdapter.adoc | 3 +-
.../modules/applib-ant/pages/XmlRootElement.adoc | 6 +-
.../modules/applib-ant/partials/module-nav.adoc | 1 -
.../modules/applib-svc/pages/LayoutService.adoc | 6 +-
44 files changed, 704 insertions(+), 824 deletions(-)
diff --git a/api/adoc/userguide/modules/fun/pages/programming-model/view-models/non-jaxb.adoc b/api/adoc/userguide/modules/fun/pages/programming-model/view-models/non-jaxb.adoc
index 95a6c0b..4133484 100644
--- a/api/adoc/userguide/modules/fun/pages/programming-model/view-models/non-jaxb.adoc
+++ b/api/adoc/userguide/modules/fun/pages/programming-model/view-models/non-jaxb.adoc
@@ -32,7 +32,7 @@ They are:
@DomainObject(nature=Nature.EXTERNAL_ENTITY)
public class CustomerRecordOnSAP { /* ... */ }
----
-|Annotated with xref:refguide:applib-ant:DomainObject.adoc#nature[`@DomainObject#nature`] and a nature of `EXTERNAL_ENTITY`, with memento derived automatically from the properties of the domain object. Collections are ignored, as are any properties annotated as xref:refguide:applib-ant:Property.adoc#notPersisted[not persisted].
+|Annotated with xref:refguide:applib-ant:DomainObject.adoc#nature[`@DomainObject#nature`] and a nature of `EXTERNAL_ENTITY`, with memento derived automatically from the properties of the domain object. Collections are ignored, as are any properties annotated as xref:refguide:applib-ant:Property.adoc#mementoSerialization[memento serialization].
| In-memory entity
|[source,java]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Action.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Action.java
index 4549519..f7968c2 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Action.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Action.java
@@ -50,62 +50,52 @@ public @interface Action {
// end::refguide[]
/**
- * Indicates that an invocation of the action should be posted to the
- * {@link org.apache.isis.applib.services.eventbus.EventBusService event bus} using a custom (subclass of)
- * {@link org.apache.isis.applib.events.domain.ActionDomainEvent}.
+ * Associates this action with a property or collection, specifying its id.
*
- * <p>For example:
+ * <p>
+ * This is an alternative to using {@link MemberOrder#name()}. To specify the order (equivalent to
+ * {@link MemberOrder#sequence()}}), use {@link #associateWithSequence()}.
* </p>
*
- * <pre>
- * public class SomeObject{
- * public static class ChangeStartDateDomainEvent extends ActionDomainEvent<SomeObject> { ... }
- *
- * @Action(domainEvent=ChangedStartDateDomainEvent.class)
- * public void changeStartDate(final Date startDate) { ...}
- * ...
- * }
- * </pre>
+ * <p>
+ * For example <code>@Action(associateWith="items", associateWithSequence="2.1")</code>
+ * </p>
*
* <p>
- * This subclass must provide a no-arg constructor; the fields are set reflectively.
+ * If an action is associated with a collection, then any matching parameters will have
+ * their choices automatically inferred from the collection (if not otherwise specified)
+ * and any collection parameter defaults can be specified using checkboxes
+ * (in the Wicket UI, at least).
* </p>
*/
// tag::refguide[]
- Class<? extends ActionDomainEvent<?>> domainEvent() default ActionDomainEvent.Default.class;
+ String associateWith() <.>
+ default "";
// end::refguide[]
/**
- * Indicates where (in the UI) the action is not visible to the user.
+ * Specifies the sequence/order in the UI for an action that's been associated with a property or collection.
*
* <p>
- * It is also possible to suppress an action's visibility using {@link ActionLayout#hidden()}.
+ * This is an alternative to using {@link MemberOrder#sequence()}, but is ignored if
+ * {@link Action#associateWith()} isn't also specified.
* </p>
*
* <p>
- * For {@link DomainService domain service} actions, the action's visibility is dependent upon its
- * {@link DomainService#nature() nature} and for contributed actions on how it is
- * {@link ActionLayout#contributed()}.
+ * For example <code>@Action(associateWith="items", associateWithSequence="2.1")</code>
* </p>
*/
// tag::refguide[]
- Where hidden() default Where.NOT_SPECIFIED;
-
- // end::refguide[]
- /**
- * The action semantics, either {@link SemanticsOf#SAFE_AND_REQUEST_CACHEABLE cached}, {@link SemanticsOf#SAFE safe} (query-only),
- * {@link SemanticsOf#IDEMPOTENT idempotent} or
- * {@link SemanticsOf#NON_IDEMPOTENT non-idempotent}.
- */
- // tag::refguide[]
- SemanticsOf semantics() default SemanticsOf.NOT_SPECIFIED;
+ String associateWithSequence() <.>
+ default "1";
// end::refguide[]
/**
* Whether the action invocation should be reified into a {@link org.apache.isis.applib.services.command.Command} object.
*/
// tag::refguide[]
- CommandReification command() default CommandReification.NOT_SPECIFIED;
+ CommandReification command() <.>
+ default CommandReification.NOT_SPECIFIED;
// end::refguide[]
/**
@@ -113,7 +103,8 @@ public @interface Action {
* {@link org.apache.isis.applib.services.command.CommandContext CommandContext} domain service should be persisted.
*/
// tag::refguide[]
- CommandPersistence commandPersistence() default CommandPersistence.PERSISTED;
+ CommandPersistence commandPersistence() <.>
+ default CommandPersistence.PERSISTED;
// end::refguide[]
/**
@@ -126,7 +117,8 @@ public @interface Action {
* </p>
*/
// tag::refguide[]
- CommandExecuteIn commandExecuteIn() default CommandExecuteIn.FOREGROUND;
+ CommandExecuteIn commandExecuteIn() <.>
+ default CommandExecuteIn.FOREGROUND;
// end::refguide[]
/**
@@ -144,90 +136,111 @@ public @interface Action {
* </p>
*/
// tag::refguide[]
- Class<? extends CommandDtoProcessor> commandDtoProcessor() default CommandDtoProcessor.class;
+ Class<? extends CommandDtoProcessor> commandDtoProcessor() <.>
+ default CommandDtoProcessor.class;
// end::refguide[]
/**
- * Whether the action invocation should be published.
+ * Indicates that an invocation of the action should be posted to the
+ * {@link org.apache.isis.applib.services.eventbus.EventBusService event bus} using a custom (subclass of)
+ * {@link org.apache.isis.applib.events.domain.ActionDomainEvent}.
+ *
+ * <p>For example:
+ * </p>
+ *
+ * <pre>
+ * public class SomeObject{
+ * public static class ChangeStartDateDomainEvent extends ActionDomainEvent<SomeObject> { ... }
+ *
+ * @Action(domainEvent=ChangedStartDateDomainEvent.class)
+ * public void changeStartDate(final Date startDate) { ...}
+ * ...
+ * }
+ * </pre>
*
* <p>
- * Requires that an implementation of the {@link org.apache.isis.applib.services.publish.PublisherService}
- * or {@link org.apache.isis.applib.services.publish.PublisherService} is registered with the framework.
+ * This subclass must provide a no-arg constructor; the fields are set reflectively.
* </p>
*/
// tag::refguide[]
- Publishing publishing() default Publishing.NOT_SPECIFIED;
-
- // end::refguide[]
- /**
- * The type-of the elements returned by the action.
- * @return
- */
- // tag::refguide[]
- Class<?> typeOf() default Object.class;
+ Class<? extends ActionDomainEvent<?>> domainEvent() <.>
+ default ActionDomainEvent.Default.class;
// end::refguide[]
/**
- * Whether the action is restricted to prototyping.
+ * For uploading {@link Blob} or {@link Clob}, optionally restrict the files accepted (eg <tt>.xslx</tt>).
*
* <p>
- * By default there are no restrictions, with the action being available in all environments.
+ * The value should be of the form "file_extension|audio/*|video/*|image/*|media_type".
* </p>
+ *
+ * @see <a href="http://www.w3schools.com/tags/att_input_accept.asp">http://www.w3schools.com</a>
*/
// tag::refguide[]
- RestrictTo restrictTo() default RestrictTo.NOT_SPECIFIED;
+ String fileAccept() <.>
+ default "";
// end::refguide[]
/**
- * Associates this action with a property or collection, specifying its id.
- *
- * <p>
- * This is an alternative to using {@link MemberOrder#name()}. To specify the order (equivalent to
- * {@link MemberOrder#sequence()}}), use {@link #associateWithSequence()}.
- * </p>
+ * Indicates where (in the UI) the action is not visible to the user.
*
* <p>
- * For example <code>@Action(associateWith="items", associateWithSequence="2.1")</code>
+ * It is also possible to suppress an action's visibility using {@link ActionLayout#hidden()}.
* </p>
*
* <p>
- * If an action is associated with a collection, then any matching parameters will have
- * their choices automatically inferred from the collection (if not otherwise specified)
- * and any collection parameter defaults can be specified using checkboxes
- * (in the Wicket UI, at least).
+ * For {@link DomainService domain service} actions, the action's visibility is dependent upon its
+ * {@link DomainService#nature() nature} and for contributed actions on how it is
+ * {@link ActionLayout#contributed()}.
* </p>
*/
// tag::refguide[]
- String associateWith() default "";
+ Where hidden() <.>
+ default Where.NOT_SPECIFIED;
// end::refguide[]
/**
- * Specifies the sequence/order in the UI for an action that's been associated with a property or collection.
- *
- * <p>
- * This is an alternative to using {@link MemberOrder#sequence()}, but is ignored if
- * {@link Action#associateWith()} isn't also specified.
- * </p>
+ * Whether the action invocation should be published.
*
* <p>
- * For example <code>@Action(associateWith="items", associateWithSequence="2.1")</code>
+ * Requires that an implementation of the {@link org.apache.isis.applib.services.publish.PublisherService}
+ * or {@link org.apache.isis.applib.services.publish.PublisherService} is registered with the framework.
* </p>
*/
// tag::refguide[]
- String associateWithSequence() default "1";
+ Publishing publishing() <.>
+ default Publishing.NOT_SPECIFIED;
// end::refguide[]
/**
- * For uploading {@link Blob} or {@link Clob}, optionally restrict the files accepted (eg <tt>.xslx</tt>).
+ * Whether the action is restricted to prototyping.
*
* <p>
- * The value should be of the form "file_extension|audio/*|video/*|image/*|media_type".
+ * By default there are no restrictions, with the action being available in all environments.
* </p>
- *
- * @see <a href="http://www.w3schools.com/tags/att_input_accept.asp">http://www.w3schools.com</a>
*/
// tag::refguide[]
- String fileAccept() default "";
+ RestrictTo restrictTo() <.>
+ default RestrictTo.NOT_SPECIFIED;
+
+ // end::refguide[]
+ /**
+ * The action semantics, either {@link SemanticsOf#SAFE_AND_REQUEST_CACHEABLE cached}, {@link SemanticsOf#SAFE safe} (query-only),
+ * {@link SemanticsOf#IDEMPOTENT idempotent} or
+ * {@link SemanticsOf#NON_IDEMPOTENT non-idempotent}.
+ */
+ // tag::refguide[]
+ SemanticsOf semantics() <.>
+ default SemanticsOf.NOT_SPECIFIED;
+
+ // end::refguide[]
+ /**
+ * The type-of the elements returned by the action.
+ * @return
+ */
+ // tag::refguide[]
+ Class<?> typeOf() <.>
+ default Object.class;
}
// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/ActionLayout.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/ActionLayout.java
index 8a6f370..f488a72 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/ActionLayout.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/ActionLayout.java
@@ -54,10 +54,27 @@ public @interface ActionLayout {
* </p>
*/
// tag::refguide[]
- BookmarkPolicy bookmarking() default BookmarkPolicy.NOT_SPECIFIED;
+ BookmarkPolicy bookmarking() <.>
+ default BookmarkPolicy.NOT_SPECIFIED;
// end::refguide[]
/**
+ * For actions of domain services that can be viewed and contributed (that is, whose
+ * {@link DomainService#nature() nature} is either {@link org.apache.isis.applib.annotation.NatureOfService#VIEW}
+ * or {@link org.apache.isis.applib.annotation.NatureOfService#VIEW_CONTRIBUTIONS_ONLY}), specifies how the
+ * contribution should be implemented, as an action, as an association, or as both.
+ *
+ * <p>
+ * Has no meaning for actions of domain entities.
+ * </p>
+ */
+ @Deprecated
+ Contributed contributed() <.>
+ default Contributed.NOT_SPECIFIED;
+
+ // tag::refguide[]
+ // end::refguide[]
+ /**
* Indicates the css class that an action should have.
*
* <p>
@@ -65,7 +82,8 @@ public @interface ActionLayout {
* </p>
*/
// tag::refguide[]
- String cssClass() default "";
+ String cssClass() <.>
+ default "";
// end::refguide[]
/**
@@ -73,7 +91,8 @@ public @interface ActionLayout {
* action (button or menu item).
*/
// tag::refguide[]
- String cssClassFa() default "";
+ String cssClassFa() <.>
+ default "";
// end::refguide[]
/**
@@ -81,28 +100,32 @@ public @interface ActionLayout {
* icon. The icon could be rendered on the left or the right of the action button
*/
// tag::refguide[]
- CssClassFaPosition cssClassFaPosition() default CssClassFaPosition.LEFT;
+ CssClassFaPosition cssClassFaPosition() <.>
+ default CssClassFaPosition.LEFT;
// end::refguide[]
/**
* Description of this action, eg to be rendered in a tooltip.
*/
// tag::refguide[]
- String describedAs() default "";
+ String describedAs() <.>
+ default "";
// end::refguide[]
/**
* Indicates where in the UI the action should <i>not</i>not be visible.
*/
// tag::refguide[]
- Where hidden() default Where.NOT_SPECIFIED;
+ Where hidden() <.>
+ default Where.NOT_SPECIFIED;
// end::refguide[]
/**
* Name of this action (overriding the name derived from its name in code).
*/
// tag::refguide[]
- String named() default "";
+ String named() <.>
+ default "";
// end::refguide[]
/**
@@ -114,11 +137,11 @@ public @interface ActionLayout {
* </p>
*/
// tag::refguide[]
- Position position() default Position.NOT_SPECIFIED;
+ Position position() <.>
+ default Position.NOT_SPECIFIED;
- @XmlType(
- namespace = "http://isis.apache.org/applib/layout/component"
- )
+ // end::refguide[]
+ @XmlType(namespace = "http://isis.apache.org/applib/layout/component")
enum Position {
BELOW,
RIGHT,
@@ -127,12 +150,12 @@ public @interface ActionLayout {
NOT_SPECIFIED
}
- // end::refguide[]
/**
* How this parameters for this action are prompted, either {@link PromptStyle#DIALOG dialog} or {@link PromptStyle#INLINE inline}.
*/
// tag::refguide[]
- PromptStyle promptStyle() default PromptStyle.AS_CONFIGURED;
+ PromptStyle promptStyle() <.>
+ default PromptStyle.AS_CONFIGURED;
// end::refguide[]
/**
@@ -140,21 +163,8 @@ public @interface ActionLayout {
* instead to redirect (forcing a re-rendering of a new page).
*/
// tag::refguide[]
- Redirect redirectPolicy() default Redirect.AS_CONFIGURED;
-
- // end::refguide[]
- /**
- * For actions of domain services that can be viewed and contributed (that is, whose
- * {@link DomainService#nature() nature} is either {@link org.apache.isis.applib.annotation.NatureOfService#VIEW}
- * or {@link org.apache.isis.applib.annotation.NatureOfService#VIEW_CONTRIBUTIONS_ONLY}), specifies how the
- * contribution should be implemented, as an action, as an association, or as both.
- *
- * <p>
- * Has no meaning for actions of domain entities.
- * </p>
- */
- // tag::refguide[]
- Contributed contributed() default Contributed.NOT_SPECIFIED;
+ Redirect redirectPolicy() <.>
+ default Redirect.AS_CONFIGURED;
}
// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Collection.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Collection.java
index 38a7d19..28fdd31 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Collection.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Collection.java
@@ -64,14 +64,8 @@ public @interface Collection {
* </p>
*/
// tag::refguide[]
- Class<? extends CollectionDomainEvent<?,?>> domainEvent() default CollectionDomainEvent.Default.class;
-
- // end::refguide[]
- /**
- * Indicates when the collection is not visible to the user.
- */
- // tag::refguide[]
- Where hidden() default Where.NOT_SPECIFIED;
+ Class<? extends CollectionDomainEvent<?,?>> domainEvent() // <.>
+ default CollectionDomainEvent.Default.class;
// end::refguide[]
/**
@@ -82,7 +76,8 @@ public @interface Collection {
* </p>
*/
// tag::refguide[]
- Editing editing() default Editing.NOT_SPECIFIED;
+ Editing editing() // <.>
+ default Editing.NOT_SPECIFIED;
// end::refguide[]
/**
@@ -90,7 +85,16 @@ public @interface Collection {
* then the reason to provide to the user as to why this property cannot be edited.
*/
// tag::refguide[]
- String editingDisabledReason() default "";
+ String editingDisabledReason() // <.>
+ default "";
+
+ // end::refguide[]
+ /**
+ * Indicates when the collection is not visible to the user.
+ */
+ // tag::refguide[]
+ Where hidden() // <.>
+ default Where.NOT_SPECIFIED;
// end::refguide[]
/**
@@ -102,7 +106,8 @@ public @interface Collection {
* </p>
*/
// tag::refguide[]
- MementoSerialization mementoSerialization() default MementoSerialization.NOT_SPECIFIED;
+ MementoSerialization mementoSerialization() // <.>
+ default MementoSerialization.NOT_SPECIFIED;
// end::refguide[]
/**
@@ -111,7 +116,8 @@ public @interface Collection {
* @return
*/
// tag::refguide[]
- Class<?> typeOf() default Object.class;
+ Class<?> typeOf() // <.>
+ default Object.class;
}
// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/CollectionLayout.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/CollectionLayout.java
index c061cbb..fe1512b 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/CollectionLayout.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/CollectionLayout.java
@@ -46,14 +46,8 @@ public @interface CollectionLayout {
* Indicates the css class that a collection should have.
*/
// tag::refguide[]
- String cssClass() default "";
-
- // end::refguide[]
- /**
- * Description of this collection, eg to be rendered in a tooltip.
- */
- // tag::refguide[]
- String describedAs() default "";
+ String cssClass() // <.>
+ default "";
// end::refguide[]
/**
@@ -68,7 +62,16 @@ public @interface CollectionLayout {
* </p>
*/
// tag::refguide[]
- String defaultView() default "";
+ String defaultView() // <.>
+ default "";
+
+ // end::refguide[]
+ /**
+ * Description of this collection, eg to be rendered in a tooltip.
+ */
+ // tag::refguide[]
+ String describedAs() // <.>
+ default "";
// end::refguide[]
/**
@@ -80,21 +83,24 @@ public @interface CollectionLayout {
* </p>
*/
// tag::refguide[]
- Where hidden() default Where.NOT_SPECIFIED;
+ Where hidden() // <.>
+ default Where.NOT_SPECIFIED;
// end::refguide[]
/**
* Name of this collection (overriding the name derived from its name in code).
*/
// tag::refguide[]
- String named() default "";
+ String named() // <.>
+ default "";
// end::refguide[]
/**
* A flag indicating whether the value of {@linkplain #named()} should be HTML escaped or not.
*/
// tag::refguide[]
- boolean namedEscaped() default true;
+ boolean namedEscaped() // <.>
+ default true;
// end::refguide[]
/**
@@ -110,7 +116,8 @@ public @interface CollectionLayout {
* collections (eg as returned from a repository query).
*/
// tag::refguide[]
- int paged() default -1;
+ int paged() // <.>
+ default -1;
// end::refguide[]
/**
@@ -133,7 +140,8 @@ public @interface CollectionLayout {
*/
@SuppressWarnings("rawtypes")
// tag::refguide[]
- Class sortedBy() default Comparator.class;
+ Class sortedBy() // <.>
+ default Comparator.class;
}
// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/CommandReification.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/CommandReification.java
index 32bef90..a2b8b68 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/CommandReification.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/CommandReification.java
@@ -23,7 +23,6 @@ package org.apache.isis.applib.annotation;
*/
// tag::refguide[]
public enum CommandReification {
-
// end::refguide[]
/**
* Whether the action should be handled as a command as per the default command configured in <tt>applicationp.properties</tt>.
@@ -34,21 +33,18 @@ public enum CommandReification {
*/
// tag::refguide[]
AS_CONFIGURED,
-
// end::refguide[]
/**
* Handle the action as a command, irrespective of any configuration settings.
*/
// tag::refguide[]
ENABLED,
-
// end::refguide[]
/**
* Do not handle the action as a command, irrespective of any configuration settings.
*/
// tag::refguide[]
DISABLED,
-
// end::refguide[]
/**
* Ignore the value provided by this annotation (meaning that the framework will keep searching, in meta
@@ -56,6 +52,5 @@ public enum CommandReification {
*/
// tag::refguide[]
NOT_SPECIFIED
-
}
// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/DomainObject.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/DomainObject.java
index 66ece7f..b38efb7 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/DomainObject.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/DomainObject.java
@@ -53,9 +53,15 @@ import org.apache.isis.applib.events.lifecycle.ObjectUpdatingEvent;
})
@Retention(RetentionPolicy.RUNTIME)
@Component @Scope("prototype")
+// tag::refguide-lifecycle-events[]
+// tag::refguide-domain-events[]
public @interface DomainObject {
// end::refguide[]
+ // ...
+
+ // end::refguide-lifecycle-events[]
+ // end::refguide-domain-events[]
/**
* Whether the entity should be audited (note: does not apply to view models or other recreatable objects.
*
@@ -65,19 +71,8 @@ public @interface DomainObject {
* </p>
*/
// tag::refguide[]
- Auditing auditing() default Auditing.NOT_SPECIFIED;
-
- // end::refguide[]
- /**
- * Whether changes to the object should be published.
- *
- * <p>
- * Requires that an implementation of the {@link org.apache.isis.applib.services.publish.PublisherService} is
- * registered with the framework.
- * </p>
- */
- // tag::refguide[]
- Publishing publishing() default Publishing.NOT_SPECIFIED;
+ Auditing auditing() // <.>
+ default Auditing.NOT_SPECIFIED;
// end::refguide[]
/**
@@ -87,7 +82,8 @@ public @interface DomainObject {
* It is sufficient to specify an interface rather than a concrete type.
*/
// tag::refguide[]
- Class<?> autoCompleteRepository() default Object.class;
+ Class<?> autoCompleteRepository() // <.>
+ default Object.class;
// end::refguide[]
/**
@@ -98,7 +94,8 @@ public @interface DomainObject {
* The method is required to accept a single string parameter, and must return a list of the domain type.
*/
// tag::refguide[]
- String autoCompleteAction() default "autoComplete";
+ String autoCompleteAction() // <.>
+ default "autoComplete";
// end::refguide[]
/**
@@ -114,7 +111,8 @@ public @interface DomainObject {
*
*/
// tag::refguide[]
- Bounding bounding() default Bounding.NOT_SPECIFIED;
+ Bounding bounding() // <.>
+ default Bounding.NOT_SPECIFIED;
// end::refguide[]
/**
@@ -125,7 +123,8 @@ public @interface DomainObject {
* </p>
*/
// tag::refguide[]
- Editing editing() default Editing.NOT_SPECIFIED;
+ Editing editing() // <.>
+ default Editing.NOT_SPECIFIED;
// end::refguide[]
/**
@@ -133,39 +132,57 @@ public @interface DomainObject {
* then the reason to provide to the user as to why the object's properties cannot be edited/collections modified.
*/
// tag::refguide[]
- String editingDisabledReason() default "Disabled";
+ String editingDisabledReason() // <.>
+ default "Disabled";
// end::refguide[]
/**
- * Provides a unique abbreviation for the object type, eg "customer.Customer" for Customer.
+ * Equivalent to {@link Mixin#method()}.
*
* <p>
- * This value, if specified, is used in the serialized form of the object's OID. An OID is
- * used by the framework to unique identify an object over time (same concept as a URN).
+ * Applicable only if {@link #nature()} is {@link Nature#MIXIN}.
* </p>
*/
// tag::refguide[]
- String objectType() default "";
+ String mixinMethod() // <.>
+ default Mixin.DEFAULT_METHOD_NAME;
// end::refguide[]
/**
* The nature of this domain object.
*/
// tag::refguide[]
- Nature nature() default Nature.NOT_SPECIFIED;
+ Nature nature() // <.>
+ default Nature.NOT_SPECIFIED;
// end::refguide[]
/**
- * Equivalent to {@link Mixin#method()}.
+ * Provides a unique abbreviation for the object type, eg "customer.Customer" for Customer.
*
* <p>
- * Applicable only if {@link #nature()} is {@link Nature#MIXIN}.
+ * This value, if specified, is used in the serialized form of the object's OID. An OID is
+ * used by the framework to unique identify an object over time (same concept as a URN).
+ * </p>
+ */
+ // tag::refguide[]
+ String objectType() // <.>
+ default "";
+
+ // end::refguide[]
+ /**
+ * Whether changes to the object should be published.
+ *
+ * <p>
+ * Requires that an implementation of the {@link org.apache.isis.applib.services.publish.PublisherService} is
+ * registered with the framework.
* </p>
*/
// tag::refguide[]
- String mixinMethod() default Mixin.DEFAULT_METHOD_NAME;
+ Publishing publishing() // <.>
+ default Publishing.NOT_SPECIFIED;
// end::refguide[]
+
/**
* Indicates that the loading of the domain object should be posted to the
* {@link org.apache.isis.applib.services.eventbus.EventBusService event bus} using a custom (subclass of)
@@ -175,10 +192,12 @@ public @interface DomainObject {
* This subclass must provide a no-arg constructor; the fields are set reflectively.
* </p>
*/
- // tag::refguide[]
- Class<? extends ObjectCreatedEvent<?>> createdLifecycleEvent() default ObjectCreatedEvent.Default.class;
+ // tag::refguide-lifecycle-events[]
+ Class<? extends ObjectCreatedEvent<?>>
+ createdLifecycleEvent() // <.>
+ default ObjectCreatedEvent.Default.class;
- // end::refguide[]
+ // end::refguide-lifecycle-events[]
/**
* Indicates that the loading of the domain object should be posted to the
* {@link org.apache.isis.applib.services.eventbus.EventBusService event bus} using a custom (subclass of)
@@ -188,10 +207,12 @@ public @interface DomainObject {
* This subclass must provide a no-arg constructor; the fields are set reflectively.
* </p>
*/
- // tag::refguide[]
- Class<? extends ObjectPersistingEvent<?>> persistingLifecycleEvent() default ObjectPersistingEvent.Default.class;
+ // tag::refguide-lifecycle-events[]
+ Class<? extends ObjectPersistingEvent<?>>
+ persistingLifecycleEvent() // <.>
+ default ObjectPersistingEvent.Default.class;
- // end::refguide[]
+ // end::refguide-lifecycle-events[]
/**
* Indicates that the loading of the domain object should be posted to the
* {@link org.apache.isis.applib.services.eventbus.EventBusService event bus} using a custom (subclass of)
@@ -201,10 +222,12 @@ public @interface DomainObject {
* This subclass must provide a no-arg constructor; the fields are set reflectively.
* </p>
*/
- // tag::refguide[]
- Class<? extends ObjectPersistedEvent<?>> persistedLifecycleEvent() default ObjectPersistedEvent.Default.class;
+ // tag::refguide-lifecycle-events[]
+ Class<? extends ObjectPersistedEvent<?>>
+ persistedLifecycleEvent() // <.>
+ default ObjectPersistedEvent.Default.class;
- // end::refguide[]
+ // end::refguide-lifecycle-events[]
/**
* Indicates that the loading of the domain object should be posted to the
* {@link org.apache.isis.applib.services.eventbus.EventBusService event bus} using a custom (subclass of)
@@ -214,10 +237,12 @@ public @interface DomainObject {
* This subclass must provide a no-arg constructor; the fields are set reflectively.
* </p>
*/
- // tag::refguide[]
- Class<? extends ObjectLoadedEvent<?>> loadedLifecycleEvent() default ObjectLoadedEvent.Default.class;
+ // tag::refguide-lifecycle-events[]
+ Class<? extends ObjectLoadedEvent<?>>
+ loadedLifecycleEvent() // <.>
+ default ObjectLoadedEvent.Default.class;
- // end::refguide[]
+ // end::refguide-lifecycle-events[]
/**
* Indicates that the loading of the domain object should be posted to the
* {@link org.apache.isis.applib.services.eventbus.EventBusService event bus} using a custom (subclass of)
@@ -227,10 +252,12 @@ public @interface DomainObject {
* This subclass must provide a no-arg constructor; the fields are set reflectively.
* </p>
*/
- // tag::refguide[]
- Class<? extends ObjectUpdatingEvent<?>> updatingLifecycleEvent() default ObjectUpdatingEvent.Default.class;
+ // tag::refguide-lifecycle-events[]
+ Class<? extends ObjectUpdatingEvent<?>>
+ updatingLifecycleEvent() // <.>
+ default ObjectUpdatingEvent.Default.class;
- // end::refguide[]
+ // end::refguide-lifecycle-events[]
/**
* Indicates that the loading of the domain object should be posted to the
* {@link org.apache.isis.applib.services.eventbus.EventBusService event bus} using a custom (subclass of)
@@ -240,10 +267,12 @@ public @interface DomainObject {
* This subclass must provide a no-arg constructor; the fields are set reflectively.
* </p>
*/
- // tag::refguide[]
- Class<? extends ObjectUpdatedEvent<?>> updatedLifecycleEvent() default ObjectUpdatedEvent.Default.class;
+ // tag::refguide-lifecycle-events[]
+ Class<? extends ObjectUpdatedEvent<?>>
+ updatedLifecycleEvent() // <.>
+ default ObjectUpdatedEvent.Default.class;
- // end::refguide[]
+ // end::refguide-lifecycle-events[]
/**
* Indicates that the loading of the domain object should be posted to the
* {@link org.apache.isis.applib.services.eventbus.EventBusService event bus} using a custom (subclass of)
@@ -253,10 +282,12 @@ public @interface DomainObject {
* This subclass must provide a no-arg constructor; the fields are set reflectively.
* </p>
*/
- // tag::refguide[]
- Class<? extends ObjectRemovingEvent<?>> removingLifecycleEvent() default ObjectRemovingEvent.Default.class;
+ // tag::refguide-lifecycle-events[]
+ Class<? extends ObjectRemovingEvent<?>>
+ removingLifecycleEvent() // <.>
+ default ObjectRemovingEvent.Default.class;
- // end::refguide[]
+ // end::refguide-lifecycle-events[]
/**
* Indicates that an invocation of <i>any</i> action of the domain object (that do not themselves specify their own
* <tt>@Action(domainEvent=...)</tt> should be posted to the
@@ -284,10 +315,12 @@ public @interface DomainObject {
* It must also use <tt>Object</tt> as its generic type. This is to allow mixins to also emit the same event.
* </p>
*/
- // tag::refguide[]
- Class<? extends ActionDomainEvent<?>> actionDomainEvent() default ActionDomainEvent.Default.class;
+ // tag::refguide-domain-events[]
+ Class<? extends ActionDomainEvent<?>>
+ actionDomainEvent() // <.>
+ default ActionDomainEvent.Default.class;
- // end::refguide[]
+ // end::refguide-domain-events[]
/**
* Indicates that changes to <i>any</i> property of the domain object (that do not themselves specify their own
* <tt>@Property(domainEvent=...)</tt> should be posted to the
@@ -310,10 +343,12 @@ public @interface DomainObject {
* It must also use <tt>Object</tt> as its generic type. This is to allow mixins to also emit the same event.
* </p>
*/
- // tag::refguide[]
- Class<? extends PropertyDomainEvent<?,?>> propertyDomainEvent() default PropertyDomainEvent.Default.class;
+ // tag::refguide-domain-events[]
+ Class<? extends PropertyDomainEvent<?,?>>
+ propertyDomainEvent() // <.>
+ default PropertyDomainEvent.Default.class;
- // end::refguide[]
+ // end::refguide-domain-events[]
/**
* Indicates that changes to <i>any</i> collection of the domain object (that do not themselves specify their own
* <tt>@Collection(domainEvent=...)</tt> should be posted to the
@@ -335,8 +370,17 @@ public @interface DomainObject {
* It must also use <tt>Object</tt> as its generic type. This is to allow mixins to also emit the same event.
* </p>
*/
- // tag::refguide[]
- Class<? extends CollectionDomainEvent<?,?>> collectionDomainEvent() default CollectionDomainEvent.Default.class;
+ // tag::refguide-domain-events[]
+ Class<? extends CollectionDomainEvent<?,?>>
+ collectionDomainEvent() // <.>
+ default CollectionDomainEvent.Default.class;
+ // end::refguide-domain-events[]
+ // tag::refguide[]
+ // tag::refguide-lifecycle-events[]
+ // ...
+ // tag::refguide-domain-events[]
}
-// end::refguide[]
\ No newline at end of file
+// end::refguide[]
+// end::refguide-lifecycle-events[]
+// end::refguide-domain-events[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/DomainObjectLayout.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/DomainObjectLayout.java
index b1360a8..8913b92 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/DomainObjectLayout.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/DomainObjectLayout.java
@@ -41,58 +41,18 @@ import org.apache.isis.applib.layout.component.CssClassFaPosition;
ElementType.ANNOTATION_TYPE
})
@Retention(RetentionPolicy.RUNTIME)
+// tag::refguide-ui-events[]
public @interface DomainObjectLayout {
// end::refguide[]
- /**
- * Which subclass of {@link TitleUiEvent} should be used to obtain a title.
- *
- * <p>
- * This subclass must provide a no-arg constructor; the fields are set reflectively.
- * </p>
- */
- // tag::refguide[]
- Class<? extends TitleUiEvent<?>> titleUiEvent() default TitleUiEvent.Default.class;
-
- // end::refguide[]
- /**
- * Which subclass of {@link IconUiEvent} should be used to obtain an icon.
- *
- * <p>
- * This subclass must provide a no-arg constructor; the fields are set reflectively.
- * </p>
- */
- // tag::refguide[]
- Class<? extends IconUiEvent<?>> iconUiEvent() default IconUiEvent.Default.class;
-
- // end::refguide[]
- /**
- * Which subclass of {@link CssClassUiEvent} should be used to obtain a CSS class.
- *
- * <p>
- * This subclass must provide a no-arg constructor; the fields are set reflectively.
- * </p>
- */
- // tag::refguide[]
- Class<? extends CssClassUiEvent<?>> cssClassUiEvent() default CssClassUiEvent.Default.class;
-
- // end::refguide[]
- /**
- * Which subclass of {@link LayoutUiEvent} should be used to obtain a layout.
- *
- * <p>
- * This subclass must provide a no-arg constructor; the fields are set reflectively.
- * </p>
- */
- // tag::refguide[]
- Class<? extends LayoutUiEvent<?>> layoutUiEvent() default LayoutUiEvent.Default.class;
-
- // end::refguide[]
+ // ...
+ // end::refguide-ui-events[]
/**
* Indicates the css class that a domain class (type) should have.
*/
// tag::refguide[]
- String cssClass() default "";
+ String cssClass() // <.>
+ default "";
// end::refguide[]
/**
@@ -100,7 +60,8 @@ public @interface DomainObjectLayout {
* domain object.
*/
// tag::refguide[]
- String cssClassFa() default "";
+ String cssClassFa() // <.>
+ default "";
// end::refguide[]
/**
@@ -112,21 +73,24 @@ public @interface DomainObjectLayout {
* </p>
*/
// tag::refguide[]
- CssClassFaPosition cssClassFaPosition() default CssClassFaPosition.LEFT;
+ CssClassFaPosition cssClassFaPosition() // <.>
+ default CssClassFaPosition.LEFT;
// end::refguide[]
/**
* Description of this class, eg to be rendered in a tooltip.
*/
// tag::refguide[]
- String describedAs() default "";
+ String describedAs() // <.>
+ default "";
// end::refguide[]
/**
* Name of this class (overriding the name derived from its name in code).
*/
// tag::refguide[]
- String named() default "";
+ String named() // <.>
+ default "";
// end::refguide[]
/**
@@ -142,21 +106,79 @@ public @interface DomainObjectLayout {
* collections (eg as returned from a repository query).
*/
// tag::refguide[]
- int paged() default -1;
+ int paged() // <.>
+ default -1;
// end::refguide[]
/**
* The plural name of the class.
*/
// tag::refguide[]
- String plural() default "";
+ String plural() // <.>
+ default "";
// end::refguide[]
/**
* Whether (and how) this domain object can be bookmarked in the UI.
*/
// tag::refguide[]
- BookmarkPolicy bookmarking() default BookmarkPolicy.NOT_SPECIFIED;
+ BookmarkPolicy bookmarking() // <.>
+ default BookmarkPolicy.NOT_SPECIFIED;
+ // end::refguide[]
+ /**
+ * Which subclass of {@link TitleUiEvent} should be used to obtain a title.
+ *
+ * <p>
+ * This subclass must provide a no-arg constructor; the fields are set reflectively.
+ * </p>
+ */
+ // tag::refguide-ui-events[]
+ Class<? extends TitleUiEvent<?>>
+ titleUiEvent() // <.>
+ default TitleUiEvent.Default.class;
+
+ // end::refguide-ui-events[]
+ /**
+ * Which subclass of {@link IconUiEvent} should be used to obtain an icon.
+ *
+ * <p>
+ * This subclass must provide a no-arg constructor; the fields are set reflectively.
+ * </p>
+ */
+ // tag::refguide-ui-events[]
+ Class<? extends IconUiEvent<?>>
+ iconUiEvent() // <.>
+ default IconUiEvent.Default.class;
+
+ // end::refguide-ui-events[]
+ /**
+ * Which subclass of {@link CssClassUiEvent} should be used to obtain a CSS class.
+ *
+ * <p>
+ * This subclass must provide a no-arg constructor; the fields are set reflectively.
+ * </p>
+ */
+ // tag::refguide-ui-events[]
+ Class<? extends CssClassUiEvent<?>>
+ cssClassUiEvent() // <.>
+ default CssClassUiEvent.Default.class;
+
+ // end::refguide-ui-events[]
+ /**
+ * Which subclass of {@link LayoutUiEvent} should be used to obtain a layout.
+ *
+ * <p>
+ * This subclass must provide a no-arg constructor; the fields are set reflectively.
+ * </p>
+ */
+ // tag::refguide-ui-events[]
+ Class<? extends LayoutUiEvent<?>>
+ layoutUiEvent() // <.>
+ default LayoutUiEvent.Default.class;
+
+ // tag::refguide[]
+ // ...
+ // tag::refguide-ui-events[]
}
// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Action.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Action.adoc
index b764016..0bda359 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Action.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Action.adoc
@@ -5,100 +5,62 @@
The `@Action` annotation groups together all domain-specific metadata for an invokable action on a domain object or domain service.
-The table below summarizes the annotation's attributes.
-
-.`@Action` attributes
-[cols="2,2,4a", options="header"]
-|===
-
-| Attribute
-| Values (default)
-| Description
-
-
-|xref:refguide:applib-ant:Action.adoc#associateWith[`associateWith()`]
-|_memberId_ +
-("")
-|associates an action with another property or collection of the action.
-
-|xref:refguide:applib-ant:Action.adoc#associateWith[`associateWith-Sequence()`]
-|_memberId_ +
-("")
-|associates an action with another property or collection of the action.
-
-|xref:refguide:applib-ant:Action.adoc#command[`command()`]
-|`AS_CONFIGURED`, `ENABLED`, `DISABLED` +
-(`AS_CONFIGURED`)
-|whether the action invocation should be reified into a `o.a.i.applib.` +
-`services.command.Command` object through the xref:refguide:applib-svc:CommandContext.adoc[`CommandContext`] service.
-
-
-|`commandExecuteIn()`
-|`FOREGROUND`,`BACKGROUND` +
-(`FOREGROUND`)
-|whether to execute the command immediately, or to persist it (assuming that an appropriate implementation of xref:refguide:applib-svc:CommandService.adoc[`CommandService`] has been configured) such that a background scheduler can execute the command asynchronously
-
-
-|`commandPersistence()`
-|`PERSISTED`, `NOT_PERSISTED`, `IF_HINTED` +
-(`PERSISTED`)
-|whether the reified `Command` (as provided by the `CommandContext` domain service) should actually be persisted (assuming an appropriate implementation of xref:refguide:applib-svc:CommandService.adoc[`CommandService`] has been configured).
-
-
-|`commandDtoProcessor()`
-|Implementation of `CommandDtoProcessor` interface +
-(null)
-|If the `Command` also implements `CommandWithDto` (meaning that it can return a `CommandDto`, in other words be converted into an XML memento), then optionally specifies a processor that can refine this XML.
-
-
-|xref:refguide:applib-ant:Action.adoc#domainEvent[`domainEvent()`]
-|subtype of `ActionDomainEvent` +
-(`ActionDomainEvent.Default`)
-|the event type to be posted to the xref:refguide:applib-svc:EventBusService.adoc[`EventBusService`] to
-broadcast the action's business rule checking (hide, disable, validate) and its invocation (pre-execute and
-post-execute).
+[source,java]
+----
+include::refguide:applib-ant:example$annotation/Action.java[tags="refguide"]
+----
+<.> xref:refguide:applib-ant:Action.adoc#associateWith[`associateWith()`]
++
+associates an action with another property or collection of the action.
+<.> xref:refguide:applib-ant:Action.adoc#associateWith[`associateWith()`]
++
+associates an action with another property or collection of the action.
-|xref:refguide:applib-ant:Action.adoc#hidden[`hidden()`]
-|`EVERYWHERE`, `NOWHERE` +
-(`NOWHERE`)
-|indicates where (in the UI) the action should be hidden from the user.
+<.> xref:refguide:applib-ant:Action.adoc#associateWith[`associateWithSequence()`]
+associates an action with another property or collection of the action.
+<.> xref:refguide:applib-ant:Action.adoc#command[`command()`]
+whether the action invocation should be reified into a `o.a.i.applib.` +
+`services.command.Command` object through the xref:refguide:applib-svc:CommandContext.adoc[`CommandContext`] service:
-|xref:refguide:applib-ant:Action.adoc#invokeOn[`invokeOn()`]
-|`OBJECT_ONLY`, `COLLECTION_ONLY`, `OBJECT_AND_COLLECTION` +
-(`OBJECT_ONLY`)
-|(deprecated - use view models and associated actions instead).
+<.> `commandExecuteIn()`
++
+Whether to execute the command immediately, or to persist it (assuming that an appropriate implementation of xref:refguide:applib-svc:CommandService.adoc[`CommandService`] has been configured) such that a background scheduler can execute the command asynchronously
-whether an action can be invoked on a single object and/or on many objects in a collection.
+<.> `commandPersistence()`
++
+Whether the reified `Command` (as provided by the `CommandContext` domain service) should actually be persisted (assuming an appropriate implementation of xref:refguide:applib-svc:CommandService.adoc[`CommandService`] has been configured).
-Currently this is only supported for no-arg actions.
+<.> `commandDtoProcessor()`
++
+If the `Command` also implements `CommandWithDto` (meaning that it can return a `CommandDto`, in other words be converted into an XML memento), then optionally specifies a processor that can refine this XML.
+<.> xref:refguide:applib-ant:Action.adoc#domainEvent[`domainEvent()`]
++
+The event type to be posted to the xref:refguide:applib-svc:EventBusService.adoc[`EventBusService`] to broadcast the action's business rule checking (hide, disable, validate) and its invocation (pre-execute and post-execute).
-|xref:refguide:applib-ant:Action.adoc#publishing[`publishing()`]
-|`AS_CONFIGURED`, `ENABLED`, `DISABLED` +
-(`AS_CONFIGURED`)
-|whether the action invocation should be published to the registered xref:refguide:applib-svc:PublisherService.adoc[`PublisherService`].
+<.> xref:refguide:applib-ant:Action.adoc#hidden[`hidden()`]
++
+Indicates where (in the UI) the action should be hidden from the user.
-|xref:refguide:applib-ant:Action.adoc#restrictTo[`restrictTo()`]
-|`NO_RESTRICTIONS`,`PROTOTYPING` +
-(`NO_RESTRICTIONS`)
-|whether the action is only available in prototyping mode, or whether it is available also in production mode.
+<.> xref:refguide:applib-ant:Action.adoc#publishing[`publishing()`]
++
+Whether the action invocation should be published to the registered xref:refguide:applib-svc:PublisherService.adoc[`PublisherService`].
-|xref:refguide:applib-ant:Action.adoc#semantics[`semantics()`]
-|`SAFE_AND_REQUEST_CACHEABLE`, `SAFE`, +
-`IDEMPOTENT`, `IDEMPOTENT_ARE_YOU_SURE` +
-`NON_IDEMPOTENT`, `NON_IDEMPOTENT_ARE_YOU_SURE` + +
-(`NON_IDEMPOTENT`)
-|the action's semantics (ie whether objects are modified as the result of invoking this action, and if so whether reinvoking the action would result in no further change; if not whether the results can be cached for the remainder of the request).
+<.> xref:refguide:applib-ant:Action.adoc#restrictTo[`restrictTo()`]
++
+Whether the action is only available in prototyping mode, or whether it is available also in production mode.
+<.> xref:refguide:applib-ant:Action.adoc#semantics[`semantics()`]
++
+The action's semantics (ie whether objects are modified as the result of invoking this action, and if so whether reinvoking the action would result in no further change; if not whether the results can be cached for the remainder of the request).
++
The `...ARE_YOU_SURE` variants cause a confirmation dialog to be displayed in the xref:vw:ROOT:about.adoc[Wicket viewer].
-|xref:refguide:applib-ant:Action.adoc#typeOf[`typeOf()`]
-|(none)
-|if the action returns a collection, hints as to the run-time type of the objects within that collection (as a fallback)
-
-|===
+<.> xref:refguide:applib-ant:Action.adoc#typeOf[`typeOf()`]
++
+If the action returns a collection, hints as to the run-time type of the objects within that collection (as a fallback)
For example:
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Action/command.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Action/command.adoc
index 4e4ef51..7959904 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Action/command.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Action/command.adoc
@@ -26,7 +26,9 @@ The annotation works with (and is influenced by the behaviour of) a number of do
Each action invocation is automatically reified by the xref:refguide:applib-svc:CommandContext.adoc[`CommandContext`] service into a `Command` object, capturing details of the target object, the action, the parameter arguments, the user, a timestamp and so on.
-If an appropriate `CommandService` is configured (for example using (non-ASF) link:https://platform.incode.org/modules/spi/command/spi-command.html[Incode Platform's command] module), then the `Command` itself is persisted.
+If an appropriate `CommandService` is configured
+//(for example using (non-ASF) link:https://platform.incode.org/modules/spi/command/spi-command.html[Incode Platform's command] module),
+then the `Command` itself is persisted.
By default, actions are invoked in directly in the thread of the invocation.
//If there is an implementation of `BackgroundCommandService` (as the (non-ASF) link:https://platform.incode.org[Incode Platform^]'s command module does provide), then this means in turn that the `BackgroundService` can be used by the domain object code to programmatically create background ``Command``s.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout.adoc
index d363879..936ed89 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout.adoc
@@ -5,72 +5,43 @@
The `@ActionLayout` annotation applies to actions, collecting together all UI hints within a single annotation.
-The table below summarizes the annotation's attributes.
-
-.`@ActionLayout` attributes
-[cols="2,2,4a", options="header"]
-|===
-
-| Attribute
-| Values (default)
-| Description
-
-
-|xref:refguide:applib-ant:ActionLayout.adoc#bookmarking[`bookmarking`]
-|`AS_ROOT`, `NEVER` +
-(`NEVER`)
-|indicates if an action (with safe xref:refguide:applib-ant:Action.adoc#semantics[action semantics]) is automatically bookmarked.
-
-
-|xref:refguide:applib-ant:ActionLayout.adoc#contributedAs[`contributedAs`]
-|`AS_BOTH`, `AS_ACTION`, `AS_ASSOCIATION`, `AS_NEITHER` +
-(`AS_BOTH`)
-|for a domain service action that can be contributed, whether to contribute as an action or as an association (ie a property or collection). +
-
-For a domain service action to be contributed, the domain services must have a xref:refguide:applib-ant:DomainService.adoc#nature[nature] nature of either `VIEW` or `VIEW_CONTRIBUTIONS_ONLY`, and the action must have xref:refguide:applib-ant:Action.adoc#semantics[safe action semantics], and takes a single argument, namely the contributee domain object.
-
-
-|xref:refguide:applib-ant:ActionLayout.adoc#cssClass[`cssClass`]
-|Any string valid as a CSS class
-|an additional CSS class around the HTML that represents for the action, to allow targetted styling in xref:refguide:config:application-specific/application-css.adoc[`application.css`]. +
-
-Supported by the xref:vw:ROOT:about.adoc[Wicket viewer] but currently ignored by the xref:vro:ROOT:about.adoc[RestfulObjects viewer].
-
-
-|xref:refguide:applib-ant:ActionLayout.adoc#cssClassFa[`cssClassFa`]
-|Any valid link:http://fortawesome.github.io/Font-Awesome/[Font awesome] icon name
-|specify a font awesome icon for the action's menu link or icon. +
-
-
-|`cssClassFaPosition()`
-|`LEFT`, `RIGHT` +
-(`LEFT`)
-|Positioning of the icon on the button/menu item.
-
+[source,java]
+----
+include::refguide:applib-ant:example$annotation/ActionLayout.java[tags="refguide"]
+----
+<.> xref:refguide:applib-ant:ActionLayout.adoc#bookmarking[`bookmarking()`]
++
+Indicates if an action (with safe xref:refguide:applib-ant:Action.adoc#semantics[action semantics]) is automatically bookmarked.
-|xref:refguide:applib-ant:ActionLayout.adoc#describedAs[`describedAs`]
-|String.
-|provides a short description of the action, eg for rendering as a 'tool tip'.
+<.> xref:refguide:applib-ant:ActionLayout.adoc#cssClass[`cssClass()`]
++
+An additional CSS class around the HTML that represents for the action, to allow targetted styling in xref:refguide:config:application-specific/application-css.adoc[`application.css`]. +
+<.> xref:refguide:applib-ant:ActionLayout.adoc#cssClassFa[`cssClassFa()`]
++
+Specify a link:http://fortawesome.github.io/Font-Awesome/[Font awesome] icon name for the action's menu link or icon.
-|xref:refguide:applib-ant:ActionLayout.adoc#hidden[`hidden`]
-|`EVERYWHERE`, `NOWHERE` +
-(`NOWHERE`)
-|indicates where (in the UI) the action should be hidden from the user.
+<.> `cssClassFaPosition()`
++
+Positioning of the icon on the button/menu item.
+<.> xref:refguide:applib-ant:ActionLayout.adoc#describedAs[`describedAs()`]
++
+Provides a short description of the action, eg for rendering as a 'tool tip'.
-|xref:refguide:applib-ant:ActionLayout.adoc#named[`named`]
-|String.
-|to override the name inferred from the action's name in code. +
+<.> xref:refguide:applib-ant:ActionLayout.adoc#hidden[`hidden()`]
++
+Indicates where (in the UI) the action should be hidden from the user.
+<.> xref:refguide:applib-ant:ActionLayout.adoc#named[`named()`]
++
+To override the name inferred from the action's name in code. +
A typical use case is if the desired name is a reserved Java keyword, such as `default` or `package`.
-|xref:refguide:applib-ant:ActionLayout.adoc#position[`position`]
-|`BELOW`, `RIGHT`, `PANEL`, `PANEL_DROPDOWN` (`BELOW`)
-|for actions associated (using xref:refguide:applib-ant:MemberOrder.adoc[`@MemberOrder#named`]) with properties, the positioning of the action's button with respect to the property
-
+<.> xref:refguide:applib-ant:ActionLayout.adoc#position[`position()`]
++
+For actions associated (using xref:refguide:applib-ant:MemberOrder.adoc[`@MemberOrder#named`]) with properties, the positioning of the action's button with respect to the property
-|===
For example:
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Collection.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Collection.adoc
index 370aa18..51e4c4e 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Collection.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Collection.adoc
@@ -5,57 +5,33 @@
The `@Collection` annotation applies to collections collecting together all domain semantics within a single annotation.
-The table below summarizes the annotation's attributes.
-
-.`@Collection` attributes
-[cols="2,2,4a", options="header"]
-|===
-
-| Attribute
-| Values (default)
-| Description
-
-
-|xref:refguide:applib-ant:Collection.adoc#domainEvent[`domainEvent`]
-|subtype of `CollectionDomainEvent` +
-(`CollectionDomainEvent.Default`)
-|the event type to be posted to the xref:refguide:applib-svc:EventBusService.adoc[`EventBusService`] to broadcast the collection's business rule checking (hide, disable, validate) and its modification (before and after).
-
-
-|xref:refguide:applib-ant:Collection.adoc#editing[`editing`]
-|`ENABLED`, `DISABLED`, `AS_CONFIGURED` +
-(`AS_CONFIGURED`)
-|whether a collection can be added to or removed from within the UI
-
-
-|`editingDisabledReason()`
-|String value
-|if `editing()` is `DISABLED`, provides a reason as to why.
-
-
-|xref:refguide:applib-ant:Collection.adoc#hidden[`hidden`]
-|`EVERYWHERE`, `OBJECT_FORMS`, `NOWHERE` +
-(`NOWHERE`)
-|indicates where (in the UI) the collection should be hidden from the user.
-
-
-|xref:refguide:applib-ant:Collection.adoc#notPersisted[`notPersisted`]
-|`true`, `false` +
-(`false`)
-|whether to exclude from snapshots. +
+[source,java]
+----
+include::refguide:applib-ant:example$annotation/Collection.java[tags="refguide"]
+----
+<.> xref:refguide:applib-ant:Collection.adoc#domainEvent[`domainEvent()`]
++
+The event type to be posted to the xref:refguide:applib-svc:EventBusService.adoc[`EventBusService`] to broadcast the collection's business rule checking (hide, disable, validate) and its modification (before and after).
-[WARNING]
-====
-Collection must also be annotated with `@javax.jdo.annotations.NotPersistent` in order to not be persisted.
-====
+<.> xref:refguide:applib-ant:Collection.adoc#editing[`editing()`]
++
+Whether a collection can be added to or removed from within the UI
+<.> `editingDisabledReason()`
++
+If `editing()` is `DISABLED`, provides a reason as to why.
+<.> xref:refguide:applib-ant:Collection.adoc#hidden[`hidden()`]
++
+Indicates where (in the UI) the collection should be hidden from the user.
-|xref:refguide:applib-ant:Collection.adoc#typeOf[`typeOf`]
-|
-|hints as to the run-time type of the objects within that collection (as a fallback)
+<.> xref:refguide:applib-ant:Collection.adoc#mementoSerialization[`mementoSerialization()`]
++
+Whether to include/exclude in snapshots. +
-|===
+<.> xref:refguide:applib-ant:Collection.adoc#typeOf[`typeOf()`]
++
+Hints as to the run-time type of the objects within that collection (as a fallback)
For example:
@@ -99,5 +75,5 @@ so that boilerplate-busting tools such as link:https://projectlombok.org/[Projec
include::Collection/domainEvent.adoc[leveloffset=+1]
include::Collection/editing.adoc[leveloffset=+1]
include::Collection/hidden.adoc[leveloffset=+1]
-include::Collection/notPersisted.adoc[leveloffset=+1]
+include::Collection/mementoSerialization.adoc[leveloffset=+1]
include::Collection/typeOf.adoc[leveloffset=+1]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Collection/notPersisted.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Collection/mementoSerialization.adoc
similarity index 54%
rename from api/applib/src/main/adoc/modules/applib-ant/pages/Collection/notPersisted.adoc
rename to api/applib/src/main/adoc/modules/applib-ant/pages/Collection/mementoSerialization.adoc
index 23dd429..af4f1b7 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Collection/notPersisted.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Collection/mementoSerialization.adoc
@@ -1,49 +1,24 @@
-= `notPersisted`
+= `mementoSerialization`
: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:
-The (somewhat misnamed) `notPersisted` attribute indicates that the collection should be excluded from any snapshots generated by the xref:refguide:applib-svc:XmlSnapshotService.adoc[`XmlSnapshotService`].
-
-
-[WARNING]
-====
-This annotation does _not_ specify that a collection is not persisted in the JDO/DataNucleus objectstore. See below for details as to how to additionally annotate the collection for this.
-====
-
+The `mementoSerialization` attribute indicates that the collection should be included or excluded from any snapshots generated by the xref:refguide:applib-svc:XmlSnapshotService.adoc[`XmlSnapshotService`].
For example:
[source,java]
----
public class Customer {
- @Collection(notPersisted=true)
+ @Collection(mementoSerialization=EXCLUDED)
public SortedSet<Order> getPreviousOrders() {...}
public void setPreviousOrder(SortedSet<Order> previousOrders) {...}
...
}
----
-Historically this annotation also hinted as to whether the collection's contents should be persisted in the object store. However, the JDO/DataNucleus objectstore does not recognize this annotation. Thus, to ensure that a collection is actually not persisted, it should *also* be annotated with `@javax.jdo.annotations.NotPersistent`.
-
-For example:
-
-[source,java]
-----
-public class Customer {
- @Collection(notPersisted=true) // <1>
- @javax.jdo.annotations.NotPersistent // <2>
- public SortedSet<Order> getPreviousOrders() {...}
- public void setPreviousOrder(SortedSet<Order> previousOrders) {...}
- ...
-}
-----
-<1> ignored by Apache Isis
-<2> ignored by JDO/DataNucleus
-
-
Alternatively, if the collection is derived, then providing only a "getter" will also work:
@@ -55,8 +30,7 @@ public class Customer {
}
----
-
== See also
-This attribute is also supported for xref:refguide:applib-ant:Property.adoc#notPersisted[properties].
+This attribute is also supported for xref:refguide:applib-ant:Property.adoc#mementoSerialization[properties].
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout.adoc
index 72a4d06..08a88f2 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout.adoc
@@ -3,68 +3,45 @@
: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 [...]
-The `@CollectionLayout` annotation applies to collections, collecting together all UI hints within a single
-annotation. It is also possible to apply the annotation to actions of domain services that are acting as contributed collections.
-
-The table below summarizes the annotation's attributes.
-
-.`@CollectionLayout` attributes
-[cols="2,2,4a", options="header"]
-|===
-
-| Attribute
-| Values (default)
-| Description
-
-
-|xref:refguide:applib-ant:CollectionLayout.adoc#cssClass[`cssClass()`]
-|Any string valid as a CSS class
-|the css class that a collection should have, to allow more targetted styling in xref:refguide:config:application-specific/application-css.adoc[`application.css`]
-
-
-|xref:refguide:applib-ant:CollectionLayout.adoc#defaultView[`defaultView()`]
-|`table`, `excel`, `calendar`, `map`, ...
-|Which view is selected by default, if multiple views are available.
-
-See the (non-ASF) link:https://platform.incode.org[Incode Platform^] for further Wicket components providing views.
-
-
-
-|xref:refguide:applib-ant:CollectionLayout.adoc#describedAs[`describedAs()`]
-|String.
-|description of this collection, eg to be rendered in a tooltip.
+The `@CollectionLayout` annotation applies to collections, collecting together all UI hints within a single annotation.
+It is also possible to apply the annotation to actions of domain services that are acting as contributed collections.
+[source,java]
+----
+include::refguide:applib-ant:example$annotation/CollectionLayout.java[tags="refguide"]
+----
+<.> xref:refguide:applib-ant:CollectionLayout.adoc#cssClass[`cssClass()`]
++
+The css class that a collection should have, to allow more targetted styling in xref:refguide:config:application-specific/application-css.adoc[`application.css`]
-|xref:refguide:applib-ant:CollectionLayout.adoc#hidden[`hidden()`]
-|`EVERYWHERE`, `OBJECT_FORMS`, `NOWHERE` +
-(`NOWHERE`)
-|indicates where (in the UI) the collection should be hidden from the user.
+<.> xref:refguide:applib-ant:CollectionLayout.adoc#defaultView[`defaultView()`]
++
+Which view is selected by default, if multiple views are available.
+<.> xref:refguide:applib-ant:CollectionLayout.adoc#describedAs[`describedAs()`]
++
+Description of this collection, eg to be rendered in a tooltip.
-|xref:refguide:applib-ant:CollectionLayout.adoc#named[`named`]
-|String.
-|to override the name inferred from the collection's name in code. +
+<.> xref:refguide:applib-ant:CollectionLayout.adoc#hidden[`hidden()`]
++
+Indicates where (in the UI) the collection should be hidden from the user.
+<.> xref:refguide:applib-ant:CollectionLayout.adoc#named[`named()`]
++
+To override the name inferred from the collection's name in code. +
A typical use case is if the desired name is a reserved Java keyword, such as `default` or `package`.
+<.> `namedEscaped()`
++
+Whether to HTML escape the name of this property.
-|namedEscaped()
-|`true`,`false` (`true`)
-|whether to HTML escape the name of this property.
-
-
-|xref:refguide:applib-ant:CollectionLayout.adoc#paged[`paged()`]
-|Positive integer
-|the page size for instances of this class when rendered within a table.
-
-
-|xref:refguide:applib-ant:CollectionLayout.adoc#sortedBy[`sortedBy()`]
-|Subclass of `java.util.Comparator` for element type
-|indicates that the elements in the `java.util.SortedSet` collection should be sorted according to a specified `Comparator` rather than their natural sort order.
-
-|===
-
+<.> xref:refguide:applib-ant:CollectionLayout.adoc#paged[`paged()`]
++
+The page size for instances of this class when rendered within a table.
+<.> xref:refguide:applib-ant:CollectionLayout.adoc#sortedBy[`sortedBy()`]
++
+Indicates that the elements in the `java.util.SortedSet` collection should be sorted according to a specified `Comparator` rather than their natural sort order.
For example:
@@ -84,30 +61,17 @@ public class ToDoItem {
}
----
-
-
[TIP]
====
As an alternative to using the `@CollectionLayout` annotation, a xref:vw:ROOT:layout.adoc#file-based[file-based layout] can be used (and is generally to be preferred since it is more flexible/powerful).
====
-
-
-
-
[TIP]
====
-The annotation is one of a handful (others including xref:refguide:applib-ant:Collection.adoc[`@Collection`], xref:refguide:applib-ant:Property.adoc[`@Property`] and xref:refguide:applib-ant:PropertyLayout.adoc[`@PropertyLayout`]) that can also be applied to the field, rather than the getter method. This is specifically
-so that boilerplate-busting tools such as link:https://projectlombok.org/[Project Lombok] can be used.
+The annotation is one of a handful (others including xref:refguide:applib-ant:Collection.adoc[`@Collection`], xref:refguide:applib-ant:Property.adoc[`@Property`] and xref:refguide:applib-ant:PropertyLayout.adoc[`@PropertyLayout`]) that can also be applied to the field, rather than the getter method.
+This is specifically so that boilerplate-busting tools such as link:https://projectlombok.org/[Project Lombok] can be used.
====
-
-
-
-
-
-
-
include::CollectionLayout/cssClass.adoc[leveloffset=+1]
include::CollectionLayout/defaultView.adoc[leveloffset=+1]
include::CollectionLayout/describedAs.adoc[leveloffset=+1]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Column.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Column.adoc
index c4672a1..ed1eb4a 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Column.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Column.adoc
@@ -9,14 +9,15 @@ Apache Isis also parses and interprets this annotation in order to build up aspe
[NOTE]
====
-Isis parses the `@Column` annotation from the Java source code; it does not query the JDO metamodel. This means that it the `@Column` annotation must be used rather than the equivalent `<column>` link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/orm/schema_mapping.html[XML metadata].
+Apache Isis parses the `@Column` annotation from the Java source code; it does not query the JDO metamodel.
+This means that it the `@Column` annotation must be used rather than the equivalent `<column>` link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/orm/schema_mapping.html[XML metadata].
-Moreover, while JDO/DataNucleus will recognize annotations on either the field or the getter method, Apache Isis (currently) only inspects the getter method. Therefore ensure that the annotation is placed there.
+Moreover, while JDO/DataNucleus will recognize annotations on either the field or the getter method, Apache Isis (currently) only inspects the getter method.
+Therefore ensure that the annotation is placed there.
====
This section identifies which attributes of `@Column` are recognized and used by Apache Isis.
-
== Nullability
The `allowsNull` attribute is used to specify if a property is mandatory or is optional.
@@ -31,12 +32,16 @@ public class Customer {
public void setMiddleInitial(String middleInitial) { /* ... */ }
----
-Isis also provides xref:refguide:applib-ant:Property.adoc#optionality[`@Property#optionality`] attribute. If both are specified, Apache Isis will check when it initializes for any contradictions, and will fail-fast with an appropriate error message in the log if there are.
-
-You should also be aware that in the lack of either the `@Column#allowsNull` or the `@Property#optionality` attributes, that the JDO and Apache Isis defaults differ. Apache Isis rule is straight-forward: properties are assumed to be required. JDO on the other hand specifies that only primitive types are mandatory; everything else is assumed to be optional. Therefore a lack of either annotation can also trigger the fail-fast validation check.
+Isis also provides xref:refguide:applib-ant:Property.adoc#optionality[`@Property#optionality`] attribute.
+If both are specified, Apache Isis will check when it initializes for any contradictions, and will fail-fast with an appropriate error message in the log if there are.
-In the vast majority of cases you should be fine just to add the `@Column#allowsNull` attribute to the getter. But see the documentation for xref:refguide:applib-ant:Property.adoc#optionality[`@Property#optionality`] attribute for discussion on one or two minor edge cases.
+You should also be aware that in the lack of either the `@Column#allowsNull` or the `@Property#optionality` attributes, that the JDO and Apache Isis defaults differ.
+Apache Isis rule is straight-forward: properties are assumed to be required.
+JDO on the other hand specifies that only primitive types are mandatory; everything else is assumed to be optional.
+Therefore a lack of either annotation can also trigger the fail-fast validation check.
+In the vast majority of cases you should be fine just to add the `@Column#allowsNull` attribute to the getter.
+But see the documentation for xref:refguide:applib-ant:Property.adoc#optionality[`@Property#optionality`] attribute for discussion on one or two minor edge cases.
== Length for ``String``s
@@ -61,11 +66,8 @@ public class Customer {
Apache Isis also provides xref:refguide:applib-ant:Property.adoc#maxLength[`@Property#maxLength`] attribute.
If both are specified, Apache Isis will check when it initializes for any contradictions, and will fail-fast with an appropriate error message in the log if there are.
-
-
== Length/scale for ``BigDecimal``s
-
The `length()` and `scale` attributes are used to infer the precision/scale of `java.math.BigDecimal` property types as they map to `decimal(n,p)` columns.
For example:
@@ -83,17 +85,17 @@ There is a subtle difference here: while `@Column#scale()` corresponds to `@Digi
If both are specified, Apache Isis will check when it initializes for any contradictions, and will fail-fast with an appropriate error message in the log if there are.
-
-
[[rg-ant-hints-and-tips]]
== Hints and Tips
-This seems to be a good place to describe some additional common mappings that use `@Column`. Unlike the sections above, the attributes specified in these hints and tips aren't actually part of Apache Isis metamodel.
-
+This seems to be a good place to describe some additional common mappings that use `@Column`.
+Unlike the sections above, the attributes specified in these hints and tips aren't actually part of Apache Isis metamodel.
=== Mapping foreign keys
-The `name` attribute can be used to override the name of the column. References to other objects are generally mapped as foreign key columns. If there are multiple references to a given type, then you will want to override the name that JDO/DataNucleus would otherwise default.
+The `name` attribute can be used to override the name of the column.
+References to other objects are generally mapped as foreign key columns.
+If there are multiple references to a given type, then you will want to override the name that JDO/DataNucleus would otherwise default.
For example (taken from link:http://github.com/estatio/estatio[estatio] app):
@@ -110,11 +112,11 @@ public class PartyRelationship {
}
----
-
-
=== Mapping ``Blob``s and ``Clob``s
-Isis provides custom value types for xref:refguide:applib-cm:classes/value-types.adoc#Blob[`Blob`]s and xref:refguide:applib-cm:classes/value-types.adoc#Clob[`Clob`]s. These value types have multiple internal fields, meaning that they corresponding to multiple columns in the database. Mapping this correctly requires using `@Column` within JDO's `@Persistent` annotation.
+Isis provides custom value types for xref:refguide:applib-cm:classes/value-types.adoc#Blob[`Blob`]s and xref:refguide:applib-cm:classes/value-types.adoc#Clob[`Clob`]s.
+These value types have multiple internal fields, meaning that they corresponding to multiple columns in the database.
+Mapping this correctly requires using `@Column` within JDO's `@Persistent` annotation.
For example, here's how to map a `Blob` (taken from http://github.com/apache/isis-app-todoapp[TodoApp]):
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Discriminator.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Discriminator.adoc
index 7b65cfa..748cdf8 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Discriminator.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Discriminator.adoc
@@ -6,28 +6,29 @@
The `@javax.jdo.annotation.Discriminator` is used by JDO/DataNucleus to specify how to discriminate between subclasses of an inheritance hierarchy.
-It is valid to add a `@Discriminator` for any class, even those not part of an explicitly mapped inheritance hierarchy. Apache Isis also checks for this annotation, and if present will use the `@Discriminator#value()` as the object type, a unique alias for the object's class name.
+It is valid to add a `@Discriminator` for any class, even those not part of an explicitly mapped inheritance hierarchy.
+Apache Isis also checks for this annotation, and if present will use the `@Discriminator#value()` as the object type, a unique alias for the object's class name.
[NOTE]
====
-Isis parses the `@Discriminator` annotation from the Java source code; it does not query the JDO metamodel. This means that it the `@Discriminator` annotation must be used rather than the equivalent `<discriminator>` link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/orm/inheritance.html[XML metadata].
+Isis parses the `@Discriminator` annotation from the Java source code; it does not query the JDO metamodel.
+This means that it the `@Discriminator` annotation must be used rather than the equivalent `<discriminator>` link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/orm/inheritance.html[XML metadata].
-Moreover, while JDO/DataNucleus will recognize annotations on either the field or the getter method, Apache Isis (currently) only inspects the getter method. Therefore ensure that the annotation is placed there.
+Moreover, while JDO/DataNucleus will recognize annotations on either the field or the getter method, Apache Isis (currently) only inspects the getter method.
+Therefore ensure that the annotation is placed there.
====
This value is used internally to generate a string representation of an objects identity (the `Oid`).
This can appear in several contexts, including:
* as the value of `Bookmark#getObjectType()` and in the `toString()` value of `Bookmark`
- (see xref:refguide:applib-svc:BookmarkService.adoc[`BookmarkService`])
- ** and thus in the "table-of-two-halves" pattern, as per the (non-ASF) link:https://platform.incode.org[Incode Platform^]'s poly module
+(see xref:refguide:applib-svc:BookmarkService.adoc[`BookmarkService`])
+** and thus in the "table-of-two-halves" pattern, as per the (non-ASF) link:https://platform.incode.org[Incode Platform^]'s poly module
* in the serialization of `OidDto` in the xref:refguide:schema:cmd[command] and xref:refguide:schema:about.adoc#ixn.adoc[interaction] schemas
* in the URLs of the xref:vro:ROOT:about.adoc[RestfulObjects viewer]
* in the URLs of the xref:vw:ROOT:about.adoc[Wicket viewer] (in general and in particular if xref:vw:ROOT:features.adoc#hints-and-copy-url[copying URLs])
* in XML snapshots generated by the xref:refguide:applib-svc:XmlSnapshotService.adoc[`XmlSnapshotService`]
-
-
== Examples
For example:
@@ -42,7 +43,6 @@ public class Customer {
has an object type of `custmgmt.Customer`.
-
== Precedence
The rules of precedence for determining a domain object's object type are:
@@ -50,13 +50,11 @@ The rules of precedence for determining a domain object's object type are:
1. xref:refguide:applib-ant:Discriminator.adoc[`@Discriminator`]
2. `@DomainObject#objectType`
3. xref:refguide:applib-ant:PersistenceCapable.adoc[`@PersistenceCapable`], if at least the `schema` attribute is defined. +
-+
-If both `schema` and `table` are defined, then the value is "`schema.table`".
++ If both `schema` and `table` are defined, then the value is "`schema.table`".
If only `schema` is defined, then the value is "`schema.className`".
4. Fully qualified class name of the entity.
-
[TIP]
====
This might be obvious, but to make explicit: we recommend that you always specify an object type for your domain objects.
@@ -65,8 +63,8 @@ Otherwise, if you refactor your code (change class name or move package), then a
At best this will require a data migration in the database; at worst it could cause external clients accessing data through the xref:vro:ROOT:about.adoc[Restful Objects] viewer to break.
====
-
[NOTE]
====
-If the object type is not unique across all domain classes then the framework will fail-fast and fail to boot. An error message will be printed in the log to help you determine which classes have duplicate object tyoes.
+If the object type is not unique across all domain classes then the framework will fail-fast and fail to boot.
+An error message will be printed in the log to help you determine which classes have duplicate object tyoes.
====
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject.adoc
index 1e0093b..19545ce 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject.adoc
@@ -6,109 +6,118 @@
The `@DomainObject` annotation applies to domain objects, collecting together all domain semantics within a single annotation.
-The table below summarizes the annotation's attributes.
+== Main API
-.`@DomainObject` attributes
-[cols="2,2,4a", options="header"]
-|===
+[source,java]
+----
+include::refguide:applib-ant:example$annotation/DomainObject.java[tags="refguide"]
+----
+<.> xref:refguide:applib-ant:DomainObject.adoc#auditing[`auditing()`]
++
+Indicates whether each of the changed properties of an object should be submitted to the registered
+xref:refguide:applib-svc:AuditerService.adoc[`AuditerService`](s)
-| Attribute
-| Values (default)
-| Description
+<.> xref:refguide:applib-ant:DomainObject.adoc#autoCompleteRepository[`autoCompleteRepository()`]
++
+Nominate a method on a domain service to be used for looking up instances of the domain object
+<.> `autoCompleteAction()`
++
+Override the method name to use on the auto-complete repository
-|xref:refguide:applib-ant:DomainObject.adoc#auditing[`auditing()`]
-|`AS_CONFIGURED`, `ENABLED`, `DISABLED` +
-(`AS_CONFIGURED`)
-|indicates whether each of the changed properties of an object should be submitted to the registered
-xref:refguide:applib-svc:AuditerService.adoc[`AuditerService`](s)
+<.> xref:refguide:applib-ant:DomainObject.adoc#bounding[`bounding()`]
++
+Whether the number of instances of this domain class is relatively small (a "bounded" set), such that instances could be selected from a drop-down list box or similar.
+<.> xref:refguide:applib-ant:DomainObject.adoc#editing[`editing()`]
++
+Whether the object's properties and collections can be edited or not (ie whether the instance should be considered to be immutable)
-|xref:refguide:applib-ant:DomainObject.adoc#autoCompleteRepository[`autoCompleteRepository()`]
-|Domain service class
-|nominate a method on a domain service to be used for looking up instances of the domain object
+<.> `editingDisabledReason()`
++
+The default reason why the object's properties and collections cannot be edited.
+<.> xref:refguide:applib-ant:DomainObject.adoc#mixinMethod[`mixinMethod()`]
++
+How to recognize the "reserved" method name, meaning that the mixin's own name will be inferred from the mixin type.
+Typical examples are "exec", "execute", "invoke", "apply" and so on.
+The default "reserved" method name is `$$`.
-|`autoCompleteAction()`
-|Method name +
-(`autoComplete()`)
-|override the method name to use on the auto-complete repository
+<.> xref:refguide:applib-ant:DomainObject.adoc#nature[`nature()`]
++
+Whether the domain object logically is an entity (part of the domain layer) or is a view model (part of the application layer); or is a mixin.
+If an entity, indicates how its persistence is managed.
+<.> xref:refguide:applib-ant:DomainObject.adoc#objectType[`objectType()`]
++
+Specify an alias for the domain class used to uniquely identify the object both within the Apache Isis runtime and externally
-|xref:refguide:applib-ant:DomainObject.adoc#bounding[`bounding()`]
-|`true`, `false` +
-(`false`)
-|Whether the number of instances of this domain class is relatively small (a "bounded" set), such that instances could be selected from a drop-down list box or similar.
+<.> xref:refguide:applib-ant:DomainObject.adoc#publishing[`publishing()`]
++
+Whether changes to the object should be published to the registered xref:refguide:applib-svc:PublisherService.adoc[`PublisherService`].
-|xref:refguide:applib-ant:DomainObject.adoc#createdLifecycleEvent[`created-` +
-`LifecycleEvent()`]
-|subtype of `ObjectCreatedEvent` +
-(`ObjectCreatedEvent.Default`)
-|the event type to be posted to the xref:refguide:applib-svc:EventBusService.adoc[`EventBusService`] whenever an instance is created
-|xref:refguide:applib-ant:DomainObject.adoc#editing[`editing()`]
-|`AS_CONFIGURED`, `ENABLED`, `DISABLED` +
-(`AS_CONFIGURED`)
-|whether the object's properties and collections can be edited or not (ie whether the instance should be considered to be immutable)
+== Entity Lifecycle API
-|xref:refguide:applib-ant:DomainObject.adoc#mixinMethod[`mixinMethod()`]
-|Method name within the mixin
-|How to recognize the "reserved" method name, meaning that the mixin's own name will be inferred from the mixin type.
-Typical examples are "exec", "execute", "invoke", "apply" and so on.
-The default "reserved" method name is `$$`.
+These attributes define the events to be fired throughout an the persistence lifecycle of a domain entity:
+[source,java]
+----
+include::refguide:applib-ant:example$annotation/DomainObject.java[tags="refguide-lifecycle-events"]
+----
+<.> xref:refguide:applib-ant:DomainObject.adoc#createdLifecycleEvent[`createdLifecycleEvent()`]
++
+The event type to be posted to the xref:refguide:applib-svc:EventBusService.adoc[`EventBusService`] whenever an instance is created
-|xref:refguide:applib-ant:DomainObject.adoc#nature[`nature()`]
-|`NOT_SPECIFIED`, `JDO_ENTITY`, `EXTERNAL_ENTITY`, `INMEMORY_ENTITY`, `MIXIN`, `VIEW_MODEL` (`NOT_SPECIFIED`)
-|whether the domain object logically is an entity (part of the domain layer) or is a view model (part of the application layer); or is a mixin.
-If an entity, indicates how its persistence is managed.
+<.> xref:refguide:applib-ant:DomainObject.adoc#persistingLifecycleEvent[`persistingLifecycleEvent()`]
++
+The event type to be posted to whenever an instance is about to be persisted
+<.> xref:refguide:applib-ant:DomainObject.adoc#persistedLifecycleEvent[`persistedLifecycleEvent()`]
++
+The event type to be posted whenever an instance has just been persisted
-|xref:refguide:applib-ant:DomainObject.adoc#objectType[`objectType()`]
-|(none, which implies fully qualified class name)
-|specify an alias for the domain class used to uniquely identify the object both within the Apache Isis runtime and externally
+<.> xref:refguide:applib-ant:DomainObject.adoc#loadedLifecycleEvent[`loadedLifecycleEvent()`]
++
+The event type to be posted whenever an instance has just been loaded from the datastore
+<.> xref:refguide:applib-ant:DomainObject.adoc#removingLifecycleEvent[`removingLifecycleEvent()`]
++
+The event type to be posted whenever an instance is about to be deleted
-|xref:refguide:applib-ant:DomainObject.adoc#persistedLifecycleEvent[`persisted-` +
-`LifecycleEvent()`]
-|subtype of `ObjectPersistedEvent` +
-(`ObjectPersistedEvent.Default`)
-|the event type to be posted to the xref:refguide:applib-svc:EventBusService.adoc[`EventBusService`] whenever an instance has just been persisted
+<.> xref:refguide:applib-ant:DomainObject.adoc#updatedLifecycleEvent[`updatedLifecycleEvent()`]
++
+The event type to be posted whenever an instance has just been updated
-|xref:refguide:applib-ant:DomainObject.adoc#persistingLifecycleEvent[`persisting-` +
-`LifecycleEvent()`]
-|subtype of `ObjectPersistingEvent` +
-(`ObjectPersistingEvent.Default`)
-|the event type to be posted to the xref:refguide:applib-svc:EventBusService.adoc[`EventBusService`] whenever an instance is about to be persisted
+<.> xref:refguide:applib-ant:DomainObject.adoc#updatingLifecycleEvent[`updatingLifecycleEvent()`]
++
+The event type to be posted whenever an instance is about to be updated
-|xref:refguide:applib-ant:DomainObject.adoc#publishing[`publishing()`]
-|`AS_CONFIGURED`, `ENABLED`, `DISABLED` +
-(`AS_CONFIGURED`)
-|whether changes to the object should be published to the registered xref:refguide:applib-svc:PublisherService.adoc[`PublisherService`].
+== Domain Events API
+These attributes define the events to be fired when a domain object's members (its actions, properties and collections) are interacted with.
-|xref:refguide:applib-ant:DomainObject.adoc#removingLifecycleEvent[`removing-` +
-`LifecycleEvent()`]
-|subtype of `ObjectRemovingEvent` +
-(`ObjectRemovingEvent.Default`)
-|the event type to be posted to the xref:refguide:applib-svc:EventBusService.adoc[`EventBusService`] whenever an instance is about to be deleted
+These attributes define the default event types; they can be overridden for each specific domain member.
-|xref:refguide:applib-ant:DomainObject.adoc#updatedLifecycleEvent[`updated-` +
-`LifecycleEvent()`]
-|subtype of `ObjectUpdatedEvent` +
-(`ObjectUpdatedEvent.Default`)
-|the event type to be posted to the xref:refguide:applib-svc:EventBusService.adoc[`EventBusService`] whenever an instance has just been updated
+[source,java]
+----
+include::refguide:applib-ant:example$annotation/DomainObject.java[tags="refguide-domain-events"]
+----
+<.> `actionDomainEvent()`
++
+The event type to be posted to the xref:refguide:applib-svc:EventBusService.adoc[`EventBusService`] whenever an action of the domain object is interacted with (if not overridden using xref:refguide:applib-ant:Action.adoc#domainevent[`@Action#domainEvent()]`).
-|xref:refguide:applib-ant:DomainObject.adoc#updatingLifecycleEvent[`updating-` +
-`LifecycleEvent()`]
-|subtype of `ObjectUpdatingEvent` +
-(`ObjectUpdatingEvent.Default`)
-|the event type to be posted to the xref:refguide:applib-svc:EventBusService.adoc[`EventBusService`] whenever an instance is about to be updated
+<.> `propertyDomainEvent()`
++
+The event type to be posted to the xref:refguide:applib-svc:EventBusService.adoc[`EventBusService`] whenever a property of the domain object is interacted with (if not overridden using xref:refguide:applib-ant:Property.adoc#domainevent[`@Property#domainEvent()]`).
-|===
+<.> `collectionDomainEvent()`
++
+The event type to be posted to the xref:refguide:applib-svc:EventBusService.adoc[`EventBusService`] whenever a collection of the domain object is interacted with (if not overridden using xref:refguide:applib-ant:Collection.adoc#domainevent[`@Collection#domainEvent()]`).
+// TODO: v2: currently missing subpages for these attributes.
For example:
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout.adoc
index bdeebe8..98df34b 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout.adoc
@@ -6,17 +6,25 @@
The `@DomainObjectLayout` annotation applies to domain classes, collecting together all UI hints within a single annotation.
+[source,java]
+----
+include::refguide:applib-ant:example$annotation/DomainObjectLayout.java[tags="refguide"]
+----
+
+[source,java]
+----
+include::refguide:applib-ant:example$annotation/DomainObjectLayout.java[tags="refguide-ui-events"]
+----
[NOTE]
====
For view models that have been annotated with `@ViewModel` the equivalent xref:refguide:applib-ant:ViewModelLayout.adoc[`@ViewModelLayout`] can be used.
====
-
The table below summarizes the annotation's attributes.
.`@DomainObjectLayout` attributes
-[cols="2,2,4a", options="header"]
+[cols="2,2,4a",options="header"]
|===
| Attribute
@@ -89,8 +97,6 @@ A typical use case is if the desired name is a reserved Java keyword, such as `d
|===
-
-
For example:
[source,java]
@@ -108,20 +114,11 @@ public class ToDoItem {
}
----
-
-
[NOTE]
====
Note that there is (currently) no support for specifying UI hints for domain objects through the dynamic xref:vw:ROOT:layout.adoc#file-based[`.layout.xml`] file (only for properties, collections and actions are supported).
====
-
-
-
-
-
-
-
include::DomainObjectLayout/bookmarking.adoc[leveloffset=+1]
include::DomainObjectLayout/cssClass.adoc[leveloffset=+1]
include::DomainObjectLayout/cssClassFa.adoc[leveloffset=+1]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainService.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainService.adoc
index 1b35d9d..8942197 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainService.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainService.adoc
@@ -6,13 +6,15 @@
The `@DomainService` annotation indicates that the (concrete) class should be automatically instantiated as a domain service.
-Domain services with this annotation do NOT need to be registered explicitly in `isis.properties`; they will be
-discovered automatically on the CLASSPATH.
+[source,java]
+----
+include::refguide:applib-ant:example$annotation/DomainService.java[tags="refguide"]
+----
The table below summarizes the annotation's attributes.
.`@DomainService` attributes
-[cols="2,2,4a", options="header"]
+[cols="2,2,4a",options="header"]
|===
| Attribute
@@ -39,8 +41,6 @@ The instanceId for services is always "1".
|===
-
-
For example:
[source,java]
@@ -55,12 +55,6 @@ public class LoanRepository {
}
----
-
-
-
-
-
-
include::DomainService/nature.adoc[leveloffset=+1]
include::DomainService/objectType.adoc[leveloffset=+1]
include::DomainService/repositoryFor.adoc[leveloffset=+1]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainServiceLayout.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainServiceLayout.adoc
index 39c8844..c432616 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainServiceLayout.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainServiceLayout.adoc
@@ -11,11 +11,18 @@ The `@DomainServiceLayout` annotation applies to domain services, collecting tog
You will also find some additional material in the xref:vw:ROOT:layout.adoc#application-menu[object layout] chapter.
====
+The annotation is:
+
+[source,java]
+----
+include::refguide:applib-ant:example$annotation/DomainServiceLayout.java[tags="refguide"]
+----
+
The table below summarizes the annotation's attributes.
.`@DomainServiceLayout` attributes
-[cols="2,2,4a", options="header"]
+[cols="2,2,4a",options="header"]
|===
| Attribute
@@ -36,8 +43,6 @@ The table below summarizes the annotation's attributes.
|===
-
-
For example:
[source,java]
@@ -53,19 +58,11 @@ public class ToDoItems {
}
----
-
-
[NOTE]
====
Note that there is (currently) no support for specifying UI hints for domain services through the dynamic xref:vw:ROOT:layout.adoc#file-based[`.layout.xml`] file (only for properties, collections and actions are supported).
====
-
-
-
-
-
-
include::DomainServiceLayout/menuBar.adoc[leveloffset=+1]
include::DomainServiceLayout/menuOrder.adoc[leveloffset=+1]
include::DomainServiceLayout/named.adoc[leveloffset=+1]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Facets.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Facets.adoc
index 6bfa700..bd3fea8 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Facets.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Facets.adoc
@@ -4,8 +4,8 @@
-The `@Facets` annotation allows `FacetFactory` implementations and so can be used to run install arbitrary `Facet`s for a type. Generally this is not needed, but can be useful for overriding a custom programming model where a `FacetFactory` is not typically included.
-
+The `@Facets` annotation allows `FacetFactory` implementations and so can be used to run install arbitrary ``Facet``s for a type.
+ Generally this is not needed, but can be useful for overriding a custom programming model where a `FacetFactory` is not typically included.
[NOTE]
====
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/HomePage.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/HomePage.adoc
index b76864c..620e408 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/HomePage.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/HomePage.adoc
@@ -4,7 +4,8 @@
-The `@HomePage` annotation allows a _single_ (no-arg, query-only) action on a _single_ domain service to be nominated as the action to invoke for the default home page. This often returns a view model that acts as some sort of dashboard, presenting key information and makeing the most commonly used actions easy to invoke.
+The `@HomePage` annotation allows a _single_ (no-arg, query-only) action on a _single_ domain service to be nominated as the action to invoke for the default home page.
+This often returns a view model that acts as some sort of dashboard, presenting key information and makeing the most commonly used actions easy to invoke.
For example, the http://github.com/apache/isis-app-todoapp[TodoApp] uses `@HomePage` to return a dashboard of todo items to complete:
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Inject.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Inject.adoc
index 4cc79a5..a675894 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Inject.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Inject.adoc
@@ -1,4 +1,4 @@
-= `@Inject` (`javax`)
+r= `@Inject` (`javax`)
: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 [...]
@@ -7,10 +7,6 @@
Apache Isis automatically injects domain services into other domain services and also into domain objects and view models.
In fact, it also injects domain services into xref:testing:integtestsupport:about.adoc[integration tests] and xref:fixtures:ROOT:about.adoc[fixture scripts].
-[NOTE]
-====
-One omission: Apache Isis (currently) does not inject services into `o.a.i.applib.spec.Specification` instances (as used by xref:refguide:applib-ant:Property.adoc#mustSatisfy[`@Property#mustSatisfy`] and xref:refguide:applib-ant:Parameter.adoc#mustSatisfy[`@Parameter#mustSatisfy`] annotations.
-====
Apache Isis supports several syntaxes for injecting domain services.
The simplest uses the `@javax.inject.Inject` annotation on the field, as defined in link:https://jcp.org/en/jsr/detail?id=330[JSR-330].
@@ -30,8 +26,6 @@ public class Customer {
<1> an alternative implementation would be to implement `findRecentOrders()` as a xref:userguide:fun:programming-model.adoc#contributed-action[contributed action].
<2> we recommend default (rather than `private`) visibility so that unit tests can easily mock out the service
-
-
== Alternative syntaxes
Apache Isis also supports setter-based injection:
@@ -44,20 +38,9 @@ public class Customer {
}
----
-and also supports an additional syntax of using `inject...` as the prefix:
-
-[source,java]
-----
-public class Customer {
- ...
- public void injectOrderRepository(OrderRepository orderRepository) { /* ... */ }
-}
-----
Generally we recommend using `@javax.inject.Inject`; it involves less code, and is more immediately familiar to most Java developers.
-
-
== Injecting collection of services
It can sometimes be useful to have declared multiple implementations of a particular domain service.
@@ -98,10 +81,6 @@ An alternative and almost equivalent design would be to publish an event using t
This alternative design is used in the (non-ASF) link:https://platform.incode.org[Incode Platform^]'s poly module, for example.
====
-
-
-
-
== Manually injecting services
Apache Isis performs dependency injection when domain entities are recreated.
@@ -123,10 +102,8 @@ View models are created identically:
TodoAppDashboard dashboard = repositoryService.instantiate(TodoAppDashboard.class);
----
-
If you prefer, though, you can simply instantiate domain objects using "new" and then inject domain services manually using xref:refguide:applib-svc:ServiceRegistry.adoc[`ServiceRegistry`]:
-
[source,java]
----
Customer cust = new Customer();
@@ -135,8 +112,6 @@ serviceRegistry.injectServicesInto(cust);
repositoryService.persist(cust);
----
-
-
[NOTE]
====
Note that using either `FactoryService#instantiate(...)` or `RepositoryService#instantiate(...)` will also automatically initialize all fields to their default values, and will also fire a "created" lifecycle event.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/MemberGroupLayout.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/MemberGroupLayout.adoc
deleted file mode 100644
index ffeb430..0000000
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/MemberGroupLayout.adoc
+++ /dev/null
@@ -1,17 +0,0 @@
-= `@MemberGroupLayout`
-
-: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 [...]
-
-
-
-The `@MemberGroupLayout` annotation specifies how an object's properties and collections are grouped together into columns, also specifying the relative positioning of those columns. It works in conjunction with the xref:refguide:applib-ant:MemberOrder.adoc[`@MemberOrder`] annotation.
-
-The annotation defines four attributes:
-
-* `columnSpans()` -- of type `int[]` -- which specifies the relative column sizes of the three columns that render properties as well as a fourth column that renders only collections
-
-* `left()` -- of type `String[]` - that specifies the order of the property groups (inferred from `@MemberOrder#name()`) as applied to properties) in the left-most column
-
-* `middle()` -- of type `String[]` - that specifies the order of the property groups (if any) as applied to properties) in the middle column
-
-
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/MemberOrder.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/MemberOrder.adoc
index 580c001..28d9dcb 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/MemberOrder.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/MemberOrder.adoc
@@ -6,8 +6,11 @@
// TODO: v2: replace @MemberOrder#name() with @PropertyLayout#group(); replace @MemberOrder#sequence() with @PropertyLayout#sequence().
The `@MemberOrder` annotation is used to specify the relative order of domain object members, that is: properties, collections and actions.
-It works in conjunction with the xref:refguide:applib-ant:MemberGroupLayout.adoc[`@MemberGroupLayout`] annotation.
+[source,java]
+----
+include::refguide:applib-ant:example$annotation/MemberOrder.java[tags="refguide"]
+----
The annotation defines two attributes:
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/MinLength.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/MinLength.adoc
index 7a32622..50cdf7e 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/MinLength.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/MinLength.adoc
@@ -5,6 +5,10 @@
The `@MinLength` annotation is used to specify the minimum number of characters in a search of an xref:refguide:applib-cm:methods.adoc#autoComplete[`autoComplete...()`] supporting method.
+[source,java]
+----
+include::refguide:applib-ant:example$annotation/MinLength.java[tags="refguide"]
+----
For example:
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Mixin.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Mixin.adoc
index 972f403..49a4e09 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Mixin.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Mixin.adoc
@@ -11,10 +11,15 @@ However, mixins are also a convenient mechanism for grouping functionality even
For further discussion on using mixins, see xref:userguide:fun:building-blocks.adoc#mixins[mixins] in the user guide.
+[source,java]
+----
+include::refguide:applib-ant:example$annotation/Mixin.java[tags="refguide"]
+----
+
The table below summarizes the annotation's attributes.
.`@Mixin` attributes
-[cols="2,2,4a", options="header"]
+[cols="2,2,4a",options="header"]
|===
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/NotPersistent.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/NotPersistent.adoc
index fbaf275..701f8fd 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/NotPersistent.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/NotPersistent.adoc
@@ -9,8 +9,10 @@ Apache Isis also uses this annotation, though (currently) only in the very minim
[NOTE]
====
-Isis parses the `@NotPersistent` annotation from the Java source code; it does not query the JDO metamodel. This means that it the `@NotPersistent` annotation must be used rather than the equivalent `<field>` link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/fields_properties.html[XML metadata].
+Isis parses the `@NotPersistent` annotation from the Java source code; it does not query the JDO metamodel.
+This means that it the `@NotPersistent` annotation must be used rather than the equivalent `<field>` link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/fields_properties.html[XML metadata].
-Moreover, while JDO/DataNucleus will recognize annotations on either the field or the getter method, Apache Isis (currently) only inspects the getter method. Therefore ensure that the annotation is placed there.
+Moreover, while JDO/DataNucleus will recognize annotations on either the field or the getter method, Apache Isis (currently) only inspects the getter method.
+Therefore ensure that the annotation is placed there.
====
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Nullable.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Nullable.adoc
index e266304..c291b31 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Nullable.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Nullable.adoc
@@ -3,10 +3,8 @@
: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 [...]
-Apache Isis' defaults for properties and parameters is that they are mandatory unless otherwise stated. The
-`@javax.annotation.Nullable` annotation is recognized by Apache Isis for both properties and
-parameters as means to indicate that the property/parameter is not mandatory.
-
+Apache Isis' defaults for properties and parameters is that they are mandatory unless otherwise stated.
+The `@javax.annotation.Nullable` annotation is recognized by Apache Isis for both properties and parameters as means to indicate that the property/parameter is not mandatory.
For example:
@@ -33,20 +31,18 @@ public Customer updateName(@javax.annotation.Nullable final String name) {
Apache Isis does provide several other ways to specify optionality: using the
xref:refguide:applib-ant:Property.adoc#optionality[`@Property#optionality()`] /
-xref:refguide:applib-ant:Parameter.adoc#optionality[`@Parameter#optionality()`] annotation. For properties, the optionality
-can also be inferred from the xref:refguide:applib-ant:Column#allowsNull.adoc[`@Column#allowsNull()`] attribute.
+xref:refguide:applib-ant:Parameter.adoc#optionality[`@Parameter#optionality()`] annotation.
+For properties, the optionality can also be inferred from the xref:refguide:applib-ant:Column#allowsNull.adoc[`@Column#allowsNull()`] attribute.
[TIP]
====
See the
-xref:refguide:applib-ant:Property.adoc#optionality[`@Property#optionality()`] documentation for a much fuller discussion on
-the relationship between using the Apache Isis annotations vs
+xref:refguide:applib-ant:Property.adoc#optionality[`@Property#optionality()`] documentation for a much fuller discussion on the relationship between using the Apache Isis annotations vs
xref:refguide:applib-ant:Column#allowsNull.adoc[`@Column#allowsNull()`].
====
-If more than one method is specified then the framework will validate that there are no incompatibilities (and fail to
-boot otherwise). This can also be verified using the xref:refguide:mvn:validate.adoc[validate goal] of the Apache
-Isis Maven plugin.
+If more than one method is specified then the framework will validate that there are no incompatibilities (and fail to boot otherwise).
+This can also be verified using the xref:refguide:mvn:validate.adoc[validate goal] of the Apache Isis Maven plugin.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Parameter.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Parameter.adoc
index 896216b..69582fa 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Parameter.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Parameter.adoc
@@ -5,10 +5,15 @@
The `@Parameter` annotation applies to action parameters collecting together all domain semantics within a single annotation.
+[source,java]
+----
+include::refguide:applib-ant:example$annotation/Parameter.java[tags="refguide"]
+----
+
The table below summarizes the annotation's attributes.
-.`@Paramter` attributes
-[cols="2,2,4a", options="header"]
+.`@Parameter` attributes
+[cols="2,2,4a",options="header"]
|===
| Attribute
@@ -19,7 +24,7 @@ The table below summarizes the annotation's attributes.
|xref:refguide:applib-ant:Parameter.adoc#fileAccept[`fileAccept()`]
|Media type or file extension
|Hints the file type to be uploaded for xref:refguide:applib-cm:classes/value-types.adoc#Blob[`Blob`]
- or xref:refguide:applib-cm:classes/value-types.adoc#Clob[`Clob`]. +
+or xref:refguide:applib-cm:classes/value-types.adoc#Clob[`Clob`]. +
+
Note that this does not prevent the user from uploading some other file type; rather it merely defaults the file type in the file open dialog.
@@ -59,9 +64,6 @@ The table below summarizes the annotation's attributes.
|===
-
-
-
For example:
[source,java]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/ParameterLayout.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/ParameterLayout.adoc
index ba2bb8a..295aa9d 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/ParameterLayout.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/ParameterLayout.adoc
@@ -6,6 +6,11 @@
The `@ParameterLayout` annotation applies to action parameters, collecting together all UI hints within a single annotation.
+[source,java]
+----
+include::refguide:applib-ant:example$annotation/ParameterLayout.java[tags="refguide"]
+----
+
The table below summarizes the annotation's attributes.
.`@ParameterLayout` attributes
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/PersistenceCapable.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/PersistenceCapable.adoc
index 73c6266..cfc3eb0 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/PersistenceCapable.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/PersistenceCapable.adoc
@@ -10,18 +10,19 @@ Apache Isis also checks for this annotation, and if the `@PersistenceCapable#sch
[NOTE]
====
-Isis parses the `@PersistenceCapable` annotation from the Java source code; it does not query the JDO metamodel. This means that it the `@PersistenceCapable` annotation must be used rather than the equivalent `<class>` link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/class_mapping.html[XML metadata].
+Isis parses the `@PersistenceCapable` annotation from the Java source code; it does not query the JDO metamodel.
+This means that it the `@PersistenceCapable` annotation must be used rather than the equivalent `<class>` link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/class_mapping.html[XML metadata].
-Moreover, while JDO/DataNucleus will recognize annotations on either the field or the getter method, Apache Isis (currently) only inspects the getter method. Therefore ensure that the annotation is placed there.
+Moreover, while JDO/DataNucleus will recognize annotations on either the field or the getter method, Apache Isis (currently) only inspects the getter method.
+Therefore ensure that the annotation is placed there.
====
-
This value is used internally to generate a string representation of an objects identity (the `Oid`).
This can appear in several contexts, including:
* as the value of `Bookmark#getObjectType()` and in the `toString()` value of `Bookmark`
- (see xref:refguide:applib-svc:BookmarkService.adoc[`BookmarkService`])
- ** and thus in the "table-of-two-halves" pattern, as per the (non-ASF) link:https://platform.incode.org[Incode Platform^]'s poly module
+(see xref:refguide:applib-svc:BookmarkService.adoc[`BookmarkService`])
+** and thus in the "table-of-two-halves" pattern, as per the (non-ASF) link:https://platform.incode.org[Incode Platform^]'s poly module
* in the serialization of `OidDto` in the xref:refguide:schema:cmd[command] and xref:refguide:schema:about.adoc#ixn.adoc[interaction] schemas
* in the URLs of the xref:vro:ROOT:about.adoc[RestfulObjects viewer]
* in the URLs of the xref:vw:ROOT:about.adoc[Wicket viewer] (in general and in particular if xref:vw:ROOT:features.adoc#hints-and-copy-url[copying URLs])
@@ -31,7 +32,6 @@ This can appear in several contexts, including:
The actual format of the object type used by Apache Isis for the concatenation of `schema()` and `@PersistenceCapable#table()`.
If the `table()` is not present, then the class' simple name is used instead.
-
== Examples
For example:
@@ -56,7 +56,6 @@ public class AddressImpl {
has an object type of `custmgmt.Address`.
-
On the other hand:
[source,java]
@@ -69,8 +68,6 @@ public class AddressImpl {
does _not_ correspond to an object type, because the `schema` attribute is missing.
-
-
== Precedence
The rules of precedence for determining a domain object's object type are:
@@ -78,13 +75,11 @@ The rules of precedence for determining a domain object's object type are:
1. xref:refguide:applib-ant:Discriminator.adoc[`@Discriminator`]
2. `@DomainObject#objectType`
3. xref:refguide:applib-ant:PersistenceCapable.adoc[`@PersistenceCapable`], if at least the `schema` attribute is defined. +
-+
-If both `schema` and `table` are defined, then the value is "`schema.table`".
++ If both `schema` and `table` are defined, then the value is "`schema.table`".
If only `schema` is defined, then the value is "`schema.className`".
4. Fully qualified class name of the entity.
-
[TIP]
====
This might be obvious, but to make explicit: we recommend that you always specify an object type for your domain objects.
@@ -93,10 +88,8 @@ Otherwise, if you refactor your code (change class name or move package), then a
At best this will require a data migration in the database; at worst it could cause external clients accessing data through the xref:vro:ROOT:about.adoc[Restful Objects] viewer to break.
====
-
-
-
[NOTE]
====
-If the object type is not unique across all domain classes then the framework will fail-fast and fail to boot. An error message will be printed in the log to help you determine which classes have duplicate object tyoes.
+If the object type is not unique across all domain classes then the framework will fail-fast and fail to boot.
+An error message will be printed in the log to help you determine which classes have duplicate object tyoes.
====
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/PreDestroy.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/PreDestroy.adoc
index 7a88496..1e67028 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/PreDestroy.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/PreDestroy.adoc
@@ -16,10 +16,10 @@ The signature of the method is:
@PreDestroy <.>
public void deinit() { /* ... */ } <.>
----
+
<.> It is not necessary to annotate the method with xref:refguide:applib-ant:Programmatic.adoc[`@Programmatic`]; it will be automatically excluded from the Apache Isis metamodel.
<.> the method can have any name, but must have `public` visibility, and accept no arguments.
-
Other use cases include obtaining connections to external datasources, eg subscribing to an ActiveMQ router, say, or initializing/cleaning up a background scheduler such as Quartz.
See also xref:refguide:applib-ant:PostConstruct.adoc[`@PostConstruct`]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Programmatic.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Programmatic.adoc
index 8677aee..fbccefc 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Programmatic.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Programmatic.adoc
@@ -6,7 +6,8 @@
The `@Programmatic` annotation causes the method to be excluded completely from the Apache Isis metamodel.
This means it won't appear in any UI or more generally in serializations obtained using the metamodel, for example xref:refguide:applib-svc:XmlSnapshotService.adoc[snapshot]s.
-A common use-case is to ignore implementation-level artifacts. For example:
+A common use-case is to ignore implementation-level artifacts.
+For example:
[source,java]
----
@@ -20,7 +21,6 @@ public class Customer implements Comparable<Customer> {
}
----
-
Note that `@Programmatic` is not the same as `@Action(hidden=Where.EVERYWHERE)` or `@Property(hidden=Where.EVERYWHERE)` etc; it actually means that the class member will not be part of the Apache Isis metamodel.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Property.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Property.adoc
index 58d188d..f3410bf 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Property.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Property.adoc
@@ -7,6 +7,10 @@ The `@Property` annotation applies to properties collecting together all domain
It is also possible to apply the annotation to actions of domain services that are acting as contributed properties.
+[source,java]
+----
+include::refguide:applib-ant:example$annotation/Property.java[tags="refguide"]
+----
.`@Property` attributes
@@ -83,7 +87,7 @@ In many/most cases you should however use xref:refguide:applib-ant:Column.adoc[`
|allows arbitrary validation to be applied
-|xref:refguide:applib-ant:Property.adoc#notPersisted[`notPersisted()`]
+|xref:refguide:applib-ant:Property.adoc#mementoSerialization[`mementoSerialization()`]
|`true`, `false` +
(`false`)
|whether to exclude from snapshots. +
@@ -176,7 +180,7 @@ include::Property/fileAccept.adoc[leveloffset=+1]
include::Property/hidden.adoc[leveloffset=+1]
include::Property/maxLength.adoc[leveloffset=+1]
include::Property/mustSatisfy.adoc[leveloffset=+1]
-include::Property/notPersisted.adoc[leveloffset=+1]
+include::Property/mementoSerialization.adoc[leveloffset=+1]
include::Property/optionality.adoc[leveloffset=+1]
include::Property/projecting.adoc[leveloffset=+1]
include::Property/publishing.adoc[leveloffset=+1]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Property/notPersisted.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Property/mementoSerialization.adoc
similarity index 50%
rename from api/applib/src/main/adoc/modules/applib-ant/pages/Property/notPersisted.adoc
rename to api/applib/src/main/adoc/modules/applib-ant/pages/Property/mementoSerialization.adoc
index b5a7e50..adc8b25 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Property/notPersisted.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Property/mementoSerialization.adoc
@@ -1,5 +1,4 @@
-[[notPersisted]]
-= `notPersisted()`
+= `mementoSerialization`
: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:
@@ -7,14 +6,7 @@
-The (somewhat misnamed) `notPersisted` attribute indicates that the collection should be excluded from any snapshots generated by the xref:refguide:applib-svc:XmlSnapshotService.adoc[`XmlSnapshotService`].
-
-
-[WARNING]
-====
-This annotation does _not_ specify that a property is not persisted in the JDO/DataNucleus objectstore.
-See below for details as to how to additionally annotate the property for this.
-====
+The `mementoSerialization` attribute indicates whether the property should be included/excluded from any snapshots generated by the xref:refguide:applib-svc:XmlSnapshotService.adoc[`XmlSnapshotService`].
For example:
@@ -22,35 +14,13 @@ For example:
[source,java]
----
public class Order {
- @Property(notPersisted=true)
+ @Property(mementoSerialization=EXCLUDED)
public Order getPreviousOrder() {...}
public void setPreviousOrder(Order previousOrder) {...}
...
}
----
-Historically this annotation also hinted as to whether the property's value contents should be persisted in the object store.
-However, the JDO/DataNucleus objectstore does not recognize this annotation.
-Thus, to ensure that a property is actually not persisted, it should *also* be annotated with `@javax.jdo.annotations.NotPersistent`.
-
-For example:
-
-[source,java]
-----
-public class Order {
- @Property(notPersisted=true) // <1>
- @javax.jdo.annotations.NotPersistent // <2>
- public Order getPreviousOrder() {...}
- public void setPreviousOrder(Order previousOrder) {...}
- ...
-}
-----
-<1> ignored by Apache Isis
-<2> ignored by JDO/DataNucleus
-
-
-
-
Alternatively, if the property is derived, then providing only a "getter" will also work:
@@ -65,5 +35,5 @@ public class Order {
== See also
-This attribute is also supported for xref:refguide:applib-ant:Collection.adoc#notPersisted[collections].
+This attribute is also supported for xref:refguide:applib-ant:Collection.adoc#mementoSerializationp[collections].
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout.adoc
index 96a4622..618e65d 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout.adoc
@@ -5,6 +5,11 @@
The `@PropertyLayout` annotation applies to properties collecting together all UI hints within a single annotation.
+[source,java]
+----
+include::refguide:applib-ant:example$annotation/PropertyLayout.java[tags="refguide"]
+----
+
The table below summarizes the annotation's attributes.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Title.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Title.adoc
index 01135b2..15ad0be 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Title.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Title.adoc
@@ -3,7 +3,13 @@
: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 [...]
-The `@Title` annotation is used to indicate which property or properties make up the object title. If more than one property is used, the order can be specified (using the same Dewey-decimal notation as used by `@MemberOrder`) and the string to use between the components can also be specified.
+The `@Title` annotation is used to indicate which property or properties make up the object title.
+If more than one property is used, the order can be specified (using the same Dewey-decimal notation as used by `@MemberOrder`) and the string to use between the components can also be specified.
+
+[source,java]
+----
+include::refguide:applib-ant:example$annotation/Title.java[tags="refguide"]
+----
For example:
@@ -25,9 +31,7 @@ public void Customer {
could be used to create names of the style "Bloggs, Joe K."
-It is also possible to annotate reference properties; in this case the
-title will return the title of the referenced object (rather than, say,
-its string representation).
+It is also possible to annotate reference properties; in this case the title will return the title of the referenced object (rather than, say, its string representation).
An additional convention for `@Title` properties is that they are hidden in tables (in other words, it implies `@Property(where=Where.ALL_TABLES)`.
For viewers that support this annotation (for example, the Wicket viewer), this convention excludes any properties whose value is already present in the title column.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/ViewModel.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/ViewModel.adoc
index 75a84b0..29c1fa6 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/ViewModel.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/ViewModel.adoc
@@ -10,6 +10,11 @@ It's a synonym for using `@DomainObject(nature=VIEW_MODEL)`.
View models are not persisted to the database, instead their state is encoded within their identity (ultimately represented in the URL).
+[source,java]
+----
+include::refguide:applib-ant:example$annotation/ViewModel.java[tags="refguide"]
+----
+
For example:
[source,java]
@@ -44,7 +49,7 @@ See this xref:userguide:btb:about.adoc#view-model-instantiation[tip] for further
View models must have a no-arg constructor; this is used internally by the framework for subsequent "recreation".
The view model's memento will be derived from the value of the view model object's properties.
-Any xref:refguide:applib-ant:Property.adoc#notPersisted[`@Property#notPersisted()`] properties will be excluded from the memento, as will any properties excluded from the metamodel using xref:refguide:applib-ant:Programmatic.adoc[`@Programmatic`].
+Any xref:refguide:applib-ant:Property.adoc#mementoSerialization[`@Property#mementoSerialization`] properties will be excluded from the memento, as will any properties excluded from the metamodel using xref:refguide:applib-ant:Programmatic.adoc[`@Programmatic`].
Properties that are merely xref:refguide:applib-ant:Property.adoc#hidden[hidden] _are_ included in the memento.
View models, as defined by `@ViewModel` (or `@DomainObject(nature=VIEW_MODEL)` for that matter) have some limitations:
@@ -56,7 +61,6 @@ View models, as defined by `@ViewModel` (or `@DomainObject(nature=VIEW_MODEL)` f
However, these limitations do _not_ apply to xref:userguide:fun:programming-model.adoc#jaxb[JAXB] view models.
If you are using view models heavily, you may wish to restrict yourself to just the JAXB flavour.
-
[NOTE]
====
The `@ViewModel` does not allow the objectType to be specified, meaning that it is incompatible with the metamodel validation check ennabled by the xref:refguide:config:configuring-core.adoc#metamodel-validation[`explicitObjectType`] configuration property.
@@ -64,6 +68,4 @@ The `@ViewModel` does not allow the objectType to be specified, meaning that it
Instead, use xref:refguide:applib-ant:DomainObject.adoc#nature[`@DomainObject#nature()`] with `Nature.VIEW_MODEL`, and specify xref:refguide:applib-ant:DomainObject.adoc#objectType[`@DomainObject#objectType()`].
====
-
-
include::ViewModel/objectType.adoc[leveloffset=+1]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/ViewModelLayout.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/ViewModelLayout.adoc
index 6b4537a..a976088 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/ViewModelLayout.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/ViewModelLayout.adoc
@@ -3,14 +3,17 @@
: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 [...]
-The `@ViewModelLayout` annotation is identical to the xref:refguide:applib-ant:DomainObjectLayout.adoc[`@DomainObjectLayout`], but is provided
-for symmetry with domain objects that have been annotated using xref:refguide:applib-ant:ViewModel.adoc[`@ViewModel`] (rather than xref:refguide:applib-ant:DomainObject.adoc#nature[`@DomainObject(nature=VIEW_MODEL)`]).
+The `@ViewModelLayout` annotation is identical to the xref:refguide:applib-ant:DomainObjectLayout.adoc[`@DomainObjectLayout`], but is provided for symmetry with domain objects that have been annotated using xref:refguide:applib-ant:ViewModel.adoc[`@ViewModel`] (rather than xref:refguide:applib-ant:DomainObject.adoc#nature[`@DomainObject(nature=VIEW_MODEL)`]).
+[source,java]
+----
+include::refguide:applib-ant:example$annotation/ViewModelLayout.java[tags="refguide"]
+----
The table below summarizes the annotation's attributes.
.`@ViewModel` attributes
-[cols="2,2,4a", options="header"]
+[cols="2,2,4a",options="header"]
|===
| Attribute
@@ -78,10 +81,6 @@ A typical use case is if the desired name is a reserved Java keyword, such as `d
|===
-
-
-
-
For example:
[source,java]
@@ -97,20 +96,11 @@ public class CategoryPieChart { /* ... */ }
<1> this annotation is intended for use with `@ViewModel`.
If a view model has been specified using the equivalent xref:refguide:applib-ant:DomainObject.adoc#nature[`@DomainObject(nature=Nature.VIEW_MODEL)`], then we recommend you use xref:refguide:applib-ant:DomainObjectLayout.adoc[`@DomainObjectLayout`] instead.
-
[NOTE]
====
Note that there is (currently) no support for specifying UI hints for view models through the dynamic xref:vw:ROOT:layout.adoc#file-based[`.layout.xml`] file (only for properties, collections and actions are supported).
====
-
-
-
-
-
-
-
-
include::ViewModelLayout/cssClass.adoc[leveloffset=+1]
include::ViewModelLayout/cssClassFa.adoc[leveloffset=+1]
include::ViewModelLayout/cssClassUiEvent.adoc[leveloffset=+1]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/XmlJavaTypeAdapter.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/XmlJavaTypeAdapter.adoc
index 1776b72..95ba023 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/XmlJavaTypeAdapter.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/XmlJavaTypeAdapter.adoc
@@ -5,7 +5,8 @@
The JAXB `@XmlJavaTypeAdapter` annotation is used with the framework-provided
`PersistentEntityAdapter` to instruct JAXB to serialize references to persistent entities using the canonical
-`OidDto` complex type: the object's type and its identifier. This is the formal XML equivalent to the `Bookmark`
+`OidDto` complex type: the object's type and its identifier.
+This is the formal XML equivalent to the `Bookmark`
provided by the xref:refguide:applib-svc:BookmarkService.adoc[`BookmarkService`].
For example:
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/XmlRootElement.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/XmlRootElement.adoc
index 7965c14..1862fd6 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/XmlRootElement.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/XmlRootElement.adoc
@@ -28,11 +28,9 @@ This adapter converts any references to such domain entities using the `oidDto`
[TIP]
====
The memento string for view models is converted into a form compatible with use within a URL.
-This is performed by the xref:refguide:applib-svc:UrlEncodingService.adoc[`UrlEncodingService`], the default implementation of which simply encodes to base 64.
-If the view model XML graph is too large to be serialized to a string, then an alternative implementation (eg which maps XML strings to a GUID, say) can be configured using the technique described in xref:userguide:btb:about.adoc#replacing-default-service-implementations[here] in the user guide.
+This is performed by the xref:refguide:applib-svc:UrlEncodingService.adoc[`UrlEncodingService`], the default implementation of which simply encodes to base 64. If the view model XML graph is too large to be serialized to a string, then an alternative implementation (eg which maps XML strings to a GUID, say) can be configured using the technique described in xref:userguide:btb:about.adoc#replacing-default-service-implementations[here] in the user guide.
====
-
== Example
This example is taken from the http://github.com/apache/isis-app-todoapp[TodoApp]:
@@ -54,8 +52,6 @@ public class ToDoItemDto implements Dto {
<1> identifies this class as a view model and defines the root element for JAXB serialization
<2> using Project Lombok for getters and setters
-
-
== See also
Although (like any other viewmodel) a JAXB-annotated can have behaviour (actions) and UI hints, you may wish to keep the DTO "clean", just focused on specifying the data contract.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/partials/module-nav.adoc b/api/applib/src/main/adoc/modules/applib-ant/partials/module-nav.adoc
index 3fe625c..dc471f6 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/partials/module-nav.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/partials/module-nav.adoc
@@ -17,7 +17,6 @@
** xref:refguide:applib-ant:Facets.adoc[Facets]
** xref:refguide:applib-ant:HomePage.adoc[HomePage]
** xref:refguide:applib-ant:Inject.adoc[Inject]
-** xref:refguide:applib-ant:MemberGroupLayout.adoc[MemberGroupLayout]
** xref:refguide:applib-ant:MemberOrder.adoc[MemberOrder]
** xref:refguide:applib-ant:Mixin.adoc[Mixin]
** xref:refguide:applib-ant:NotPersistent.adoc[NotPersistent.]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/pages/LayoutService.adoc b/api/applib/src/main/adoc/modules/applib-svc/pages/LayoutService.adoc
index b49f662..9ab7492 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/pages/LayoutService.adoc
+++ b/api/applib/src/main/adoc/modules/applib-svc/pages/LayoutService.adoc
@@ -29,12 +29,11 @@ The `CURRENT` style corresponds to the layout already loaded for the domain clas
The other three styles allow the developer to choose how much metadata is to be specified in the XML, and how much (if any) will be obtained elsewhere, typically from annotations in the metamodel.
The table below summarises the choices:
-[cols="<.>,^.>,^.>,^.>",options="header"]
+[cols="<.>,^.>,^.>",options="header"]
.Styles
|===
| Style
-|xref:refguide:applib-ant:MemberGroupLayout.adoc[`@MemberGroupLayout`]
| xref:refguide:applib-ant:MemberOrder.adoc[`@MemberOrder`]
| xref:refguide:applib-ant:ActionLayout.adoc[`@ActionLayout`], xref:refguide:applib-ant:PropertyLayout.adoc[`@PropertyLayout`], xref:refguide:applib-ant:CollectionLayout.adoc[`@CollectionLayout`]
@@ -42,17 +41,14 @@ The table below summarises the choices:
|`COMPLETE`
|serialized as XML
|serialized as XML
-|serialized as XML
|`NORMALIZED`
|serialized as XML
-|serialized as XML
|not in the XML
|`MINIMAL`
-|serialized as XML
|not in the XML
|not in the XML