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 2015/05/20 06:37:33 UTC
[10/10] isis git commit: ISIS-1133: reference chapter (annotations,
mostly)
ISIS-1133: reference chapter (annotations, mostly)
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/74e29802
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/74e29802
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/74e29802
Branch: refs/heads/master
Commit: 74e2980219b4f6eac9e23d99d73dd15f438052a6
Parents: 11f68f5
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Wed May 20 00:34:45 2015 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Wed May 20 00:34:45 2015 +0100
----------------------------------------------------------------------
.../src/main/asciidoc/user-guide/1 | 17 +
.../main/asciidoc/user-guide/_/Aggregated.md | 13 +
.../src/main/asciidoc/user-guide/_/Defaulted.md | 15 +
.../src/main/asciidoc/user-guide/_/Encodable.md | 17 +
.../asciidoc/user-guide/_/EqualByContent.md | 16 +
.../user-guide/_/Exploration-deprecated.md | 24 +
.../asciidoc/user-guide/_/Mask-deprecated.md | 47 ++
.../user-guide/_/MemberGroups-deprecated.md | 7 +
.../asciidoc/user-guide/_/NotPersistable.md | 39 +
.../src/main/asciidoc/user-guide/_/Parseable.md | 21 +
.../src/main/asciidoc/user-guide/_/Value.md | 22 +
.../asciidoc/user-guide/_ug_appendices.adoc | 1 +
.../user-guide/_ug_appendices_addons.adoc | 17 +
.../_ug_appendices_addons_settings-module.adoc | 49 ++
.../user-guide/_ug_reference-annotations.adoc | 38 +
.../_ug_reference-annotations_aaa.adoc | 14 +
...ug_reference-annotations_aaa_deprecated.adoc | 328 ++++++++
.../_ug_reference-annotations_aaa_jee.adoc | 35 +
.../_ug_reference-annotations_aaa_main.adoc | 91 +++
.../_ug_reference-annotations_aaa_other.adoc | 56 ++
.../_ug_reference-annotations_aaa_partial.adoc | 43 +
...ug_reference-annotations_manpage-action.adoc | 623 +++++++++++++++
...erence-annotations_manpage-actionlayout.adoc | 634 +++++++++++++++
...eference-annotations_manpage-collection.adoc | 538 +++++++++++++
...ce-annotations_manpage-collectionlayout.adoc | 631 +++++++++++++++
...ug_reference-annotations_manpage-digits.adoc | 12 +
...erence-annotations_manpage-domainobject.adoc | 416 ++++++++++
...-annotations_manpage-domainobjectlayout.adoc | 569 +++++++++++++
...rence-annotations_manpage-domainservice.adoc | 170 ++++
...annotations_manpage-domainservicelayout.adoc | 159 ++++
...ug_reference-annotations_manpage-facets.adoc | 15 +
..._reference-annotations_manpage-homepage.adoc | 21 +
...ug_reference-annotations_manpage-inject.adoc | 15 +
...e-annotations_manpage-membergrouplayout.adoc | 8 +
...ference-annotations_manpage-memberorder.adoc | 127 +++
...reference-annotations_manpage-minlength.adoc | 36 +
...reference-annotations_manpage-parameter.adoc | 318 ++++++++
...nce-annotations_manpage-parameterlayout.adoc | 553 +++++++++++++
...erence-annotations_manpage-programmatic.adoc | 45 ++
..._reference-annotations_manpage-property.adoc | 767 ++++++++++++++++++
...ence-annotations_manpage-propertylayout.adoc | 801 +++++++++++++++++++
...rence-annotations_manpage-requestscoped.adoc | 15 +
..._ug_reference-annotations_manpage-title.adoc | 45 ++
...reference-annotations_manpage-viewmodel.adoc | 198 +++++
...nce-annotations_manpage-viewmodellayout.adoc | 500 ++++++++++++
.../user-guide/_ug_reference-classes.adoc | 13 +
...eference-classes_applib-utility-classes.adoc | 144 ++++
.../_ug_reference-classes_mixins.adoc | 11 +
.../_ug_reference-classes_superclasses.adoc | 52 ++
...ce-classes_superclasses_fixture-scripts.adoc | 8 +
.../_ug_reference-classes_value-types.adoc | 19 +
.../user-guide/_ug_reference-methods.adoc | 11 +
.../_ug_reference-methods_prefixes.adoc | 27 +
.../_ug_reference-methods_prefixes_aaa.adoc | 151 ++++
...eference-methods_prefixes_manpage-addTo.adoc | 8 +
...e-methods_prefixes_manpage-autoComplete.adoc | 8 +
...erence-methods_prefixes_manpage-choices.adoc | 8 +
...eference-methods_prefixes_manpage-clear.adoc | 8 +
...erence-methods_prefixes_manpage-default.adoc | 8 +
...erence-methods_prefixes_manpage-disable.adoc | 8 +
..._reference-methods_prefixes_manpage-get.adoc | 8 +
...reference-methods_prefixes_manpage-hide.adoc | 8 +
...ference-methods_prefixes_manpage-modify.adoc | 8 +
...nce-methods_prefixes_manpage-removeFrom.adoc | 8 +
..._reference-methods_prefixes_manpage-set.adoc | 8 +
...rence-methods_prefixes_manpage-validate.adoc | 8 +
...-methods_prefixes_manpage-validateAddTo.adoc | 8 +
...ods_prefixes_manpage-validateRemoveFrom.adoc | 8 +
.../_ug_reference-methods_reserved.adoc | 14 +
.../_ug_reference-methods_reserved_aaa.adoc | 126 +++
...rence-methods_reserved_manpage-cssClass.adoc | 8 +
...erence-methods_reserved_manpage-disable.adoc | 8 +
...eference-methods_reserved_manpage-getId.adoc | 8 +
...reference-methods_reserved_manpage-hide.adoc | 8 +
...rence-methods_reserved_manpage-iconName.adoc | 8 +
...eference-methods_reserved_manpage-title.adoc | 8 +
...rence-methods_reserved_manpage-validate.adoc | 8 +
.../user-guide/_ug_reference-services.adoc | 16 +
.../user-guide/_ug_reference-services_api.adoc | 30 +
.../_ug_reference-services_api_aaa.adoc | 215 +++++
...ces_api_manpage-ActionInvocationContext.adoc | 8 +
...-services_api_manpage-BackgroundService.adoc | 8 +
...ce-services_api_manpage-BookmarkService.adoc | 8 +
...rence-services_api_manpage-ClockService.adoc | 8 +
...nce-services_api_manpage-CommandContext.adoc | 8 +
...ce-services_api_manpage-DeepLinkService.adoc | 8 +
...vices_api_manpage-DomainObjectContainer.adoc | 8 +
...rence-services_api_manpage-EmailService.adoc | 8 +
...ce-services_api_manpage-EventBusService.adoc | 15 +
...-services_api_manpage-GuiceBeanProvider.adoc | 8 +
...nce-services_api_manpage-IsisJdoSupport.adoc | 129 +++
...nce-services_api_manpage-MementoService.adoc | 8 +
...e-services_api_manpage-MetamodelService.adoc | 8 +
...-services_api_manpage-QueryResultsCache.adoc | 8 +
...ference-services_api_manpage-ScratchPad.adoc | 8 +
...erence-services_api_manpage-SudoService.adoc | 8 +
...nce-services_api_manpage-WrapperFactory.adoc | 18 +
...services_api_manpage-XmlSnapshotService.adoc | 8 +
.../user-guide/_ug_reference-services_spi.adoc | 25 +
.../_ug_reference-services_spi_aaa.adoc | 214 +++++
...ce-services_spi_manpage-AuditingService.adoc | 13 +
...es_spi_manpage-BackgroundCommandService.adoc | 12 +
...vices_spi_manpage-ClassDiscoveryService.adoc | 8 +
...nce-services_spi_manpage-CommandService.adoc | 11 +
...vices_spi_manpage-ContentMappingService.adoc | 8 +
...s_spi_manpage-ContentNegotiationService.adoc | 8 +
...es_spi_manpage-EmailNotificationService.adoc | 8 +
...ce-services_spi_manpage-EventSerializer.adoc | 8 +
...ervices_spi_manpage-ExceptionRecognizer.adoc | 8 +
...nce-services_spi_manpage-LocaleProvider.adoc | 8 +
...-services_spi_manpage-PublishingService.adoc | 11 +
...services_spi_manpage-TranslationService.adoc | 8 +
...rvices_spi_manpage-TranslationsResolver.adoc | 8 +
...services_spi_manpage-UserProfileService.adoc | 8 +
...ces_spi_manpage-UserRegistrationService.adoc | 8 +
.../main/asciidoc/user-guide/_ug_reference.adoc | 25 -
.../user-guide/_ug_reference_addons.adoc | 17 -
.../_ug_reference_addons_settings-module.adoc | 49 --
.../user-guide/_ug_reference_annotations.adoc | 39 -
.../_ug_reference_annotations_aaa.adoc | 14 -
...ug_reference_annotations_aaa_deprecated.adoc | 328 --------
.../_ug_reference_annotations_aaa_jee.adoc | 35 -
.../_ug_reference_annotations_aaa_main.adoc | 91 ---
.../_ug_reference_annotations_aaa_other.adoc | 55 --
.../_ug_reference_annotations_aaa_partial.adoc | 43 -
...ug_reference_annotations_manpage_action.adoc | 8 -
...erence_annotations_manpage_actionlayout.adoc | 8 -
...eference_annotations_manpage_collection.adoc | 8 -
...ce_annotations_manpage_collectionlayout.adoc | 8 -
...ug_reference_annotations_manpage_digits.adoc | 8 -
...erence_annotations_manpage_domainobject.adoc | 8 -
..._annotations_manpage_domainobjectlayout.adoc | 8 -
...rence_annotations_manpage_domainservice.adoc | 8 -
...annotations_manpage_domainservicelayout.adoc | 8 -
...ug_reference_annotations_manpage_facets.adoc | 8 -
..._reference_annotations_manpage_homepage.adoc | 8 -
...ug_reference_annotations_manpage_inject.adoc | 8 -
...e_annotations_manpage_membergrouplayout.adoc | 8 -
...ference_annotations_manpage_memberorder.adoc | 8 -
...reference_annotations_manpage_minlength.adoc | 8 -
...reference_annotations_manpage_parameter.adoc | 8 -
...erence_annotations_manpage_programmatic.adoc | 8 -
..._reference_annotations_manpage_property.adoc | 8 -
...ence_annotations_manpage_propertylayout.adoc | 8 -
...rence_annotations_manpage_requestscoped.adoc | 8 -
..._ug_reference_annotations_manpage_title.adoc | 8 -
...reference_annotations_manpage_viewmodel.adoc | 8 -
...nce_annotations_manpage_viewmodellayout.adoc | 8 -
.../_ug_reference_applib-utility-classes.adoc | 144 ----
.../user-guide/_ug_reference_methods.adoc | 14 -
.../user-guide/_ug_reference_methods_aaa.adoc | 117 ---
.../_ug_reference_methods_manpage_cssClass.adoc | 8 -
.../_ug_reference_methods_manpage_getId.adoc | 8 -
.../_ug_reference_methods_manpage_iconName.adoc | 8 -
.../_ug_reference_methods_manpage_title.adoc | 8 -
.../user-guide/_ug_reference_mixins.adoc | 11 -
.../user-guide/_ug_reference_prefixes.adoc | 27 -
.../user-guide/_ug_reference_prefixes_aaa.adoc | 151 ----
.../_ug_reference_prefixes_manpage_addTo.adoc | 8 -
...reference_prefixes_manpage_autoComplete.adoc | 8 -
.../_ug_reference_prefixes_manpage_choices.adoc | 8 -
.../_ug_reference_prefixes_manpage_clear.adoc | 8 -
.../_ug_reference_prefixes_manpage_default.adoc | 8 -
.../_ug_reference_prefixes_manpage_disable.adoc | 8 -
.../_ug_reference_prefixes_manpage_get.adoc | 8 -
.../_ug_reference_prefixes_manpage_hide.adoc | 8 -
.../_ug_reference_prefixes_manpage_modify.adoc | 8 -
...g_reference_prefixes_manpage_removeFrom.adoc | 8 -
.../_ug_reference_prefixes_manpage_set.adoc | 8 -
..._ug_reference_prefixes_manpage_validate.adoc | 8 -
...eference_prefixes_manpage_validateAddTo.adoc | 8 -
...nce_prefixes_manpage_validateRemoveFrom.adoc | 8 -
.../user-guide/_ug_reference_services-api.adoc | 30 -
.../_ug_reference_services-api_aaa.adoc | 215 -----
..._services-api_action-invocation-context.adoc | 8 -
...ference_services-api_background-service.adoc | 8 -
...reference_services-api_bookmark-service.adoc | 8 -
...ug_reference_services-api_clock-service.adoc | 8 -
..._reference_services-api_command-context.adoc | 8 -
...eference_services-api_deep-link-service.adoc | 8 -
...ce_services-api_domain-object-container.adoc | 8 -
...ug_reference_services-api_email-service.adoc | 8 -
...eference_services-api_event-bus-service.adoc | 15 -
...erence_services-api_guice-bean-provider.adoc | 8 -
...reference_services-api_isis-jdo-support.adoc | 129 ---
..._reference_services-api_memento-service.adoc | 8 -
...eference_services-api_metamodel-service.adoc | 8 -
...erence_services-api_query-results-cache.adoc | 8 -
.../_ug_reference_services-api_scratch-pad.adoc | 8 -
..._ug_reference_services-api_sudo-service.adoc | 8 -
..._reference_services-api_wrapper-factory.adoc | 18 -
...rence_services-api_xml-snapshot-service.adoc | 8 -
.../user-guide/_ug_reference_services-spi.adoc | 25 -
.../_ug_reference_services-spi_aaa.adoc | 214 -----
...reference_services-spi_auditing-service.adoc | 13 -
...services-spi_background-command-service.adoc | 12 -
...ce_services-spi_class-discovery-service.adoc | 8 -
..._reference_services-spi_command-service.adoc | 11 -
...ce_services-spi_content-mapping-service.adoc | 8 -
...ervices-spi_content-negotiation-service.adoc | 8 -
...services-spi_email-notification-service.adoc | 8 -
...reference_services-spi_event-serializer.adoc | 8 -
...rence_services-spi_exception-recognizer.adoc | 8 -
..._reference_services-spi_locale-provider.adoc | 8 -
...ference_services-spi_publishing-service.adoc | 11 -
...erence_services-spi_translation-service.adoc | 8 -
...ence_services-spi_translations-resolver.adoc | 8 -
...rence_services-spi_user-profile-service.adoc | 8 -
..._services-spi_user-registration-service.adoc | 8 -
.../user-guide/_ug_reference_superclasses.adoc | 52 --
..._reference_superclasses_fixture-scripts.adoc | 8 -
.../user-guide/_ug_reference_value-types.adoc | 19 -
.../src/main/asciidoc/user-guide/ug.adoc | 10 +-
adocs/template/document.html.erb | 2 +-
.../applib/annotation/CommandPersistence.java | 6 -
.../isis/applib/annotation/MinLength.java | 7 +-
.../isis/applib/annotation/Parameter.java | 3 +
217 files changed, 9799 insertions(+), 2484 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/74e29802/adocs/documentation/src/main/asciidoc/user-guide/1
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/1 b/adocs/documentation/src/main/asciidoc/user-guide/1
new file mode 100644
index 0000000..6a752ec
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/1
@@ -0,0 +1,17 @@
+mv -- _ug_reference_services-spi.adoc _ug_reference-services_spi.adoc
+mv -- _ug_reference_services-spi_aaa.adoc _ug_reference-services_spi_aaa.adoc
+mv -- _ug_reference_services-spi_auditing-service.adoc _ug_reference-services_spi_auditing-service.adoc
+mv -- _ug_reference_services-spi_background-command-service.adoc _ug_reference-services_spi_background-command-service.adoc
+mv -- _ug_reference_services-spi_class-discovery-service.adoc _ug_reference-services_spi_class-discovery-service.adoc
+mv -- _ug_reference_services-spi_command-service.adoc _ug_reference-services_spi_command-service.adoc
+mv -- _ug_reference_services-spi_content-mapping-service.adoc _ug_reference-services_spi_content-mapping-service.adoc
+mv -- _ug_reference_services-spi_content-negotiation-service.adoc _ug_reference-services_spi_content-negotiation-service.adoc
+mv -- _ug_reference_services-spi_email-notification-service.adoc _ug_reference-services_spi_email-notification-service.adoc
+mv -- _ug_reference_services-spi_event-serializer.adoc _ug_reference-services_spi_event-serializer.adoc
+mv -- _ug_reference_services-spi_exception-recognizer.adoc _ug_reference-services_spi_exception-recognizer.adoc
+mv -- _ug_reference_services-spi_locale-provider.adoc _ug_reference-services_spi_locale-provider.adoc
+mv -- _ug_reference_services-spi_publishing-service.adoc _ug_reference-services_spi_publishing-service.adoc
+mv -- _ug_reference_services-spi_translation-service.adoc _ug_reference-services_spi_translation-service.adoc
+mv -- _ug_reference_services-spi_translations-resolver.adoc _ug_reference-services_spi_translations-resolver.adoc
+mv -- _ug_reference_services-spi_user-profile-service.adoc _ug_reference-services_spi_user-profile-service.adoc
+mv -- _ug_reference_services-spi_user-registration-service.adoc _ug_reference-services_spi_user-registration-service.adoc
http://git-wip-us.apache.org/repos/asf/isis/blob/74e29802/adocs/documentation/src/main/asciidoc/user-guide/_/Aggregated.md
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_/Aggregated.md b/adocs/documentation/src/main/asciidoc/user-guide/_/Aggregated.md
new file mode 100644
index 0000000..530e0e8
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_/Aggregated.md
@@ -0,0 +1,13 @@
+Title: @Aggregated
+
+[//]: # (content copied to _user-guide_xxx)
+
+
+> This annotation has partial/incomplete support.
+
+This annotation indicates that the object is aggregated, or wholly owned, by a root object.
+
+This information could in theory provide useful semantics for some object store implementations, eg to store the aggregated objects "inline". The JDO ObjectStore does *not* use this semantic, however.
+
+At the time of writing none of the viewers exploit this metadata.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/74e29802/adocs/documentation/src/main/asciidoc/user-guide/_/Defaulted.md
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_/Defaulted.md b/adocs/documentation/src/main/asciidoc/user-guide/_/Defaulted.md
new file mode 100644
index 0000000..e6132af
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_/Defaulted.md
@@ -0,0 +1,15 @@
+Title: @Defaulted
+
+[//]: # (content copied to _user-guide_xxx)
+
+> This annotation has partial/incomplete support.
+
+The concept of "defaulted" means being able to provide a default value
+for the type by way of the
+`org.apache.isis.applib.adapters.DefaultsProvider` interface. Generally
+this only applies to value types, where the `@Value` annotation implies encodability through the `ValueSemanticsProvider` interface.
+
+For these reasons the `@Defaulted` annotation is generally never applied
+directly, but can be thought of as a placeholder for future enhancements
+whereby non-value types might also have a default value provided for
+them.
http://git-wip-us.apache.org/repos/asf/isis/blob/74e29802/adocs/documentation/src/main/asciidoc/user-guide/_/Encodable.md
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_/Encodable.md b/adocs/documentation/src/main/asciidoc/user-guide/_/Encodable.md
new file mode 100644
index 0000000..9dc7496
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_/Encodable.md
@@ -0,0 +1,17 @@
+Title: @Encodable
+
+[//]: # (content copied to _user-guide_xxx)
+
+> This annotation has partial/incomplete support.
+
+> In particular, the Wicket viewer uses Apache Wicket's Converter API instead.
+
+Encodability means the ability to convert an object to-and-from a
+string, by way of the `org.apache.isis.applib.adapters.EncoderDecoder`
+interface. Generally this only applies to value types, where the `@Value`
+annotation implies encodability through the `ValueSemanticsProvider` interface.
+
+For these reasons the `@Encodable` annotation is generally never applied
+directly, but can be thought of as a placeholder for future enhancements
+whereby non-value types might also be directly encoded.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/74e29802/adocs/documentation/src/main/asciidoc/user-guide/_/EqualByContent.md
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_/EqualByContent.md b/adocs/documentation/src/main/asciidoc/user-guide/_/EqualByContent.md
new file mode 100644
index 0000000..7cae540
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_/EqualByContent.md
@@ -0,0 +1,16 @@
+Title: @EqualByContent
+
+[//]: # (content copied to _user-guide_xxx)
+
+> This annotation has partial/incomplete support.
+
+Equal-by-content is a characteristic of value types, and is implied by
+any class annotated with the the `@Value` annotation (see ? and also ?).
+
+The `@EqualByContent` annotation exists so that this semantic could, if
+required, by applied directly to an object without it necessarily also
+being annotated as a value.
+
+That said, this annotation is only really for completeness. Moreover,
+the semantic captured by this annotation is currently used by the
+framework (not in any object store nor viewer).
http://git-wip-us.apache.org/repos/asf/isis/blob/74e29802/adocs/documentation/src/main/asciidoc/user-guide/_/Exploration-deprecated.md
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_/Exploration-deprecated.md b/adocs/documentation/src/main/asciidoc/user-guide/_/Exploration-deprecated.md
new file mode 100644
index 0000000..4dead04
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_/Exploration-deprecated.md
@@ -0,0 +1,24 @@
+Title: @Exploration
+
+[//]: # (content copied to _user-guide_xxx)
+
+> Deprecated, use instead [@Action#restrictTo()](./Action.html).
+
+The `@Exploration` annotation marks an action method as available in
+exploration mode only, and therefore not intended for use in the
+production system.
+
+
+For example:
+
+ public class Customer {
+ public Order placeNewOrder() { ... }
+ @Exploration
+ public List<Order> listRecentOrders() { ... }
+ ...
+ }
+
+
+#### See also
+
+See also the [@Prototype](./Prototype-deprecated.html) annotation.
http://git-wip-us.apache.org/repos/asf/isis/blob/74e29802/adocs/documentation/src/main/asciidoc/user-guide/_/Mask-deprecated.md
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_/Mask-deprecated.md b/adocs/documentation/src/main/asciidoc/user-guide/_/Mask-deprecated.md
new file mode 100644
index 0000000..d2fbb88
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_/Mask-deprecated.md
@@ -0,0 +1,47 @@
+Title: @Mask
+
+[//]: # (content copied to _user-guide_xxx)
+
+> Deprecated, never supported.
+
+
+The `@Mask` annotation may be applied to any property, or to any
+parameter within an action method, that allows the user to type in text
+as input. It can also annotate a string-based value type, and thereby
+apply to all properties or parameters of that type.
+
+The mask serves to validate, and potentially to normalise, the format of
+the input. The characters that can be used are based on Swing's
+`javax.swing.text.MaskFormatter`, and also Java's
+`java.util.SimpleDateFormat`.
+
+For example, on a property:
+
+ public class Email {
+ @Mask("(NNN)NNN-NNNN")
+ public String getTelephoneNumber() {...}
+ public void setTelephoneNumber(String telNo) {...}
+ ...
+ }
+
+Or, on an action parameter:
+
+ public void ContactRepository {
+ public void newContact(
+ @Named("Contact Name") String contactName
+ ,@Mask("(NNN)NNN-NNNN")
+ @Named("Telephone Number") String telNo) {
+ ...
+ }
+ ...
+ }
+
+Or, on a value type:
+
+ @Value(...)
+ @MaxLength(30)
+ public class CustomerFirstName {
+ ...
+ }
+
+See also `@RegEx` annotation <!--, ?-->.
http://git-wip-us.apache.org/repos/asf/isis/blob/74e29802/adocs/documentation/src/main/asciidoc/user-guide/_/MemberGroups-deprecated.md
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_/MemberGroups-deprecated.md b/adocs/documentation/src/main/asciidoc/user-guide/_/MemberGroups-deprecated.md
new file mode 100644
index 0000000..3c90443
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_/MemberGroups-deprecated.md
@@ -0,0 +1,7 @@
+Title: @MemberGroups
+
+[//]: # (content copied to _user-guide_xxx)
+
+> Deprecated, use instead [@MemberGroupLayout](./MemberGroupLayout.html) or [dynamic layouts](../../components/viewers/wicket/dynamic-layouts.html).
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/74e29802/adocs/documentation/src/main/asciidoc/user-guide/_/NotPersistable.md
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_/NotPersistable.md b/adocs/documentation/src/main/asciidoc/user-guide/_/NotPersistable.md
new file mode 100644
index 0000000..79400da
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_/NotPersistable.md
@@ -0,0 +1,39 @@
+Title: @NotPersistable
+
+[//]: # (content copied to _user-guide_xxx)
+
+> This annotation has partial/incomplete support.
+
+> In particular, it is not supported by: Wicket viewer. [ISIS-743](https://issues.apache.org/jira/browse/ISIS-743) has been raised contemplating the removal of this annotation.
+
+The `@NotPersistable` annotation indicates that transient instances of
+this class may be created but may not be persisted. The framework will
+not provide the user with an option to 'save' the object, and attempting
+to persist such an object programmatically would be an error.
+
+For example:
+
+ public class InputForm {
+ // members and actions here
+ }
+
+This annotation can also take a single parameter indicating whether it
+is only the user that cannot persist the object, for example the
+following code would prevent the user from saving the object (via the
+viewer) but still allow the program to persist the object.
+
+For example:
+
+ @NotPersistable(By.USER)
+ public class InputForm {
+ ...
+ }
+
+The acceptable values for the parameter are:
+
+- `By.USER`
+
+- `By.USER_OR_PROGRAM`
+
+By default the annotated object is effectively transient (ie default to
+`By.USER_OR_PROGRAM`).
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/74e29802/adocs/documentation/src/main/asciidoc/user-guide/_/Parseable.md
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_/Parseable.md b/adocs/documentation/src/main/asciidoc/user-guide/_/Parseable.md
new file mode 100644
index 0000000..b06babe
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_/Parseable.md
@@ -0,0 +1,21 @@
+Title: @Parseable
+
+[//]: # (content copied to _user-guide_xxx)
+
+> This annotation has partial/incomplete support.
+
+> In particular, the Wicket viewer uses Apache Wicket's Converter API instead.
+
+Parseability means being able to parse a string representation into an
+object by way of the `org.apache.isis.applib.adapters.Parser` interface.
+Generally this only applies to value types, where the `@Value` annotation
+<!--(see ?)--> implies encodability through the `ValueSemanticsProvider`
+interface <!--(see ?)-->.
+
+For these reasons the `@Parser` annotation is generally never applied
+directly, but can be thought of as a placeholder for future enhancements
+whereby non-value types might also have be able to be parsed.
+
+> **Note**
+>
+> The `@AutoComplete` also allows objects to be looked up from a string represention.
http://git-wip-us.apache.org/repos/asf/isis/blob/74e29802/adocs/documentation/src/main/asciidoc/user-guide/_/Value.md
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_/Value.md b/adocs/documentation/src/main/asciidoc/user-guide/_/Value.md
new file mode 100644
index 0000000..6dccd2b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_/Value.md
@@ -0,0 +1,22 @@
+Title: @Value
+
+[//]: # (content copied to _user-guide_xxx)
+
+> This annotation has partial/incomplete support.
+
+The `@Value` annotation indicates that a class should be treated as a
+value type rather than as a reference (or entity) type. It does this
+providing an implementation of a
+`org.apache.isis.applib.adapters.ValueSemanticsProvider`.
+
+For example:
+
+ @Value(semanticsProviderClass=ComplexNumberValueSemanticsProvider.class)
+ public class ComplexNumber {
+ ...
+ }
+
+The `ValueSemanticsProvider` allows the framework to interact with the
+value, parsing strings and displaying as text, and encoding/decoding
+(for serialization).
+
http://git-wip-us.apache.org/repos/asf/isis/blob/74e29802/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices.adoc
index 7d016da..1f33ca0 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices.adoc
@@ -4,6 +4,7 @@
:_imagesdir: images/
+include::_ug_appendices_addons.adoc[leveloffset=+1]
include::_ug_appendices_dev-env.adoc[leveloffset=+1]
include::_ug_appendices_release-notes.adoc[leveloffset=+1]
include::_ug_appendices_migration-notes.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/74e29802/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_addons.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_addons.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_addons.adoc
new file mode 100644
index 0000000..b9ba7c3
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_addons.adoc
@@ -0,0 +1,17 @@
+= Isis Addons
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+This section highlights a number of the addons available at http://isisaddons.org[Isis Addons] website that do _not_ implement any of the Isis' SPIs. Note that it is _not_ intended to be comprehensive.
+
+[NOTE]
+====
+The http://isisaddons.org[Isis Addons], while maintained by Isis committers, are entirely independent of the Apache Software Foundation.
+====
+
+
+include::_ug_appendices_addons_settings-module.adoc[leveloffset=+1]
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/74e29802/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_addons_settings-module.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_addons_settings-module.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_addons_settings-module.adoc
new file mode 100644
index 0000000..8355192
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_addons_settings-module.adoc
@@ -0,0 +1,49 @@
+= Settings Services
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+The http://github.com/isisaddons/isis-module-settings}[Isis addons' settings] module provides a simple way to store both global (application-level) settings as well as per-user settings.
+
+The settings service is documented here for your convenience; the full README can be found on the http://github.com/isisaddons/isis-module-settings}[github site].
+
+
+== Application Settings
+
+=== API
+
+IMPORTANT: TODO
+
+=== Implementation
+
+In the case of `ApplicationSettingsService`, the service is implemented by `ApplicationSettingsServiceJdo`, with the `ApplicationSetting` interface implemented by a `ApplicationSettingsJdo` entity.
+
+The service also provides the ability to create list all existing settings, create new settings (of whichever datatype), update settings, and to delete settings.
+
+These actions can be hidden using security if need be.
+
+== User Settings
+
+=== API
+
+IMPORTANT: TODO
+
+=== Implementation
+
+In the case of `UserSettingsService`, the service is implemented by `UserSettingsServiceJdo`, with the `UserSetting` interface implemented by a `UserSettingsJdo` entity.
+
+As for application settings, the user settings service also provides the ability to create list all existing settings, create new settings (of whichever datatype), update settings, and to delete settings.
+
+These actions can be hidden using security if need be.
+
+
+== Registration and Configuration
+
+The `ApplicationSettingsServiceJdo` class and `UserSettingsServiceJdo` are annotated with `@DomainService` and so are automatically registered with the framework, with actions appearing on the secondary menu bar.
+
+IMPORTANT: TODO - screenshot of settings menu
+
+All actions from the services emit domain events. If you wish to hide/disable these default actions in your application, we recommend using up a subscriber on the actions' domain events to veto their visibility/usability.
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/74e29802/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations.adoc
new file mode 100644
index 0000000..527d88e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations.adoc
@@ -0,0 +1,38 @@
+= Reference: Annotations
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+IMPORTANT: TODO
+
+
+include::_ug_reference-annotations_aaa.adoc[leveloffset=+1]
+
+include::_ug_reference-annotations_manpage-Action.adoc[leveloffset=+1]
+include::_ug_reference-annotations_manpage-ActionLayout.adoc[leveloffset=+1]
+include::_ug_reference-annotations_manpage-Collection.adoc[leveloffset=+1]
+include::_ug_reference-annotations_manpage-Collectionlayout.adoc[leveloffset=+1]
+include::_ug_reference-annotations_manpage-DomainObject.adoc[leveloffset=+1]
+include::_ug_reference-annotations_manpage-DomainObjectLayout.adoc[leveloffset=+1]
+include::_ug_reference-annotations_manpage-DomainService.adoc[leveloffset=+1]
+include::_ug_reference-annotations_manpage-DomainServiceLayout.adoc[leveloffset=+1]
+include::_ug_reference-annotations_manpage-Parameter.adoc[leveloffset=+1]
+include::_ug_reference-annotations_manpage-ParameterLayout.adoc[leveloffset=+1]
+include::_ug_reference-annotations_manpage-Property.adoc[leveloffset=+1]
+include::_ug_reference-annotations_manpage-PropertyLayout.adoc[leveloffset=+1]
+include::_ug_reference-annotations_manpage-Viewmodel.adoc[leveloffset=+1]
+include::_ug_reference-annotations_manpage-ViewmodelLayout.adoc[leveloffset=+1]
+
+include::_ug_reference-annotations_manpage-Facets.adoc[leveloffset=+1]
+include::_ug_reference-annotations_manpage-HomePage.adoc[leveloffset=+1]
+include::_ug_reference-annotations_manpage-MemberGroupLayout.adoc[leveloffset=+1]
+include::_ug_reference-annotations_manpage-MemberOrder.adoc[leveloffset=+1]
+include::_ug_reference-annotations_manpage-MinLength.adoc[leveloffset=+1]
+include::_ug_reference-annotations_manpage-Programmatic.adoc[leveloffset=+1]
+include::_ug_reference-annotations_manpage-Title.adoc[leveloffset=+1]
+
+include::_ug_reference-annotations_manpage-Digits.adoc[leveloffset=+1]
+include::_ug_reference-annotations_manpage-Inject.adoc[leveloffset=+1]
+include::_ug_reference-annotations_manpage-RequestScoped.adoc[leveloffset=+1]
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/74e29802/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa.adoc
new file mode 100644
index 0000000..fef66c7
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa.adoc
@@ -0,0 +1,14 @@
+= Summary
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+include::_ug_reference-annotations_aaa_main.adoc[leveloffset=+1]
+include::_ug_reference-annotations_aaa_other.adoc[leveloffset=+1]
+include::_ug_reference-annotations_aaa_jee.adoc[leveloffset=+1]
+include::_ug_reference-annotations_aaa_deprecated.adoc[leveloffset=+1]
+include::_ug_reference-annotations_aaa_partial.adoc[leveloffset=+1]
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/74e29802/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_deprecated.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_deprecated.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_deprecated.adoc
new file mode 100644
index 0000000..15f22d6
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_deprecated.adoc
@@ -0,0 +1,328 @@
+= Deprecated Annotations
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+
+.Deprecated Annotations
+[cols="2,4a,3a,1,1", options="header"]
+|===
+|Annotation
+|Purpose
+|Use instead
+|Layer
+|`.layout +
+.json`?
+
+|`@ActionOrder`
+|Order of buttons and menu items representing actions.
+|`@MemberOrder`
+|UI
+|Yes
+
+|`@ActionInteraction`
+|Enable subscribers on the Event Bus Service to either veto, validate or take further steps before/after an action has been invoked.
+|`@Action#domainEvent()`
+|Domain
+|
+
+|`@ActionSemantics`
+|Query-only, idempotent or non-idempotent.
+|`@Action#semantics()`
+|Domain
+|
+
+|`@Audited`
+|Audit changes to an object.
+|`@DomainObject#` +
+`auditing()`
+|Domain
+|
+
+|`@AutoComplete`
+|Repository method to search for entities
+|`@DomainObject` +
+`#autoCompleteRepository()`
+|UI/Domain
+|
+
+|`@Bookmarkable`
+|Whether (and how) to create a bookmark for visited object.
+|`@DomainObjectLayout` +
+`#bookmarking()`
+|UI
+|
+
+|`@Bounded`
+|Bounded (and limited) number of instances of an entity type, translates into a drop-down for any property of that type.
+|`@DomainObject#bounded()`
+|Domain
+|
+
+|`@Bulk`
+|Indicates an action is a bulk action, can be applied to multiple instances.
+|`@Action#invokeOn()`
+|UI, Domain
+|
+
+|`@CollectionInteraction`
+|Enable subscribers on the Event Bus Service to either veto, validate or take further steps before/after a collection has been added to or removed from.
+|`@Collection#domainEvent()`
+|Domain
+|
+
+|`@Command`
+|Action invocation should be reified as a command object, optionally persistable for profiling and enhanced auditing, and background/async support.
+|`@Action#command()`
+|Domain
+|
+
+|`@CssClass`
+|Allow visual representation of individual objects or object members layout to be customized by application-specific CSS.
+|`#cssClass()` attribute for: `@DomainObjectLayout`, `@PropertyLayout`, `@CollectionLayout`, `@ActionLayout` and `@ParameterLayout`
+|UI
+|Yes
+
+|`@CssClassFa`
+|So that font awesome icons can be applied to action buttons/menu items and optionally as an object icon.
+|`@ActionLayout#cssClassFa()`
+|UI
+|Yes
+
+|`@Debug`
+|Action only invokable in debug mode.
+|Use prototype mode instead (`@Action#restrictTo()`)
+|UI
+|
+
+|`@DescribedAs`
+|Provide a longer description/tool-tip of an object or object member.
+|`#describedAs()` attribute for `@DomainObjectLayout`, `@PropertyLayout`, `@CollectionLayout`, `@ActionLayout` and `@ParameterLayout`
+|UI
+|Yes
+
+|`@Disabled`
+|Object property cannot be edited, an object collection cannot be added to/removed from, or an object action cannot be invoked.
+|`#editing()` attribute for `@Property` and `@Collection#editing()`; see also `@DomainObject`
+|UI, Domain
+|Yes
+
+|`@Exploration`
+|Action available in special 'exploration' mode.
+|`@Action#restrictTo()` (combines exploration and prototyping modes).
+|UI
+|
+
+|`@FieldOrder`
+|Order of properties and collections.
+|`@MemberOrder`
+|UI
+|Yes
+
+|`@Hidden`
+|Object member is not visible, or on domain service (to indicate that none of its actions are visible).
+|For domain object members, use `@Action#hidden()`, `@Property#hidden()` or `@Collection#hidden()`. +
+For domain service, use `@DomainService(nature=DOMAIN)`
+|UI, Domain
+|Yes
+
+|`@Idempotent`
+|Whether an action is idempotent (can be invoked multiple times with same post-condition).
+|`@Action#semantics`
+|Domain
+|
+
+|`@Ignore`
+|Exclude this method from the metamodel.
+|`@Programmatic`
+|Domain
+|
+
+|`@Immutable`
+|An object's state cannot be changed (properties cannot be edited, collections cannot be added to or removed from). Actions can still be invoked.
+|`@DomainObject#editing()`
+|Domain
+|
+
+|`@Mask`
+|How to parse/render values (never properly supported)
+|(None)
+|UI/domain
+|
+
+|`@MaxLength`
+|Maximum length of a property value (strings).
+|`#maxLength()` attribute for `@Property` or `@Parameter`
+|Domain
+|
+
+|`@MemberGroups`
+|Layout of properties and collections of a domain object or view model object.
+|`@MemberGroupLayout` or dynamic layout.
+|UI
+|Yes
+
+|`@MultiLine`
+|Render string property over multiple lines (a textarea rather than a textbox).
+|`#multiLine()` attribute for `@PropertyLayout` and`@ParameterLayout`
+|UI
+|Yes
+
+|`@MustSatisfy`
+|Specify arbitrary specification constraints on a property or action parameter.
+|`#mustSatisfy()` attribute for `@Property` and `@Parameter`
+|Domain
+|
+
+|`@Named`
+|Override name inferred from class. Required for parameter names (prior to Java8).
+|`#named()` attribute for `@DomainServiceLayout`, `@DomainObjectLayout`, `@PropertyLayout`, `@CollectionLayout`, `@ActionLayout` and `@ParameterLayout`
+|UI
+|Yes
+
+|`@NotContributed`
+|Indicates that a domain service action is not rendered as an action on the (entity) types of its parameters. For 1-arg query-only actions, controls whether the domain service action is rendered as a property or collection on the entity type of its parameter.
+|Use `@DomainService#nature()` to specify whether any of the actions in a domain service should appear in the menu bars (applies at type level, not action level).
+For individual actions, use `@ActionLayout` to specify whether any individual action should be contributed only as an action or as an association (property or collection).
+|UI
+|
+
+|`@NotInServiceMenu`
+|Indicates that a domain service should not be rendered in the application menu (at top of page in Wicket viewer).
+|`@DomainService#nature()` to specify none of the actions in a domain service should appear in the menu bars
+|UI
+|
+
+|`@NotPersisted`
+|Indicates that an object property is not persisted (meaning it is excluded from view model mementos, and should not be audited).
+|`@Property#notPersisted()`
+|Domain, Persistence
+|
+
+|`@ObjectType`
+|For constructing the external identifier (URI) of an entity instance (part of its URL in both Wicket viewer and Restful Objects viewer). Also part of the toString representation of bookmarks, if using the Bookmark Service
+|`@DomainObject#objectType()`
+|Domain
+|
+
+|`@Optional`
+|Specifies that a property or action parameter is not mandatory.
+|`#optionality()` attribute for `@Property` or `@Parameter`
+|Domain
+|
+
+|`@Paged`
+|Number of instances to display in tables representing (standalone or parented) collections.
+|`#paged()` attribute for `@DomainObjectLayout` or `@CollectionLayout`
+|UI
+|Yes
+
+|`@Plural`
+|For the irregular plural form of an entity type.
+|`@DomainObjectLayout#plural()`
+|UI
+|
+
+|`@PostsAction` +
+`InvokedEvent`
+|Post a domain event to the Event Bus Service indicating that an action has been invoked.
+|`@Action#domainEvent()`
+|Domain
+|
+
+|`@PostsCollection` +
+`AddedToEvent`
+|Post a domain event to the Event Bus Service indicating that an element has been added to a collection.
+|`@Collection#domainEvent()`
+|Domain
+|
+
+|`@PostsCollection` +
+`RemovedFromEvent`
+|Post a domain event to the Event Bus Service indicating that an element has been removed from a collection.
+|`@Collection#domainEvent()`
+|Domain
+|
+
+|`@PostsProperty` +
+`ChangedEvent`
+|Post a domain event to the Event Bus Service indicating that the value of a property has changed.
+|`@Property#domainEvent()`
+|Domain
+|
+
+|`@PropertyInteraction`
+|Enable subscribers on the Event Bus Service to either veto, validate or take further steps before/after a property has been modified or cleared.
+|`@Property#domainEvent()`
+|Domain
+|
+
+|`@Prototype`
+|Indicates that an action should only be visible in 'prototype' mode.
+|`@Action#restrictTo()`
+|UI
+|Yes
+
+|`@PublishedAction`
+|Action invocation should be serialized and published by configured PublishingService (if any), eg to other systems.|`@Action#publishing()`
+|Domain
+|
+
+|`@PublishedObject`
+|Change to object should be serialized and published by configured PublishingService (if any), eg to other systems.
+|`@DomainObject#publishing()`
+|Domain
+|
+
+|`@QueryOnly`
+|Whether an action is query-only (has no side-effects).
+|`@Action#semantics()`
+|Domain
+|
+
+|`@RegEx`
+|Validate change to value of string property.
+|`#regexPattern()` for `@Property` or `@Parameter`.
+|Domain
+|
+
+|`@Render`
+|Eagerly (or lazily) render the contents of a collection.
+|`@CollectionLayout#render()`
+|UI
+|Yes
+
+|`@RenderedAsDayBefore`
+|Render dates as the day before; ie store [a,b) internally but render [a,b-1]) to end-user.
+|`#renderedAsDayBefore()` attribute for `@PropertyLayout` and `@ParameterLayout`.
+|UI
+|
+
+|`@Resolve`
+|Eagerly (or lazily) render the contents of a collection (same as `@Render)`
+|`@CollectionLayout#render()`
+|UI
+|Yes
+
+|`@SortedBy`
+|Display instances in collections in the order determined by the provided Comparator.
+|`@CollectionLayout#sortedBy()`
+|UI
+|Yes
+
+|`@TypeOf`
+|The type of entity stored within a collection, or as the result of invoking an action, if cannot be otherwise inferred, eg from generics.
+|`#typeOf()` attribute for `@Collection` and `@Action`
+|Domain
+|
+
+|`@TypicalLength`
+|The typical length of a string property, eg to determine a sensible length for a textbox.
+|`#typicalLength()` attribute for `@PropertyLayout` and `@ParameterLayout`
+|UI
+|Yes
+
+|===
+
http://git-wip-us.apache.org/repos/asf/isis/blob/74e29802/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_jee.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_jee.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_jee.adoc
new file mode 100644
index 0000000..75015ff
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_jee.adoc
@@ -0,0 +1,35 @@
+= Java EE Annotations
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+.Java EE Annotations
+[cols="2,4a,1,1", options="header"]
+|===
+|Annotation
+|Purpose
+|Layer
+|`.layout +
+.json`?
+
+|<<__code_requestscoped_code_javax, `@javax.enterprise.context.RequestScoped`>>
+|Specify that a domain service has request-scope (rather than a singleton).
+|Domain
+|
+
+|<<__code_inject_code_javax, `@javax.inject.Inject`>>
+|Inject domain service into a domain object (entity or view model) or another domain service.
+|Domain
+|
+
+|<<__code_digits_code_javax, `@javax.validation.constraints.Digits`>>
+|Precision/scale for BigDecimal values.
+|Domain
+|
+
+|===
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/74e29802/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_main.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_main.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_main.adoc
new file mode 100644
index 0000000..cc44f08
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_main.adoc
@@ -0,0 +1,91 @@
+= Core annotations
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+.Core annotations for domain objects, services and members (as of 1.8.0)
+[cols="2,4a,1,1", options="header"]
+|===
+|Annotation
+|Purpose
+|Layer
+|`.layout +
+.json`?
+
+|<<__code_action_code, `@Action`>>
+|Domain semantics for actions
+|Domain
+|
+
+|<<__code_actionlayout_code, `@ActionLayout`>>
+|User interface hints for actions
+|UI
+|Yes
+
+|<<__code_collection_code, `@Collection`>>
+|Domain semantics for collections
+|Domain
+|
+
+|<<__code_collectionlayout_code, `@CollectionLayout`>>
+|User interface hints for collections
+|UI
+|Yes
+
+|<<__code_domainobject_code, `@DomainObject`>>
+|Domain semantics for domain object (entities and optionally view models, see also `@ViewModel)`
+|Domain
+|
+
+|<<__code_domainobjectlayout_code, `@DomainObjectLayout`>>
+|User interface hints for domain object (entities and optionally view models, see also `@ViewModelLayout)`
+|UI
+|Yes
+
+|<<__code_domainservice_code, `@DomainService`>>
+|Class is a domain service (rather than an entity or view model)
+|Domain
+|
+
+|<<__code_domainservicelayout_code, `@DomainServiceLayout`>>
+|User interface hints for domain services
+|UI
+|
+
+|<<__code_parameter_code, `@Parameter`>>
+|Domain semantics for action parameters
+|Domain
+|
+
+|<<__code_propertylayout_code, `@PropertyLayout`>>
+|Layout hints for an action parameter (currently: its label position either to top or the left).
+|UI
+|Yes
+
+|<<__code_property_code, `@Property`>>
+|Domain semantics for properties
+|Domain
+|
+
+|<<__code_propertylayout_code, `@PropertyLayout`>>
+|Layout hints for a property
+|UI
+|Yes
+
+|<<__code_viewmodel_code, `@ViewModel`>>
+|Specify that a class is a view model (as opposed to an entity or domain service); equivalent to `@DomainObject(nature`=VIEW_MODEL).
+|Domain, Persistence
+|
+
+|<<__code_ViewModelLayout_code, `@ViewModelLayout`>>
+|User interface hints for view models.
+For use with `@ViewModel`. If specifying view models using `@DomainObject(nature=VIEW_MODEL)` then use `@DomainObjectLayout`)
+|UI
+|Yes
+
+|===
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/74e29802/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_other.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_other.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_other.adoc
new file mode 100644
index 0000000..0339f33
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_other.adoc
@@ -0,0 +1,56 @@
+= Other Isis Annotations
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+.Other Isis Annotations
+[cols="2,4a,1,1", options="header"]
+|===
+|Annotation
+|Purpose
+|Layer
+|`.layout +
+.json`?
+
+|<<__code_facets_code, `@Facets`>>
+|Install arbitrary facets within the Isis metamodel.
+|(any)
+|
+
+|<<__code_homepage_code, `@HomePage`>>
+|Query-only action (on domain service) to be invoked, result of which is rendered as the user's home page.
+|UI
+|
+
+|<<__code_membergrouplayout_code, `@MemberGroupLayout`>>
+|Grouping of properties into groups, and organizing of properties, collections into columns.
+|UI
+|Yes
+
+
+|<<__code_memberorder_code, `@MemberOrder`>>
+|Ordering of properties, collections and actions, and also associating actions with either a property or a collection.
+|UI
+|Yes
+
+
+|<<__code_minlength_code, `@MinLength`>>
+|Minimum number of characters required for an auto-complete search argument.
+|UI
+|
+
+
+|<<__code_programmatic_code, `@Programmatic`>>
+|Ignore a public method, excluded from the Isis metamodel.
+|Domain
+|
+
+|<<__code_title_code, `@Title`>>
+|Indicates which of the object's properties should be used to build up a title for the object.
+|UI
+
+|===
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/74e29802/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_partial.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_partial.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_partial.adoc
new file mode 100644
index 0000000..cbc33ad
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_partial.adoc
@@ -0,0 +1,43 @@
+= Incomplete/partial support
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+.Annotations with incomplete/partial support
+[cols="2,4a,1", options="header"]
+|===
+|Annotation
+|Purpose
+|Layer
+
+|`@Aggregated`
+|Part of an aggregate root
+|Domain, Persistence
+
+|`@Defaulted`
+|Indicates that a (value) class has a default value.
+|Domain
+
+|`@Encodable`
+|Indicates that a (value) class can be serialized/encoded.
+|Persistence
+
+|`@EqualByContent`
+|Indicates that a value class has equality semantics.
+|Domain
+
+|`@NotPersistable`
+|Indicates that a domain object may not be programmatically persisted (partly supported).
+|Domain, Persistence
+
+|`@Parseable`
+|Indicates that a (value) class can be reconstructed from a string.
+|UI, Domain
+
+|`@Value`
+|Specify that a class has value-semantics.
+|Domain
+
+|===
http://git-wip-us.apache.org/repos/asf/isis/blob/74e29802/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-action.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-action.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-action.adoc
new file mode 100644
index 0000000..a3eee9d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-action.adoc
@@ -0,0 +1,623 @@
+= anchor:reference-annotations_manpage-[]`@Action`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+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,4", options="header"]
+|===
+
+| Attribute
+| Values (default)
+| Description
+
+
+|xref:__a_id_reference_annotations_manpage_action_a_command[`command()`]
+|`AS_CONFIGURED`, `ENABLED`, `DISABLED` +
+(`AS_CONFIGURED`)
+|whether the action invocation should be reified into a `org.apache.isis.applib.services.command.Command` object.
+
+|`commandExecuteIn()`
+|`FOREGROUND`,`BACKGROUND` +
+(`FOREGROUND`)
+|whether to execute the command immediately, or to persist it (assuming that an appropriate implementation of `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 `CommandService` has been configured).
+
+
+
+|xref:__a_id_reference_annotations_manpage_action_a_domainevent[`domainEvent()`]
+|subtype of `ActionDomainEvent` +
+(`ActionDomainEvent.Default`)
+|the event type to be posted to the <<__code_eventbusservice_code, `EventBusService`>> to broadcast the action's business rule checking (hide, disable, validate) and its invocation (pre-execute and post-execution).
+
+
+|xref:__a_id_reference_annotations_manpage_action_a_hidden[`hidden()`]
+|`true`,`false` +
+(`false`)
+|indicates where (in the UI) the action is not visible to the user.
+
+
+|xref:__a_id_reference_annotations_manpage_action_a_invokeon[`invokeOn()`]
+|`OBJECT_ONLY`, `COLLECTION_ONLY`, `OBJECT_AND_COLLECTION` +
+(`OBJECT_ONLY`)
+|whether an action can be invoked on a single object and/or on many objects in a collection.
+
+
+|xref:__a_id_reference_annotations_manpage_action_a_publishing[`publishing()`]
+|`AS_CONFIGURED`, `ENABLED`, `DISABLED` +
+(`AS_CONFIGURED`)
+|whether changes to the object should be published to the registered link:../publishing-service.html[publishing service].
+
+|`publishingPayloadFactory()`
+|subtype of `PublishingPayloadFactoryForAction` (none)
+|specifies that a custom implementation of `PublishingPayloadFactoryForAction` be used to create the (payload of the) published event
+
+
+|xref:__a_id_reference_annotations_manpage_action_a_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:__a_id_reference_annotations_manpage_action_a_semantics[`semantics()`]
+|`QUERY`, `IDEMPOTENT`, `NON_IDEMPOTENT` +
+(`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)
+
+|xref:__a_id_reference_annotations_manpage_action_a_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)
+
+|===
+
+
+
+
+
+
+== anchor:reference-annotations_manpage-Action[]Command
+
+Using `@Action(command=...)` allows an action invocation to be made into a concrete object such that it can be inspected and persisted, for various purposes. These include enhanced profiling/auditing, as well as being able to defer the execution of the action and have it be invoked in the background.
+
+The annotation works (and influences the behaviour of) the `CommandContext`, `CommandService`, `BackgroundService` and `BackgroundCommandService` domain services (documented link:../../../reference/services/command-context.html[here] and link:../../../reference/services/background-service.html[here]).
+
+By default, actions are invoked in directly in the thread of the invocation.
+
+Each action invocation is reified by the `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` service is configured (for example the link:../../../components/objectstores/jdo/services/command-service-jdo.html[CommandServiceJdo] JDO implementation), then the `Command` itself is persisted.
+
+If the `BackgroundService` is configured, then commands can be invoked by means of a separate background process. If an appropriate `BackgroundCommandService` service is configured (for example, the link:../../../components/objectstores/jdo/services/background-command-service-jdo.html[BackgroundCommandServiceJdo] JDO implementation), then the background command is persisted.
+
+=== `command()`
+
+The `command()` attribute determines whether the action invocation should be reified into a `Command` object (by the `CommandContext` service).
+
+The default is `AS_CONFIGURED`, meaning that the configuration property:
+
+[source,ini]
+----
+isis.services.command.actions
+----
+
+IMPORTANT: TODO - document this property in the runtime configuration chapter
+
+is used to determine the whether the action is reified:
+
+* `all` - all actions are reified
+* `ignoreSafe` (or `ignoreQueryOnly`) - actions with safe (read-only) semantics are ignored, but actions which may modify data are not ignored
+* `none` - no actions are reifired.
+
+This default can be overridden on an action-by-action basis; if `command()` is set to `ENABLED` then the action is reified irrespective of the configured value; if set to `DISABLED` then the action is NOT reified irrespective of the configured value.
+
+The `@Action(command=...)` annotation can be annotated on action methods, to influence this behaviour:
+
+[source,java]
+----
+public class Order {
+ @Action(command=CommandReification.ENABLED)
+ public Invoice generateInvoice(...) { ... }
+}
+----
+
+corresponds to the behaviour described above; the `Command` object is persisted (assuming an appropriate `CommandService` is defined, and executed immediately in the foreground).
+
+
+
+=== `commandPersistence()`
+
+If the action has been reified, then the `commandPersistence()` attribute determines whether that `Command` object
+should then also be persisted (the default), or not persisted, or only if hinted.
+
+To explain this last alternative:
+
+[source,java]
+----
+public class Order {
+ @Action(
+ command=CommandReification.ENABLED,
+ commandPersistence=CommandPersistence.IF_HINTED)
+ public Invoice generateInvoice(...) { ... }
+}
+----
+
+will suppress the persistence of the `Command` object _unless_ a child background `Command` has been created in the body of the action by way of the `BackgroundService`.
+
+Next:
+
+[source,java]
+----
+public class Order {
+ @Command(
+ command=CommandReification.ENABLED,
+ commandExecuteIn=CommandExecuteIn.FOREGROUND,
+ commandPersistence=CommandPersistence.NOT_PERSISTED)
+ public Invoice generateInvoice(...) { ... }
+
+}
+----
+
+will prevent the parent `Command` object from being persisted, _even if_ a child background `Command` is created.
+
+
+=== `commandExecuteIn()`
+
+For persisted commands, the `commandExecuteIn()` attribute determines whether the `Command` should be executed in the
+foreground (the default) or executed in the background.
+
+Background execution means that the command is not executed immediately, but is available for a configured
+link:../services/background-service.html[background service] to execute, eg by way of an in-memory scheduler such as Quartz.
+
+For example:
+
+[source,java]
+----
+public class Order {
+ @Action(
+ command=CommandReification.ENABLED,
+ commandExecuteIn=CommandExecuteIn.BACKGROUND)
+ public Invoice generateInvoice(...) { ... }
+}
+----
+
+will result in the `Command` being persisted but its execution deferred to a background execution mechanism. The
+returned object from this action is the persisted `Command` itself.
+
+
+[NOTE]
+====
+Replaces the deprecated `@Command` annotation.
+====
+
+
+
+
+
+== anchor:reference-annotations_manpage-Action[]domainEvent()
+
+Every interaction with a domain object action causes multiple events to be fired, in the following phases:
+
+* Hide phase: to check that the action is visible (has not been hidden)
+* Disable phase: to check that the action is usable (has not been disabled)
+* Validate phase: to check that the action's arguments are valid
+* Pre-execute phase: before the invocation of the action
+* Post-execute: after the invocation of the action
+
+
+
+Subscribers subscribe through the link:../services/event-bus-service.html[Event Bus Service]
+using Guava annotations and can influence each of these phases.
+
+By default the event raised is `ActionDomainEvent.Default`. For example:
+
+[source,java]
+----
+public class ToDoItem {
+ ...
+ @Action()
+ public ToDoItem completed() { ... }
+}
+----
+
+
+Optionally a subclass can be declared:
+
+[source,java]
+----
+public class ToDoItem {
+
+ public static class CompletedEvent extends AbstractActionDomainEvent {
+ private static final long serialVersionUID = 1L;
+ public CompletedEvent(
+ final ToDoItem source,
+ final Identifier identifier,
+ final Object... arguments) {
+ super("completed", source, identifier, arguments);
+ }
+ }
+
+ @Action(domainEvent=CompletedEvent.class)
+ public ToDoItem completed() { ... }
+
+}
+----
+
+
+=== Subscribers
+
+Subscribers (which must be domain services) subscribe using the Guava API.
+Subscribers can be either coarse-grained (if they subscribe to the top-level event type):
+
+[source,java]
+----
+@DomainService
+public class SomeSubscriber {
+ @Programmatic
+ @com.google.common.eventbus.Subscribe
+ public void on(ActionInteractionEvent ev) {
+ ...
+ }
+}
+----
+
+or can be fine-grained by subscribing to specific event subtypes:
+
+[source,java]
+----
+@DomainService
+public class SomeSubscriber {
+ @Programmatic
+ @com.google.common.eventbus.Subscribe
+ public void on(ToDoItem.CompletedEvent ev) {
+ ...
+ }
+}
+----
+
+The subscriber's method is called (up to) 5 times:
+
+* whether to veto visibility (hide)
+* whether to veto usability (disable)
+* whether to veto execution (validate)
+* steps to perform prior to the action being invoked.
+* steps to perform after the action has been invoked.
+
+The subscriber can distinguish these by calling `ev.getEventPhase()`. Thus the general form is:
+
+[source,java]
+----
+@Programmatic
+@com.google.common.eventbus.Subscribe
+public void on(ActionInteractionEvent ev) {
+ switch(ev.getPhase()) {
+ case HIDE:
+ ...
+ break;
+ case DISABLE:
+ ...
+ break;
+ case VALIDATE:
+ ...
+ break;
+ case EXECUTING:
+ ...
+ break;
+ case EXECUTED:
+ ...
+ break;
+ }
+}
+----
+
+[IMPORTANT]
+====
+TODO: Axon framework annotations also supported
+====
+
+
+Vetoing is performed by calling the appropriate method on the event:
+
+* To hide:
+
+`ev.hide()`
+
+or
+
+`ev.veto("")`
+
+* To disable:
+
+`ev.disable("...");`
+
+or
+
+`ev.veto("...");`
+
+* To invalidate:
+
+`ev.invalidate("...");`
+
+or
+
+`ev.veto("...");`
+
+It is also possible to abort the transaction during the executing or executed
+phases by throwing an exception. If the exception is a subtype of `RecoverableException`
+then the exception will be rendered as a user-friendly warning (eg Growl/toast)
+rather than an error.
+
+=== Raising events programmatically.
+
+Normally events are only raised for interactions through the UI. However, events can be raised programmatically by
+wrapping the target object using the link:../services/wrapper-factory.html[Wrapper Factory] service.
+
+
+[NOTE]
+====
+Replaces the deprecated `@ActionInteraction` annotation.
+====
+
+
+
+
+
+
+
+
+== anchor:reference-annotations_manpage-Action[]`hidden()`
+
+Actions can be hidden at the domain-level, indicating that they are not visible to the end-user. For example:
+
+[source,java]
+----
+public class Customer {
+
+ @Action(hidden=EVERYWHERE)
+ public void updateStatus() { ... }
+ ...
+}
+----
+
+The only value that currently makes sense is `EVERYWHERE` (or its synonym `ANYWHERE`).
+
+
+
+=== See also
+
+It is also possible to use `@ActionLayout` or link:../../components/viewers/wicket/dynamic-layouts.html[dynamic layouts]
+such that the action can be hidden at the view layer. Both options are provided with a view that in the future the
+view-layer semantics may be under the control of (expert) users, whereas domain-layer semantics cannot be overridden
+or modified by the user.
+
+For `DomainService` actions, the action's visibility is dependent upon its `DomainService#nature()` and for contributed
+actions on how it is `ActionLayout#contributed()`.
+
+
+
+
+
+
+== anchor:reference-annotations_manpage-Action[]`invokeOn()`
+
+Indicates whether the an action can be invoked on a single object (the default) and/or on many objects in a collection.
+
+For example:
+
+[source]
+----
+public class ToDoItem {
+ ...
+ @Action(invokeOn=InvokeOn.OBJECT_AND_COLLECTION)
+ public void markAsCompleted() {
+ setCompleted(true);
+ }
+}
+----
+
+
+Actions to be invoked on collection (currently) have a number of constraints:
+
+* It must take no arguments
+* It cannot be hidden (any annotations or supporting methods to that effect will be ignored
+* It cannot be disabled (any annotations or supporting methods to that effect will be ignored).
+
+
+The example given above is probably ok, because `setCompleted()` is most likely idempotent. However, if the action also called some other method, then we should add a guard.
+
+For example, rather than:
+
+[source,java]
+----
+ @Action(invokeOn=InvokeOn.OBJECT_AND_COLLECTION)
+ public void markAsCompleted() {
+ setCompleted(true);
+ todoTotalizer.incrementNumberCompleted();
+ }
+----
+
+the action should instead be written:
+
+[source,java]
+----
+ @Action(invokeOn=InvokeOn.OBJECT_AND_COLLECTION)
+ public void markAsCompleted() {
+ if(isCompleted()) {
+ return;
+ }
+ setCompleted(true);
+ todoTotalizer.incrementNumberCompleted();
+ }
+----
+
+
+Note also that this attribute has no meaning if annotated on an action of a domain service.
+
+[NOTE]
+====
+Replaces the deprecated `@Bulk` annotation.
+====
+
+
+
+
+
+
+
+== anchor:reference-annotations_manpage-Action[]Publishing
+
+Publishing (to the registered implementation of a `PublishingService` is managed by the `publishing()` and `publishingPayloadFactory()` attributes.
+
+
+=== `publishing()`
+
+Indicates whether the action invocation should be published to the link:../publishing-service.html[publishing service].
+
+The default is `AS_CONFIGURED`, meaning that the configuration property:
+
+[source,ini]
+----
+isis.services.publish.actions
+----
+
+[IMPORTANT]
+====
+TODO: document this setting in runtime configuration
+====
+
+
+is used to determine the whether the action is published:
+
+* `all` - all actions are published
+* `ignoreSafe` (or `ignoreQueryOnly`) - actions with safe (read-only) semantics are ignored, but actions which may modify data are not ignored
+* `none` - no actions are published
+
+This default can be overridden on an action-by-action basis; if `command()` is set to `ENABLED` then the action is reified irrespective of the configured value; if set to `DISABLED` then the action is NOT reified irrespective of the configured value.
+
+=== `publishingPayloadFactory()`
+
+The `publishingPayloadFactory()` specifies the class to use to create the (payload of the) event to be published by the publishing factory.
+Rather than simply broadcast that the action was invoked, the payload factory allows a "fatter" payload to be isntantiated
+that can eagerly push commonly-required information to all subscribers. For at least some subscribers this should avoid
+the necessity to query back for additional information.
+
+
+[NOTE]
+====
+Replaces the deprecated `@PublishedAction` annotation.
+====
+
+
+
+
+
+
+== anchor:reference-annotations_manpage-Action[]`restrictTo()`
+
+Whether the action is restricted to prototyping.
+
+By default there are no restrictions, with the action being available in all environments.
+
+
+The `@Prototype` annotation marks an action method as available in
+prototype mode only, and therefore not intended for use in the
+production system.
+
+For example:
+
+[source]
+----
+public class Customer {
+ public Order placeNewOrder() { ... }
+ @Action(restrictTo=RestrictTo.PROTOTYPING)
+ public List<Order> listRecentOrders() { ... }
+ ...
+}
+----
+
+
+
+[NOTE]
+====
+Replaces the deprecated `@Exploration` and `@Prototype` annotations.
+====
+
+
+
+
+
+
+
+== anchor:reference-annotations_manpage-Action[]`semantics()`
+
+This annotation, which applies only to actions, describes whether the
+invocation is safe (as no side-effects), is idempotent (may have
+side-effects but always has the same post-conditions), or is neither safe
+nor idempotent. If the annotation is missing then the framework assumes
+non-idempotent.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ @Action(semantics=SemanticsOf.SAFE)
+ public CreditRating checkCredit() { ... }
+
+ @Action(semantics=SemanticsOf.IDEMPOTENT)
+ public void changeOfAddress(Address address) { ... }
+
+ @Action(semantics=SemanticsOf.NON_IDEMPOTENT)
+ public Order placeNewOrder() { ... }
+ ...
+}
+----
+
+The annotation was introduced for the restfulobjects viewer in order
+that action invocations could be made available using either HTTP GET,
+PUT or POST (respectively). It is now also used in core runtime's
+in-built concurrency checking; the invocation of a safe action does not
+perform a concurrency check, whereas non-safe actions do perform a
+concurrency check.
+
+
+[NOTE]
+====
+This attribute replaces the deprecated `@QueryOnly` and `Idempotent` annotations and also the `@ActionSemantics` annotation.
+====
+
+
+
+
+
+
+
+== anchor:reference-annotations_manpage-Action[]`typeOf()`
+
+Specifies the type-of the elements returned by the action (returning a collection), when for whatever reason the type cannot be inferred from the generic type, or to provide a hint about the actual run-time (as opposed to compile-time) type.
+
+
+For example:
+
+[source]
+----
+public void AccountService {
+ @Action(typeOf=Customer.class)
+ public List errantAccounts() {
+ return CustomerDatabase.allNewCustomers();
+ }
+ ...
+}
+----
+
+[NOTE]
+====
+Replaces the deprecated `@TypeOf` annotation.
+====
+