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/06/12 15:19:14 UTC
[5/5] isis git commit: ISIS-1133: domain service SPIs; mixins;
tidying up remainder to get into state for publishing (albeit not
complete, but good enough)
ISIS-1133: domain service SPIs; mixins; tidying up remainder to get into state for publishing (albeit not complete, but good enough)
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/84e85548
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/84e85548
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/84e85548
Branch: refs/heads/master
Commit: 84e85548367f15fa93cd84a24b65f5381868e2a6
Parents: aeed114
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Fri Jun 12 14:15:53 2015 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Fri Jun 12 14:15:53 2015 +0100
----------------------------------------------------------------------
README.md | 56 +--
adocs/documentation/monitor.rb | 6 +-
.../_ug_appendices_dev-env_intellij.adoc | 5 +-
.../_ug_appendices_migration-notes.adoc | 240 +++++++++++
.../_ug_appendices_release-notes.adoc | 2 +-
.../user-guide/_ug_core-concepts_add-ons.adoc | 31 +-
.../_ug_core-concepts_building-blocks.adoc | 178 +-------
...re-concepts_framework-provided-services.adoc | 87 ++--
..._core-concepts_other-deployment-options.adoc | 2 +-
...core-concepts_principles_apache-isis-vs.adoc | 5 +-
.../_ug_core-concepts_principles_your-apps.adoc | 8 +-
.../asciidoc/user-guide/_ug_deployment_gae.adoc | 416 +------------------
.../user-guide/_ug_deployment_jvm-flags.adoc | 10 -
.../user-guide/_ug_deployment_tomcat.adoc | 22 +-
.../_ug_extending_programming-model.adoc | 6 +-
...ding_programming-model_custom-validator.adoc | 2 +-
..._extending_programming-model_finetuning.adoc | 8 +-
.../_ug_extending_restfulobjects-viewer.adoc | 120 ++----
...g_wicket-viewer_replacing-page-elements.adoc | 11 +-
..._ug_getting-started_simpleapp-archetype.adoc | 10 +-
...dless-access_BackgroundCommandExecution.adoc | 33 +-
.../main/asciidoc/user-guide/_ug_how-tos.adoc | 12 +-
.../user-guide/_ug_how-tos_business-rules.adoc | 22 +-
...w-tos_class-structure_action-parameters.adoc | 14 +-
...ow-tos_class-structure_class-definition.adoc | 4 +-
..._ug_how-tos_class-structure_collections.adoc | 5 +-
...aged-1-to-m-bidirectional-relationships.adoc | 64 ---
...ow-tos_class-structure_ignoring-methods.adoc | 4 +-
...how-tos_class-structure_inject-services.adoc | 14 +-
...lass-structure_properties-vs-parameters.adoc | 3 +-
.../_ug_how-tos_class-structure_properties.adoc | 5 +-
.../_ug_how-tos_contributed-members.adoc | 55 ++-
.../asciidoc/user-guide/_ug_how-tos_crud.adoc | 10 +-
.../user-guide/_ug_how-tos_derived-members.adoc | 28 +-
.../user-guide/_ug_how-tos_domain-services.adoc | 154 ++++++-
.../_ug_how-tos_drop-downs-and-defaults.adoc | 42 +-
.../_ug_how-tos_entity-relationships.adoc | 7 +-
...aged-1-to-m-bidirectional-relationships.adoc | 58 +++
.../user-guide/_ug_how-tos_ui-hints.adoc | 7 +-
...g_how-tos_ui-hints_action-icons-and-css.adoc | 17 +-
.../user-guide/_ug_how-tos_ui-hints_layout.adoc | 8 +-
...how-tos_ui-hints_names-and-descriptions.adoc | 17 +-
...ow-tos_ui-hints_object-titles-and-icons.adoc | 10 +-
.../user-guide/_ug_isis-addons-modules.adoc | 135 ------
..._ug_isis-addons-modules_devutils-module.adoc | 74 ----
..._ug_isis-addons-modules_settings-module.adoc | 132 ------
.../user-guide/_ug_isis-in-pictures.adoc | 60 +--
.../asciidoc/user-guide/_ug_more-advanced.adoc | 2 +-
.../_ug_more-advanced_assembling.adoc | 12 -
...d_assembling_overriding-jdo-annotations.adoc | 55 ---
...-advanced_assembling_vetoing-visibility.adoc | 9 -
.../_ug_more-advanced_bulk-actions.adoc | 3 +-
.../_ug_more-advanced_decoupling.adoc | 4 +-
..._ug_more-advanced_decoupling_db-schemas.adoc | 18 +-
.../_ug_more-advanced_decoupling_event-bus.adoc | 128 +-----
...ore-advanced_decoupling_pushing-changes.adoc | 140 +++++++
...-advanced_decoupling_vetoing-visibility.adoc | 15 +
.../user-guide/_ug_more-advanced_i18n.adoc | 255 +-----------
.../_ug_more-advanced_mapping-rdbms-views.adoc | 3 +-
.../_ug_more-advanced_multi-tenancy.adoc | 2 +-
...ore-advanced_overriding-jdo-annotations.adoc | 55 +++
.../_ug_more-advanced_tips-n-tricks.adoc | 8 +-
...ore-advanced_tips-n-tricks_are-you-sure.adoc | 19 +-
...ore-advanced_tips-n-tricks_enhance-only.adoc | 8 +-
...-advanced_tips-n-tricks_per-user-themes.adoc | 5 +-
...-tricks_render-all-properties-in-tables.adoc | 9 +-
...tricks_simulating-collections-of-values.adoc | 8 +-
...s-n-tricks_suppress-actions-from-the-ui.adoc | 14 -
...g_more-advanced_transactions-and-errors.adoc | 10 +-
.../_ug_more-advanced_view-models.adoc | 9 +-
...e-annotations_manpage-Action_restrictTo.adoc | 2 +-
.../_ug_reference-classes_mixins.adoc | 48 ++-
.../user-guide/_ug_reference-classes_super.adoc | 2 +-
...classes_utility_manpage-ObjectContracts.adoc | 3 -
...eference-object-layout_application-menu.adoc | 4 +-
...ference-object-layout_static-vs-dynamic.adoc | 2 +
.../_ug_reference-object-layout_static.adoc | 11 +-
.../user-guide/_ug_reference-services-api.adoc | 2 +-
...rence-services-api_manpage-ClockService.adoc | 4 +-
...nce-services-api_manpage-WrapperFactory.adoc | 6 +-
.../user-guide/_ug_reference-services-spi.adoc | 16 +-
...ce-services-spi_manpage-AuditingService.adoc | 2 +-
...es-spi_manpage-BackgroundCommandService.adoc | 2 +-
...vices-spi_manpage-ClassDiscoveryService.adoc | 3 +-
...nce-services-spi_manpage-CommandService.adoc | 2 +-
...s-spi_manpage-ContentNegotiationService.adoc | 18 +-
...vices-spi_manpage-RepresentationService.adoc | 106 +++++
...services-spi_manpage-TranslationService.adoc | 2 +-
...services-spi_manpage-UserProfileService.adoc | 58 +--
...ces-spi_manpage-UserRegistrationService.adoc | 65 +--
.../user-guide/_ug_restfulobjects-viewer.adoc | 2 +-
.../_ug_restfulobjects-viewer_features.adoc | 2 +-
...ug_restfulobjects-viewer_hints-and-tips.adoc | 5 +
.../main/asciidoc/user-guide/_ug_runtime.adoc | 5 +-
...me_application-specific_application-css.adoc | 4 +-
...ime_application-specific_application-js.adoc | 3 +-
.../_ug_runtime_configuration-files.adoc | 49 ---
...me_configuration-files_deployment-types.adoc | 14 -
.../_ug_runtime_configuring-core.adoc | 52 ++-
.../_ug_runtime_configuring-datanucleus.adoc | 2 +-
...s_disabling-persistence-by-reachability.adoc | 20 +-
...atanucleus_eagerly-registering-entities.adoc | 12 +-
...time_configuring-datanucleus_properties.adoc | 8 +-
...ring-datanucleus_using-jndi-data-source.adoc | 6 +-
.../_ug_runtime_deployment-types.adoc | 12 +
.../_ug_runtime_specifying-components.adoc | 72 ++++
.../user-guide/_ug_runtime_web-xml.adoc | 17 +-
.../_ug_security_api-for-applications.adoc | 7 +-
...security_configuring-isis-to-use-bypass.adoc | 6 +-
..._security_configuring-isis-to-use-shiro.adoc | 2 +-
...shiro-isis-enhanced-wildcard-permission.adoc | 4 +-
.../_ug_security_shiro-isis-ldap-realm.adoc | 14 +-
.../_ug_security_shiro-jdbc-realm.adoc | 2 -
...ug_testing_fixture-scripts_sudo-service.adoc | 2 +-
...esting_unit-test-support_contract-tests.adoc | 4 +-
.../user-guide/_ug_tutorials_pet-clinic.adoc | 22 +-
...tutorials_stop-scaffolding-start-coding.adoc | 8 +-
..._wicket-viewer_customisation_about-page.adoc | 2 +-
...wicket-viewer_features_bookmarked-pages.adoc | 7 +-
...et-viewer_features_file-upload-download.adoc | 9 +-
...cket-viewer_features_hints-and-copy-url.adoc | 11 +-
..._ug_wicket-viewer_features_recent-pages.adoc | 3 +-
.../user-guide/_ug_wicket-viewer_layout.adoc | 2 +-
.../images/isis-in-pictures/010-login.png | Bin 0 -> 53308 bytes
.../isis-in-pictures/020-install-fixtures.png | Bin 0 -> 84507 bytes
.../030-dashboard-view-model.png | Bin 0 -> 118239 bytes
.../isis-in-pictures/040-domain-entity.png | Bin 0 -> 100818 bytes
.../isis-in-pictures/050-edit-property.png | Bin 0 -> 97649 bytes
.../isis-in-pictures/060-invoke-action.png | Bin 0 -> 118082 bytes
.../isis-in-pictures/065-contributions.png | Bin 0 -> 108489 bytes
.../isis-in-pictures/067-contributed-action.png | Bin 0 -> 25914 bytes
.../isis-in-pictures/070-pluggable-views.png | Bin 0 -> 123721 bytes
.../images/isis-in-pictures/080-gmap3-view.png | Bin 0 -> 789875 bytes
.../isis-in-pictures/090-fullcalendar2-view.png | Bin 0 -> 97057 bytes
.../100-excel-view-and-docx.png | Bin 0 -> 76401 bytes
.../images/isis-in-pictures/110-docx.png | Bin 0 -> 61616 bytes
.../images/isis-in-pictures/120-auditing.png | Bin 0 -> 94736 bytes
.../images/isis-in-pictures/130-security.png | Bin 0 -> 99024 bytes
.../images/isis-in-pictures/140-i18n.png | Bin 0 -> 85032 bytes
.../images/isis-in-pictures/150-appsettings.png | Bin 0 -> 78960 bytes
.../isis-in-pictures/160-switch-tenancy.png | Bin 0 -> 78881 bytes
.../images/isis-in-pictures/170-me.png | Bin 0 -> 78866 bytes
.../isis-in-pictures/180-app-user-entity.png | Bin 0 -> 121847 bytes
.../isis-in-pictures/190-switch-theme.png | Bin 0 -> 107121 bytes
.../images/isis-in-pictures/200-rest-api.png | Bin 0 -> 94725 bytes
.../isis-in-pictures/210-fixture-scripts.png | Bin 0 -> 19918 bytes
.../isis-in-pictures/220-testing-happy-case.png | Bin 0 -> 5934 bytes
.../230-testing-wrapper-factory.png | Bin 0 -> 7216 bytes
.../isis-in-pictures/240-domain-events.png | Bin 0 -> 4313 bytes
.../250-domain-event-subscriber.png | Bin 0 -> 3350 bytes
.../isis-in-pictures/260-domain-event-test.png | Bin 0 -> 27515 bytes
.../service-collaborations.png | Bin 0 -> 10368 bytes
.../service-collaborations.pptx | Bin 0 -> 52460 bytes
.../UserProfileService/todoapp.png | Bin 0 -> 65234 bytes
...configure-shiro-to-use-custom-jdbc-realm.png | Bin 0 -> 33149 bytes
.../configure-shiro-to-use-shiro-jdbc-realm.png | Bin 33149 -> 0 bytes
.../src/main/asciidoc/user-guide/ug.adoc | 35 +-
.../services/publish/PublishingService.java | 6 +-
images/010-login.png | Bin 53308 -> 0 bytes
images/020-install-fixtures.png | Bin 84507 -> 0 bytes
images/030-dashboard-view-model.png | Bin 118239 -> 0 bytes
images/040-domain-entity.png | Bin 100818 -> 0 bytes
images/050-edit-property.png | Bin 97649 -> 0 bytes
images/060-invoke-action.png | Bin 118082 -> 0 bytes
images/065-contributions.png | Bin 108489 -> 0 bytes
images/067-contributed-action.png | Bin 25914 -> 0 bytes
images/070-pluggable-views.png | Bin 123721 -> 0 bytes
images/080-gmap3-view.png | Bin 789875 -> 0 bytes
images/090-fullcalendar2-view.png | Bin 97057 -> 0 bytes
images/100-excel-view-and-docx.png | Bin 76401 -> 0 bytes
images/110-docx.png | Bin 61616 -> 0 bytes
images/120-auditing.png | Bin 94736 -> 0 bytes
images/130-security.png | Bin 99024 -> 0 bytes
images/140-i18n.png | Bin 85032 -> 0 bytes
images/150-appsettings.png | Bin 78960 -> 0 bytes
images/160-switch-tenancy.png | Bin 78881 -> 0 bytes
images/170-me.png | Bin 78866 -> 0 bytes
images/180-app-user-entity.png | Bin 121847 -> 0 bytes
images/190-switch-theme.png | Bin 107121 -> 0 bytes
images/200-rest-api.png | Bin 94725 -> 0 bytes
images/210-fixture-scripts.png | Bin 19918 -> 0 bytes
images/220-testing-happy-case.png | Bin 5934 -> 0 bytes
images/230-testing-wrapper-factory.png | Bin 7216 -> 0 bytes
images/240-domain-events.png | Bin 4313 -> 0 bytes
images/250-domain-event-subscriber.png | Bin 3350 -> 0 bytes
images/260-domain-event-test.png | Bin 27515 -> 0 bytes
186 files changed, 1596 insertions(+), 2203 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/84e85548/README.md
----------------------------------------------------------------------
diff --git a/README.md b/README.md
index 175d675..3720bf3 100644
--- a/README.md
+++ b/README.md
@@ -17,19 +17,19 @@ The todoapp also integrates with a number of other [Isis Addons](http://www.isis
Apache Isis integrates with [Apache Shiro](http://shiro.apache.org)™. The core framework supports file-based realms, while the Isis Addons [security module](http://github.com/isisaddons/isis-module-security) provides a well-features subdomain of users, roles and permissions against features derived from the Isis metamodel. The example todoapp integrates with the security module.
-
+
### Install Fixtures
Apache Isis has lots of features to help you prototype and then fully test your application. One such are fixture scripts, which allow pre-canned data to be installed in the running application. This is great to act as the starting point for identifying new stories; later on when the feature is being implemented, the same fixture script can be re-used within that feature's integration tests. (More on tests later).
-
+
### Dashboard and View Models
Most of the time the end-user interacts with representations of persistent domain entities, but Isis also supports view models which can aggregate data from multiple sources. The todoapp example uses a "dashboard" view model to list todo items not yet done vs those completed.
-
+
In general we recommend to initially focus only on domain entities; this will help drive out a good domain model. Later on view models can be introduced in support of specific use cases.
@@ -37,7 +37,7 @@ In general we recommend to initially focus only on domain entities; this will he
The screenshot below is of the todoapp's `ToDoItem` domain entity. Like all web pages, this UI is generated at runtime, directly from the domain object itself. There are no controllers or HTML to write.
-
+
In addition to the domain entity, Apache Isis allows layout metadata hints to be provided, for example to specify the grouping of properties, the positioning of those groups into columns, the association of actions (the buttons) with properties or collections, the icons on the buttons, and so on. This metadata can be specified either as annotations or in JSON form; the benefit of the latter is that it can be updated (and the UI redrawn) without restarting the app.
@@ -47,7 +47,7 @@ Any production-ready app will require this metadata but (like the view models di
By default properties on domain entities are editable, meaning they can be changed directly. In the todoapp example, the `ToDoItem`'s description is one such editable property:
-
+
Note that some of the properties are read-only even in edit mode; individual properties can be made non-editable. It is also possible to make all properties disabled and thus enforce changes only through actions (below).
@@ -55,7 +55,7 @@ Note that some of the properties are read-only even in edit mode; individual pro
The other way to modify an entity is to an invoke an action. In the screenshot below the `ToDoItem`'s category and subcategory can be updated together using an action:
-
+
There are no limitations on what an action can do; it might just update a single object, it could update multiple objects. Or, it might not update any objects at all, but could instead perform some other activity, such as sending out email or printing a document.
@@ -67,33 +67,33 @@ As an alternative to placing actions (business logic) on a domain object, it can
In the screenshot below the highlighted "export as xml" action, the "relative priority" property (and "previous" and "next" actions) and also the "similar to" collection are all contributed:
-
+
Contributions are defined by the signature of the actions on the contributing service. The code snippet below shows how this works for the "export as xml" action:
-
+
## Extensible Views
The Apache Isis viewer is implemented using [Apache Wicket](http://wicket.apache.org)™, and has been architected to be extensible. For example, when a collection of objects is rendered, this is just one several views, as shown in the selector drop-down:
-
+
The Isis Addons' [gmap3 component](https://github.com/isisaddons/isis-wicket-gmap3) will render any domain entity (such as `ToDoItem`) that implements its `Locatable` interface:
-
+
Simiarly the Isis Addons' [fullcalendar2 component](https://github.com/isisaddons/isis-wicket-fullcalendar2) will render any domain entity (such as `ToDoItem`) that implements its `Calendarable` interface:
-
+
Yet another "view" (though this one is rather simpler is that provided by the Isis Addons [excel component](https://github.com/isisaddons/isis-wicket-excel). This provides a download button to the table as a spreadsheet:
-
+
The screenshot above also shows an "export to Word" action. This is *not* a view but instead is a (contributed) action that uses the Isis Addons [docx module](https://github.com/isisaddons/isis-module-docx) to perform a "mail-merge":
-
+
## Security, Auditing and other Services
@@ -101,25 +101,25 @@ As well as providing extensions to the UI, the Isis addons provides a rich set o
Under the activity menu are four sets of services which provide support for [user session logging/auditing](https://github.com/isisaddons/isis-module-sessionlogger), [command profiling](https://github.com/isisaddons/isis-module-command), [(object change) auditing](https://github.com/isisaddons/isis-module-audit) (shown) and (inter-system) [event publishing](https://github.com/isisaddons/isis-module-publishing):
-
+
In the security menu is access to the rich set of functionality provided by the Isis addons [security module](https://github.com/isisaddons/isis-module-security):
-
+
In the prototyping menu is the ability to download a GNU gettext `.po` file for translation. This file can then be translated into multiple languages so that your app can support different locales. Note that this feature is part of Apache Isis core (it is not in Isis Addons):
-
+
The Isis addons also provides a module for managing application and user [settings](https://github.com/isisaddons/isis-module-settings). Most apps (the todoapp example included) won't expose these services directly, but will usually wrap them in their own app-specific settings service that trivially delegates to the settings module's services:
-
+
### Multi-tenancy support
Of the various Isis addons, the [security module](https://github.com/isisaddons/isis-module-security) has the most features. One significant feature is the ability to associate users and objects with a "tenancy". The todoapp uses this feature so that different users' list of todo items are kept separate from one another. A user with administrator is able to switch their own "tenancy" to the tenancy of some other user, in order to access the objects in that tenancy:
-
+
For more details, see the [security module](https://github.com/isisaddons/isis-module-security) README.
@@ -127,11 +127,11 @@ For more details, see the [security module](https://github.com/isisaddons/isis-m
Most of the [security module](https://github.com/isisaddons/isis-module-security)'s services are on the security module, which would normally be provided only to administrators. Kept separate is the "me" action:
-
+
Assuming they have been granted permissions, this allows a user to access an entity representing their own user account:
-
+
If not all of these properties are required, then they can be hidden either using security or though Isis' internal event bus (described below). Conversely, additional properties can be "grafted onto" the user using the contributed properties/collections discussed previously.
@@ -139,13 +139,13 @@ If not all of these properties are required, then they can be hidden either usin
Apache Isis' Wicket viewer uses [Twitter Bootstrap](http://getbootstrap.com), which means that it can be themed. If more than one theme has been configured for the app, then the viewer allows the end-user to switch their theme:
-
+
## REST API
In addition to Isis' Wicket viewer, it also provides a fully fledged REST API, as an implementation of the [Restful Objects](http://restfulobjects.org) specification. The screenshot below shows accessing this REST API using a Chrome plugin:
-
+
Like the Wicket viewer, the REST API is generated automatically from the domain objects (entities and view models).
@@ -153,15 +153,15 @@ Like the Wicket viewer, the REST API is generated automatically from the domain
Earlier on we noted that Apache Isis allows fixtures to be installed through the UI. These same fixture scripts can be reused within integration tests. For example, the code snippet below shows how the `FixtureScripts` service injected into an integration test can then be used to set up data:
-
+
The tests themselves are run in junit. While these are integration tests (so talking to a real database), they are no more complex than a regular unit test:
-
+
To simulate the business rules enforced by Apache Isis, the domain object can be "wrapped" in a proxy. For example, if using the Wicket viewer then Apache Isis will enforce the rule (implemented in the `ToDoItem` class itself) that a completed item cannot have the "completed" action invoked upon it. The wrapper simulates this by throwing an appropriate exception:
-
+
## Internal Event Bus
@@ -169,15 +169,15 @@ Contributions, discussed earlier, are an important tool in ensuring that the pac
Another important tool to ensure your codebase remains maintainable is Isis' internal event bus. It is probably best explained by example; the code below says that the "complete" action should emit a `ToDoItem.Completed` event:
-
+
Domain service (application-scoped, stateless) can then subscribe to this event:
-
+
And this test verifies that completing an action causes the subscriber to be called:
-
+
In fact, the domain event is fired not once, but (up to) 5 times. It is called 3 times prior to execution, to check that the action is visible, enabled and that arguments are valid. It is then additionally called prior to execution, and also called after execution. What this means is that a subscriber can in either veto access to an action of some publishing object, and/or it can perform cascading updates if the action is allowed to proceed.
http://git-wip-us.apache.org/repos/asf/isis/blob/84e85548/adocs/documentation/monitor.rb
----------------------------------------------------------------------
diff --git a/adocs/documentation/monitor.rb b/adocs/documentation/monitor.rb
index df7b28a..93d17a6 100644
--- a/adocs/documentation/monitor.rb
+++ b/adocs/documentation/monitor.rb
@@ -79,13 +79,13 @@ def process(file,srcBasePath,targetBasePath,templateDir,i,lastTimeGenerated,prim
unless regenerate == "" then
- # if regenerated within last 3 seconds, then wait a while
+ # if regenerated within last 6 seconds, then wait a while
currentTime = Time.now
timeSinceLast = currentTime.to_i - lastTimeGenerated.to_i
- timeUntilNext = 3 - timeSinceLast
+ timeUntilNext = 6 - timeSinceLast
if not priming and
timeUntilNext > 0 then
- puts "skipping before regenerating (3 seconds not yet elapsed)"
+ puts "skipping before regenerating (6 seconds not yet elapsed)"
else
# wait 1 further second for any additional edits
sleep 1
http://git-wip-us.apache.org/repos/asf/isis/blob/84e85548/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_dev-env_intellij.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_dev-env_intellij.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_dev-env_intellij.adoc
index 0f42dd9..42e3030 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_dev-env_intellij.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_dev-env_intellij.adoc
@@ -357,6 +357,8 @@ To fix the issue, try:
One thing worth knowing; IntelliJ actively scans the filesystem all the time. It's therefore (almost always) fine to build the app from the Maven command line; IntelliJ will detect the changes and keep in sync. If you want to force that, use `File > Synchronize`, `ctrl-alt-Y`.
+
+
== Advanced
In this section are a couple of options that will reduce the length of the change code/build/deploy/review feedback loop.
@@ -364,7 +366,8 @@ In this section are a couple of options that will reduce the length of the chang
=== Setting up Dynamic Reloading
-IMPORTANT: TODO
+IMPORTANT: TODO - see link:http://blog.jetbrains.com/idea/2013/07/get-true-hot-swap-in-java-with-dcevm-and-intellij-idea/[IntelliJ blog].
+
=== Setting up JRebel
http://git-wip-us.apache.org/repos/asf/isis/blob/84e85548/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_migration-notes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_migration-notes.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_migration-notes.adoc
index c5e12d4..d8a5d0d 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_migration-notes.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_migration-notes.adoc
@@ -321,3 +321,243 @@ annotations are encountered. These can be viewed either in the console or by br
be displayed).
+
+
+
+== Migrating from v1.6.0 to 1.7.0
+
+In v1.7.0 we've continued the work started in v1.6.0 in modularizing the framework. The most important change to note is that all Isis core modules (with the Maven `groupId` of `org.apache.isis.module` have now MOVED to [http://www.isisaddons.org](Isis Addons).
+
+In addition, we've retired some obsolete (and unused) functionality, specifically the `ProfileStore` component.
+
+To move up amounts to changing POM files and, where required, updating package names for any referenced modules.
+
+=== Reorganized 'modules'
+
+The following modules are no longer released as part of Isis core and have moved to Isis Addons (or in one case, back into Isis core).
+
+Minor changes are required to `pom.xml` files and (in some cases) to `isis.properties` config file.
+
+In one or two exceptional cases it may be necessary to fix up import statements if there are reference to changed package/class names in code (most likely any dependency on the `devutils` module or `settings` module).
+
+==== Audit module
+
+In `pom.xml`, replace:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.isis.module</groupId>
+ <artifactId>isis-module-audit-jdo</artifactId>
+</dependency>
+----
+
+with:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.isisaddons.module.audit</groupId>
+ <artifactId>isis-module-audit-dom</artifactId>
+</dependency>
+----
+
+If necessary, also update any services registered in `isis.properties` (package/class names may have changed slightly).
+
+==== Command module
+
+In `pom.xml`, replace:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.isis.module</groupId>
+ <artifactId>isis-module-command-jdo</artifactId>
+</dependency>
+----
+
+with:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.isisaddons.module.command</groupId>
+ <artifactId>isis-module-command-dom</artifactId>
+</dependency>
+----
+
+If necessary, also update any services registered in `isis.properties` (package/class names may have changed slightly).
+
+==== DevUtils module
+
+In `pom.xml`, replace:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.isis.module</groupId>
+ <artifactId>isis-module-devutils-applib</artifactId>
+</dependency>
+----
+
+with:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.isisaddons.module.devutils</groupId>
+ <artifactId>isis-module-devutils-dom</artifactId>
+</dependency>
+----
+
+Remove any references to:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.isis.module</groupId>
+ <artifactId>isis-module-devutils</artifactId>
+</dependency>
+----
+
+or to:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.isis.module</groupId>
+ <artifactId>isis-module-devutils-impl</artifactId>
+</dependency>
+----
+
+These modules are no longer required (the `org.apache.isis.module:isis-module-devutils-applib`
+and `org.apache.isis.module:isis-module-devutils-impl` submodules have been combined
+into the new `org.isisaddons.module.devutils:isis-module-devutils-dom` module).
+
+If necessary, also update any services registered in `isis.properties` (package/class names may have changed slightly).
+
+==== Publishing module
+
+In `pom.xml`, replace:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.isis.module</groupId>
+ <artifactId>isis-module-publishing-jdo</artifactId>
+</dependency>
+----
+
+with:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.isisaddons.module.publishing</groupId>
+ <artifactId>isis-module-publishing-dom</artifactId>
+</dependency>
+----
+
+If necessary, also update any services registered in `isis.properties` (package/class names may have changed slightly).
+
+==== Publishing Event Serializer RO module
+
+Remove any references to:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.isis.module</groupId>
+ <artifactId>isis-module-publishingeventserializer-ro</artifactId>
+</dependency>
+----
+
+This module has been merged with `org.isisaddons.module.publishing:isis-module-publishing-dom`, above.
+
+==== Settings module
+
+In `pom.xml`, replace:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.isis.module</groupId>
+ <artifactId>isis-module-settings-applib</artifactId>
+</dependency>
+----
+
+with:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.isisaddons.module.settings</groupId>
+ <artifactId>isis-module-settings-dom</artifactId>
+</dependency>
+----
+
+Remove any references to:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.isis.module</groupId>
+ <artifactId>isis-module-settings</artifactId>
+</dependency>
+----
+
+or to:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.isis.module</groupId>
+ <artifactId>isis-module-settings-impl</artifactId>
+</dependency>
+----
+
+These modules are no longer required (the `org.apache.isis.module:isis-module-settings-applib`
+and `org.apache.isis.module:isis-module-settings-impl` submodules have been combined
+into the new `org.isisaddons.module.settings:isis-module-settings-dom` module).
+
+If necessary, also update any services registered in `isis.properties` (package/class names may have changed slightly).
+
+==== Background module
+
+In `pom.xml`, remove:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.isis.module</groupId>
+ <artifactId>isis-module-background</artifactId>
+</dependency>
+----
+
+The service classes have been moved into existing `org.apache.isis.core:isis-core-runtime` Maven module (that is, already be referenced in the `pom.xml`).
+
+If necessary, also update any services registered in `isis.properties` (package/class names may have changed slightly).
+
+=== Retired `ProfileStore` component
+
+As per <a href='https://issues.apache.org/jira/browse/ISIS-802'>ISIS-802</a>, the ProfileStore component has been removed. This functionality was not surfaced or available in the Wicket or Restful Objects viewers, so there is no meaningful loss of functionality. However, Maven `pom.xml` files will require updating:
+
+Specifically, remove any dependencies on `org.apache.isis:isis-core-profilestore`:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.isis.core</groupId>
+ <artifactId>isis-core-profilestore</artifactId>
+</dependency>
+----
+
+A number of corresponding classes/interfaces have also been removed from the Isis applib:
+
+* `org.apache.isis.applib.fixtures.userprofile.UserProfileService`
+* `org.apache.isis.applib.fixtures.userprofile.UserProfileServiceAware`
+* `org.apache.isis.applib.fixtures.UserProfileFixture`
+* `org.apache.isis.applib.profiles.Profile`
+* `org.apache.isis.applib.profiles.Perspective`
+
+It is highly unlikely that any existing production code references these classes.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/84e85548/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_release-notes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_release-notes.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_release-notes.adoc
index 0b122c3..6aa6c9f 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_release-notes.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_release-notes.adoc
@@ -1,5 +1,5 @@
[[_ug_appendices_release-notes]]
-= = Release Notes
+= Release Notes
: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/
http://git-wip-us.apache.org/repos/asf/isis/blob/84e85548/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_add-ons.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_add-ons.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_add-ons.adoc
index 817bd65..83777e3 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_add-ons.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_add-ons.adoc
@@ -1,8 +1,35 @@
[[_ug_core-concepts_add-ons]]
-= Add-ons
+= Isis Add-ons
: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
+The link:http://www.isisaddons.org[Isis Addons] website provides a number of reusable modules and other extensions for Apache Isis. This chapter focuses just on the modules, all of which have a name of the form `isis-module-xxx`.
+
+[WARNING]
+====
+Note that Isis addons, while maintained by Isis committers, are not part of the ASF.
+====
+
+
+
+The modules themselves fall into four broad groups:
+
+* modules that provide an implementations of API defined by Apache Isis +
++
+where Isis has hooks to use the service if defined by provides no implementations of its own. The http://github.com/isisaddons/isis-module-command[command], http://github.com/isisaddons/isis-module-audit[auditing], http://github.com/isisaddons/isis-module-publishing[publishing], http://github.com/isisaddons/isis-module-security[security] and http://github.com/isisaddons/isis-module-sessionlogger[sessionlogger] modules fall into this category. Typically the domain objects themselves wouldn't interact with these services
+
+* modules that provide standalone domain services with their own API and implementation +
++
+These are simply intended to be used by domain objects. The http://github.com/isisaddons/isis-module-docx[docx], http://github.com/isisaddons/isis-module-excel[excel], http://github.com/isisaddons/isis-module-settings[settings] and http://github.com/isisaddons/isis-module-stringinterpolator[stringinterpolator] fall into this category.
+
+* modules that provide standalone domain entities (and supporting services) for a particular subdomain +
++
+The http://github.com/isisaddons/isis-module-tags[tags] module falls into this category
+
+* modules that provide developer utilities +
++
+Not intended for use by either the framework or domain objects, but provide utilities that the developer themselves might use. The http://github.com/isisaddons/isis-module-devutils[devutils] module (not suprisingly) falls into this category
+
+Each of the modules has a full README and example application demonstrating their usage. The sections below briefly outline the capabilities of these modules.
http://git-wip-us.apache.org/repos/asf/isis/blob/84e85548/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_building-blocks.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_building-blocks.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_building-blocks.adoc
index 30a4f97..80e045d 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_building-blocks.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_building-blocks.adoc
@@ -8,6 +8,8 @@ IMPORTANT: TODO
## A MetaModel with Explicit and Inferred Semantics
+IMPORTANT: TODO
+
* use of annotations
** reuse JEE annotations where possible
* layout hints are overridable, to avoid restarting the app/speed up feedback
@@ -15,6 +17,8 @@ IMPORTANT: TODO
## Domain Objects and Domain Services
+IMPORTANT: TODO
+
* domain model
** domain objects
*** domain entity
@@ -28,10 +32,13 @@ Anything else can be (should be) ignored by annotating with `@Programmatic`.
## Properties, Collections and Actions
+IMPORTANT: TODO
## Domain Entities vs View Models
+IMPORTANT: TODO
+
`@DomainObject(nature=...)`
@@ -44,8 +51,11 @@ Domain services are instantiated once and once only by the framework, and are us
For convenience you can inherit from AbstractService or one of its subclasses, but this is not mandatory.
+
### Domain Services vs View Services
+IMPORTANT: TODO
+
`@DomainService(nature=...)`
.Factories, Repositories and Services
@@ -55,185 +65,29 @@ A distinction is sometimes made between a factory (that creates object) and a re
In Apache Isis these are all implemented as domain services. Indeed, it is quite common to have a domain service that acts as both a factory and a repository.
****
-## Value Objects (Primitives)
-
-
-
-## Contributions
-
-
-
-## Event Bus
-
-
-
-
-
-
-=== Registering domain services
-
-As noted link:../../how-tos/how-to-09-010-How-to-register-domain-services,-repositories-and-factories.html[elsewhere], domain services (which includes repositories and factories) should be registered in the `isis.properties` configuration file, under `isis.services` key (a comma-separated list):
-
-For example:
-
-[source,ini]
-----
-isis.services = com.mycompany.myapp.employee.Employees\,
- com.mycompany.myapp.claim.Claims\,
- ...
-----
-
-This will then result in the framework instantiating a single instance of each of the services listed.
-
-If all services reside under a common package, then the `isis.services.prefix` can specify this prefix:
-
-[source,ini]
-----
-isis.services.prefix = com.mycompany.myapp
-isis.services = employee.Employees,\
- claim.Claims,\
- ...
-----
-
-This is quite rare, however; you will often want to use default implementations of domain services that are provided by the framework and so will not reside under this prefix.
-
-Examples of framework-provided services (as defined in the applib) include clock, auditing, publishing, exception handling, view model support, snapshots/mementos, and user/application settings management; see the xref:_ug_reference-services-api[here] and _ug_reference-services-spi[here] for further details.
-
-=== Service scopes
-By default all domain services are considered to be singletons, and thread-safe.
-Sometimes though a service's lifetime is applicable only to a single request; in other words it is request-scoped.
-The CDI annotation `@javax.enterprise.context.RequestScoped` is used to indicate this fact:
-
-[source,java]
-----
- @javax.enterprise.context.RequestScoped
- public class MyService extends AbstractService {
- ...
- }
-----
-
-The framework provides a number of request-scoped services, include a scratchpad service, query results caching, and support for co-ordinating bulk actions. See xref:_ug_reference-services-api[here] and xref:_ug_reference-services-spi[here] for further details.
-
-
-=== (Suppressing) contributed actions
-
-Any n-parameter action provided by a service will automatically be contributed to the list of actions for each of its (entity) parameters. From the viewpoint of the entity the action is called a contributed action.
-
-For example, given a service:
-
-[source,java]
-----
-public interface Library {
- public Loan borrow(Loanable l, Borrower b);
-}
-----
-
-and the entities:
-
-[source,java]
-----
-public class Book implements Loanable { ... }y
-----
-
-and
-
-[source,java]
-----
-public class LibraryMember implements Borrower { ... }
-----
-
-then the `borrow(...)` action will be contributed to both `Book` and to `LibraryMember`.
-
-This is an important capability because it helps to decouple the concrete classes from the services.
-
-If necessary, though, this behaviour can be suppressed by annotating the service action with `@org.apache.isis.applib.annotations.NotContributed`.
-
-For example:
-
-[source,java]
-----
-public interface Library {
- @NotContributed
- public Loan borrow(Loanable l, Borrower b);
-}
-----
-
-If annotated at the interface level, then the annotation will be inherited by every concrete class. Alternatively the annotation can be applied at the implementation class level and only apply to that particular implementation.
-
-Note that an action annotated as being `@NotContributed` will still appear in the service menu for the service. If an action should neither be contributed nor appear in service menu items, then simply annotate it as `@Hidden`.
-
-=== (Suppressing) service menu items
-
-By default every action of a service (by which we also mean repositories and factories) will be rendered in the viewer, eg as a menu item for that service menu. This behaviour can be suppressed by annotating the action using `@org.apache.isis.applib.annotations.NotInServiceMenu`.
-
-For example:
-
-[source,java]
-----
-public interface Library {
- @NotInServiceMenu
- public Loan borrow(Loanable l, Borrower b);
-}
-----
-
-Note that an action annotated as being `@NotInServiceMenu` will still be contributed. If an action should neither be contributed nor appear in service menu items, then simply annotate it as `@Hidden`.
-
-Alternatively, this can be performed using a supporting method:
-
-[source,java]
-----
-public class LibraryImpl implements Library {
- public Loan borrow(Loanable l, Borrower b) { ... }
- public boolean notInServiceMenuBorrow() { ... }
-}
-----
-
-=== (Suppressing) service menus
-
-If none of the service menu items should appear, then the service itself should be annotated as `@Hidden`.
-
-For example:
+## Value Objects (Primitives)
-[source,java]
-----
-@Hidden
-public interface EmailService {
- public void sendEmail(String to, String from, String subject, String body);
- public void forwardEmail(String to, String from, String subject, String body);
-}
-----
+IMPORTANT: TODO
-=== Initializing Services
-Services can optionally declare lifecycle callbacks to initialize them (when the app is deployed) and to shut them down (when the app is undeployed).
-An Isis session _is_ available when initialization occurs (so services can interact with the object store, for example).
+## Contributions
-==== Initialization
+IMPORTANT: TODO
-The framework will call any `public` method annotated with `@javax.annotation.PostConstruct` and with either no arguments of an argument of type `Map<String,String>`:
-or
-In the latter case, the framework passes in the configuration (`isis.properties` and any other component-specific configuration files).
-==== Shutdown
+## Event Bus
-Shutdown is similar; the framework will call any method annotated with `@javax.annotation.PreDestroy`:
+IMPORTANT: TODO
-=== The getId() method
-Optionally, a service may provide a `getId()` method:
-[source,java]
-----
-public String getId()
-----
-This method returns a logical identifier for a service, independent of its implementation. Currently it used only by perspectives, providing a label by which to record the services that are available for a current user's profile. <!--See ? for more about profiles and perspectives.-->
http://git-wip-us.apache.org/repos/asf/isis/blob/84e85548/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_framework-provided-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_framework-provided-services.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_framework-provided-services.adoc
index 425c905..9961500 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_framework-provided-services.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_framework-provided-services.adoc
@@ -4,82 +4,51 @@
:_basedir: ../
:_imagesdir: images/
-IMPORTANT: TODO
-
-## API vs SPI
Most framework domain services are API: they exist to provide support functionality to the application's domain objects and services. In this case an implementation of the service will be available, either by Apache Isis itself or by Isis Addons (non ASF).
Some framework domain services are SPI: they exist primarily so that the application can influence the framework's behaviour. In these cases there is (usually) no default implementation; it is up to the application to provide an implementation.
-## Autoregistration of Domain services
-
-Where a domain service has an implementation, it is (almost always) automatically registered just by virtue of being on the `CLASSPATH`.
-
-The one exception is <<ExceptionRecognizer>>.
-
-It is possible to replacing automatically-registered domain services.
-
-
-## Overview of Domain Services
-
-Unless indicated as SPI, each of the following has an implementation in Isis core.
-
-A full list of services (including those with implementations in link:http://www.isisaddons.org[Isis Addons] (non-ASF)) can be found in the xref:_ug_domain-services-spi[Domain Services (SPI)] chapter.
-
-### `DomainObjectContainer`
-
-### `ClockService`
-
-### `IsisSupportJdo`
-
-### `ExceptionRecognizer`
-
-### `WrapperFactory`
-
-### `EventBusService`
-
-### Commands/Background
-
-#### `CommandContext`
-
-#### `BackgroundService`
-
-### Information Sharing
-
-#### `ScratchPad`
-
-#### `ActionInvocationContext`
-
-#### `QueryResultsCache`
-
-### `EmailService`
-
-### UserManagement
-
-#### `UserProfileService` (SPI)
-
-#### `UserRegistrationService` (SPI)
-
-#### `EmailNotificationService`
-
-### Bookmarks and Mementos
+General purpose:
-#### `BookmarkService`
+* xref:_ug_reference-services-api_manpage-DomainObjectContainer[`DomainObjectContainer`]
+* xref:_ug_reference-services-api_manpage-ClockService[`ClockService`]
+* xref:_ug_reference-services-api_manpage-IsisSupportJdo[`IsisSupportJdo`]
+* xref:_ug_reference-services-api_manpage-WrapperFactory[`WrapperFactory`]
+* xref:_ug_reference-services-api_manpage-EventBusService[`EventBusService`]
+* xref:_ug_reference-services-api_manpage-EmailService[`EmailService`]
-#### `MementoService`
+Commands/Background/Auditing:
-#### `DeepLinkService`
+* xref:_ug_reference-services-api_manpage-CommandContext[`CommandContext`] (SPI)
+* xref:_ug_reference-services-spi_manpage-CommandService[`CommandService`] (SPI)
+* xref:_ug_reference-services-spi_manpage-AuditingService[`AuditingService`] (SPI)
+* xref:_ug_reference-services-api_manpage-BackgroundService[`BackgroundService`]
+* xref:_ug_reference-services-spi_manpage-BackgroundCommandService[`BackgroundCommandService`] (SPI)
+* xref:_ug_reference-services-spi_manpage-PublishingService[`PublishingService`] (SPI)
-#### `XmlSnapshotService`
+Information Sharing:
+* xref:_ug_reference-services-api_manpage-ScratchPad[`ScratchPad`]
+* xref:_ug_reference-services-api_manpage-ActionInvocationContext[`ActionInvocationContext`]
+* xref:_ug_reference-services-api_manpage-QueryResultsCache[`QueryResultsCache`]
+UserManagement:
+* xref:_ug_reference-services-spi_manpage-UserProfileService[`UserProfileService`] (SPI)
+* xref:_ug_reference-services-spi_manpage-UserRegistrationService[`UserRegistrationService`] (SPI)
+* xref:_ug_reference-services-spi_manpage-EmailNotificationService[`EmailNotificationService`] (SPI)
+Bookmarks and Mementos:
+* xref:_ug_reference-services-api_manpage-BookmarkService[`BookmarkService`]
+* xref:_ug_reference-services-api_manpage-MementoService[`MementoService`]
+* xref:_ug_reference-services-api_manpage-DeepLinkService[`DeepLinkService`]
+* xref:_ug_reference-services-api_manpage-XmlSnapshotService[`XmlSnapshotService`]
+A full list of services can be found in the xref:_ug_domain-services-api[Domain Services (API)] and xref:_ug_domain-services-spi[Domain Services (SPI)] reference chapters.
http://git-wip-us.apache.org/repos/asf/isis/blob/84e85548/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_other-deployment-options.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_other-deployment-options.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_other-deployment-options.adoc
index 53d9620..ce6bece 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_other-deployment-options.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_other-deployment-options.adoc
@@ -18,7 +18,7 @@ Let's start though with the default use case for Isis: building line-of-business
Apache Wicket, and therefore Apache Isis in this configuration, is a stateful architecture. As a platform it is certainly capable of supporting user bases of several thousand (with perhaps one or two hundred concurrent); however it isn't an architecture that you should try to scale up to tens of thousands of concurrent users.
-The UI UI generated by the Wicket viewer is well suited to many line-of-business apps, but it's also worth knowing that (with a little knowledge of the Wicket APIs) it relatively straightforward to extend. As described in xref:_ug_isis-addons-modules[Isis addons] chapter, the viewer already has integrations with https://github.com/isisaddons/isis-wicket-gmap3[google maps], https://github.com/isisaddons/isis-wicket-fullcalendar2[a full calendar] and an https://github.com/isisaddons/isis-wicket-excel[export to Excel] component. We are also aware of integrations with SVG images (for floor maps of shopping center) and of custom widgets displaying a catalogue (text and images) of medical diseases.
+The UI UI generated by the Wicket viewer is well suited to many line-of-business apps, but it's also worth knowing that (with a little knowledge of the Wicket APIs) it relatively straightforward to extend. As described in xref:_ug_core-concepts_add-ons[Isis addons] chapter, the viewer already has integrations with https://github.com/isisaddons/isis-wicket-gmap3[google maps], https://github.com/isisaddons/isis-wicket-fullcalendar2[a full calendar] and an https://github.com/isisaddons/isis-wicket-excel[export to Excel] component. We are also aware of integrations with SVG images (for floor maps of shopping center) and of custom widgets displaying a catalogue (text and images) of medical diseases.
Deploying on Isis means that the framework also manages object persistence. For many line-of-business applications this will mean using a relational database. It is also possible (courtesy of its integratinon with link:http://www.datanucleus.org[DataNucleus]) to deploy an Isis app to a NoSQL store such as Neo4J or MongoDB; and it is also possible to deploy to cloud platforms such as link:https://cloud.google.com/appengine/docs[Google App Engine (GAE)].
http://git-wip-us.apache.org/repos/asf/isis/blob/84e85548/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles_apache-isis-vs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles_apache-isis-vs.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles_apache-isis-vs.adoc
index 10d9ca9..cb4bcda 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles_apache-isis-vs.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles_apache-isis-vs.adoc
@@ -14,14 +14,16 @@ include::_ug_core-concepts_principles_apache-isis-vs_mvc-server-side-frameworks.
== vs CQRS
-
+IMPORTANT: TODO
== vs Event Sourcing
+IMPORTANT: TODO
== vs Angular
+IMPORTANT: TODO
@@ -31,3 +33,4 @@ include::_ug_core-concepts_principles_apache-isis-vs_metawidget.adoc[leveloffset
== vs OpenXava
+IMPORTANT: TODO
http://git-wip-us.apache.org/repos/asf/isis/blob/84e85548/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles_your-apps.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles_your-apps.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles_your-apps.adoc
index 7981282..7e73413 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles_your-apps.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles_your-apps.adoc
@@ -9,7 +9,7 @@ IMPORTANT: TODO
== Decoupled
-IMPORTANT: TODO ...
+IMPORTANT: TODO
Long-term Cost of ownership
@@ -25,14 +25,12 @@ Using:
== Honouring the Single Responsibility Principle
-IMPORTANT: TODO
-
-* behaviourally Complete vs Contributions
+IMPORTANT: TODO - behaviourally Complete vs Contributions
== Testable
-IMPORTANT: TODO
+IMPORTANT: WIP
While Apache Isis can be used (very effectively) for simple CRUD-style applications, it is also intended to be used for complex business domains. Ensuring that the business logic in such applications is correct means that the framework must (and does) provide robust testing support, both for developer-level unit testing and business-level (end-to-end) integration testing.
http://git-wip-us.apache.org/repos/asf/isis/blob/84e85548/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_gae.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_gae.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_gae.adoc
index 53cd4da..d06d75c 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_gae.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_gae.adoc
@@ -33,11 +33,8 @@ Instead, GAE defines a link:https://cloud.google.com/appengine/docs/java/datasto
The above notwithstanding, Andy Jefferson at DataNucleus tells us:
-____
-
-GAE JDO/JPA does support _some_ type conversion, because looking at http://code.google.com/p/datanucleus-appengine/source/browse/trunk/src/com/google/appengine/datanucleus/StoreFieldManager.java#349[StoreFieldManager.java] for any field that is Object-based and not a relation nor Serialized it will call http://code.google.com/p/datanucleus-appengine/source/browse/trunk/src/com/google/appengine/datanucleus/TypeConversionUtils.java#736[TypeConverstionUtils.java] and that looks for a `TypeConverter` (specify `@Extension` with key of "type-converter-name" against a field and value as the `TypeConverter` class) and it should convert it. Similarly when getting the value from the datastore.
-
-____
+pass:[<div class="extended-quote-first"><p>]GAE JDO/JPA does support _some_ type conversion, because looking at http://code.google.com/p/datanucleus-appengine/source/browse/trunk/src/com/google/appengine/datanucleus/StoreFieldManager.java#349[StoreFieldManager.java] for any field that is Object-based and not a relation nor Serialized it will call http://code.google.com/p/datanucleus-appengine/source/browse/trunk/src/com/google/appengine/datanucleus/TypeConversionUtils.java#736[TypeConverstionUtils.java] and that looks for a `TypeConverter` (specify `@Extension` with key of "type-converter-name" against a field and value as the `TypeConverter` class) and it should convert it. Similarly when getting the value from the datastore.
+pass:[</p></div>]
On further investigation, it seems that the GAE implementation performs a type check on a `SUPPORTED_TYPES` Java set, in `com.google.appengine.api.datastore.DataTypeUtils`:
@@ -49,412 +46,3 @@ if (!supportedTypes.contains(value.getClass())) {
----
We still need to try out Andy's recipe, above.
-
-=== A GAE compatible version of `ToDoItem.java`
-
-... as per the http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] (non-ASF), is as follows:
-
-[source,java]
-----
-@javax.jdo.annotations.Queries( {
- @javax.jdo.annotations.Query(
- name="todo_all", language="JDOQL",
- value="SELECT FROM dom.todo.ToDoItem WHERE ownedBy == :ownedBy"),
- @javax.jdo.annotations.Query(
- name="todo_notYetComplete", language="JDOQL",
- value="SELECT FROM dom.todo.ToDoItem WHERE ownedBy == :ownedBy && complete == false"),
- @javax.jdo.annotations.Query(
- name="todo_complete", language="JDOQL",
- value="SELECT FROM dom.todo.ToDoItem WHERE ownedBy == :ownedBy && complete == true"),
- @javax.jdo.annotations.Query(
- name="todo_similarTo", language="JDOQL",
- value="SELECT FROM dom.todo.ToDoItem WHERE ownedBy == :ownedBy && category == :category"),
- @javax.jdo.annotations.Query(
- name="todo_autoComplete", language="JDOQL",
- value="SELECT FROM dom.todo.ToDoItem WHERE ownedBy == :ownedBy && description.startsWith(:description)")
-})
-@javax.jdo.annotations.Version(strategy= VersionStrategy.VERSION_NUMBER, column="VERSION")
-@ObjectType("TODO")
-@Auditable
-@AutoComplete(repository=ToDoItems.class, action="autoComplete")
-@MemberGroups({"General", "Detail"})
-@javax.jdo.annotations.PersistenceCapable
-public class ToDoItem implements Comparable<ToDoItem> {
-// @PrimaryKey
-// @Persistent(valueStrategy = javax.jdo.annotations.IdGeneratorStrategy.IDENTITY)
-// @Extension(vendorName="datanucleus", key="gae.encoded-pk", value="true")
-// private String key;
- @Persistent(valueStrategy=IdGeneratorStrategy.IDENTITY)
- @PrimaryKey
- private Long id;
-
- private static final long ONE_WEEK_IN_MILLIS = 7 * 24 * 60 * 60 * 1000L;
-
- public static enum Category {
- Professional, Domestic, Other;
- }
-
- // {{ Identification on the UI
- public String title() {
- final TitleBuffer buf = new TitleBuffer();
- buf.append(getDescription());
- if (isComplete()) {
- buf.append(" - Completed!");
- } else {
- if (getDueBy() != null) {
- SimpleDateFormat sdf = new SimpleDateFormat("dd-MM-yyyy");
- buf.append(" due by ", sdf.format(getDueBy()));
- }
- }
- return buf.toString();
- }
-
- // }}
-
- // {{ Description
- private String description;
-
- @RegEx(validation = "\\w[@&:\\-\\,\\.\\+ \\w]*")
- // words, spaces and selected punctuation
- @MemberOrder(sequence = "1")
- @DescribedAs("Enter the description")
- public String getDescription() {
- return description;
- }
-
- public void setDescription(final String description) {
- this.description = description;
- }
- // }}
-
- // {{ DueBy (property)
- private Date dueBy;
-
- @javax.jdo.annotations.Persistent
- @MemberOrder(name="Detail", sequence = "3")
- @Optional
- @DescribedAs("Enter the date")
- public Date getDueBy() {
- return dueBy;
- }
-
- public void setDueBy(final Date dueBy) {
- this.dueBy = dueBy;
- }
- public void clearDueBy() {
- setDueBy(null);
- }
- // proposed new value is validated before setting
- public String validateDueBy(final Date dueBy) {
- if (dueBy == null) {
- return null;
- }
- return isMoreThanOneWeekInPast(dueBy) ? "Due by date cannot be more than one week old" : null;
- }
- // }}
-
- // {{ Category
- private Category category;
-
- @MemberOrder(sequence = "2")
- @DescribedAs("Enter the category")
- public Category getCategory() {
- return category;
- }
-
- public void setCategory(final Category category) {
- this.category = category;
- }
- // }}
-
- // {{ OwnedBy (property)
- private String ownedBy;
-
- @Hidden
- // not shown in the UI
- public String getOwnedBy() {
- return ownedBy;
- }
-
- public void setOwnedBy(final String ownedBy) {
- this.ownedBy = ownedBy;
- }
-
- // }}
-
- // {{ Complete (property)
- private boolean complete;
-
- @Disabled
- // cannot be edited as a property
- @MemberOrder(sequence = "4")
- public boolean isComplete() {
- return complete;
- }
-
- public void setComplete(final boolean complete) {
- this.complete = complete;
- }
-
- // {{ Notes (property)
- private String notes;
-
- @Hidden(where=Where.ALL_TABLES)
- @Optional
- @MultiLine(numberOfLines=4)
- @MemberOrder(name="Detail", sequence = "6")
- public String getNotes() {
- return notes;
- }
-
- public void setNotes(final String notes) {
- this.notes = notes;
- }
- // }}
-
- // {{ Attachment (property)
- private BlobKey attachment;
-
- @Persistent
- @Optional
- @MemberOrder(name="Detail", sequence = "7")
- public BlobKey getAttachment() {
- return attachment;
- }
-
- public void setAttachment(final BlobKey attachment) {
- this.attachment = attachment;
- }
- // }}
-
- // {{ Version (derived property)
- @Hidden(where=Where.ALL_TABLES)
- @Disabled
- @MemberOrder(name="Detail", sequence = "99")
- @Named("Version")
- public Long getVersionSequence() {
- if(!(this instanceof PersistenceCapable)) {
- return null;
- }
- PersistenceCapable persistenceCapable = (PersistenceCapable) this;
- final Long version = (Long) JDOHelper.getVersion(persistenceCapable);
- return version;
- }
- public boolean hideVersionSequence() {
- return !(this instanceof PersistenceCapable);
- }
- // }}
-
- // {{ completed (action)
- @Bulk
- @MemberOrder(sequence = "1")
- public ToDoItem completed() {
- setComplete(true);
- return this;
- }
-
- // disable action dependent on state of object
- public String disableCompleted() {
- return complete ? "Already completed" : null;
- }
- // }}
-
- // {{ notYetCompleted (action)
- @MemberOrder(sequence = "2")
- public ToDoItem notYetCompleted() {
- setComplete(false);
- return this;
- }
-
- // disable action dependent on state of object
- public String disableNotYetCompleted() {
- return !complete ? "Not yet completed" : null;
- }
- // }}
-
- // {{ dependencies (Collection)
- @Unowned
- private List<ToDoItem> dependencies = new ArrayList<ToDoItem>();
-
- @Disabled
- @MemberOrder(sequence = "1")
- @Resolve(Type.EAGERLY)
- public List<ToDoItem> getDependencies() {
- return dependencies;
- }
-
- public void setDependencies(final List<ToDoItem> dependencies) {
- this.dependencies = dependencies;
- }
- // }}
-
- // {{ add (action)
- @MemberOrder(name="dependencies", sequence = "3")
- public ToDoItem add(final ToDoItem toDoItem) {
- getDependencies().add(toDoItem);
- return this;
- }
- public String validateAdd(final ToDoItem toDoItem) {
- if(getDependencies().contains(toDoItem)) {
- return "Already a dependency";
- }
- if(toDoItem == this) {
- return "Can't set up a dependency to self";
- }
- return null;
- }
- public List<ToDoItem> choices0Add() {
- return toDoItems.allToDos();
- }
-
- // }}
-
- // {{ remove (action)
- @MemberOrder(name="dependencies", sequence = "4")
- public ToDoItem remove(final ToDoItem toDoItem) {
- getDependencies().remove(toDoItem);
- return this;
- }
- public String disableRemove(final ToDoItem toDoItem) {
- return getDependencies().isEmpty()? "No dependencies to remove": null;
- }
- public String validateRemove(final ToDoItem toDoItem) {
- if(!getDependencies().contains(toDoItem)) {
- return "Not a dependency";
- }
- return null;
- }
- public List<ToDoItem> choices0Remove() {
- return getDependencies();
- }
- // }}
-
- // {{ clone (action)
- @Named("Clone")
- // the name of the action in the UI
- @MemberOrder(sequence = "3")
- // nb: method is not called "clone()" is inherited by java.lang.Object and
- // (a) has different semantics and (b) is in any case automatically ignored
- // by the framework
- public ToDoItem duplicate() {
- return toDoItems.newToDo(getDescription() + " - Copy", getCategory(), getDueBy());
- }
- // }}
-
- // {{ isDue (programmatic)
- @Programmatic
- // excluded from the framework's metamodel
- public boolean isDue() {
- if (getDueBy() == null) {
- return false;
- }
- return !isMoreThanOneWeekInPast(getDueBy());
- }
-
- // }}
-
- // {{ SimilarItems (derived collection)
- @MemberOrder(sequence = "5")
- @NotPersisted
- @Resolve(Type.EAGERLY)
- public List<ToDoItem> getSimilarItems() {
- return toDoItems.similarTo(this);
- }
-
- // }}
-
- // {{ compareTo (programmatic)
- /**
- * by complete flag, then due by date, then description
- */
- // exclude from the framework's metamodel
- @Override
- public int compareTo(final ToDoItem other) {
- if (isComplete() && !other.isComplete()) {
- return +1;
- }
- if (!isComplete() && other.isComplete()) {
- return -1;
- }
- if (getDueBy() == null && other.getDueBy() != null) {
- return +1;
- }
- if (getDueBy() != null && other.getDueBy() == null) {
- return -1;
- }
- if (getDueBy() == null && other.getDueBy() == null || getDueBy().equals(this.getDueBy())) {
- return getDescription().compareTo(other.getDescription());
- }
- return getDueBy().compareTo(getDueBy());
- }
- // }}
-
- // {{ helpers
- private static boolean isMoreThanOneWeekInPast(final Date dueBy) {
- return dueBy.getTime() < Clock.getTime() - ONE_WEEK_IN_MILLIS;
- }
-
- // }}
-
- // {{ filters (programmatic)
- @SuppressWarnings("unchecked")
- public static Filter<ToDoItem> thoseDue() {
- return Filters.and(Filters.not(thoseComplete()), new Filter<ToDoItem>() {
- @Override
- public boolean accept(final ToDoItem t) {
- return t.isDue();
- }
- });
- }
-
- public static Filter<ToDoItem> thoseComplete() {
- return new Filter<ToDoItem>() {
- @Override
- public boolean accept(final ToDoItem t) {
- return t.isComplete();
- }
- };
- }
-
- public static Filter<ToDoItem> thoseOwnedBy(final String currentUser) {
- return new Filter<ToDoItem>() {
- @Override
- public boolean accept(final ToDoItem toDoItem) {
- return Objects.equal(toDoItem.getOwnedBy(), currentUser);
- }
-
- };
- }
-
- public static Filter<ToDoItem> thoseSimilarTo(final ToDoItem toDoItem) {
- return new Filter<ToDoItem>() {
- @Override
- public boolean accept(final ToDoItem eachToDoItem) {
- return Objects.equal(toDoItem.getCategory(), eachToDoItem.getCategory()) &&
- Objects.equal(toDoItem.getOwnedBy(), eachToDoItem.getOwnedBy()) &&
- eachToDoItem != toDoItem;
- }
-
- };
- }
- // }}
-
- // {{ injected: DomainObjectContainer
- @SuppressWarnings("unused")
- private DomainObjectContainer container;
-
- public void setDomainObjectContainer(final DomainObjectContainer container) {
- this.container = container;
- }
- // }}
-
- // {{ injected: ToDoItems
- private ToDoItems toDoItems;
-
- public void setToDoItems(final ToDoItems toDoItems) {
- this.toDoItems = toDoItems;
- }
- // }}
-
-}
-----
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/84e85548/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_jvm-flags.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_jvm-flags.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_jvm-flags.adoc
index 531d100..d3edc30 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_jvm-flags.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_jvm-flags.adoc
@@ -7,13 +7,3 @@
IMPORTANT: TODO
-for the `WrapperFactory` (uses link:http://www.javassist.org[Javassist])
-
-using:
-
-[source,ini]
-----
--XX:+CMSClassUnloadingEnabled -XX:+UseConcMarkSweepGC
-----
-
-You can hint the JVM to unload dynamically created classes which ClassLoaders are still around.
http://git-wip-us.apache.org/repos/asf/isis/blob/84e85548/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_tomcat.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_tomcat.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_tomcat.adoc
index 900170d..d29ca1a 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_tomcat.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_tomcat.adoc
@@ -4,12 +4,32 @@
:_basedir: ../
:_imagesdir: images/
+
IMPORTANT: TODO
-eg Tomcat
== Externalized Configuration
+IMPORTANT: TODO
+
+
== JVM Args
+IMPORTANT: TODO
+
+
+for the `WrapperFactory` (uses link:http://www.javassist.org[Javassist])
+
+using:
+
+[source,ini]
+----
+-XX:+CMSClassUnloadingEnabled -XX:+UseConcMarkSweepGC
+----
+
+You can hint the JVM to unload dynamically created classes which ClassLoaders are still around.
+
+
== Using a JNDI Datasource
+
+See the guidance in the xref:_ug_runtime_configuring-datanucleus_using-jndi-data-source[configuring datanucleus] section.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/84e85548/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model.adoc
index 2e06f43..aad09c6 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model.adoc
@@ -1,13 +1,13 @@
[[_ug_extending_programming-model]]
-= Extending the Programming Model
+= Programming Model
: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_extending_programming-model_custom-validator.adoc[leveloffset=+1]
+This section describes three mechanisms you can use to extend or alter the programming conventions that Isis understands to build up its metamodel.
+include::_ug_extending_programming-model_custom-validator.adoc[leveloffset=+1]
include::_ug_extending_programming-model_finetuning.adoc[leveloffset=+1]
-
include::_ug_extending_programming-model_layout-metadata-reader.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/84e85548/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model_custom-validator.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model_custom-validator.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model_custom-validator.adoc
index a0c5ca8..82eb1ba 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model_custom-validator.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model_custom-validator.adoc
@@ -10,7 +10,7 @@ For example, the validator will detect any orphaned supporting methods (eg `hide
[NOTE]
====
-The support for <<Disallowing deprecated annotations>> is also implemented using the metamodel validator.
+The support for xref:_ug_reference-annotations_aaa_deprecated[disallowing deprecated annotations] is also implemented using the metamodel validator.
====
You can also impose your own application-specific rules by installing your own metamodel validator. To give just one example, you could impose naming standards such as ensuring that a domain-specific abbreviation such as "ISBN" is always consistently capitalized wherever it appears in a class member.
http://git-wip-us.apache.org/repos/asf/isis/blob/84e85548/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model_finetuning.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model_finetuning.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model_finetuning.adoc
index 31d737e..45d4c6b 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model_finetuning.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model_finetuning.adoc
@@ -30,7 +30,7 @@ There are many many such ``Facet``s, and are used to do such things get values f
-== Modifying the Programming Model
+== Modifying the Prog. Model
The default implementation of `ProgrammingModel` is https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/progmodels/dflt/ProgrammingModelFacetsJava5.java[ProgrammingModelFacetsJava5], which registers a large number of ``FacetFactory``s.
@@ -38,7 +38,7 @@ By editing `isis.properties` you can modify the programming conventions either b
Let's see how this is done.
-=== Fine-tuning the existing programming model
+=== Including or excluding facets
Suppose that you wanted to completely remove support for the (already deprecated) `@ActionOrder` annotation. This would be done using:
@@ -64,9 +64,9 @@ This http://isis.markmail.org/thread/472c3mrvcgnripst[thread] from the users mai
-== Specifying a new programming model
+== Replacing the Prog. Model
-If you want to make many changes to the programming model, then (rather than include/exclude lots of facet factories) you can specify a completely new programming model. For this you'll first need an implementation of ``ProgrammingModel``.
+If you want to make many changes to the programming model, then (rather than include/exclude lots of facet factories) you can specify a completely new programming model. For this you'll first need an implementation of `ProgrammingModel`.
One option is to subclass from `ProgammingModelFacetsJava5`; in your subclass you could remove any ``FacetFactory``s that you wanted to exclude, as well as registering your own implementations.