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 2016/01/04 16:22:59 UTC
[4/9] isis git commit: ISIS-1287: splitting out contributors vs
committers guides
http://git-wip-us.apache.org/repos/asf/isis/blob/49ccfd90/adocs/documentation/src/main/asciidoc/guides/_cgcon_ide_intellij.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cgcon_ide_intellij.adoc b/adocs/documentation/src/main/asciidoc/guides/_cgcon_ide_intellij.adoc
new file mode 100644
index 0000000..c38c8e2
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cgcon_ide_intellij.adoc
@@ -0,0 +1,492 @@
+[[_cgcon_ide_intellij]]
+= Developing using IntelliJ IDEA
+: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/
+:toc: right
+
+
+
+[NOTE]
+====
+This material does not constitute an endorsement; JetBrains is not affiliated to Apache Software Foundation in any way.
+====
+
+This section describes how to install and setup JetBrains' IntelliJ IDEA, then how to import an application into IntelliJ and run it.
+
+
+
+== Installing and Setting up
+
+This section covers installation and setup. These notes relates to IntelliJ Community Edition 14.1.x, with
+screenshots taken for Windows.
+
+
+=== Download and Install
+
+https://www.jetbrains.com/idea/download/[Download] latest version of IntelliJ Community Edition, and install:
+
+Start the wizard, click through the welcome page:
+
+.IntelliJ Installation Wizard - Welcome page
+image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/010-welcome-page.png[width="400px"]
+
+Choose the location to install the IDE:
+
+.IntelliJ Installation Wizard - Choose Location
+image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/020-choose-location.png[width="400px"]
+
+Adjust any installation options as you prefer:
+
+.IntelliJ Installation Wizard - Installation Options
+image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/030-installation-options.png[width="400px"]
+
+and the start menu:
+
+.IntelliJ Installation Wizard - Start Menu Folder
+image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/040-start-menu-folder.png[width="400px"]
+
+and finish up the wizard:
+
+.IntelliJ Installation Wizard - Completing the Wizard
+image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/050-completing.png[width="400px"]
+
+Later on we'll specify the Apache Isis/ASF code style settings, so for now select `I do not want to import settings`:
+
+.IntelliJ Installation Wizard - Import Settings
+image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/060-import-settings-or-not.png[width="400px"]
+
+Finally, if you are young and trendy, set the UI theme to Darcula:
+
+.IntelliJ Installation Wizard Set UI Theme
+image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/070-set-ui-theme.png[width="600px"]
+
+
+
+
+=== New Project
+
+In IntelliJ a project can contain multiple modules; these need not be physically located together. (If you are previously an Eclipse user, you can think of it as similar to an Eclipse workspace).
+
+Start off by creating a new project:
+
+.IntelliJ Create New Project
+image::{_imagesdir}appendices/dev-env/intellij-idea/020-create-new-project/010-new-project-create.png[width="400px"]
+
+We want to create a new *Java* project:
+
+.IntelliJ Create New Project - Create a Java project
+image::{_imagesdir}appendices/dev-env/intellij-idea/020-create-new-project/020-java-project-setup-jdk.png[width="600px"]
+
+We therefore need to specify the JDK.
+
+NOTE: at the time of writing Apache Isis supports only Java 7; Java 8 is scheduled for support in Apache Isis v1.9.0
+
+
+.IntelliJ Create New Java Project - Select the JDK
+image::{_imagesdir}appendices/dev-env/intellij-idea/020-create-new-project/030-java-project-select-jdk.png[width="300px"]
+
+Specify the directory containing the JDK:
+
+.IntelliJ Create New Project - Select the JDK location
+image::{_imagesdir}appendices/dev-env/intellij-idea/020-create-new-project/050-name-and-location.png[width="400px"]
+
+Finally allow IntelliJ to create the directory for the new project:
+
+.IntelliJ Create New Project
+image::{_imagesdir}appendices/dev-env/intellij-idea/020-create-new-project/060-create-dir.png[width="200px"]
+
+
+
+=== Import Settings
+
+Next we need to configure IntelliJ with ASF/Apache Isis' standard templates and coding conventions. These are bundled as the `settings.jar` JAR file link:resources/appendices/dev-env/intellij/isis-settings.jar[download from the Apache Isis website]).
+
+Import using: `File > Import Settings`, and specify the directory that you have downloaded the file to:
+
+.IntelliJ Import Settings - Specify JAR file
+image::{_imagesdir}appendices/dev-env/intellij-idea/030-import-settings/010-settings-import-jar.png[width="400px"]
+
+Select all the (two) categories of settings available in the JAR file:
+
+.IntelliJ Import Settings - Select all categories
+image::{_imagesdir}appendices/dev-env/intellij-idea/030-import-settings/020-select-all.png[width="300px"]
+
+And then restart:
+
+.IntelliJ Import Settings - Restart
+image::{_imagesdir}appendices/dev-env/intellij-idea/030-import-settings/030-restart.png[width="200px"]
+
+
+[[_cgcon_ide_intellij_other-settings-compiler]]
+=== Other Settings (Compiler)
+
+There are also some other settings that influence the compiler. We highly recommend you set these.
+
+On the *Compiler* Settings page, ensure that `build automatically` is enabled (and optionally `compile independent modules in parallel`):
+
+.IntelliJ Compiler Settings
+image::{_imagesdir}appendices/dev-env/intellij-idea/040-other-settings-compiler/010-build-automatically.png[width="600px"]
+
+
+On the *Annotation Processors* page, enable and adjust for the 'default' setting:
+
+.IntelliJ Annotation Processor Settings
+image::{_imagesdir}appendices/dev-env/intellij-idea/040-other-settings-compiler/020-annotation-processor.png[width="600px"]
+
+This setting enables the generation of the `Q*` classes for DataNucleus type-safe queries, as well as being required
+for frameworks such as xref:_cg_ide_project-lombok[Project Lombok].
+
+[NOTE]
+====
+IntelliJ may also have inferred these settings for specific projects/modules when importing; review the list on the left to see if the default is overridden and fix/delete as required.
+====
+
+
+
+[[_cgcon_ide_intellij_other-settings-maven]]
+=== Other Settings (Maven)
+
+There are also some other settings for Maven that we recommend you adjust (though these are less critical):
+
+First, specify an up-to-date Maven installation, using `File > Settings` (or `IntelliJ > Preferences` if on MacOS):
+
+.IntelliJ Maven Settings - Installation
+image::{_imagesdir}appendices/dev-env/intellij-idea/042-other-settings-maven/010-maven-installation.png[width="600px"]
+
+Still on the Maven settings page, configure as follows:
+
+.IntelliJ Maven Settings - Configuration
+image::{_imagesdir}appendices/dev-env/intellij-idea/042-other-settings-maven/020-maven-configuration.png[width="600px"]
+
+
+=== Other Settings (Misc)
+
+These settings are optional but also recommended.
+
+On the *auto import* page, check the `optimize imports on the fly` and `add unambiguous imports on the fly`
+
+.IntelliJ Maven Settings - Auto Import
+image::{_imagesdir}appendices/dev-env/intellij-idea/044-other-settings-misc/010-auto-import.png[width="600px"]
+
+
+
+
+== Importing Maven Modules
+
+Let's load in some actual code! We do this by importing the Maven modules.
+
+First up, open up the Maven tool window (`View > Tool Windows > Maven Projects`). You can then use the 'plus' button to add Maven modules. In the screenshot you can see we've loaded in Apache Isis core; the modules are listed in the _Maven Projects_ window and corresponding (IntelliJ) modules are shown in the _Projects_ window:
+
+.IntelliJ Maven Module Management - Importing Maven modules
+image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/010-maven-modules-view.png[width="730px"]
+
+We can then import another module (from some other directory). For example, here we are importing the Isis Addons' todoapp example:
+
+
+.IntelliJ Maven Module Management - Importing another Module
+image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/020-adding-another-module.png[width="400px"]
+
+You should then see the new Maven module loaded in the _Projects_ window and also the _Maven Projects_ window:
+
+.IntelliJ Maven Module Management -
+image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/030-other-module-added.png[width="730px"]
+
+If any dependencies are already loaded in the project, then IntelliJ will automatically update the CLASSPATH to resolve to locally held modules (rather from `.m2/repository` folder). So, for example (assuming that the `<version>` is correct, of course), the Isis todoapp will have local dependencies on the Apache Isis core.
+
+You can press F4 (or use `File > Project Structure`) to see the resolved classpath for any of the modules loaded into the project.
+
+If you want to focus on one set of code (eg the Isis todoapp but not Apache Isis core) then you _could_ remove the module; but better is to ignore those modules. This will remove from the the _Projects_ window but keep them available in the _Maven Projects_ window for when you next want to work on them:
+
+.IntelliJ Maven Module Management - Ignoring Modules
+image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/040-ignoring-modules.png[width="730px"]
+
+Confirm that it's ok to ignore these modules:
+
+.IntelliJ Maven Module Management - Ignoring Modules (ctd)
+image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/050-ignoring-modules-2.png[width="300px"]
+
+All being well you should see that the _Projects_ window now only contains the code you are working on. Its classpath dependencies will be adjusted (eg to resolve to Apache Isis core from `.m2/repository`):
+
+.IntelliJ Maven Module Management - Updated Projects Window
+image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/060-ignored-modules.png[width="730px"]
+
+
+
+== Running
+
+Let's see how to run both the app and the tests.
+
+=== Running the App
+
+Once you've imported your Isis application, we should run it. We do this by creating a Run configuration, using `Run > Edit Configurations`.
+
+Set up the details as follows:
+
+.IntelliJ Running the App - Run Configuration
+image::{_imagesdir}appendices/dev-env/intellij-idea/110-running-the-app/010-run-configuration.png[width="600px"]
+
+We specify the `Main class` to be `org.apache.isis.WebServer`; this is a wrapper around Jetty. It's possible to pass program arguments to this (eg to automatically install fixtures), but for now leave this blank.
+
+Also note that `Use classpath of module` is the webapp module for your app, and that the `working directory` is `$MODULE_DIR$`.
+
+Next, and most importantly, configure the DataNucleus enhancer to run for your `dom` goal. This can be done by defining a Maven goal to run before the app:
+
+.IntelliJ Running the App - Datanucleus Enhancer Goal
+image::{_imagesdir}appendices/dev-env/intellij-idea/110-running-the-app/020-datanucleus-enhancer-goal.png[width="400px"]
+
+The `-o` flag in the goal means run off-line; this will run faster.
+
+WARNING: if you forget to set up the enhancer goal, or don't run it on the correct (dom) module, then you will get all sorts of errors when you startup. These usually manifest themselves as class cast exception in DataNucleus.
+
+You should now be able to run the app using `Run > Run Configuration`. The same configuration can also be used to debug the app if you so need.
+
+
+=== Running the Unit Tests
+
+The easiest way to run the unit tests is just to right click on the `dom` module in the _Project Window_, and choose run unit tests. Hopefully your tests will pass (!).
+
+.IntelliJ Running the App - Unit Tests Run Configuration
+image::{_imagesdir}appendices/dev-env/intellij-idea/110-running-the-app/030-running-unit-tests.png[width="600px"]
+
+As a side-effect, this will create a run configuration, very similar to the one we manually created for the main app:
+
+.IntelliJ Running the App - Unit Tests Run Configuration
+image::{_imagesdir}appendices/dev-env/intellij-idea/110-running-the-app/040-running-unit-tests-run-configuration.png[width="600px"]
+
+Thereafter, you should run units by selecting this configuration (if you use the right click approach you'll end up with lots of run configurations, all similar).
+
+=== Running the Integration Tests
+
+Integration tests can be run in the same way as unit tests, however the `dom` module must also have been enhanced.
+
+One approach is to initially run the tests use the right click on the `integtests` module; the tests will fail because the code won't have been enhanced, but we can then go and update the run configuration to run the datanucleus enhancer goal (same as when running the application):
+
+.IntelliJ Running the App - Integration Tests Run Configuration
+image::{_imagesdir}appendices/dev-env/intellij-idea/110-running-the-app/050-running-integration-tests-run-configuration.png[width="600px"]
+
+
+
+
+== Hints and Tips
+
+=== Keyboard Cheat Sheets
+
+You can download 1-page PDFs cheat sheets for IntelliJ's keyboard shortcuts:
+* for link:https://www.jetbrains.com/idea/docs/IntelliJIDEA_ReferenceCard.pdf[Windows]
+* for link:https://www.jetbrains.com/idea/docs/IntelliJIDEA_ReferenceCard_Mac.pdf[MacOS]
+
+Probably the most important shortcut on them is for `Find Action`:
+- `ctrl-shift-A` on Windows
+- `cmd-shift-A` on MacOS.
+
+This will let you search for any action just by typing its name.
+
+### Switch between Tools & Editors
+
+The Tool Windows are the views around the editor (to left, bottom and right). It's possible to move these around to your preferred locations.
+
+* Use `alt-1` through `alt-9` (or `cmd-1` through `alt-9`) to select the tool windows
+** Press it twice and the tool window will hide itself; so can use to toggle
+* If in the _Project Window_ (say) and hit enter on a file, then it will be shown in the editor, but (conveniently) the focus remains in the tool window. To switch to the editor, just press `Esc`.
+** If in the _Terminal Window_, you'll need to press `Shift-Esc`.
+* If on the editor and want to locate the file in (say) the _Project Window_, use `alt-F1`.
+* To change the size of any tool window, use `ctrl-shift-arrow`
+
+Using these shortcuts you can easily toggle between the tool windows and the editor, without using the mouse. Peachy!
+
+=== Navigating Around
+
+For all of the following, you don't need to type every letter, typing "ab" will actually search for ".*a.*b.*".
+
+* to open classes or files or methods that you know the name of:
+** `ctrl-N` to open class
+** `ctrl-shift-N` to open a file
+** (bit fiddly this) `ctrl-shift-alt-N` to search for any symbol.
+* open up dialog of recent files: `ctrl-E`
+* search for any file: `shift-shift`
+
+Navigating around:
+* find callers of a method (the call hierarchy): `ctrl-alt-H`
+* find subclasses or overrides: `ctrl-alt-B`
+* find superclasses/interface/declaration: `ctrl-B`
+
+Viewing the structure (ie outline) of a class
+* `ctrl-F12` will pop-up a dialog showing all members
+** hit `ctrl-F12` again to also see inherited members
+
+
+=== Editing
+
+* Extend selection using `ctrl-W`
+** and contract it down again using `ctrl-shift-W`
+* to duplicate a line, it's `ctrl-D`
+** if you have some text selected (or even some lines), it'll actually duplicate the entire selection
+* to delete a line, it's `ctrl-X`
+* to move a line up or down: `shift-alt-up` and `shift-alt-down`
+** if you have selected several lines, it'll move them all togethe
+* `ctrl-shift-J` can be handy for joining lines together
+** just hit enter to split them apart (even in string quotes; IntelliJ will "do the right thing")
+
+### Intentions and Code Completion
+
+Massively useful is the "Intentions" popup; IntelliJ tries to guess what you might want to do. You can activate this using`alt-enter`, whenever you see a lightbulb/tooltip in the margin of the current line.
+
+Code completion usually happens whenever you type '.'. You can also use `ctrl-space` to bring these up.
+
+In certain circumstances (eg in methods0) you can also type `ctrl-shift-space` to get a smart list of methods etc that you might want to call. Can be useful.
+
+Last, when invoking a method, use `ctrl-P` to see the parameter types.
+
+
+=== Refactoring
+
+Loads of good stuff on the `Refactor` menu; most used are:
+
+* Rename (`shift-F6`)
+* Extract
+** method: `ctrl-alt-M`
+** variable: `ctrl-alt-V`
+* Inline method/variable: `ctrl-alt-N`
+* Change signature
+
+If you can't remember all those shortcuts, just use `ctrl-shift-alt-T` (might want to rebind that to something else!) and get a context-sensitive list of refactorings available for the currently selected object
+
+
+=== Plugins
+
+You might want to set up some additional plugins. You can do this using `File > Settings > Plugins` (or equivalently `File > Other Settings > Configure Plugins`).
+
+Recommended are:
+
+* link:https://plugins.jetbrains.com/plugin/7179?pr=idea[Maven Helper] plugin
++
+More on this below.
+
+* link:https://github.com/asciidoctor/asciidoctor-intellij-plugin[AsciiDoctor] plugin
++
+Useful if you are doing any authoring of documents.
+
+Some others you might like to explore are:
+
+.IntelliJ Plugins
+image::{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/020-some-plugins-confirmation.png[width="600px"]
+
+==== Maven Helper Plugin
+
+This plugin provides a couple of great features. One is better visualization of dependency trees (similar to Eclipse).
+
+If you open a `pom.xml` file, you'll see an additional "Dependencies" tab:
+
+image::{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/010-dependency-tab.png[width="600px",link="{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/010-dependency-tab.png"]
+
+Clicking on this gives a graphical tree representation of the dependencies, similar to that obtained by `mvn dependency:tree`, but filterable.
+
+image::{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/020-dependency-as-tree.png[width="600px",link="{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/020-dependency-as-tree.png"]
+
+The plugin also provides the ability to easily run a Maven goal on a project:
+
+image::{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/030-maven-run-goal.png[width="600px",link="{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/030-maven-run-goal.png"]
+
+This menu can also be bound to a keystroke so that it is available as a pop-up:
+
+image::{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/040-maven-quick-run.png[width="600px",link="{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/040-maven-quick-run.png"]
+
+
+=== Troubleshooting
+
+When a Maven module is imported, IntelliJ generates its own project files (suffix `.ipr`), and the application is actually built from that.
+
+Occasionally these don't keep in sync (even if auto-import of Maven modules has been enabled).
+
+To fix the issue, try:
+* reimport module
+* rebuild selected modules/entire project
+* remove and then re-add the project
+* restart, invalidating caches
+* hit StackOverflow (!)
+
+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`.
+
+If you hit an error of "duplicate classes":
+
+image::{_imagesdir}appendices/dev-env/intellij-idea/060-troubleshooting/010-duplicate-classes.png[width="600px",link="{_imagesdir}appendices/dev-env/intellij-idea/060-troubleshooting/010-duplicate-classes.png"]
+
+then make sure you have correctly configured the xref:_cg_ide_intellij_other-settings-compiler[annotation processor]
+settings. Pay attention in particular to the "Production sources directory" and "Test sources directory", that these
+are set up correctly.
+
+
+
+== Running Integration Tests
+
+
+When running integration tests from within IntelliJ, make sure that the `search for tests` radio button is set to `In single module`:
+
+image::{_imagesdir}appendices/dev-env/intellij-idea/400-running-integtests/run-debug-configuration-single-module.png[width="600px",link="{_imagesdir}appendices/dev-env/intellij-idea/400-running-integtests/run-debug-configuration-single-module.png"]
+
+If this radio button is set to one of the other options then you may obtain class loading issues; these result from IntelliJ attempting to run unit tests of the `dom` project that depend on test classes in that module, but using the classpath of the `integtests` module whereby the `dom` test-classes (`test-jar` artifact) are not exposed on the Maven classpath.
+
+
+[[_cgcon_ide_intellij_advanced]]
+== Advanced
+
+In this section are a couple of options that will reduce the length of the change code/build/deploy/review feedback loop.
+
+
+[[_cgcon_ide_intellij_advanced_dcevm]]
+=== Setting up Dynamic Reloading
+
+link:github.com/dcevm/dcevm[DCEVM] enhances the JVM with true hot-swap adding/removing of methods as well as more
+reliable hot swapping of the implementation of existing methods.
+
+In the context of Apache Isis, this is very useful for contributed actions and mixins and also view models; you should
+then be able to write these actions and have them be picked up without restarting the application.
+
+Changing persisting domain entities is more problematic, for two reasons: the JDO/DataNucleus enhancer needs to run on
+domain entities, and also at runtime JDO/DataNucleus would need to rebuild its own metamodel. You may find that adding
+actions will work, but adding new properties or collections is much less likely to.
+
+To set up DCEVM, download the appropriate JAR from the link:https://dcevm.github.io/[github page], and run the
+installer. For example:
+
+[source,bash]
+----
+java -jar DCEVM-light-8u51-installer.jar
+----
+
+[TIP]
+====
+Be sure to run with appropriate privileges to be able to write to the installation directories of the JDK. If running
+on Windows, that means running as `Administrator`.
+====
+
+
+After a few seconds this will display a dialog listing all installations of JDK that have been found:
+
+image::{_imagesdir}appendices/dev-env/intellij-idea/070-advanced/010-dcevm-list-of-found-jdk-installations.png[width="600px",link="{_imagesdir}appendices/dev-env/intellij-idea/070-advanced/010-dcevm-list-of-found-jdk-installations.png"]
+
+
+Select the corresponding installation, and select `Replace by DCEVM`.
+
+image::{_imagesdir}appendices/dev-env/intellij-idea/070-advanced/020-dcevm-once-installed.png[width="600px",link="{_imagesdir}appendices/dev-env/intellij-idea/070-advanced/020-dcevm-once-installed.png"]
+
+
+In IntelliJ, register the JDK in `File > Project Structure` dialog:
+
+image::{_imagesdir}appendices/dev-env/intellij-idea/070-advanced/030-dcevm-intellij-project-structure.png[width="600px",link="{_imagesdir}appendices/dev-env/intellij-idea/070-advanced/030-dcevm-intellij-project-structure.png"]
+
+Finally, in the run configuration, select the patched JDK:
+
+image::{_imagesdir}appendices/dev-env/intellij-idea/070-advanced/040-dcevm-run-configuration.png[width="600px",link="{_imagesdir}appendices/dev-env/intellij-idea/070-advanced/040-dcevm-run-configuration.png"]
+
+
+
+
+=== Setting up JRebel
+
+See the repo for the (non-ASF) link:https://github.com/isisaddons/isis-jrebel-plugin[Isis JRebel] plugin. With some
+modification, this should work for IntelliJ too.
+
+Note that JRebel is a commercial product, requiring a license. At the time of writing there is also currently a
+non-commercial free license (though note this comes with some usage conditions).
http://git-wip-us.apache.org/repos/asf/isis/blob/49ccfd90/adocs/documentation/src/main/asciidoc/guides/_cgcon_ide_project-lombok.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cgcon_ide_project-lombok.adoc b/adocs/documentation/src/main/asciidoc/guides/_cgcon_ide_project-lombok.adoc
new file mode 100644
index 0000000..28695f0
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cgcon_ide_project-lombok.adoc
@@ -0,0 +1,50 @@
+[[_cgcon_ide_project-lombok]]
+= Project Lombok
+: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/
+
+
+
+link:https://projectlombok.org/[Project Lombok] is an open source project to reduce the amount of boilerplate in
+your code.
+
+For example, rather than write:
+
+[source,java]
+----
+private String name;
+public String getName() {
+ return name;
+}
+public void setName(String name) {
+ this.name = name;
+}
+----
+
+you can instead write simply:
+
+[source,java]
+----
+@Getter @Setter
+private String name;
+----
+
+Under the covers it is implemented as an annotation processor; it basically hooks into the Java compiler
+so that it can emit additional bytecode (eg for the getter and setter). See xref:_cg_ide_intellij_other-settings-compiler[here] for details of setting up in IntelliJ (Eclipse has very similar support).
+
+Apache Isis supports link:https://projectlombok.org/[Project Lombok], in that the annotations that would normally be placed on the getter (namely xref:rgant.adoc#_rgant-Property[`Property`], xref:rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`], xref:rgant.adoc#_rgant-Collection[`@Collection`], xref:rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`] and xref:rgant.adoc#_rgant-MemberOrder[`@MemberOrder`]) can be placed on the field instead.
+
+
+There are plugins for Lombok for maven; it's just a matter of adding the required dependency. To compile the code
+within your IDE (eg so that its compiler "knows" that there is, actually, a getter and setter) will require an
+Lombok plugin appropriate to that IDE. See the link:https://projectlombok.org/download.html[Lombok download page] for more information.
+
+
+
+== Future thoughts
+
+In the future we might extend/fork Lombok so that it understands Isis' own annotations (ie xref:rgant.adoc#_rgant-Property[`@Property`] and xref:rgant.adoc#_rgant-Collection[`@Collection`])
+rather than Lombok's own `@Getter` and `@Setter.
+
+It might also be possible to use Lombok to generate the domain event classes for each member.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/49ccfd90/adocs/documentation/src/main/asciidoc/guides/_cgcon_isis-maven-plugin.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cgcon_isis-maven-plugin.adoc b/adocs/documentation/src/main/asciidoc/guides/_cgcon_isis-maven-plugin.adoc
new file mode 100644
index 0000000..b2ee804
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cgcon_isis-maven-plugin.adoc
@@ -0,0 +1,79 @@
+[[_cgcon_isis-maven-plugin]]
+= Apache Isis Maven Plugin
+: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/
+:toc: right
+
+The Apache Isis Maven plugin defines three goals:
+
+* `validate` +
++
+Use to verify at build time that the metamodel of an application is valid. This runs the `MetaModelValidator` that is also run when the application is started up.
+
+* `swagger` +
++
+Uses the xref:rgsvc.adoc#_rgsvc_api_SwaggerService[`SwaggerService`] to generate link:http://swagger.io[Swagger] spec files that describe the public and/or private RESTful APIs exposed by the xref:ugvro.adoc#[RestfulObjects viewer].
+
+* `xsd` +
++
+Uses the xref:rgsvc.adoc#_rgsvc_api_JaxbService[`JaxbService`] to generate XSD schemas from any JAXB-annotated view models/DTOs. +
++
+This is instead of and preferable to using the JAXB link:https://jaxb.java.net/2.2.4/docs/schemagen.html[schemagen] tool, because it uses the framework's support (via xref:rgant.adoc#_rgant-XmlJavaValueType[`@XmlJavaValueType`]) to translate any references to domain objects into ``OidDto``s (as defined by the Apache Isis xref:rgcms.adoc#_rgcms_schema-common[common schema]).
+
+The `validate` goal is by default bound to the `test` phase, and the `swagger` goal is by default bound to the `package` phase; both are typically of your application's `dom` sub-module. The `xsd` goal meanwhile defaults to the `generate-resources` phase, and this is generally used in a completely separate sub-module. An example can be found in the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] example app; the separate submodule that uses the `xsd` goal is (also) called `todoapp-xsd`.
+
+All of these goals require an xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`] to point the plugin at, so that
+it knows how to bootstrap an Isis runtime. This is discussed below, followed by sections on configuring the two goals.
+
+
+== `AppManifest`
+
+As noted in the introduction, all the goals require an xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`]
+to point the plugin at, so that it knows how to bootstrap an Isis runtime.
+
+This can be extremely minimal. For example, the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp]'s
+manifest is:
+
+
+[source,java]
+----
+package domainapp.dom;
+...
+public class DomainAppDomManifest implements AppManifest {
+ @Override
+ public List<Class<?>> getModules() {
+ return Arrays.asList(
+ DomainAppDomainModule.class // domain (entities and repositories)
+ );
+ }
+ @Override
+ public List<Class<?>> getAdditionalServices() { return Collections.emptyList(); }
+ @Override
+ public String getAuthenticationMechanism() { return null; }
+ @Override
+ public String getAuthorizationMechanism() { return null; }
+ @Override
+ public List<Class<? extends FixtureScript>> getFixtures() { return null; }
+ @Override
+ public Map<String, String> getConfigurationProperties() { return null; }
+}
+----
+
+where `DomainAppDomainModule` simply identifies the package for the manifest to search under:
+
+[source,java]
+----
+package domainapp.dom;
+public final class DomainAppDomainModule { }
+----
+
+
+As you'll see below, the configuration for each of the goals both refer to this app manifest.
+
+
+
+include::_cgcon_isis-maven-plugin_validate.adoc[leveloffset=+1]
+include::_cgcon_isis-maven-plugin_swagger.adoc[leveloffset=+1]
+include::_cgcon_isis-maven-plugin_xsd.adoc[leveloffset=+1]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/49ccfd90/adocs/documentation/src/main/asciidoc/guides/_cgcon_isis-maven-plugin_swagger.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cgcon_isis-maven-plugin_swagger.adoc b/adocs/documentation/src/main/asciidoc/guides/_cgcon_isis-maven-plugin_swagger.adoc
new file mode 100644
index 0000000..770bb67
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cgcon_isis-maven-plugin_swagger.adoc
@@ -0,0 +1,107 @@
+[[_cgcon_isis-maven-plugin_swagger]]
+= `swagger` goal
+: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/
+:toc: right
+
+
+The `swagger` goal of the `isis-maven-plugin` uses the xref:rgsvc.adoc#_rgsvc_api_SwaggerService[`SwaggerService`] to
+generate link:http://swagger.io[Swagger] spec files to describe the public and/or private RESTful APIs exposed by the xref:ugvro.adoc#[RestfulObjects viewer].
+
+These spec files, once generated, can then be used in the build pipeline to generate client-side stubs, typically using Swagger's own link:https://github.com/swagger-api/swagger-codegen/tree/master/modules/swagger-codegen-maven-plugin[swagger-codegen-maven] plugin.
+
+
+The `swagger` goal defines the following properties:
+
+* `appManifest` - fully qualified class name for the app manifest used to bootstrap the application (see discussion above)
+
+* `fileNamePrefix` - (optional) a prefix to the generated file names (is suffixed by the requested visibilities, see below). +
++
+Defaults to `swagger`.
+
+* `visibilities` - (optional) list of required visibilities. +
++
+Defaults to [`PUBLIC`, `PRIVATE`] (meaning that two spec files will be created).
+
+* `format` - (optional) which format to generate, either `JSON` or `YAML`. +
++
+Defaults to `JSON`.
+
+* `output` - (optional) subdirectory under the `target` directory to generate the swagger spec files +
++
+Defaults to `generated-resources/isis-swagger`
+
+
+== `dom` submodule
+
+Update the `pom.xml` (in your project's `dom` module):
+
+[source,xml]
+----
+<profile>
+ <id>isis-swagger</id>
+ <activation>
+ <property>
+ <name>!skip.isis-swagger</name> <!--1-->
+ </property>
+ </activation>
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.isis.tool</groupId>
+ <artifactId>isis-maven-plugin</artifactId>
+ <version>${isis.version}</version> <!--2-->
+ <configuration>
+ <appManifest>domainapp.dom.DomainAppDomManifest</appManifest> <!--3-->
+ <visibilities> <!--4-->
+ <visibility>PUBLIC</visibility>
+ <visibility>PRIVATE</visibility>
+ </visibilities>
+ <format>JSON</format> <!--5-->
+ <fileNamePrefix>swagger</fileNamePrefix> <!--5-->
+ </configuration>
+ <dependencies>
+ <dependency>
+ <groupId>${project.groupId}</groupId>
+ <artifactId>simpleapp-dom</artifactId> <!--6-->
+ <version>${project.version}</version>
+ </dependency>
+ <dependency>
+ <groupId>com.google.guava</groupId>
+ <artifactId>guava</artifactId>
+ <version>16.0.1</version>
+ </dependency>
+ </dependencies>
+ <executions>
+ <execution>
+ <phase>package</phase>
+ <goals>
+ <goal>swagger</goal> <!--7-->
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+</profile>
+----
+<1> the profile is active by default, though can be disabled using `-Dskip.isis-swagger`
+<2> set to `1.11.0` (or any later version)
+<3> the manifest discussed previously; adjust as required
+<4> the visibilities to create (one swagger spec file per visibility listed)
+<5> which file format to generate the spec files as.
+<6> the `dom` module for the project; adjust as required
+<7> binds the plugin's `swagger` goal to the Maven `package` lifecycle phase (ie the goal will be called when `mvn package` is run).
+
+
+
+
+== To run
+
+The plugin is activated by default, so is run simply using:
+
+[source,bash]
+----
+mvn package
+----
http://git-wip-us.apache.org/repos/asf/isis/blob/49ccfd90/adocs/documentation/src/main/asciidoc/guides/_cgcon_isis-maven-plugin_validate.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cgcon_isis-maven-plugin_validate.adoc b/adocs/documentation/src/main/asciidoc/guides/_cgcon_isis-maven-plugin_validate.adoc
new file mode 100644
index 0000000..867542d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cgcon_isis-maven-plugin_validate.adoc
@@ -0,0 +1,241 @@
+[[_cgcon_isis-maven-plugin_validate]]
+= `validate` goal
+: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/
+:toc: right
+
+
+The Apache Isis programming model requires that a number of naming conventions are followed.
+
+For example, the validator will detect any orphaned supporting methods (eg `hideXxx()`) if the corresponding property
+or action has been renamed or deleted but the supporting method was not also updated. Another example is that a class
+cannot have a title specified both using `title()` method and also using `@Title` annotation.
+
+When running the application these are enforced by the `MetaModelValidator` component that detects these errors, failing fast.
+
+The purpose of the `validate` goal of the `isis-maven-plugin` is to enforce these naming conventions at build time,
+typically enforced by way of a continuous integration server.
+
+The `validate` goal defines a single property:
+
+* `appManifest` - fully qualified class name for the app manifest used to bootstrap the application (see discussion above)
+
+The sections below explain how to configure the plugin within an app.
+
+[NOTE]
+====
+The instructions given here relate to `1.10.0`. This goal was also released for `1.9.0`, but with a slightly
+different configuration; see the final section for differences.
+====
+
+
+== `dom` submodule
+
+Update the `pom.xml` (in your project's `dom` module):
+
+[source,xml]
+----
+<profile>
+ <id>isis-validate</id>
+ <activation>
+ <property>
+ <name>!skip.isis-validate</name> <!--1-->
+ </property>
+ </activation>
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.isis.tool</groupId>
+ <artifactId>isis-maven-plugin</artifactId>
+ <version>${isis.version}</version> <!--2-->
+ <configuration>
+ <appManifest>domainapp.dom.DomainAppDomManifest</appManifest> <!--3-->
+ </configuration>
+ <dependencies>
+ <dependency>
+ <groupId>${project.groupId}</groupId>
+ <artifactId>simpleapp-dom</artifactId> <!--4-->
+ <version>${project.version}</version>
+ </dependency>
+ <!-- workaround to avoid conflict with plexus-default -->
+ <dependency>
+ <groupId>com.google.guava</groupId>
+ <artifactId>guava</artifactId>
+ <version>16.0.1</version>
+ </dependency>
+ </dependencies>
+ <executions>
+ <execution>
+ <phase>test</phase>
+ <goals>
+ <goal>validate</goal> <!--5-->
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+</profile>
+----
+<1> the profile is active by default, though can be disabled using `-Dskip.isis-validate`
+<2> set to `1.10.0` (or any later version)
+<3> the manifest discussed previously; adjust as required
+<4> the `dom` module for the project; adjust as required
+<5> binds the plugin's `validate` goal to the Maven `test` lifecycle phase (ie the goal will be called when `mvn test` is run).
+
+
+
+
+== To run
+
+The plugin is activated by default, so is run simply using:
+
+[source,bash]
+----
+mvn test
+----
+
+This will run any tests, and then also - because the plugin is activated by the `isis-validate` property and bound to the `test` phase, will run the plugin's `validate` goal.
+
+
+If for any reason you want to disable the validation, use:
+
+[source,bash]
+----
+mvn test -Dskip.isis-validate
+----
+
+
+
+== Example of failure
+
+In the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp] application the `SimpleObject` defines an `updateName` action. This has a supporting method:
+
+
+[source,java]
+----
+public SimpleObject updateName( ... ) { ... }
+public String default0UpdateName() { ... }
+----
+
+We can introduce an error by misspelling the supporting method, for example:
+
+[source,java]
+----
+public String default0XUpdateName() { ... }
+----
+
+Running `mvn test` then generates this output:
+
+
+[source,bash]
+----
+[error]
+[error]
+[error]
+[error] domainapp.dom.simple.SimpleObject#default0XUpdateName: has prefix default, is probably a supporting method for a property, collection or action. If the method is intended to be an action, then rename and use @ActionLayout(named="...") or ignore completely using @Programmatic
+[error]
+[error]
+[error]
+[INFO] ------------------------------------------------------------------------
+[INFO] Reactor Summary:
+[INFO]
+[INFO] Simple App ......................................... SUCCESS [ 0.087 s]
+[INFO] Simple App DOM ..................................... FAILURE [ 4.182 s]
+[INFO] Simple App Fixtures ................................ SKIPPED
+[INFO] Simple App Application ............................. SKIPPED
+[INFO] Simple App Integration Tests ....................... SKIPPED
+[INFO] Simple App Webapp .................................. SKIPPED
+[INFO] ------------------------------------------------------------------------
+[INFO] BUILD FAILURE
+[INFO] ------------------------------------------------------------------------
+[INFO] ...
+[ERROR] Failed to execute goal org.apache.isis.tool:isis-maven-plugin:1.12.0-SNAPSHOT:validate (default) on project simpleapp-dom: 1 problems found. -> [Help 1]
+----
+
+If one were to attempt to run the application, the same error would appear in the log files on startup (and the application would not boot).
+
+
+
+
+== Custom validation rules
+
+It is also possible to customize the validation, explained xref:ugbtb.adoc#_ugbtb_programming-model_custom-validator[here]. For example, you could enforce project-specific conventions by implementing a custom `MetaModelValidator`, and registering using a configuration property.
+
+To support this using `AppManifest`s, override its `getConfigurationProperties()` method:
+
+[source,ini]
+----
+public class DomainAppDomManifest implements AppManifest {
+ ...
+ public Map<String, String> getConfigurationProperties() {
+ final Map<String, String> map = Maps.newTreeMap();
+ map.put("isis.reflector.validator","com.mycompany.myapp.MyMetaModelValidator");
+ return map;
+ }
+}
+----
+
+
+== 1.9.0 version
+
+The `1.9.0` version of the plugin requires slightly different configuratoin. Rather than using an `AppManifest`, instead the configuration directory containing `isis.properties` is specified:
+
+[source,xml]
+----
+<profile>
+ <id>isis-validate</id>
+ <activation>
+ <activeByDefault>false</activeByDefault> <!--1-->
+ </activation>
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.isis.tool</groupId>
+ <artifactId>isis-maven-plugin</artifactId>
+ <version>1.9.0-SNAPSHOT</version>
+ <configuration>
+ <isisConfigDir>../webapp/src/main/webapp/WEB-INF</isisConfigDir> <!--2-->
+ </configuration>
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.isis.example.application</groupId>
+ <artifactId>simpleapp-dom</artifactId>
+ <version>1.9.0-SNAPSHOT</version>
+ </dependency>
+ <!-- workaround to avoid conflict with plexus-default -->
+ <dependency>
+ <groupId>com.google.guava</groupId>
+ <artifactId>guava</artifactId>
+ <version>16.0.1</version>
+ </dependency>
+ </dependencies>
+ <executions>
+ <execution>
+ <phase>test</phase>
+ <goals>
+ <goal>validate</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+</profile>
+----
+<1> activated using the `-P` profile flag rather than a `-D` system property
+<2> specify the `isisConfigDir` directory (containing the `isis.properties` file).
+
+To use the `1.9.0` version, use:
+
+[source,bash]
+----
+mvn -P isis-validate test
+----
+
+[NOTE]
+====
+Note that the `isisConfigDir` property was removed in `1.10.0`; only the `AppManifest` approach is supported.
+====
+
http://git-wip-us.apache.org/repos/asf/isis/blob/49ccfd90/adocs/documentation/src/main/asciidoc/guides/_cgcon_isis-maven-plugin_xsd.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cgcon_isis-maven-plugin_xsd.adoc b/adocs/documentation/src/main/asciidoc/guides/_cgcon_isis-maven-plugin_xsd.adoc
new file mode 100644
index 0000000..024fc49
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cgcon_isis-maven-plugin_xsd.adoc
@@ -0,0 +1,329 @@
+[[_cgcon_isis-maven-plugin_xsd]]
+= `xsd` goal
+: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/
+:toc: right
+
+
+The `xsd` goal of the `isis-maven-plugin` uses the xref:rgsvc.adoc#_rgsvc_api_JaxbService[`JaxbService`] to
+generate XSD schemas from any JAXB-annotated xref:ugbtb.adoc#_ugbtb_view-models[view model/DTOs].
+
+This is instead of and preferable to using the JAXB link:https://jaxb.java.net/2.2.4/docs/schemagen.html[schemagen]
+tool, because it uses the framework's support (via
+xref:rgant.adoc#_rgant-XmlJavaValueType[`@XmlJavaValueType`]) to translate any references to domain
+objects into ``OidDto``s (as defined by the Apache Isis xref:rgcms.adoc#_rgcms_schema-common[common schema]).
+
+The `xsd` goal defines the following properties:
+
+* `appManifest` - fully qualified class name for the app manifest used to bootstrap the application (see discussion above)
+
+* `jaxbClasses` - a list of xref:rg.adoc#_ugbtb_view-models_jaxb[JAXB-annotated view model] classes;
+
+* `output` - (optional) subdirectory under the `target` directory to generate the XSDs +
++
+Defaults to `generated-resources/isis-xsd`
+
+* `separate` - (optional) whether to create separate directories for each JAXB-class. +
++
+Defaults to `false`. Most DTO classes will reference one another or the xref:rgcms.adoc#_rgcms_schema-common[common schema]. Normally it's fine to merge all these XSDs together. This property, if set, results in each a separate directory for each generation of its XSD or XSDs.
+
+As a convenience to any (Java) consumers, the XSDs generated from the view models can then in turn be generated
+into DTOs. The original view models and these DTOs are similar but not identical: while the view models can only be used
+within the Isis application (they may reference underlying domain entities) whereas the DTO classes generated from the
+XSDs can be used standalone, eg by a Java subscriber running on an ESB such as Apache Camel.
+
+The rest of this section explains how to configure a new `xsd` submodule that uses the `isis-maven-plugin` along with
+other standard plugins in order to generate both XSDs and DTOs. The `pom.xml` described below uses Maven profiles
+to separate out these two responsibilities.
+
+
+[[_cgcon_isis-maven-plugin_xsd]]
+== `xsd` submodule
+
+We recommend creating a new submodule that will perform the following build steps:
+
+* run the `xsd` goal (in the `generate-resources` phase) to generate the XSDs from the specified view model/DTOs
+
+* use the link:http://maven.apache.org/plugins/maven-assembly-plugin/[maven-assembly-plugin] to bundle the
+ generated XSD files into a zip file.
+
+* use the `xjc-gen` to generate corresponding DTO classes from the XSDs. +
++
+These are _not_ the same as the original view models; they are provided as a convenience for subscribers to marshall XML documents into Java classes, but running as a standalone process (not part of the Isis app)
+
+
+These two main responsibilities can then be placed into separate Maven profiles, for better modularity. The diagram
+below shows the overall design:
+
+image::{_imagesdir}maven-plugin/xsd-goal.png[width="800px",link="{_imagesdir}maven-plugin/xsd-goal.png"]
+
+For example, here is the `pom.xml` file for the (non-ASF)
+http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] example app's `todoapp-xsd` submodule.
+
+First, the usual boilerplate:
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+
+ <parent>
+ <groupId>org.isisaddons.app</groupId>
+ <artifactId>todoapp</artifactId>
+ <version>1.12.0-SNAPSHOT</version>
+ </parent>
+
+ <artifactId>todoapp-xsd</artifactId>
+ <name>Isis Addons ToDoApp XSD</name>
+
+ <dependencies>
+ <dependency>
+ <groupId>${project.groupId}</groupId>
+ <artifactId>todoapp-app</artifactId> <!--1-->
+ </dependency>
+ </dependencies>
+
+ <profiles>
+ <profile>
+ <id>isis-xsd</id> <!--2-->
+ ...
+ </profile>
+ <profile>
+ <id>xjc</id> <!--3-->
+ ...
+ </profile>
+ </profiles>
+</project>
+----
+<1> depends on the rest of the application's modules
+<2> XSD generation, to run the `xsd` goal and then assemble into a zip file; within a profile for modularity
+<3> XJC generation, to run the `xjc` to generate Java DTO classes from XSDs; within a profile for modularity
+
+
+
+
+
+
+=== XSD profile
+
+The `isis-xsd` profile runs the `xsd` goal of the `isis-maven-plugin`; these are then zipped up by the assembly plugin:
+
+[source,xml]
+----
+<profile>
+ <id>isis-xsd</id>
+ <activation>
+ <property>
+ <name>!skip.isis-xsd</name> <!--1-->
+ </property>
+ </activation>
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.isis.tool</groupId>
+ <artifactId>isis-maven-plugin</artifactId>
+ <version>${isis.version}</version>
+ <configuration>
+ <appManifest>todoapp.dom.ToDoAppDomManifest</appManifest> <!--2-->
+ <jaxbClasses> <!--3-->
+ <jaxbClass>todoapp.app.viewmodels.todoitem.v1_0.ToDoItemDto</jaxbClass>
+ <jaxbClass>todoapp.app.viewmodels.todoitem.v1_1.ToDoItemDto</jaxbClass>
+ </jaxbClasses>
+ </configuration>
+ <dependencies>
+ <dependency>
+ <groupId>${project.groupId}</groupId>
+ <artifactId>todoapp-dom</artifactId>
+ <version>${project.version}</version>
+ </dependency>
+ <dependency> <!--4-->
+ <groupId>com.google.guava</groupId>
+ <artifactId>guava</artifactId>
+ <version>16.0.1</version>
+ </dependency>
+ </dependencies>
+ <executions>
+ <execution>
+ <phase>generate-sources</phase> <!--5-->
+ <goals>
+ <goal>xsd</goal> <!--6-->
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ <plugin>
+ <artifactId>maven-assembly-plugin</artifactId> <!--7-->
+ <version>2.5.3</version>
+ <configuration>
+ <descriptor>src/assembly/dep.xml</descriptor> <!--8-->
+ </configuration>
+ <executions>
+ <execution>
+ <id>create-archive</id>
+ <phase>package</phase>
+ <goals>
+ <goal>single</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+</profile>
+----
+<1> enabled _unless_ `skip.isis-xsd` property specified
+<2> specify the app manifest to bootstrap the Isis runtime within the maven plugin
+<3> enumerate all JAXB-annotated view models
+<4> workaround to avoid conflict with plexus-default
+<5> by default is bound to `generate-resources`, but bind instead to `generate-sources` if also running the `xjc` profile: the XSD are an input to `xjc`, but it is bound by default to `generate-sources` and the `generate-sources` phase runs before the `generate-resources`.
+<6> run the `xsd` goal
+<7> define the assembly plugin
+<8> assembles the XSD schemas into a zip file, as defined by the `dep.xml` file (see below).
+
+ The `dep.xml` file, referenced by the `assembly` plugin, is defined as:
+
+[source,xml]
+----
+<assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2
+ http://maven.apache.org/xsd/assembly-1.1.2.xsd">
+ <id>xsd</id>
+ <formats>
+ <format>zip</format>
+ </formats>
+ <fileSets>
+ <fileSet>
+ <directory>${project.build.directory}/generated-resources/isis-xsd</directory> <!--1-->
+ <outputDirectory>/</outputDirectory>
+ </fileSet>
+ </fileSets>
+</assembly>
+----
+<1> the location that the `xsd` goal writes to.
+
+
+
+=== XJC profile
+
+The `xjc` profile reads the XSD generated by the `xsd` goal, and from it generates Java DTOs. Note that this isn't
+round-tripping: the original view model is only for use within the Isis app, whereas the DTO generated from the XSDs
+is for use in a standalone context, eg in a Java subscriber on an event bus.
+
+The `xjc` profile is defined as:
+
+[source,xml]
+----
+<profile>
+ <id>xjc</id>
+ <activation>
+ <property>
+ <name>!skip.xjc</name> <!--1-->
+ </property>
+ </activation>
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.jvnet.jaxb2.maven2</groupId>
+ <artifactId>maven-jaxb2-plugin</artifactId>
+ <version>0.12.3</version>
+ <executions>
+ <execution>
+ <id>xjc-generate</id>
+ <phase>generate-sources</phase>
+ <goals>
+ <goal>generate</goal>
+ </goals>
+ </execution>
+ </executions>
+ <configuration>
+ <removeOldOutput>true</removeOldOutput>
+ <schemaDirectory> <!--2-->
+ target/generated-resources/isis-xsd/viewmodels.app.todoapp/todoitem
+ </schemaDirectory>
+ <schemaIncludes> <!--3-->
+ <schemaInclude>v1_0/todoitem.xsd</schemaInclude>
+ <schemaInclude>v1_1/todoitem.xsd</schemaInclude>
+ </schemaIncludes>
+ <catalog>src/main/resources/catalog.xml</catalog> <!--4-->
+ </configuration>
+ </plugin>
+ <plugin>
+ <groupId>org.codehaus.mojo</groupId>
+ <artifactId>build-helper-maven-plugin</artifactId> <!--5-->
+ <version>1.9.1</version>
+ <executions>
+ <execution>
+ <id>add-source</id>
+ <phase>generate-sources</phase>
+ <goals>
+ <goal>add-source</goal>
+ </goals>
+ <configuration>
+ <sources>
+ <source>target/generated-sources/xjc</source> <!--6-->
+ </sources>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+</profile>
+----
+<1> enabled _unless_ `skip.xjc` property specified
+<2> specifies the directory that the XSD schemas were generated to by the `isis-maven-plugin`
+<3> specify each of the XSDs to be processed
+<4> catalog file indicates the location of the referenced link:_rgcms_schema-common[common schema] XSDs.
+<5> the `build-helper-maven-plugin` adds the Java source generated by the `xjc` plugin so that it can be compiled and
+packaged as any other code
+<6> the location that the `xjc` plugin generates its source code.
+
+
+The referenced `catalog.xml` file instructs the `xjc` plugin how to resolve referenced schema locations. Only a
+reference for the Apache Isis link:_rgcms_schema-common[common schema] is likely to be needed:
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE catalog
+ PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN"
+ "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">
+<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
+ <public publicId="http://isis.apache.org/schema/common"
+ uri="http://isis.apache.org/schema/common/common.xsd"/> <!--1-->
+</catalog>
+----
+<1> resolve the common schema from the Apache Isis website
+
+
+== To run
+
+The plugin is activated by default, so is run simply using:
+
+[source,bash]
+----
+mvn package
+----
+
+This will generate the XSDs, the DTOs from the XSDs, and package up the XSDs into a ZIP file and the generated DTO
+class files into a regular JAR package.
+
+
+If for any reason you want to disable the generation of the DTOs, use:
+
+[source,bash]
+----
+mvn package -Dskip.xjc
+----
+
+If you want to disable the generation of both the XSDs and the DTOs, use:
+
+[source,bash]
+----
+mvn package -Dskip.xjc -Dskip.isis-xsd
+----
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/49ccfd90/adocs/documentation/src/main/asciidoc/guides/_cgcon_policies.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cgcon_policies.adoc b/adocs/documentation/src/main/asciidoc/guides/_cgcon_policies.adoc
new file mode 100644
index 0000000..0deac4b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cgcon_policies.adoc
@@ -0,0 +1,14 @@
+[[_cgcon_policies]]
+= Policies
+: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/
+:toc: right
+
+
+
+This chapter pulls together various policy documents relating to the development of Apache Isis'.
+
+include::_cgcon_policies_versioning-policy.adoc[leveloffset=+1]
+include::_cgcon_policies_git-policy.adoc[leveloffset=+1]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/49ccfd90/adocs/documentation/src/main/asciidoc/guides/_cgcon_policies_git-policy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cgcon_policies_git-policy.adoc b/adocs/documentation/src/main/asciidoc/guides/_cgcon_policies_git-policy.adoc
new file mode 100644
index 0000000..ff3cc6f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cgcon_policies_git-policy.adoc
@@ -0,0 +1,98 @@
+[[_cgcon_policies_git-policy]]
+= Git Policy
+: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/
+:toc: right
+
+
+
+These notes recommend how contributors should work with git. To understand these notes, the only real concepts that you need to grok are:
+
+* git commits form an acyclic graph, with each commit pointing to its parent commit (or commit**s**, if a merge)
+
+* a branch is merely a pointer to one of these commits; git calls the main branch `master`
+
+* git commits happen in two steps: first they are added to the index (also called the staging area), then they are committed.
+
+For more background reading, see:
+
+* http://git-scm.com/book[Pro Git] book (free in electronic form)
+* https://github.s3.amazonaws.com/media/book.pdf[Git community book]
+* http://git-scm.com/2011/07/11/reset.html[git reset demystified] - differentiating the working directory vs index/staging area
+
+And, of course, there is loads of good advice on http://stackoverflow.com/questions/tagged/git[stackoverflow.com]
+
+
+
+== Workflow
+
+There are many ways of using Git, but the Apache Isis committers have adopted the following workflow:
+
+* create a topic branch for a feature +
++
+[source,bash]
+----
+git checkout -b ISIS-999
+----
+
+* periodically, push the branch to origin (for safekeeping): +
++
+[source,bash]
+----
+git push origin ISIS-999
+----
+
+
+* `rebase` the topic branch periodically on master. +
++
+How often you do this will depend on whether you are collaborating with others on the feature. You need to ensure that your co-worker has no outstanding work before you do this; otherwise it'll create merge conflict hell for them:
++
+[source,bash]
+----
+git checkout master
+git pull
+git checkout ISIS-999
+git rebase master
+git push origin ISIS-999 --force
+----
+
+* when feature is complete, rebase once more (as above), then switch to master and perform a `merge --no-ff`: +
++
+[source,bash]
+----
+git checkout master
+git merge --no-ff ISIS-999
+----
+
+* finally, remove the branch +
++
+[source,bash]
+----
+git branch -d ISIS-999
+git push origin --delete ISIS-999
+----
+
+This way of working gives us the full history on the branch as to what the thought processes were for the feature, but only a single commit on to `master` to see the ultimate impact of the changes (acting a bit like a summary).
+
+
+
+
+
+== Commit message
+
+The minimum we expect in a commit messages is:
+
+[source,bash]
+----
+ISIS-nnn: brief summary here
+
+- optionally, longer details
+- should be written here
+- in bullet points
+----
+
+
+where `ISIS-nnn` is a ticket raised in our https://issues.apache.org/jira/browse/ISIS[JIRA issue tracker].
+
+For non-committers we typically expect more detail again; see the xref:cgcon.adoc#_cgcon_contributing[contributing] page for the longer format recommended for contributors to use.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/49ccfd90/adocs/documentation/src/main/asciidoc/guides/_cgcon_policies_versioning-policy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cgcon_policies_versioning-policy.adoc b/adocs/documentation/src/main/asciidoc/guides/_cgcon_policies_versioning-policy.adoc
new file mode 100644
index 0000000..0c8be7a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cgcon_policies_versioning-policy.adoc
@@ -0,0 +1,35 @@
+[[_cgcom_versioning-policy]]
+= Versioning Policy
+: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/
+:toc: right
+
+
+
+
+
+## Semantic Versioning
+
+Starting from v1.0.0, Apache Isis has adopted link:http://semver.org[semantic versioning] for its versioning policy.
+
+Version numbers are in the form `x.y.z`:
+
+- x is bumped up whenever there a breaking API change
+- y is bumped up whenever there is a new feature that does not break API
+- z is bumped up for minor bug fixes.
+
+This scheme would be adopted for both core and components.
+
+
+
+
+
+
+## Version ranges
+
+Version ranges may not be used. If necessary, end-users can use `<dependencyManagement` elements to have combine components built against different versions of core.
+
+That said, this can introduce instability and so generally we recommend that end-users configure the `maven-enforcer-plugin` and its link:http://maven.apache.org/enforcer/enforcer-rules/dependencyConvergence.html[DependencyConvergence] rule. This will help avoid "jar hell" (components having conflicting dependencies of core).
+
+If there is a conflict, we would ask that end-users engage with Apache Isis committers to have an updated version of the component(s) pushed out.
http://git-wip-us.apache.org/repos/asf/isis/blob/49ccfd90/adocs/documentation/src/main/asciidoc/guides/_rgant-Title.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-Title.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-Title.adoc
index 8ac4423..25473fc 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-Title.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-Title.adoc
@@ -40,7 +40,7 @@ present in the title column. This convention can be overridden using
== Lombok support
-If xref:cg.adoc#_cg_ide_project-lombok[Project Lombok] is being used, then `@Title` can be specified on the backing field.
+If xref:cgcon.adoc#_cgcon_ide_project-lombok[Project Lombok] is being used, then `@Title` can be specified on the backing field.
For example:
http://git-wip-us.apache.org/repos/asf/isis/blob/49ccfd90/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api.adoc
index 2370132..541a160 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api.adoc
@@ -249,7 +249,7 @@ SpecificationProvider`].
|`SwaggerServiceDefault` +
``o.a.i.core`` +
``isis-core-metamodel``
-|A `SwaggerServiceMenu` domain service is also provided which enables the swagger spec to be downloaded. Apache Isis' xref:cg.adoc#_cg_isis-maven-plugin[Maven plugin] also provides a xref:cg.adoc#_cg_isis-maven-plugin_swagger[swagger goal] which allows the spec file(s) to be generated at build time (eg so that client-side stubs can then be generated in turn).
+|A `SwaggerServiceMenu` domain service is also provided which enables the swagger spec to be downloaded. Apache Isis' xref:cgcon.adoc#_cgcon_isis-maven-plugin[Maven plugin] also provides a xref:cgcon.adoc#_cgcon_isis-maven-plugin_swagger[swagger goal] which allows the spec file(s) to be generated at build time (eg so that client-side stubs can then be generated in turn).
|xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`o.a.i.applib.` +
http://git-wip-us.apache.org/repos/asf/isis/blob/49ccfd90/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_SwaggerService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_SwaggerService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_SwaggerService.adoc
index 67395af..707cd2d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_SwaggerService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_SwaggerService.adoc
@@ -66,6 +66,6 @@ implementation of `SwaggerService` service is automatically registered and injec
A `SwaggerServiceMenu` domain service provides a prototype action that enables the swagger spec to be downloaded from the Wicket viewer's UI.
-Apache Isis' xref:cg.adoc#_cg_isis-maven-plugin[Maven plugin] also provides a xref:cg.adoc#_cg_isis-maven-plugin_swagger[swagger goal] which allows the spec file(s) to be generated at build time. this then allows client-side stubs can then be generated in turn as part of a build pipeline.
+Apache Isis' xref:cgcon.adoc#_cgcon_isis-maven-plugin[Maven plugin] also provides a xref:cgcon.adoc#_cgcon_isis-maven-plugin_swagger[swagger goal] which allows the spec file(s) to be generated at build time. this then allows client-side stubs can then be generated in turn as part of a build pipeline.
http://git-wip-us.apache.org/repos/asf/isis/blob/49ccfd90/adocs/documentation/src/main/asciidoc/guides/_tg_pet-clinic.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_tg_pet-clinic.adoc b/adocs/documentation/src/main/asciidoc/guides/_tg_pet-clinic.adoc
index 03342b1..39f836d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_tg_pet-clinic.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_tg_pet-clinic.adoc
@@ -154,7 +154,7 @@ Go back to the splash screen, and quit the app. Note that the database runs in-m
== Dev environment
-Set up xref:cg.adoc#_cg_ide[an IDE] and import the project to be able to run and debug the app.
+Set up xref:cgcon.adoc#_cgcon_ide[an IDE] and import the project to be able to run and debug the app.
Then set up a launch configuration so that you can run the app from within the IDE. To save having to run the fixtures
every time, specify the following system properties:
http://git-wip-us.apache.org/repos/asf/isis/blob/49ccfd90/adocs/documentation/src/main/asciidoc/guides/_tg_stop-scaffolding-start-coding.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_tg_stop-scaffolding-start-coding.adoc b/adocs/documentation/src/main/asciidoc/guides/_tg_stop-scaffolding-start-coding.adoc
index 56d951f..fb9de46 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_tg_stop-scaffolding-start-coding.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_tg_stop-scaffolding-start-coding.adoc
@@ -90,7 +90,7 @@ Go back to the splash screen, and quit the app. Note that the database runs in-m
== Dev environment
-Set up xref:cg.adoc#_cg_ide[an IDE] and import the project to be able to run and debug the app.
+Set up xref:cgcon.adoc#_cgcon_ide[an IDE] and import the project to be able to run and debug the app.
Then set up a launch configuration and check that you can:
http://git-wip-us.apache.org/repos/asf/isis/blob/49ccfd90/adocs/documentation/src/main/asciidoc/guides/_ugbtb_programming-model_custom-validator.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_programming-model_custom-validator.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_programming-model_custom-validator.adoc
index 37ad7e8..34c0b06 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_programming-model_custom-validator.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_programming-model_custom-validator.adoc
@@ -17,7 +17,7 @@ You can also impose your own application-specific rules by installing your own m
[TIP]
====
-Isis' xref:cg.adoc#_cg_isis-maven-plugin[Maven plugin] will also validate the domain object model during build time.
+Isis' xref:cgcon.adoc#_cgcon_isis-maven-plugin[Maven plugin] will also validate the domain object model during build time.
====
http://git-wip-us.apache.org/repos/asf/isis/blob/49ccfd90/adocs/documentation/src/main/asciidoc/guides/_ugbtb_view-models_jaxb.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_view-models_jaxb.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_view-models_jaxb.adoc
index 0e72233..a2dceda 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_view-models_jaxb.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_view-models_jaxb.adoc
@@ -230,7 +230,7 @@ on the server).
== Generating XSDs and DTOs
-The xref:cg.adoc#_cg_isis-maven-plugin[Apache Isis maven plugin] provides the xref:cg.adoc#_cg_isis-maven-plugin_xsd[xsd] goal that allows the XSDs to be generated from any JAXB-annotated view models.
+The xref:cgcon.adoc#_cgcon_isis-maven-plugin[Apache Isis maven plugin] provides the xref:cgcon.adoc#_cgcon_isis-maven-plugin_xsd[xsd] goal that allows the XSDs to be generated from any JAXB-annotated view models.
These use the xref:rgsvc.adoc#_rgsvc_api_JaxbService[`JaxbService`] to generate the schemas; using the
standard `schemagen` command line will not correctly interpret any references to domain entities as OIDs.
http://git-wip-us.apache.org/repos/asf/isis/blob/49ccfd90/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started.adoc
index 955501c..5de99a3 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started.adoc
@@ -26,7 +26,7 @@ Apache Isis is a Java based framework, so in terms of prerequisites, you'll need
* Java 7 or 8 JDK
* link:http://maven.apache.org[Apache Maven] 3.0.5 or later
-You'll probably also want to use an IDE; the Apache Isis committers use either IntelliJ or Eclipse; in the xref:cg.adoc#_cg_ide[Contributors' Guide] we have detailed setup instructions for using these two IDEs. If you're a NetBeans user you should have no problems as it too has strong support for Maven.
+You'll probably also want to use an IDE; the Apache Isis committers use either IntelliJ or Eclipse; in the xref:cgcon.adoc#_cgcon_ide[Contributors' Guide] we have detailed setup instructions for using these two IDEs. If you're a NetBeans user you should have no problems as it too has strong support for Maven.
When building and running within an IDE, you'll also need to configure the Datanucleus enhancer. This is implemented as a Maven plugin, so in the case of IntelliJ, it's easy enough to run the enhancer as required. It should be just as straightforward for NetBeans too.
http://git-wip-us.apache.org/repos/asf/isis/blob/49ccfd90/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started_datanucleus-enhancer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started_datanucleus-enhancer.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started_datanucleus-enhancer.adoc
index 121277e..b1d80a8 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started_datanucleus-enhancer.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started_datanucleus-enhancer.adoc
@@ -103,5 +103,5 @@ Again, the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp
====
If running on Windows, then there's a good chance you'll hit the http://msdn.microsoft.com/en-us/library/aa365247%28VS.85%29.aspx#maxpath[maximum path length limit]. In this case the `persistence.xml` file is mandatory rather than optional.
-This file is also required if you are using developing in Eclipse and relying on the DataNucleus plugin for Eclipse rather than the DataNucleus plugin for Maven. More information can be found xref:cg.adoc#_cg_ide_eclipse[here].
+This file is also required if you are using developing in Eclipse and relying on the DataNucleus plugin for Eclipse rather than the DataNucleus plugin for Maven. More information can be found xref:cgcon.adoc#_cgcon_ide_eclipse[here].
====
http://git-wip-us.apache.org/repos/asf/isis/blob/49ccfd90/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started_simpleapp-archetype.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started_simpleapp-archetype.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started_simpleapp-archetype.adoc
index 77342fb..b91137b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started_simpleapp-archetype.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started_simpleapp-archetype.adoc
@@ -143,7 +143,7 @@ You can also take the built WAR file and deploy it into a standalone servlet con
=== From within the IDE
-Most of the time, though, you'll probably want to run the app from within your IDE. The mechanics of doing this will vary by IDE; see the xref:cg.adoc#_cg_ide[Contributors' Guide] for details of setting up Eclipse or IntelliJ IDEA. Basically, though, it amounts to running `org.apache.isis.WebServer`, and ensuring that the xref:ugfun.adoc#_ugfun_getting-started_datanucleus-enhancer[DataNucleus enhancer] has properly processed all domain entities.
+Most of the time, though, you'll probably want to run the app from within your IDE. The mechanics of doing this will vary by IDE; see the xref:cgcon.adoc#_cgcon_ide[Contributors' Guide] for details of setting up Eclipse or IntelliJ IDEA. Basically, though, it amounts to running `org.apache.isis.WebServer`, and ensuring that the xref:ugfun.adoc#_ugfun_getting-started_datanucleus-enhancer[DataNucleus enhancer] has properly processed all domain entities.
Here's what the setup looks like in IntelliJ IDEA:
@@ -262,7 +262,7 @@ To log in, use `sven/pass`.
Once you are familiar with the generated app, you'll want to start modifying it. There is plenty of guidance on this site; check out the 'programming model how-tos' section on the main link:../documentation.html[documentation] page first).
-If you use Eclipse or IntelliJ IDEA, do also install the xref:cg.adoc#_cg_ide-templates[IDE templates]; these will help you follow the Apache Isis naming conventions.
+If you use Eclipse or IntelliJ IDEA, do also install the xref:cgcon.adoc#_cgcon_ide-templates[IDE templates]; these will help you follow the Apache Isis naming conventions.
http://git-wip-us.apache.org/repos/asf/isis/blob/49ccfd90/adocs/documentation/src/main/asciidoc/guides/_ugtst_unit-test-support_contract-tests.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugtst_unit-test-support_contract-tests.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugtst_unit-test-support_contract-tests.adoc
index 0073431..81dfefe 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugtst_unit-test-support_contract-tests.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugtst_unit-test-support_contract-tests.adoc
@@ -68,7 +68,7 @@ This contract test automatically checks that bidirectional 1:m or 1:1 associatio
[TIP]
====
-(If using the JDO objectstore, then) there is generally no need to programmatically maintain 1:m relationships (indeed it may introduce subtle errors). For more details, see xref:ugfun.adoc#_ugfun_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships[here]. Also check out the xref:cg.adoc#_cg_ide-templates[IDE templates] for further guidance.
+(If using the JDO objectstore, then) there is generally no need to programmatically maintain 1:m relationships (indeed it may introduce subtle errors). For more details, see xref:ugfun.adoc#_ugfun_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships[here]. Also check out the xref:cgcon.adoc#_cgcon_ide-templates[IDE templates] for further guidance.
====
For example, suppose that `ParentDomainObject` and `ChildDomainObject` have a 1:m relationship (`ParentDomainObject#children` / `ChildDomainObject#parent`), and also `PeerDomainObject` has a 1:1 relationship with itself (`PeerDomainObject#next` / `PeerDomainObject#previous`).