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 2017/03/08 00:00:37 UTC
[39/44] isis-site git commit: ISIS-1594: provide an 'edit' button
http://git-wip-us.apache.org/repos/asf/isis-site/blob/83a3755a/content/guides/dg.html
----------------------------------------------------------------------
diff --git a/content/guides/dg.html b/content/guides/dg.html
index 14acdb6..35ac34e 100644
--- a/content/guides/dg.html
+++ b/content/guides/dg.html
@@ -1,12 +1,10 @@
<!doctype html>
<html class="no-js" lang="en">
-<head>
- <meta charset="utf-8"/>
- <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
-
- <title>Developers' Guide</title>
-
- <!--
+ <head>
+ <meta charset="utf-8">
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
+ <title>Developers' Guide</title>
+ <!--
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
@@ -23,31 +21,21 @@
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
- -->
-
- <!-- No caching headers -->
- <meta http-equiv="cache-control" content="no-cache" />
- <meta http-equiv="pragma" content="no-cache" />
- <meta http-equiv="expires" content="-1" />
-
-
- <!-- TODO: need to (re)instate CDN in the future (not using for now just so can develop off-line -->
- <link href="../css/foundation/5.5.1/foundation.css" rel="stylesheet" />
- <script src="../js/foundation/5.5.1/vendor/modernizr.js"></script>
- <link href="../css/asciidoctor/colony.css" rel="stylesheet">
- <link href="../css/font-awesome/4.3.0/css/font-awesome.min.css" rel="stylesheet">
-
-
-
-
- <link href="../css/github-fork-ribbon-css/0.1.1/gh-fork-ribbon.css" rel="stylesheet" />
- <!--[if lt IE 9]>
+ -->
+ <!-- No caching headers -->
+ <meta http-equiv="cache-control" content="no-cache">
+ <meta http-equiv="pragma" content="no-cache">
+ <meta http-equiv="expires" content="-1">
+ <!-- TODO: need to (re)instate CDN in the future (not using for now just so can develop off-line -->
+ <link href="../css/foundation/5.5.1/foundation.css" rel="stylesheet">
+ <script src="../js/foundation/5.5.1/vendor/modernizr.js"></script>
+ <link href="../css/asciidoctor/colony.css" rel="stylesheet">
+ <link href="../css/font-awesome/4.3.0/css/font-awesome.min.css" rel="stylesheet">
+ <link href="../css/github-fork-ribbon-css/0.1.1/gh-fork-ribbon.css" rel="stylesheet">
+ <!--[if lt IE 9]>
<link href="../css/github-fork-ribbon-css/0.1.1/gh-fork-ribbon.ie.css" rel="stylesheet" />
- <![endif]-->
-
-
-
- <style type="text/css">
+ <![endif]-->
+ <style type="text/css">
pre code {
background-color: inherit;
border-style: none;
@@ -192,9 +180,8 @@ table.CodeRay td.code>pre{padding:0}
color:#fff;
font-size: 1.1em;
}
- </style>
-
- <style>
+ </style>
+ <style>
@media only screen and (min-width: 40.063em) {
.top-bar {
.contain-to-grid .top-bar {
@@ -205,9 +192,8 @@ table.CodeRay td.code>pre{padding:0}
.row {
max-width: 80rem;
}
- </style>
-
- <style>
+ </style>
+ <style>
.extended-quote,
.extended-quote-first {
margin-left: 40px;
@@ -231,9 +217,8 @@ table.CodeRay td.code>pre{padding:0}
text-shadow: 0 1px 2px rgba(0, 0, 0, 0.1);
}
- </style>
-
- <style>
+ </style>
+ <style>
body {
position: relative;
}
@@ -255,6 +240,7 @@ table.CodeRay td.code>pre{padding:0}
div#doc-content {
margin-top: 30px;
+ padding-top: 30px;
}
div.documentation-page table.frame-all {
@@ -286,9 +272,8 @@ table.CodeRay td.code>pre{padding:0}
min-height: 2000px;
}
- </style>
-
- <style>
+ </style>
+ <style>
@media only screen and (min-width: 768px) {
#toc.toc2 ul ul { margin-left: -10px; }
@@ -316,15 +301,13 @@ table.CodeRay td.code>pre{padding:0}
body div#toc2 li.tocify-item.active a {
color: red;
}
- </style>
-
- <style>
+ </style>
+ <style>
footer {
margin-top: 1000px;
}
- </style>
-
- <style>
+ </style>
+ <style>
/* overriding colony.css stylesheet */
.literalblock pre, .literalblock pre[class], .listingblock pre, .listingblock pre[class] {
/*padding: 1.25em 1.5625em 1.125em 1.5625em;*/
@@ -372,9 +355,8 @@ table.CodeRay td.code>pre{padding:0}
.imageblock img {
margin-bottom: 10px;
}
- </style>
-
- <style>
+ </style>
+ <style>
/* from http://ben.balter.com/2014/03/13/pages-anchor-links/ */
.header-link {
position: absolute;
@@ -395,9 +377,8 @@ table.CodeRay td.code>pre{padding:0}
h6:hover .header-link {
opacity: 1;
}
- </style>
-
- <style>
+ </style>
+ <style>
.top-bar
{
-webkit-transition-duration: .5s;
@@ -425,1014 +406,921 @@ table.CodeRay td.code>pre{padding:0}
-webkit-transition-property: -webkit-transform;
transition-property: transform;
}
- </style>
-
- <style>
+ </style>
+ <style>
#doc-content a.guide {
color: white;
}
- </style>
-
- <style>
+ </style>
+ <style>
.tocify {
margin-top: 80px;
}
- </style>
-
-
-</script>
-
-</head>
-<body>
-
-<<div class="github-fork-ribbon-wrapper right" style="position: fixed;">
- <div class="github-fork-ribbon">
- <a href="https://github.com/apache/isis#fork-destination-box">Fork me on GitHub</a>
- </div>
-</div>
-
-
-<div class="row">
-
- <div class="fixed contain-to-grid header">
- <nav class="top-bar" data-topbar role="navigation" style="max-width: 80rem">
- <ul class="title-area">
- <li class="name">
- <h1>
- <a href="/index.html">Apache Isis™</a>
- </h1>
- </li>
- <!-- Remove the class "menu-icon" to get rid of menu icon. Take out "Menu" to just have icon alone -->
- <li class="toggle-topbar menu-icon"><a href="#"><span>Menu</span></a></li>
- </ul>
-
- <section class="top-bar-section">
- <ul class="right">
-
- <li class="has-form">
- <FORM class="searchbox navbar-form navbar-right" id="searchbox_012614087480249044419:dn-q5gtwxya" action="http://www.google.com/cse">
- <div class="row collapse">
- <input type="hidden" name="cx" value="012614087480249044419:dn-q5gtwxya">
- <INPUT type="hidden" name="cof" value="FORID:0">
- <INPUT class="form-control" name="q" type="text" placeholder="Search">
- </div>
- </FORM>
- </li>
-
- </ul>
-
- <!-- Left Nav Section -->
- <ul class="left">
-
- <li><a href="/documentation.html">Documentation</a></li>
- <li><a href="/downloads.html">Downloads</a></li>
- <li><a href="/help.html">Help</a></li>
- <li><a href="/asf.html">@ASF</a></li>
-
- </ul>
-
- </section>
- </nav>
- </div>
-</div>
-
-<div class="row">
-
- <div id="doc-content-left" class="large-9 medium-9 columns">
-
-
- <div id="doc-content">
- <div class="sect1">
-<h2 id="_dg">1. Developers' Guide</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>This developers' guide is for:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>programmers who want to just use Apache Isis to build applications, and want help setting up their development
-environment or to build their code from the command line (eg to execute within a continuous integration server such
-as Jenkins)</p>
-</li>
-<li>
-<p>programmers who want to contribute back patches (bug fixes, new features) either to the codebase or the framework’s documentation</p>
-</li>
-<li>
-<p>committers of Apache Isis itself who want guidance on release process, publishing documents and other related procedures.</p>
-</li>
-</ul>
-</div>
-<div class="sect2">
-<h3 id="_other_guides">1.1. Other Guides</h3>
-<div class="paragraph">
-<p>Apache Isis documentation is broken out into a number of user, reference and "supporting procedures" guides.</p>
-</div>
-<div class="paragraph">
-<p>The user guides available are:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p><a href="ugfun.html">Fundamentals</a></p>
-</li>
-<li>
-<p><a href="ugvw.html">Wicket viewer</a></p>
-</li>
-<li>
-<p><a href="ugvro.html">Restful Objects viewer</a></p>
-</li>
-<li>
-<p><a href="ugdno.html">DataNucleus object store</a></p>
-</li>
-<li>
-<p><a href="ugsec.html">Security</a></p>
-</li>
-<li>
-<p><a href="ugtst.html">Testing</a></p>
-</li>
-<li>
-<p><a href="ugbtb.html">Beyond the Basics</a></p>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>The reference guides are:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p><a href="rgant.html">Annotations</a></p>
-</li>
-<li>
-<p><a href="rgsvc.html">Domain Services</a></p>
-</li>
-<li>
-<p><a href="rgcfg.html">Configuration Properties</a></p>
-</li>
-<li>
-<p><a href="rgcms.html">Classes, Methods and Schema</a></p>
-</li>
-<li>
-<p><a href="rgmvn.html">Apache Isis Maven plugin</a></p>
-</li>
-<li>
-<p><a href="rgfis.html">Framework Internal Services</a></p>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>The remaining guides are:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p><a href="#">Developers' Guide</a> (this guide)</p>
-</li>
-<li>
-<p><a href="cgcom.html">Committers' Guide</a> (release procedures and related practices)</p>
-</li>
-</ul>
-</div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_dg_ide">2. Using an IDE</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>The vast majority of Java developers use an IDE to assist with developing their code, and we highly recommend that you do like wise as you develop your Apache Isis applications using an IDE. Apache Isis is built with Maven, and all modern IDEs can import Maven projects.</p>
-</div>
-<div class="paragraph">
-<p>This chapter shows how to setup and use two of the most popular IDEs, IntelliJ IDEA and Eclipse.</p>
-</div>
-<div class="sect2">
-<h3 id="_dg_ide_intellij">2.1. Developing using IntelliJ IDEA</h3>
-<div class="admonitionblock note">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-note" title="Note"></i>
-</td>
-<td class="content">
-<div class="paragraph">
-<p>This material does not constitute an endorsement; JetBrains is not affiliated to Apache Software Foundation in any way. JetBrains does however provide complimentary copies of the IntelliJ IDE to Apache committers.</p>
-</div>
-</td>
-</tr>
-</table>
-</div>
-<div class="paragraph">
-<p>This section describes how to install and setup JetBrains' IntelliJ IDEA, then how to import an application into IntelliJ and run it.</p>
-</div>
-<div class="sect3">
-<h4 id="_dg_ide_intellij_installing">2.1.1. Installing and Setting up</h4>
-<div class="paragraph">
-<p>This section covers installation and setup. These notes/screenshots were prepared using IntelliJ Community Edition 14.1.x, but are believed to be compatible with more recent versions/other editions of the IDE.</p>
-</div>
-<div class="sect4">
-<h5 id="_dg_ide_intellij_installing_download">Download and Install</h5>
-<div class="paragraph">
-<p><a href="https://www.jetbrains.com/idea/download/">Download</a> latest version of IntelliJ Community Edition, and install:</p>
-</div>
-<div class="paragraph">
-<p>Start the wizard, click through the welcome page:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<img src="images/appendices/dev-env/intellij-idea/010-installing/010-welcome-page.png" alt="010 welcome page" width="400px">
-</div>
-<div class="title">Figure 1. IntelliJ Installation Wizard - Welcome page</div>
-</div>
-<div class="paragraph">
-<p>Choose the location to install the IDE:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<img src="images/appendices/dev-env/intellij-idea/010-installing/020-choose-location.png" alt="020 choose location" width="400px">
-</div>
-<div class="title">Figure 2. IntelliJ Installation Wizard - Choose Location</div>
-</div>
-<div class="paragraph">
-<p>Adjust any installation options as you prefer:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<img src="images/appendices/dev-env/intellij-idea/010-installing/030-installation-options.png" alt="030 installation options" width="400px">
-</div>
-<div class="title">Figure 3. IntelliJ Installation Wizard - Installation Options</div>
-</div>
-<div class="paragraph">
-<p>and the start menu:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<img src="images/appendices/dev-env/intellij-idea/010-installing/040-start-menu-folder.png" alt="040 start menu folder" width="400px">
-</div>
-<div class="title">Figure 4. IntelliJ Installation Wizard - Start Menu Folder</div>
-</div>
-<div class="paragraph">
-<p>and finish up the wizard:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<img src="images/appendices/dev-env/intellij-idea/010-installing/050-completing.png" alt="050 completing" width="400px">
-</div>
-<div class="title">Figure 5. IntelliJ Installation Wizard - Completing the Wizard</div>
-</div>
-<div class="paragraph">
-<p>Later on we’ll specify the Apache Isis/ASF code style settings, so for now select <code>I do not want to import settings</code>:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<img src="images/appendices/dev-env/intellij-idea/010-installing/060-import-settings-or-not.png" alt="060 import settings or not" width="400px">
-</div>
-<div class="title">Figure 6. IntelliJ Installation Wizard - Import Settings</div>
-</div>
-<div class="paragraph">
-<p>Finally, if you are a trendy hipster, set the UI theme to Darcula:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<img src="images/appendices/dev-env/intellij-idea/010-installing/070-set-ui-theme.png" alt="070 set ui theme" width="600px">
-</div>
-<div class="title">Figure 7. IntelliJ Installation Wizard Set UI Theme</div>
-</div>
-</div>
-<div class="sect4">
-<h5 id="_dg_ide_intellij_installing_new-project">New Project</h5>
-<div class="paragraph">
-<p>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).</p>
-</div>
-<div class="paragraph">
-<p>Start off by creating a new project:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<img src="images/appendices/dev-env/intellij-idea/020-create-new-project/010-new-project-create.png" alt="010 new project create" width="400px">
-</div>
-<div class="title">Figure 8. IntelliJ Create New Project</div>
-</div>
-<div class="paragraph">
-<p>We want to create a new <strong>Java</strong> project:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<img src="images/appendices/dev-env/intellij-idea/020-create-new-project/020-java-project-setup-jdk.png" alt="020 java project setup jdk" width="500px">
-</div>
-<div class="title">Figure 9. IntelliJ Create New Project - Create a Java project</div>
-</div>
-<div class="paragraph">
-<p>We therefore need to specify the JDK. Apache Isis supports both Java 7 and Java 8.</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<img src="images/appendices/dev-env/intellij-idea/020-create-new-project/030-java-project-select-jdk.png" alt="030 java project select jdk" width="250px">
-</div>
-<div class="title">Figure 10. IntelliJ Create New Java Project - Select the JDK</div>
-</div>
-<div class="paragraph">
-<p>Specify the directory containing the JDK:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<img src="images/appendices/dev-env/intellij-idea/020-create-new-project/050-name-and-location.png" alt="050 name and location" width="400px">
-</div>
-<div class="title">Figure 11. IntelliJ Create New Project - Select the JDK location</div>
-</div>
-<div class="paragraph">
-<p>Finally allow IntelliJ to create the directory for the new project:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<img src="images/appendices/dev-env/intellij-idea/020-create-new-project/060-create-dir.png" alt="060 create dir" width="250px">
-</div>
-<div class="title">Figure 12. IntelliJ Create New Project</div>
-</div>
-</div>
-<div class="sect4">
-<h5 id="_dg_ide_intellij_file-templates">File templates</h5>
-<div class="paragraph">
-<p>Next we recommend you import a set of standard file templates. These are used to create new classes or supporting files:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<img src="images/appendices/dev-env/intellij-idea/030-import-settings/040-file-templates.png" alt="040 file templates" width="400px">
-</div>
-<div class="title">Figure 13. File templates</div>
-</div>
-<div class="paragraph">
-<p>The file templates are provided as a settings JAR file, namely <strong><a href="resources/appendices/dev-env/intellij/isis-settings-file-templates.jar">isis-settings-file-templates.jar</a></strong>. Download this file.</p>
-</div>
-<div class="paragraph">
-<p>Next, import using <code>File > Import Settings</code>, specifying the directory that you have downloaded the file to:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<img src="images/appendices/dev-env/intellij-idea/030-import-settings/010-settings-import-jar.png" alt="010 settings import jar" width="400px">
-</div>
-<div class="title">Figure 14. IntelliJ Import Settings - Specify JAR file</div>
-</div>
-<div class="paragraph">
-<p>Select all the categories (there should just be one), and hit OK. then hit restart.</p>
-</div>
-<div class="admonitionblock warning">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-warning" title="Warning"></i>
-</td>
-<td class="content">
-<div class="paragraph">
-<p>Apparently no categories are shown if importing into IntelliJ 2016.1.1 Community Edition (and perhaps other 2016
-versions). The file does import ok into IntelliJ 15.0.x, so we think this is a bug in the 2016 version.</p>
-</div>
-<div class="paragraph">
-<p>The workaround is to extract the <code>.jar</code> file locally and copy the files into IntelliJ’s <code>config</code> directory, somewhere
-in your home directory:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>Windows <code><User home>\.IdeaIC2016\config</code></p>
-</li>
-<li>
-<p>Linux <code>~/..IdeaIC2016/config</code></p>
-</li>
-<li>
-<p>Mac OS <code>~/Library/Preferences/IdeaIC2016</code></p>
-</li>
-</ul>
-</div>
-</td>
-</tr>
-</table>
-</div>
-</div>
-<div class="sect4">
-<h5 id="_dg_ide_intellij_live-templates">Live templates</h5>
-<div class="paragraph">
-<p>We also recommend you import a set of live templates. These are used to add new methods to existing classes:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<img src="images/appendices/dev-env/intellij-idea/030-import-settings/050-live-templates.png" alt="050 live templates" width="600px">
-</div>
-<div class="title">Figure 15. Live templates</div>
-</div>
-<div class="paragraph">
-<p>The live templates have a prefix of prefixed either:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p><code>is</code> : for Apache Isis domain objects</p>
-</li>
-<li>
-<p><code>ju</code> : for JUnit tests</p>
-</li>
-<li>
-<p><code>jm</code> : for JMock mocks or libraries</p>
-</li>
-<li>
-<p><code>ad</code> : for Asciidoc documentation; a full list can be found in the <a href="#_dg_asciidoc-templates">appendix</a>.</p>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>The live templates are also provided as a settings JAR file, namely <strong><a href="resources/appendices/dev-env/intellij/isis-settings-live-templates.jar">isis-settings-live-templates.jar</a></strong>.
-Download and import (as for the previous settings JAR files).</p>
-</div>
-</div>
-<div class="sect4">
-<h5 id="_dg_ide_intellij_coding-standards">Coding Standards</h5>
-<div class="paragraph">
-<p>Next, we suggest you recommend you import settings for standard ASF/Apache Isis coding conventions. This file is also
-provided as a settings file, namely <strong><a href="resources/appendices/dev-env/intellij/isis-settings-code-style.jar">isis-settings-code-style.jar</a></strong>. Download and import (as for the above settings JAR files).</p>
-</div>
-</div>
-<div class="sect4">
-<h5 id="_dg_ide_intellij_other-settings-compiler">Other Settings (Compiler)</h5>
-<div class="paragraph">
-<p>There are also some other settings that influence the compiler. We highly recommend you set these.</p>
-</div>
-<div class="paragraph">
-<p>On the <strong>Compiler</strong> Settings page, ensure that <code>build automatically</code> is enabled (and optionally <code>compile independent modules in parallel</code>):</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<img src="images/appendices/dev-env/intellij-idea/040-other-settings-compiler/010-build-automatically.png" alt="010 build automatically" width="700px">
-</div>
-<div class="title">Figure 16. IntelliJ Compiler Settings</div>
-</div>
-<div class="paragraph">
-<p>On the <strong>Annotation Processors</strong> page, enable and adjust for the 'default' setting:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<img src="images/appendices/dev-env/intellij-idea/040-other-settings-compiler/020-annotation-processor.png" alt="020 annotation processor" width="700px">
-</div>
-<div class="title">Figure 17. IntelliJ Annotation Processor Settings</div>
-</div>
-<div class="paragraph">
-<p>This setting enables the generation of the <code>Q*</code> classes for DataNucleus type-safe queries, as well as being required
-for frameworks such as <a href="#_cg_ide_project-lombok">Project Lombok</a>.</p>
-</div>
-<div class="admonitionblock note">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-note" title="Note"></i>
-</td>
-<td class="content">
-<div class="paragraph">
-<p>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.</p>
-</div>
-</td>
-</tr>
-</table>
-</div>
-</div>
-<div class="sect4">
-<h5 id="_dg_ide_intellij_other-settings-maven">Other Settings (Maven)</h5>
-<div class="paragraph">
-<p>There are also some other settings for Maven that we recommend you adjust (though these are less critical):</p>
-</div>
-<div class="paragraph">
-<p>First, specify an up-to-date Maven installation, using <code>File > Settings</code> (or <code>IntelliJ > Preferences</code> if on MacOS):</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<img src="images/appendices/dev-env/intellij-idea/042-other-settings-maven/010-maven-installation.png" alt="010 maven installation" width="700px">
-</div>
-<div class="title">Figure 18. IntelliJ Maven Settings - Installation</div>
-</div>
-<div class="paragraph">
-<p>Still on the Maven settings page, configure as follows:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<img src="images/appendices/dev-env/intellij-idea/042-other-settings-maven/020-maven-configuration.png" alt="020 maven configuration" width="700px">
-</div>
-<div class="title">Figure 19. IntelliJ Maven Settings - Configuration</div>
-</div>
-</div>
-<div class="sect4">
-<h5 id="_other_settings_misc">Other Settings (Misc)</h5>
-<div class="paragraph">
-<p>These settings are optional but also recommended.</p>
-</div>
-<div class="paragraph">
-<p>On the <strong>auto import</strong> page, check the <code>optimize imports on the fly</code> and <code>add unambiguous imports on the fly</code></p>
-</div>
-<div class="imageblock">
-<div class="content">
-<img src="images/appendices/dev-env/intellij-idea/044-other-settings-misc/010-auto-import.png" alt="010 auto import" width="700px">
-</div>
-<div class="title">Figure 20. IntelliJ Maven Settings - Auto Import</div>
-</div>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_dg_ide_intellij_importing-maven-modules">2.1.2. Importing Maven Modules</h4>
-<div class="paragraph">
-<p>Let’s load in some actual code! We do this by importing the Maven modules.</p>
-</div>
-<div class="paragraph">
-<p>First up, open up the Maven tool window (<code>View > Tool Windows > Maven Projects</code>). 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 <em>Maven Projects</em> window and corresponding (IntelliJ) modules are shown in the <em>Projects</em> window:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<img src="images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/010-maven-modules-view.png" alt="010 maven modules view" width="730px">
-</div>
-<div class="title">Figure 21. IntelliJ Maven Module Management - Importing Maven modules</div>
-</div>
-<div class="paragraph">
-<p>We can then import another module (from some other directory). For example, here we are importing the Isis Addons' todoapp example:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<img src="images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/020-adding-another-module.png" alt="020 adding another module" width="400px">
-</div>
-<div class="title">Figure 22. IntelliJ Maven Module Management - Importing another Module</div>
-</div>
-<div class="paragraph">
-<p>You should then see the new Maven module loaded in the <em>Projects</em> window and also the <em>Maven Projects</em> window:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<img src="images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/030-other-module-added.png" alt="030 other module added" width="730px">
-</div>
-<div class="title">Figure 23. IntelliJ Maven Module Management -</div>
-</div>
-<div class="paragraph">
-<p>If any dependencies are already loaded in the project, then IntelliJ will automatically update the CLASSPATH to resolve to locally held modules (rather from <code>.m2/repository</code> folder). So, for example (assuming that the <code><version></code> is correct, of course), the Isis todoapp will have local dependencies on the Apache Isis core.</p>
-</div>
-<div class="paragraph">
-<p>You can press F4 (or use <code>File > Project Structure</code>) to see the resolved classpath for any of the modules loaded into the project.</p>
-</div>
-<div class="paragraph">
-<p>If you want to focus on one set of code (eg the Isis todoapp but not Apache Isis core) then you <em>could</em> remove the module; but better is to ignore those modules. This will remove from the the <em>Projects</em> window but keep them available in the <em>Maven Projects</em> window for when you next want to work on them:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<img src="images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/040-ignoring-modules.png" alt="040 ignoring modules" width="730px">
-</div>
-<div class="title">Figure 24. IntelliJ Maven Module Management - Ignoring Modules</div>
-</div>
-<div class="paragraph">
-<p>Confirm that it’s ok to ignore these modules:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<img src="images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/050-ignoring-modules-2.png" alt="050 ignoring modules 2" width="300px">
-</div>
-<div class="title">Figure 25. IntelliJ Maven Module Management - Ignoring Modules (ctd)</div>
-</div>
-<div class="paragraph">
-<p>All being well you should see that the <em>Projects</em> window now only contains the code you are working on. Its classpath dependencies will be adjusted (eg to resolve to Apache Isis core from <code>.m2/repository</code>):</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<img src="images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/060-ignored-modules.png" alt="060 ignored modules" width="730px">
-</div>
-<div class="title">Figure 26. IntelliJ Maven Module Management - Updated Projects Window</div>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_dg_ide_intellij_running">2.1.3. Running</h4>
-<div class="paragraph">
-<p>Let’s see how to run both the app and the tests.</p>
-</div>
-<div class="sect4">
-<h5 id="_dg_ide_intellij_running_the-app">Running the App</h5>
-<div class="paragraph">
-<p>Once you’ve imported your Isis application, we should run it. We do this by creating a Run configuration, using <code>Run > Edit Configurations</code>.</p>
-</div>
-<div class="paragraph">
-<p>Set up the details as follows:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<img src="images/appendices/dev-env/intellij-idea/110-running-the-app/010-run-configuration.png" alt="010 run configuration" width="600px">
-</div>
-<div class="title">Figure 27. IntelliJ Running the App - Run Configuration</div>
-</div>
-<div class="paragraph">
-<p>We specify the <code>Main class</code> to be <code>org.apache.isis.WebServer</code>; 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.</p>
-</div>
-<div class="paragraph">
-<p>Also note that <code>Use classpath of module</code> is the webapp module for your app, and that the <code>working directory</code> is <code>$MODULE_DIR$</code>.</p>
-</div>
-<div class="paragraph">
-<p>Next, and most importantly, configure the DataNucleus enhancer to run for your <code>dom</code> goal. This can be done by defining a Maven goal to run before the app:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<img src="images/appendices/dev-env/intellij-idea/110-running-the-app/020-datanucleus-enhancer-goal.png" alt="020 datanucleus enhancer goal" width="400px">
-</div>
-<div class="title">Figure 28. IntelliJ Running the App - Datanucleus Enhancer Goal</div>
-</div>
-<div class="paragraph">
-<p>The <code>-o</code> flag in the goal means run off-line; this will run faster.</p>
-</div>
-<div class="admonitionblock warning">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-warning" title="Warning"></i>
-</td>
-<td class="content">
-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.
-</td>
-</tr>
-</table>
-</div>
-<div class="paragraph">
-<p>You should now be able to run the app using <code>Run > Run Configuration</code>. The same configuration can also be used to debug the app if you so need.</p>
-</div>
-</div>
-<div class="sect4">
-<h5 id="_dg_ide_intellij_running_unit-tests">Running the Unit Tests</h5>
-<div class="paragraph">
-<p>The easiest way to run the unit tests is just to right click on the <code>dom</code> module in the <em>Project Window</em>, and choose run unit tests. Hopefully your tests will pass (!).</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<img src="images/appendices/dev-env/intellij-idea/110-running-the-app/030-running-unit-tests.png" alt="030 running unit tests" width="600px">
-</div>
-<div class="title">Figure 29. IntelliJ Running the App - Unit Tests Run Configuration</div>
-</div>
-<div class="paragraph">
-<p>As a side-effect, this will create a run configuration, very similar to the one we manually created for the main app:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<img src="images/appendices/dev-env/intellij-idea/110-running-the-app/040-running-unit-tests-run-configuration.png" alt="040 running unit tests run configuration" width="600px">
-</div>
-<div class="title">Figure 30. IntelliJ Running the App - Unit Tests Run Configuration</div>
-</div>
-<div class="paragraph">
-<p>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).</p>
-</div>
-</div>
-<div class="sect4">
-<h5 id="_dg_ide_intellij_running_integ-tests">Running the Integration Tests</h5>
-<div class="paragraph">
-<p>Integration tests can be run in the same way as unit tests, however the <code>dom</code> module must also have been enhanced.</p>
-</div>
-<div class="paragraph">
-<p>One approach is to initially run the tests use the right click on the <code>integtests</code> 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):</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<img src="images/appendices/dev-env/intellij-idea/110-running-the-app/050-running-integration-tests-run-configuration.png" alt="050 running integration tests run configuration" width="600px">
-</div>
-<div class="title">Figure 31. IntelliJ Running the App - Integration Tests Run Configuration</div>
-</div>
-<div class="paragraph">
-<p>Also make sure that the <code>search for tests</code> radio button is set to <code>In single module</code>:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<a class="image" href="images/appendices/dev-env/intellij-idea/400-running-integtests/run-debug-configuration-single-module.png"><img src="images/appendices/dev-env/intellij-idea/400-running-integtests/run-debug-configuration-single-module.png" alt="run debug configuration single module" width="600px"></a>
-</div>
-</div>
-<div class="paragraph">
-<p>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 <code>dom</code> project that depend on test classes in that module, but using the classpath of the <code>integtests</code> module whereby the <code>dom</code> test-classes (<code>test-jar</code> artifact) are not exposed on the Maven classpath.</p>
-</div>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_dg_ide_intellij_hints-and-tips">2.1.4. Hints and Tips</h4>
-<div class="sect4">
-<h5 id="_dg_ide_intellij_hints-and-tips_keyboard-cheat-sheets">Keyboard Cheat Sheets</h5>
-<div class="paragraph">
-<p>You can download 1-page PDFs cheat sheets for IntelliJ’s keyboard shortcuts:
-* for <a href="https://www.jetbrains.com/idea/docs/IntelliJIDEA_ReferenceCard.pdf">Windows</a>
-* for <a href="https://www.jetbrains.com/idea/docs/IntelliJIDEA_ReferenceCard_Mac.pdf">MacOS</a></p>
-</div>
-<div class="paragraph">
-<p>Probably the most important shortcut on them is for <code>Find Action</code>:
-- <code>ctrl-shift-A</code> on Windows
-- <code>cmd-shift-A</code> on MacOS.</p>
-</div>
-<div class="paragraph">
-<p>This will let you search for any action just by typing its name.</p>
-</div>
-</div>
-<div class="sect4">
-<h5 id="_switch_between_tools_editors">Switch between Tools & Editors</h5>
-<div class="paragraph">
-<p>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.</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>Use <code>alt-1</code> through <code>alt-9</code> (or <code>cmd-1</code> through <code>alt-9</code>) to select the tool windows</p>
-<div class="ulist">
-<ul>
-<li>
-<p>Press it twice and the tool window will hide itself; so can use to toggle</p>
-</li>
-</ul>
-</div>
-</li>
-<li>
-<p>If in the <em>Project Window</em> (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 <code>Esc</code>.</p>
-<div class="ulist">
-<ul>
-<li>
-<p>If in the <em>Terminal Window</em>, you’ll need to press <code>Shift-Esc</code>.</p>
-</li>
-</ul>
-</div>
-</li>
-<li>
-<p>If on the editor and want to locate the file in (say) the <em>Project Window</em>, use <code>alt-F1</code>.</p>
-</li>
-<li>
-<p>To change the size of any tool window, use <code>ctrl-shift-arrow</code></p>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>Using these shortcuts you can easily toggle between the tool windows and the editor, without using the mouse. Peachy!</p>
-</div>
-</div>
-<div class="sect4">
-<h5 id="_dg_ide_intellij_hints-and-tips_navigating-around">Navigating Around</h5>
-<div class="paragraph">
-<p>For all of the following, you don’t need to type every letter, typing "ab" will actually search for ".<strong>a.*b.</strong>".</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>to open classes or files or methods that you know the name of:</p>
-<div class="ulist">
-<ul>
-<li>
-<p><code>ctrl-N</code> to open class</p>
-</li>
-<li>
-<p><code>ctrl-shift-N</code> to open a file</p>
-</li>
-<li>
-<p>(bit fiddly this) <code>ctrl-shift-alt-N</code> to search for any symbol.</p>
-</li>
-</ul>
-</div>
-</li>
-<li>
-<p>open up dialog of recent files: <code>ctrl-E</code></p>
-</li>
-<li>
-<p>search for any file: <code>shift-shift</code></p>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>Navigating around:
-* find callers of a method (the call hierarchy): <code>ctrl-alt-H</code>
-* find subclasses or overrides: <code>ctrl-alt-B</code>
-* find superclasses/interface/declaration: <code>ctrl-B</code></p>
-</div>
-<div class="paragraph">
-<p>Viewing the structure (ie outline) of a class
-* <code>ctrl-F12</code> will pop-up a dialog showing all members
-** hit <code>ctrl-F12</code> again to also see inherited members</p>
-</div>
-</div>
-<div class="sect4">
-<h5 id="_dg_ide_intellij_hints-and-tips_editing">Editing</h5>
-<div class="ulist">
-<ul>
-<li>
-<p>Extend selection using <code>ctrl-W</code></p>
-<div class="ulist">
-<ul>
-<li>
-<p>and contract it down again using <code>ctrl-shift-W</code></p>
-</li>
-</ul>
-</div>
-</li>
-<li>
-<p>to duplicate a line, it’s <code>ctrl-D</code></p>
-<div class="ulist">
-<ul>
-<li>
-<p>if you have some text selected (or even some lines), it’ll actually duplicate the entire selection</p>
-</li>
-</ul>
-</div>
-</li>
-<li>
-<p>to delete a line, it’s <code>ctrl-X</code></p>
-</li>
-<li>
-<p>to move a line up or down: <code>shift-alt-up</code> and <code>shift-alt-down</code></p>
-<div class="ulist">
-<ul>
-<li>
-<p>if you have selected several lines, it’ll move them all togethe</p>
-</li>
-</ul>
-</div>
-</li>
-<li>
-<p><code>ctrl-shift-J</code> can be handy for joining lines together</p>
-<div class="ulist">
-<ul>
-<li>
-<p>just hit enter to split them apart (even in string quotes; IntelliJ will "do the right thing")</p>
-</li>
-</ul>
-</div>
-</li>
-</ul>
-</div>
-</div>
-<div class="sect4">
-<h5 id="_intentions_and_code_completion">Intentions and Code Completion</h5>
-<div class="paragraph">
-<p>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.</p>
-</div>
-<div class="paragraph">
-<p>Code completion usually happens whenever you type '.'. You can also use <code>ctrl-space</code> to bring these up.</p>
-</div>
-<div class="paragraph">
-<p>In certain circumstances (eg in methods0) you can also type <code>ctrl-shift-space</code> to get a smart list of methods etc that you might want to call. Can be useful.</p>
-</div>
-<div class="paragraph">
-<p>Last, when invoking a method, use <code>ctrl-P</code> to see the parameter types.</p>
-</div>
-</div>
-<div class="sect4">
-<h5 id="_dg_ide_intellij_hints-and-tips_refactoring">Refactoring</h5>
-<div class="paragraph">
-<p>Loads of good stuff on the <code>Refactor</code> menu; most used are:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>Rename (<code>shift-F6</code>)</p>
-</li>
-<li>
-<p>Extract</p>
-<div class="ulist">
-<ul>
-<li>
-<p>method: <code>ctrl-alt-M</code></p>
-</li>
-<li>
-<p>variable: <code>ctrl-alt-V</code></p>
-</li>
-</ul>
-</div>
-</li>
-<li>
-<p>Inline method/variable: <code>ctrl-alt-N</code></p>
-</li>
-<li>
-<p>Change signature</p>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>If you can’t remember all those shortcuts, just use <code>ctrl-shift-alt-T</code> (might want to rebind that to something else!) and get a context-sensitive list of refactorings available for the currently selected object</p>
-</div>
-</div>
-<div class="sect4">
-<h5 id="_dg_ide_intellij_hints-and-tips_plugins">Plugins</h5>
-<div class="paragraph">
-<p>You might want to set up some additional plugins. You can do this using <code>File > Settings > Plugins</code> (or equivalently <code>File > Other Settings > Configure Plugins</code>).</p>
-</div>
-<div class="paragraph">
-<p>Recommended are:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p><a href="https://plugins.jetbrains.com/plugin/7179?pr=idea">Maven Helper</a> plugin</p>
-<div class="paragraph">
-<p>More on this below.</p>
-</div>
-</li>
-<li>
-<p><a href="https://github.com/asciidoctor/asciidoctor-intellij-plugin">AsciiDoctor</a> plugin</p>
-<div class="paragraph">
-<p>Useful if you are doing any authoring of documents.</p>
-</div>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>Some others you might like to explore are:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<img src="images/appendices/dev-env/intellij-idea/050-some-plugins/020-some-plugins-confirmation.png" alt="020 some plugins confirmation" width="600px">
-</div>
-<div class="title">Figure 32. IntelliJ Plugins</div>
-</div>
-<div class="sect5">
-<h6 id="_dg_ide_intellij_hints-and-tips_plugins_maven-helper-plugin">Maven Helper Plugin</h6>
-<div class="paragraph">
-<p>This plugin provides a couple of great features. One is better visualization of dependency trees (similar to Eclipse).</p>
-</div>
-<div class="paragraph">
-<p>If you open a <code>pom.xml</code> file, you’ll see an additional "Dependencies" tab:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<a class="image" href="images/appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/010-dependency-tab.png"><img src="images/appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/010-dependency-tab.png" alt="010 dependency tab" width="600px"></a>
-</div>
-</div>
-<div class="paragraph">
-<p>Clicking on this gives a graphical tree representation of the dependencies, similar to that obtained by <code>mvn dependency:tree</code>, but filterable.</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<a class="image" href="images/appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/020-dependency-as-tree.png"><img src="images/appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/020-dependency-as-tree.png" alt="020 dependency as tree" width="600px"></a>
-</div>
-</div>
-<div class="paragraph">
-<p>The plugin also provides the ability to easily run a Maven goal on a project:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<a class="image" href="images/appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/030-maven-run-goal.png"><img src="images/appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/030-maven-run-goal.png" alt="030 maven run goal" width="600px"></a>
-</div>
-</div>
-<div class="paragraph">
-<p>This menu can also be bound to a keystroke so that it is available as a pop-up:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<a class="image" href="images/appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/040-maven-quick-run.png"><img src="images/appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/040-maven-quick-run.png" alt="040 maven quick run" width="600px"></a>
-</div>
-</div>
-</div>
-</div>
-<div class="sect4">
-<h5 id="_dg_ide_intellij_troubleshooting">Troubleshooting</h5>
-<div class="paragraph">
-<p>When a Maven module is imported, IntelliJ generates its own project files (suffix <code>.ipr</code>), and the application is actually built from that.</p>
-</div>
-<div class="paragraph">
-<p>Occasionally these don’t keep in sync (even if auto-import of Maven modules has been enabled).</p>
-</div>
-<div class="paragraph">
-<p>To fix the issue, try:
-* reimport module
-* rebuild selected modules/entire project
-* remove and then re-add the project
-* restart, invalidating caches
-* hit StackOverflow (!)</p>
-</div>
-<div class="paragraph">
-<p>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 <code>File > Synchronize</code>, <code>ctrl-alt-Y</code>.</p>
-</div>
-<div class="paragraph">
-<p>If you hit an error of "duplicate classes":</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<a class="image" href="images/appendices/dev-env/intellij-idea/060-troubleshooting/010-duplicate-classes.png"><img src="images/appendices/dev-env/intellij-idea/060-troubleshooting/010-duplicate-classes.png" alt="010 duplicate classes" width="600px"></a>
-</div>
-</div>
-<div class="paragraph">
-<p>then make sure you have correctly configured the <a href="#_cg_ide_intellij_other-settings-compiler">annotation processor</a>
-settings. Pay attention in particular to the "Production sources directory" and "Test sources directory", that these
-are set up correctly.</p>
-</div>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_dg_ide_intellij_advanced">2.1.5. Faster turnaround times</h4>
-<div class="paragraph">
-<p>In this section are several options that will reduce the time it takes between making a source code edit and seeing the results in the running app. code/build/deploy/review feedback loop.</p>
-</div>
-<div class="sect4">
-<h5 id="_dg_ide_intellij_advanced_gradle-compile-enhance">Using Grade to compile/enhance</h5>
-<div class="paragraph">
-<p>Running an Apache Isis application requires that the DataNucleus enhancer runs on the compiled bytecode. As described <a href="#_dg_ide_intellij_running_the-app">above</a>, the recommended way to do this with IntelliJ is to use a Run configuration that runs the enhancer goal prior to launch.</p>
-</div>
-<div class="paragraph">
-<p>Alternative, you can use the following <code>build.gradle</code> script in your <code>dom</code> module:</p>
-</div>
-<div class="listingblock">
-<div class="title"><code>build.gradle</code></div>
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="groovy">apply <span class="key">plugin</span>: <span class="string"><span class="delimiter">'</span><span class="content">java</span><span class="delimiter">'</span></span>
+ </style>
+ <style>
+ .tocify {
+ margin-top: 80px;
+ }
+ </style>
+ </head>
+ <body>
+ <div class="row">
+ <div class="fixed contain-to-grid header">
+ <nav class="top-bar" data-topbar role="navigation" style="max-width: 80rem">
+ <ul class="title-area">
+ <li class="name"> <h1> <a href="/index.html">Apache Isis\u2122</a> </h1> </li>
+ <!-- Remove the class "menu-icon" to get rid of menu icon. Take out "Menu" to just have icon alone -->
+ <li class="toggle-topbar menu-icon"><a href="#"><span>Menu</span></a></li>
+ </ul>
+ <section class="top-bar-section">
+ <ul class="right">
+ <li class="has-form">
+ <form class="searchbox navbar-form navbar-right" id="searchbox_012614087480249044419:dn-q5gtwxya" action="http://www.google.com/cse">
+ <div class="row collapse">
+ <input type="hidden" name="cx" value="012614087480249044419:dn-q5gtwxya">
+ <input type="hidden" name="cof" value="FORID:0">
+ <input class="form-control" name="q" type="text" placeholder="Search">
+ </div>
+ </form> </li>
+ </ul>
+ <!-- Left Nav Section -->
+ <ul class="left">
+ <li><a href="/documentation.html">Documentation</a></li>
+ <li><a href="/downloads.html">Downloads</a></li>
+ <li><a href="/help.html">Help</a></li>
+ <li><a href="/asf.html">@ASF</a></li>
+ </ul>
+ </section>
+ </nav>
+ </div>
+ </div>
+ <div class="row">
+ <div id="doc-content-left" class="large-9 medium-9 columns">
+ <div id="doc-content">
+ <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg.adoc"" style="float: right; font-size: small; padding: 6px; "><i class="fa fa-pencil-square-o"></i> Edit</button>
+ <div class="sect1">
+ <h2 id="_dg">1. Developers' Guide</h2>
+ <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/_dg.adoc"" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button>
+ <div class="sectionbody">
+ <div class="paragraph">
+ <p>This developers' guide is for:</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p>programmers who want to just use Apache Isis to build applications, and want help setting up their development environment or to build their code from the command line (eg to execute within a continuous integration server such as Jenkins)</p> </li>
+ <li> <p>programmers who want to contribute back patches (bug fixes, new features) either to the codebase or the framework\u2019s documentation</p> </li>
+ <li> <p>committers of Apache Isis itself who want guidance on release process, publishing documents and other related procedures.</p> </li>
+ </ul>
+ </div>
+ <div class="sect2">
+ <h3 id="_other_guides">1.1. Other Guides</h3>
+ <div class="paragraph">
+ <p>Apache Isis documentation is broken out into a number of user, reference and "supporting procedures" guides.</p>
+ </div>
+ <div class="paragraph">
+ <p>The user guides available are:</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p><a href="ugfun.html">Fundamentals</a></p> </li>
+ <li> <p><a href="ugvw.html">Wicket viewer</a></p> </li>
+ <li> <p><a href="ugvro.html">Restful Objects viewer</a></p> </li>
+ <li> <p><a href="ugdno.html">DataNucleus object store</a></p> </li>
+ <li> <p><a href="ugsec.html">Security</a></p> </li>
+ <li> <p><a href="ugtst.html">Testing</a></p> </li>
+ <li> <p><a href="ugbtb.html">Beyond the Basics</a></p> </li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>The reference guides are:</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p><a href="rgant.html">Annotations</a></p> </li>
+ <li> <p><a href="rgsvc.html">Domain Services</a></p> </li>
+ <li> <p><a href="rgcfg.html">Configuration Properties</a></p> </li>
+ <li> <p><a href="rgcms.html">Classes, Methods and Schema</a></p> </li>
+ <li> <p><a href="rgmvn.html">Apache Isis Maven plugin</a></p> </li>
+ <li> <p><a href="rgfis.html">Framework Internal Services</a></p> </li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>The remaining guides are:</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p><a href="#">Developers' Guide</a> (this guide)</p> </li>
+ <li> <p><a href="cgcom.html">Committers' Guide</a> (release procedures and related practices)</p> </li>
+ </ul>
+ </div>
+ </div>
+ </div>
+ </div>
+ <div class="sect1">
+ <h2 id="_dg_ide">2. Using an IDE</h2>
+ <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/_dg_ide.adoc"" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button>
+ <div class="sectionbody">
+ <div class="paragraph">
+ <p>The vast majority of Java developers use an IDE to assist with developing their code, and we highly recommend that you do like wise as you develop your Apache Isis applications using an IDE. Apache Isis is built with Maven, and all modern IDEs can import Maven projects.</p>
+ </div>
+ <div class="paragraph">
+ <p>This chapter shows how to setup and use two of the most popular IDEs, IntelliJ IDEA and Eclipse.</p>
+ </div>
+ <div class="sect2">
+ <h3 id="_dg_ide_intellij">2.1. Developing using IntelliJ IDEA</h3>
+ <div class="admonitionblock note">
+ <table>
+ <tbody>
+ <tr>
+ <td class="icon"> <i class="fa icon-note" title="Note"></i> </td>
+ <td class="content">
+ <div class="paragraph">
+ <p>This material does not constitute an endorsement; JetBrains is not affiliated to Apache Software Foundation in any way. JetBrains does however provide complimentary copies of the IntelliJ IDE to Apache committers.</p>
+ </div> </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div class="paragraph">
+ <p>This section describes how to install and setup JetBrains' IntelliJ IDEA, then how to import an application into IntelliJ and run it.</p>
+ </div>
+ <div class="sect3">
+ <h4 id="_dg_ide_intellij_installing">2.1.1. Installing and Setting up</h4>
+ <div class="paragraph">
+ <p>This section covers installation and setup. These notes/screenshots were prepared using IntelliJ Community Edition 14.1.x, but are believed to be compatible with more recent versions/other editions of the IDE.</p>
+ </div>
+ <div class="sect4">
+ <h5 id="_dg_ide_intellij_installing_download">Download and Install</h5>
+ <div class="paragraph">
+ <p><a href="https://www.jetbrains.com/idea/download/">Download</a> latest version of IntelliJ Community Edition, and install:</p>
+ </div>
+ <div class="paragraph">
+ <p>Start the wizard, click through the welcome page:</p>
+ </div>
+ <div class="imageblock">
+ <div class="content">
+ <img src="images/appendices/dev-env/intellij-idea/010-installing/010-welcome-page.png" alt="010 welcome page" width="400px">
+ </div>
+ <div class="title">
+ Figure 1. IntelliJ Installation Wizard - Welcome page
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>Choose the location to install the IDE:</p>
+ </div>
+ <div class="imageblock">
+ <div class="content">
+ <img src="images/appendices/dev-env/intellij-idea/010-installing/020-choose-location.png" alt="020 choose location" width="400px">
+ </div>
+ <div class="title">
+ Figure 2. IntelliJ Installation Wizard - Choose Location
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>Adjust any installation options as you prefer:</p>
+ </div>
+ <div class="imageblock">
+ <div class="content">
+ <img src="images/appendices/dev-env/intellij-idea/010-installing/030-installation-options.png" alt="030 installation options" width="400px">
+ </div>
+ <div class="title">
+ Figure 3. IntelliJ Installation Wizard - Installation Options
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>and the start menu:</p>
+ </div>
+ <div class="imageblock">
+ <div class="content">
+ <img src="images/appendices/dev-env/intellij-idea/010-installing/040-start-menu-folder.png" alt="040 start menu folder" width="400px">
+ </div>
+ <div class="title">
+ Figure 4. IntelliJ Installation Wizard - Start Menu Folder
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>and finish up the wizard:</p>
+ </div>
+ <div class="imageblock">
+ <div class="content">
+ <img src="images/appendices/dev-env/intellij-idea/010-installing/050-completing.png" alt="050 completing" width="400px">
+ </div>
+ <div class="title">
+ Figure 5. IntelliJ Installation Wizard - Completing the Wizard
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>Later on we\u2019ll specify the Apache Isis/ASF code style settings, so for now select <code>I do not want to import settings</code>:</p>
+ </div>
+ <div class="imageblock">
+ <div class="content">
+ <img src="images/appendices/dev-env/intellij-idea/010-installing/060-import-settings-or-not.png" alt="060 import settings or not" width="400px">
+ </div>
+ <div class="title">
+ Figure 6. IntelliJ Installation Wizard - Import Settings
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>Finally, if you are a trendy hipster, set the UI theme to Darcula:</p>
+ </div>
+ <div class="imageblock">
+ <div class="content">
+ <img src="images/appendices/dev-env/intellij-idea/010-installing/070-set-ui-theme.png" alt="070 set ui theme" width="600px">
+ </div>
+ <div class="title">
+ Figure 7. IntelliJ Installation Wizard Set UI Theme
+ </div>
+ </div>
+ </div>
+ <div class="sect4">
+ <h5 id="_dg_ide_intellij_installing_new-project">New Project</h5>
+ <div class="paragraph">
+ <p>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).</p>
+ </div>
+ <div class="paragraph">
+ <p>Start off by creating a new project:</p>
+ </div>
+ <div class="imageblock">
+ <div class="content">
+ <img src="images/appendices/dev-env/intellij-idea/020-create-new-project/010-new-project-create.png" alt="010 new project create" width="400px">
+ </div>
+ <div class="title">
+ Figure 8. IntelliJ Create New Project
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>We want to create a new <strong>Java</strong> project:</p>
+ </div>
+ <div class="imageblock">
+ <div class="content">
+ <img src="images/appendices/dev-env/intellij-idea/020-create-new-project/020-java-project-setup-jdk.png" alt="020 java project setup jdk" width="500px">
+ </div>
+ <div class="title">
+ Figure 9. IntelliJ Create New Project - Create a Java project
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>We therefore need to specify the JDK. Apache Isis supports both Java 7 and Java 8.</p>
+ </div>
+ <div class="imageblock">
+ <div class="content">
+ <img src="images/appendices/dev-env/intellij-idea/020-create-new-project/030-java-project-select-jdk.png" alt="030 java project select jdk" width="250px">
+ </div>
+ <div class="title">
+ Figure 10. IntelliJ Create New Java Project - Select the JDK
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>Specify the directory containing the JDK:</p>
+ </div>
+ <div class="imageblock">
+ <div class="content">
+ <img src="images/appendices/dev-env/intellij-idea/020-create-new-project/050-name-and-location.png" alt="050 name and location" width="400px">
+ </div>
+ <div class="title">
+ Figure 11. IntelliJ Create New Project - Select the JDK location
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>Finally allow IntelliJ to create the directory for the new project:</p>
+ </div>
+ <div class="imageblock">
+ <div class="content">
+ <img src="images/appendices/dev-env/intellij-idea/020-create-new-project/060-create-dir.png" alt="060 create dir" width="250px">
+ </div>
+ <div class="title">
+ Figure 12. IntelliJ Create New Project
+ </div>
+ </div>
+ </div>
+ <div class="sect4">
+ <h5 id="_dg_ide_intellij_file-templates">File templates</h5>
+ <div class="paragraph">
+ <p>Next we recommend you import a set of standard file templates. These are used to create new classes or supporting files:</p>
+ </div>
+ <div class="imageblock">
+ <div class="content">
+ <img src="images/appendices/dev-env/intellij-idea/030-import-settings/040-file-templates.png" alt="040 file templates" width="400px">
+ </div>
+ <div class="title">
+ Figure 13. File templates
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>The file templates are provided as a settings JAR file, namely <strong><a href="resources/appendices/dev-env/intellij/isis-settings-file-templates.jar">isis-settings-file-templates.jar</a></strong>. Download this file.</p>
+ </div>
+ <div class="paragraph">
+ <p>Next, import using <code>File > Import Settings</code>, specifying the directory that you have downloaded the file to:</p>
+ </div>
+ <div class="imageblock">
+ <div class="content">
+ <img src="images/appendices/dev-env/intellij-idea/030-import-settings/010-settings-import-jar.png" alt="010 settings import jar" width="400px">
+ </div>
+ <div class="title">
+ Figure 14. IntelliJ Import Settings - Specify JAR file
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>Select all the categories (there should just be one), and hit OK. then hit restart.</p>
+ </div>
+ <div class="admonitionblock warning">
+ <table>
+ <tbody>
+ <tr>
+ <td class="icon"> <i class="fa icon-warning" title="Warning"></i> </td>
+ <td class="content">
+ <div class="paragraph">
+ <p>Apparently no categories are shown if importing into IntelliJ 2016.1.1 Community Edition (and perhaps other 2016 versions). The file does import ok into IntelliJ 15.0.x, so we think this is a bug in the 2016 version.</p>
+ </div>
+ <div class="paragraph">
+ <p>The workaround is to extract the <code>.jar</code> file locally and copy the files into IntelliJ\u2019s <code>config</code> directory, somewhere in your home directory:</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p>Windows <code><User home>\.IdeaIC2016\config</code></p> </li>
+ <li> <p>Linux <code>~/..IdeaIC2016/config</code></p> </li>
+ <li> <p>Mac OS <code>~/Library/Preferences/IdeaIC2016</code></p> </li>
+ </ul>
+ </div> </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ </div>
+ <div class="sect4">
+ <h5 id="_dg_ide_intellij_live-templates">Live templates</h5>
+ <div class="paragraph">
+ <p>We also recommend you import a set of live templates. These are used to add new methods to existing classes:</p>
+ </div>
+ <div class="imageblock">
+ <div class="content">
+ <img src="images/appendices/dev-env/intellij-idea/030-import-settings/050-live-templates.png" alt="050 live templates" width="600px">
+ </div>
+ <div class="title">
+ Figure 15. Live templates
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>The live templates have a prefix of prefixed either:</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p><code>is</code> : for Apache Isis domain objects</p> </li>
+ <li> <p><code>ju</code> : for JUnit tests</p> </li>
+ <li> <p><code>jm</code> : for JMock mocks or libraries</p> </li>
+ <li> <p><code>ad</code> : for Asciidoc documentation; a full list can be found in the <a href="#_dg_asciidoc-templates">appendix</a>.</p> </li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>The live templates are also provided as a settings JAR file, namely <strong><a href="resources/appendices/dev-env/intellij/isis-settings-live-templates.jar">isis-settings-live-templates.jar</a></strong>. Download and import (as for the previous settings JAR files).</p>
+ </div>
+ </div>
+ <div class="sect4">
+ <h5 id="_dg_ide_intellij_coding-standards">Coding Standards</h5>
+ <div class="paragraph">
+ <p>Next, we suggest you recommend you import settings for standard ASF/Apache Isis coding conventions. This file is also provided as a settings file, namely <strong><a href="resources/appendices/dev-env/intellij/isis-settings-code-style.jar">isis-settings-code-style.jar</a></strong>. Download and import (as for the above settings JAR files).</p>
+ </div>
+ </div>
+ <div class="sect4">
+ <h5 id="_dg_ide_intellij_other-settings-compiler">Other Settings (Compiler)</h5>
+ <div class="paragraph">
+ <p>There are also some other settings that influence the compiler. We highly recommend you set these.</p>
+ </div>
+ <div class="paragraph">
+ <p>On the <strong>Compiler</strong> Settings page, ensure that <code>build automatically</code> is enabled (and optionally <code>compile independent modules in parallel</code>):</p>
+ </div>
+ <div class="imageblock">
+ <div class="content">
+ <img src="images/appendices/dev-env/intellij-idea/040-other-settings-compiler/010-build-automatically.png" alt="010 build automatically" width="700px">
+ </div>
+ <div class="title">
+ Figure 16. IntelliJ Compiler Settings
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>On the <strong>Annotation Processors</strong> page, enable and adjust for the 'default' setting:</p>
+ </div>
+ <div class="imageblock">
+ <div class="content">
+ <img src="images/appendices/dev-env/intellij-idea/040-other-settings-compiler/020-annotation-processor.png" alt="020 annotation processor" width="700px">
+ </div>
+ <div class="title">
+ Figure 17. IntelliJ Annotation Processor Settings
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>This setting enables the generation of the <code>Q*</code> classes for DataNucleus type-safe queries, as well as being required for frameworks such as <a href="#_cg_ide_project-lombok">Project Lombok</a>.</p>
+ </div>
+ <div class="admonitionblock note">
+ <table>
+ <tbody>
+ <tr>
+ <td class="icon"> <i class="fa icon-note" title="Note"></i> </td>
+ <td class="content">
+ <div class="paragraph">
+ <p>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.</p>
+ </div> </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ </div>
+ <div class="sect4">
+ <h5 id="_dg_ide_intellij_other-settings-maven">Other Settings (Maven)</h5>
+ <div class="paragraph">
+ <p>There are also some other settings for Maven that we recommend you adjust (though these are less critical):</p>
+ </div>
+ <div class="paragraph">
+ <p>First, specify an up-to-date Maven installation, using <code>File > Settings</code> (or <code>IntelliJ > Preferences</code> if on MacOS):</p>
+ </div>
+ <div class="imageblock">
+ <div class="content">
+ <img src="images/appendices/dev-env/intellij-idea/042-other-settings-maven/010-maven-installation.png" alt="010 maven installation" width="700px">
+ </div>
+ <div class="title">
+ Figure 18. IntelliJ Maven Settings - Installation
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>Still on the Maven settings page, configure as follows:</p>
+ </div>
+ <div class="imageblock">
+ <div class="content">
+ <img src="images/appendices/dev-env/intellij-idea/042-other-settings-maven/020-maven-configuration.png" alt="020 maven configuration" width="700px">
+ </div>
+ <div class="title">
+ Figure 19. IntelliJ Maven Settings - Configuration
+ </div>
+ </div>
+ </div>
+ <div class="sect4">
+ <h5 id="_other_settings_misc">Other Settings (Misc)</h5>
+ <div class="paragraph">
+ <p>These settings are optional but also recommended.</p>
+ </div>
+ <div class="paragraph">
+ <p>On the <strong>auto import</strong> page, check the <code>optimize imports on the fly</code> and <code>add unambiguous imports on the fly</code></p>
+ </div>
+ <div class="imageblock">
+ <div class="content">
+ <img src="images/appendices/dev-env/intellij-idea/044-other-settings-misc/010-auto-import.png" alt="010 auto import" width="700px">
+ </div>
+ <div class="title">
+ Figure 20. IntelliJ Maven Settings - Auto Import
+ </div>
+ </div>
+ </div>
+ </div>
+ <div class="sect3">
+ <h4 id="_dg_ide_intellij_importing-maven-modules">2.1.2. Importing Maven Modules</h4>
+ <div class="paragraph">
+ <p>Let\u2019s load in some actual code! We do this by importing the Maven modules.</p>
+ </div>
+ <div class="paragraph">
+ <p>First up, open up the Maven tool window (<code>View > Tool Windows > Maven Projects</code>). You can then use the 'plus' button to add Maven modules. In the screenshot you can see we\u2019ve loaded in Apache Isis core; the modules are listed in the <em>Maven Projects</em> window and corresponding (IntelliJ) modules are shown in the <em>Projects</em> window:</p>
+ </div>
+ <div class="imageblock">
+ <div class="content">
+ <img src="images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/010-maven-modules-view.png" alt="010 maven modules view" width="730px">
+ </div>
+ <div class="title">
+ Figure 21. IntelliJ Maven Module Management - Importing Maven modules
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>We can then import another module (from some other directory). For example, here we are importing the Isis Addons' todoapp example:</p>
+ </div>
+ <div class="imageblock">
+ <div class="content">
+ <img src="images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/020-adding-another-module.png" alt="020 adding another module" width="400px">
+ </div>
+ <div class="title">
+ Figure 22. IntelliJ Maven Module Management - Importing another Module
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>You should then see the new Maven module loaded in the <em>Projects</em> window and also the <em>Maven Projects</em> window:</p>
+ </div>
+ <div class="imageblock">
+ <div class="content">
+ <img src="images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/030-other-module-added.png" alt="030 other module added" width="730px">
+ </div>
+ <div class="title">
+ Figure 23. IntelliJ Maven Module Management -
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>If any dependencies are already loaded in the project, then IntelliJ will automatically update the CLASSPATH to resolve to locally held modules (rather from <code>.m2/repository</code> folder). So, for example (assuming that the <code><version></code> is correct, of course), the Isis todoapp will have local dependencies on the Apache Isis core.</p>
+ </div>
+ <div class="paragraph">
+ <p>You can press F4 (or use <code>File > Project Structure</code>) to see the resolved classpath for any of the modules loaded into the project.</p>
+ </div>
+ <div class="paragraph">
+ <p>If you want to focus on one set of code (eg the Isis todoapp but not Apache Isis core) then you <em>could</em> remove the module; but better is to ignore those modules. This will remove from the the <em>Projects</em> window but keep them available in the <em>Maven Projects</em> window for when you next want to work on them:</p>
+ </div>
+ <div class="imageblock">
+ <div class="content">
+ <img src="images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/040-ignoring-modules.png" alt="040 ignoring modules" width="730px">
+ </div>
+ <div class="title">
+ Figure 24. IntelliJ Maven Module Management - Ignoring Modules
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>Confirm that it\u2019s ok to ignore these modules:</p>
+ </div>
+ <div class="imageblock">
+ <div class="content">
+ <img src="images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/050-ignoring-modules-2.png" alt="050 ignoring modules 2" width="300px">
+ </div>
+ <div class="title">
+ Figure 25. IntelliJ Maven Module Management - Ignoring Modules (ctd)
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>All being well you should see that the <em>Projects</em> window now only contains the code you are working on. Its classpath dependencies will be adjusted (eg to resolve to Apache Isis core from <code>.m2/repository</code>):</p>
+ </div>
+ <div class="imageblock">
+ <div class="content">
+ <img src="images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/060-ignored-modules.png" alt="060 ignored modules" width="730px">
+ </div>
+ <div class="title">
+ Figure 26. IntelliJ Maven Module Management - Updated Projects Window
+ </div>
+ </div>
+ </div>
+ <div class="sect3">
+ <h4 id="_dg_ide_intellij_running">2.1.3. Running</h4>
+ <div class="paragraph">
+ <p>Let\u2019s see how to run both the app and the tests.</p>
+ </div>
+ <div class="sect4">
+ <h5 id="_dg_ide_intellij_running_the-app">Running the App</h5>
+ <div class="paragraph">
+ <p>Once you\u2019ve imported your Isis application, we should run it. We do this by creating a Run configuration, using <code>Run > Edit Configurations</code>.</p>
+ </div>
+ <div class="paragraph">
+ <p>Set up the details as follows:</p>
+ </div>
+ <div class="imageblock">
+ <div class="content">
+ <img src="images/appendices/dev-env/intellij-idea/110-running-the-app/010-run-configuration.png" alt="010 run configuration" width="600px">
+ </div>
+ <div class="title">
+ Figure 27. IntelliJ Running the App - Run Configuration
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>We specify the <code>Main class</code> to be <code>org.apache.isis.WebServer</code>; this is a wrapper around Jetty. It\u2019s possible to pass program arguments to this (eg to automatically install fixtures), but for now leave this blank.</p>
+ </div>
+ <div class="paragraph">
+ <p>Also note that <code>Use classpath of module</code> is the webapp module for your app, and that the <code>working directory</code> is <code>$MODULE_DIR$</code>.</p>
+ </div>
+ <div class="paragraph">
+ <p>Next, and most importantly, configure the DataNucleus enhancer to run for your <code>dom</code> goal. This can be done by defining a Maven goal to run before the app:</p>
+ </div>
+ <div class="imageblock">
+ <div class="content">
+ <img src="images/appendices/dev-env/intellij-idea/110-running-the-app/020-datanucleus-enhancer-goal.png" alt="020 datanucleus enhancer goal" width="400px">
+ </div>
+ <div class="title">
+ Figure 28. IntelliJ Running the App - Datanucleus Enhancer Goal
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>The <code>-o</code> flag in the goal means run off-line; this will run faster.</p>
+ </div>
+ <div class="admonitionblock warning">
+ <table>
+ <tbody>
+ <tr>
+ <td class="icon"> <i class="fa icon-warning" title="Warning"></i> </td>
+ <td class="content"> if you forget to set up the enhancer goal, or don\u2019t 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. </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div class="paragraph">
+ <p>You should now be able to run the app using <code>Run > Run Configuration</code>. The same configuration can also be used to debug the app if you so need.</p>
+ </div>
+ </div>
+ <div class="sect4">
+ <h5 id="_dg_ide_intellij_running_unit-tests">Running the Unit Tests</h5>
+ <div class="paragraph">
+ <p>The easiest way to run the unit tests is just to right click on the <code>dom</code> module in the <em>Project Window</em>, and choose run unit tests. Hopefully your tests will pass (!).</p>
+ </div>
+ <div class="imageblock">
+ <div class="content">
+ <img src="images/appendices/dev-env/intellij-idea/110-running-the-app/030-running-unit-tests.png" alt="030 running unit tests" width="600px">
+ </div>
+ <div class="title">
+ Figure 29. IntelliJ Running the App - Unit Tests Run Configuration
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>As a side-effect, this will create a run configuration, very similar to the one we manually created for the main app:</p>
+ </div>
+ <div class="imageblock">
+ <div class="content">
+ <img src="images/appendices/dev-env/intellij-idea/110-running-the-app/040-running-unit-tests-run-configuration.png" alt="040 running unit tests run configuration" width="600px">
+ </div>
+ <div class="title">
+ Figure 30. IntelliJ Running the App - Unit Tests Run Configuration
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>Thereafter, you should run units by selecting this configuration (if you use the right click approach you\u2019ll end up with lots of run configurations, all similar).</p>
+ </div>
+ </div>
+ <div class="sect4">
+ <h5 id="_dg_ide_intellij_running_integ-tests">Running the Integration Tests</h5>
+ <div class="paragraph">
+ <p>Integration tests can be run in the same way as unit tests, however the <code>dom</code> module must also have been enhanced.</p>
+ </div>
+ <div class="paragraph">
+ <p>One approach is to initially run the tests use the right click on the <code>integtests</code> module; the tests will fail because the code won\u2019t 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):</p>
+ </div>
+ <div class="imageblock">
+ <div class="content">
+ <img src="images/appendices/dev-env/intellij-idea/110-running-the-app/050-running-integration-tests-run-configuration.png" alt="050 running integration tests run configuration" width="600px">
+ </div>
+ <div class="title">
+ Figure 31. IntelliJ Running the App - Integration Tests Run Configuration
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>Also make sure that the <code>search for tests</code> radio button is set to <code>In single module</code>:</p>
+ </div>
+ <div class="imageblock">
+ <div class="content">
+ <a class="image" href="images/appendices/dev-env/intellij-idea/400-running-integtests/run-debug-configuration-single-module.png"><img src="images/appendices/dev-env/intellij-idea/400-running-integtests/run-debug-configuration-single-module.png" alt="run debug configuration single module" width="600px"></a>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>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 <code>dom</code> project that depend on test classes in that module, but using the classpath of the <code>integtests</code> module whereby the <code>dom</code> test-classes (<code>test-jar</code> artifact) are not exposed on the Maven classpath.</p>
+ </div>
+ </div>
+ </div>
+ <div class="sect3">
+ <h4 id="_dg_ide_intellij_hints-and-tips">2.1.4. Hints and Tips</h4>
+ <div class="sect4">
+ <h5 id="_dg_ide_intellij_hints-and-tips_keyboard-cheat-sheets">Keyboard Cheat Sheets</h5>
+ <div class="paragraph">
+ <p>You can download 1-page PDFs cheat sheets for IntelliJ\u2019s keyboard shortcuts: * for <a href="https://www.jetbrains.com/idea/docs/IntelliJIDEA_ReferenceCard.pdf">Windows</a> * for <a href="https://www.jetbrains.com/idea/docs/IntelliJIDEA_ReferenceCard_Mac.pdf">MacOS</a></p>
+ </div>
+ <div class="paragraph">
+ <p>Probably the most important shortcut on them is for <code>Find Action</code>: - <code>ctrl-shift-A</code> on Windows - <code>cmd-shift-A</code> on MacOS.</p>
+ </div>
+ <div class="paragraph">
+ <p>This will let you search for any action just by typing its name.</p>
+ </div>
+ </div>
+ <div class="sect4">
+ <h5 id="_switch_between_tools_editors">Switch between Tools & Editors</h5>
+ <div class="paragraph">
+ <p>The Tool Windows are the views around the editor (to left, bottom and right). It\u2019s possible to move these around to your preferred locations.</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p>Use <code>alt-1</code> through <code>alt-9</code> (or <code>cmd-1</code> through <code>alt-9</code>) to select the tool windows</p>
+ <div class="ulist">
+ <ul>
+ <li> <p>Press it twice and the tool window will hide itself; so can use to toggle</p> </li>
+ </ul>
+ </div> </li>
+ <li> <p>If in the <em>Project Window</em> (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 <code>Esc</code>.</p>
+ <div class="ulist">
+ <ul>
+ <li> <p>If in the <em>Terminal Window</em>, you\u2019ll need to press <code>Shift-Esc</code>.</p> </li>
+ </ul>
+ </div> </li>
+ <li> <p>If on the editor and want to locate the file in (say) the <em>Project Window</em>, use <code>alt-F1</code>.</p> </li>
+ <li> <p>To change the size of any tool window, use <code>ctrl-shift-arrow</code></p> </li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>Using these shortcuts you can easily toggle between the tool windows and the editor, without using the mouse. Peachy!</p>
+ </div>
+ </div>
+ <div class="sect4">
+ <h5 id="_dg_ide_intellij_hints-and-tips_navigating-around">Navigating Around</h5>
+ <div class="paragraph">
+ <p>For all of the following, you don\u2019t need to type every letter, typing "ab" will actually search for ".<strong>a.*b.</strong>".</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p>to open classes or files or methods that you know the name of:</p>
+ <div class="ulist">
+ <ul>
+ <li> <p><code>ctrl-N</code> to open class</p> </li>
+ <li> <p><code>ctrl-shift-N</code> to open a file</p> </li>
+ <li> <p>(bit fiddly this) <code>ctrl-shift-alt-N</code> to search for any symbol.</p> </li>
+ </ul>
+ </div> </li>
+ <li> <p>open up dialog of recent files: <code>ctrl-E</code></p> </li>
+ <li> <p>search for any file: <code>shift-shift</code></p> </li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>Navigating around: * find callers of a method (the call hierarchy): <code>ctrl-alt-H</code> * find subclasses or overrides: <code>ctrl-alt-B</code> * find superclasses/interface/declaration: <code>ctrl-B</code></p>
+ </div>
+ <div class="paragraph">
+ <p>Viewing the structure (ie outline) of a class * <code>ctrl-F12</code> will pop-up a dialog showing all members ** hit <code>ctrl-F12</code> again to also see inherited members</p>
+ </div>
+ </div>
+ <div class="sect4">
+ <h5 id="_dg_ide_intellij_hints-and-tips_editing">Editing</h5>
+ <div class="ulist">
+ <ul>
+ <li> <p>Extend selection using <code>ctrl-W</code></p>
+ <div class="ulist">
+ <ul>
+ <li> <p>and contract it down again using <code>ctrl-shift-W</code></p> </li>
+ </ul>
+ </div> </li>
+ <li> <p>to duplicate a line, it\u2019s <code>ctrl-D</code></p>
+ <div class="ulist">
+ <ul>
+ <li> <p>if you have some text selected (or even some lines), it\u2019ll actually duplicate the entire selection</p> </li>
+ </ul>
+ </div> </li>
+ <li> <p>to delete a line, it\u2019s <code>ctrl-X</code></p> </li>
+ <li> <p>to move a line up or down: <code>shift-alt-up</code> and <code>shift-alt-down</code></p>
+ <div class="ulist">
+ <ul>
+ <li> <p>if you have selected several lines, it\u2019ll move them all togethe</p> </li>
+ </ul>
+ </div> </li>
+ <li> <p><code>ctrl-shift-J</code> can be handy for joining lines together</p>
+ <div class="ulist">
+ <ul>
+ <li> <p>just hit enter to split them apart (even in string quotes; IntelliJ will "do the right thing")</p> </li>
+ </ul>
+ </div> </li>
+ </ul>
+ </div>
+ </div>
+ <div class="sect4">
+ <h5 id="_intentions_and_code_completion">Intentions and Code Completion</h5>
+ <div class="paragraph">
+ <p>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.</p>
+ </div>
+ <div class="paragraph">
+ <p>Code completion usually happens whenever you type '.'. You can
<TRUNCATED>